Core I/O and media
Logical paths, local and remote URIs, serialization, image/video normalization, and tiled media processing.
On this page
Core I/O gives model integrations one contract for where data lives and how it is represented. Path helpers resolve logical WorldFoundry locations; storage helpers operate on local paths and supported URI schemes; serialization chooses a format explicitly or from a suffix; media helpers normalize common image/video inputs before model-specific preprocessing begins.
Resolve logical paths, do not hard-code hosts
worldfoundry_path_tokens computes roots for checkpoints, datasets, models, artifacts, caches, source repositories, and Conda environments. Explicit environment values win; otherwise the resolver uses predictable WorldFoundry cache or repository-adjacent defaults.
from worldfoundry.core.io.paths import (
checkpoint_root_path,
resolve_worldfoundry_path,
worldfoundry_path_tokens,
)
env = {
"WORLDFOUNDRY_HOME": "/srv/wf",
"WORLDFOUNDRY_CKPT_DIR": "/models/checkpoints",
}
tokens = worldfoundry_path_tokens(env)
assert tokens["WORLDFOUNDRY_CKPT_DIR"] == "/models/checkpoints"
assert checkpoint_root_path("matrix-game-2", env=env) == \
resolve_worldfoundry_path("${WORLDFOUNDRY_CKPT_DIR}/matrix-game-2", env)Passing an env mapping makes path resolution testable without mutating the process environment. resolve_data_path is different: it points inside package-owned static data and should not be used for downloaded datasets.
Serialization round trip
from pathlib import Path
from tempfile import TemporaryDirectory
from worldfoundry.core import dump_serialized, load_serialized
with TemporaryDirectory() as directory:
path = Path(directory) / "request.yaml"
dump_serialized({"seed": 42, "actions": ["forward", "left"]}, path)
payload = load_serialized(path)
assert payload["seed"] == 42When file_format is omitted, the suffix selects JSON, YAML, JSONL, pickle/gzip, NumPy, Torch, image, video, CSV/Pandas, or tar handling. When no file is supplied, text and binary formats return their serialized value. Pickle and unrestricted Torch checkpoints are executable formats; do not load them from an untrusted source.
Video shape boundary
coerce_video_frames is the normalization boundary for paths, Torch tensors, NumPy arrays, PIL frame lists, and tensor frame lists. It returns a uint8 NumPy array in T × H × W × C layout. video_tensor_to_uint8_frames handles normalized C × T × H × W or single-batch tensors and makes the value range explicit. read_video adds decoder metadata, while load_frames_from_video is for selected frame indices.
Use materialize_video_input when a subprocess or external runtime requires a local filename. Use TileProcessor only for codec/model functions that explicitly support overlapping spatiotemporal tiles; it changes execution layout but blends overlaps back into one output.
Complete reference
The blocks below are the generated signatures for this category. Use the on-page symbol index to jump; source links open the defining implementation behind each lazy export.
56 public symbols
def checkpoint_root_path(*parts: str | Path,specific_env: str | None = None,env: Mapping[str, str] | None = None) -> Pathworldfoundry.core.io.paths.checkpoint_root_pathfrom worldfoundry.core.io.paths import checkpoint_root_pathOverview
Resolves a target model checkpoint directory path with nested subfolders. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: Path.
Source docstring
Resolves a target model checkpoint directory path with nested subfolders.
Avoids host-specific hardcoding by querying general and model-specific variables.
Parameters
partsstr | Path- Child path components appended to the resolved checkpoint root.
specific_envstr | None- Optional model-specific environment variable that takes precedence over `
WORLDFOUNDRY_CKPT_DIR`.default:None envMapping[str, str] | None- Environment mapping used instead of `
os.environ`.default:None
Returns: Path — Resolved checkpoint path without creating it.
def coerce_video_frames(video_input)worldfoundry.core.coerce_video_framesfrom worldfoundry.core import coerce_video_framesOverview
Normalize common video inputs into a uint8 THWC numpy array. Belongs to Core I/O and media (paths, URIs, images, video, serialization).
Parameters
video_input
Color
clsOverview
Small color helper compatible with legacy model-runtime config printers. Belongs to Core I/O and media (paths, URIs, images, video, serialization).
Methods
copy_uri
funcdef copy_uri(src: str | os.PathLike[str],dst: str | os.PathLike[str],**storage_options) -> strworldfoundry.core.copy_urifrom worldfoundry.core import copy_uriOverview
Copy one URI to another using storage-aware byte streams. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: str.
Parameters
srcstr | os.PathLike[str]dststr | os.PathLike[str]storage_options
Returns: str
crop_and_resize
funcdef crop_and_resize(image: Image.Image,height: int,width: int) -> Image.Imageworldfoundry.core.crop_and_resizefrom worldfoundry.core import crop_and_resizeOverview
Center-crop and resize a PIL image to `(width, height). Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: Image.Image`.
Parameters
imageImage.Imageheightintwidthint
Returns: Image.Image
dump_serialized
funcdef dump_serialized(obj: Any,file: str | Path | IO[Any] | None = None,file_format: str | None = None,encoding: str = 'utf-8',**kwargs: Any) -> str | bytes | Noneworldfoundry.core.dump_serializedfrom worldfoundry.core import dump_serializedOverview
Dump an object to a URI, file object, or string when `file is None. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: str | bytes | None`.
Parameters
objAnyfilestr | Path | IO[Any] | None- default:
None file_formatstr | None- default:
None encodingstr- default:
'utf-8' kwargsAny
Returns: str | bytes | None
exists_uri
funcdef exists_uri(uri: str | os.PathLike[str], **storage_options) -> boolworldfoundry.core.exists_urifrom worldfoundry.core import exists_uriOverview
Return whether a WorldFoundry URI (local or remote scheme) currently exists.
Parameters
uristr | os.PathLike[str]storage_options
Returns: bool
def extract_frames_from_video_url(video_url: str)worldfoundry.core.extract_frames_from_video_urlfrom worldfoundry.core import extract_frames_from_video_urlOverview
Decode a remote video URL and return RGB PIL frames. Belongs to Core I/O and media (paths, URIs, images, video, serialization).
Parameters
video_urlstr
file_sha256
funcdef file_sha256(path: str | os.PathLike[str], , chunk_size: int = 1024 1024) -> strworldfoundry.core.file_sha256from worldfoundry.core import file_sha256Overview
Compute a file's SHA-256 digest without loading the whole artifact into memory. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: str.
Parameters
pathstr | os.PathLike[str]chunk_sizeint- default:
1024 * 1024
Returns: str
def get_video_details(video_path: str | Path) -> tuple[int, float, float]worldfoundry.core.get_video_detailsfrom worldfoundry.core import get_video_detailsOverview
Return `(total_frames, fps, duration_seconds) for a local video. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: tuple[int, float, float]`.
Parameters
video_pathstr | Path
Returns: tuple[int, float, float]
def hf_download_or_fpath(path: str | PathLike[str] | None) -> str | Anyworldfoundry.core.hf_download_or_fpathfrom worldfoundry.core import hf_download_or_fpathOverview
Backwards-compatible alias for :func:resolve_hf_path. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: str | Any.
Parameters
pathstr | PathLike[str] | None
Returns: str | Any
hfd_root_path
funcdef hfd_root_path(parts: str | Path, env: Mapping[str, str] | None = None) -> Pathworldfoundry.core.io.paths.hfd_root_pathfrom worldfoundry.core.io.paths import hfd_root_pathOverview
Resolves the hfd-style local downloader checkpoint directory. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: Path.
Parameters
partsstr | PathenvMapping[str, str] | None- default:
None
Returns: Path
def infer_serialization_format(file: str | Path | IO[Any] | None,file_format: str | None = None) -> strworldfoundry.core.infer_serialization_formatfrom worldfoundry.core import infer_serialization_formatOverview
Infer a normalized serialization format key. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: str.
Parameters
filestr | Path | IO[Any] | Nonefile_formatstr | None- default:
None
Returns: str
is_remote_uri
funcdef is_remote_uri(uri: str | os.PathLike[str]) -> boolworldfoundry.core.is_remote_urifrom worldfoundry.core import is_remote_uriOverview
Return whether a path needs a non-local storage backend. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: bool.
Parameters
uristr | os.PathLike[str]
Returns: bool
join_uri
funcdef join_uri(base: str | os.PathLike[str], parts: str | os.PathLike[str]) -> strworldfoundry.core.join_urifrom worldfoundry.core import join_uriOverview
Join path components without losing remote URI schemes. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: str.
Parameters
basestr | os.PathLike[str]partsstr | os.PathLike[str]
Returns: str
jsonable
funcdef jsonable(value: Any) -> Anyworldfoundry.core.jsonablefrom worldfoundry.core import jsonableOverview
Recursively convert common runtime objects into JSON-safe values. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: Any.
Parameters
valueAny- Dataclass, `
to_dictobject, path, mapping, sequence, tensor/ array-like object withtolist`, callable, primitive, or fallback object.
Notes
Mapping keys are stringified, sets become lists, callables become a module/qualified-name record, and otherwise unsupported objects fall back to `repr`. This is evidence serialization, not a reversible object codec.
Returns: Any — A tree containing only JSON-compatible primitives and containers.
def load_frames_from_video(video_path: str | Path,indices: Iterable[int],video_decode_backend: str = 'decord',eval_: bool = True)worldfoundry.core.load_frames_from_videofrom worldfoundry.core import load_frames_from_videoOverview
Load selected RGB frames into a torch tensor using decord or OpenCV. Belongs to Core I/O and media (paths, URIs, images, video, serialization).
Parameters
video_pathstr | PathindicesIterable[int]video_decode_backendstr- default:
'decord' eval_bool- default:
True
load_serialized
funcdef load_serialized(file: str | Path | IO[Any],file_format: str | None = None,encoding: str = 'utf-8',**kwargs: Any) -> Anyworldfoundry.core.load_serializedfrom worldfoundry.core import load_serializedOverview
Load a structured object from a URI or file object. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: Any.
Parameters
filestr | Path | IO[Any]file_formatstr | None- default:
None encodingstr- default:
'utf-8' kwargsAny
Returns: Any
def load_video_frames(video_path: str | Path)worldfoundry.core.load_video_framesfrom worldfoundry.core import load_video_framesOverview
Decode a local or remote video into a uint8 THWC numpy array. Belongs to Core I/O and media (paths, URIs, images, video, serialization).
Parameters
video_pathstr | Path
def local_model_root_path(env: Mapping[str, str] | None = None) -> Pathworldfoundry.core.io.paths.local_model_root_pathfrom worldfoundry.core.io.paths import local_model_root_pathOverview
Resolves the root directory containing local model weights, configs, and adapters. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: Path.
Parameters
envMapping[str, str] | None- default:
None
Returns: Path
class LowMemoryImageFolder(folder, file_list = None)worldfoundry.core.LowMemoryImageFolderfrom worldfoundry.core import LowMemoryImageFolderOverview
Lazy image-folder reader that loads frames on demand. Belongs to Core I/O and media (paths, URIs, images, video, serialization).
Parameters
folderfile_list- default:
None
class LowMemoryVideo(file_name: str)worldfoundry.core.LowMemoryVideofrom worldfoundry.core import LowMemoryVideoOverview
Lazy video reader that loads frames on demand. Belongs to Core I/O and media (paths, URIs, images, video, serialization).
Parameters
file_namestr
def materialize_hf_snapshot(repo_id_or_path: str | os.PathLike[str],revision: str | None = None,cache_dir: str | os.PathLike[str] | None = None,allow_patterns: str | Sequence[str] | None = None,ignore_patterns: str | Sequence[str] | None = None,required_files: Sequence[str] = (),local_files_only: bool | None = None,token: str | bool | None = None) -> Pathworldfoundry.core.materialize_hf_snapshotfrom worldfoundry.core import materialize_hf_snapshotOverview
Return a local snapshot for either a path or Hugging Face repo id. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: Path.
Source docstring
Return a local snapshot for either a path or Hugging Face repo id.
Remote downloads are serialized on rank zero and then reopened in local-only mode, avoiding partial-cache races in multi-GPU jobs.
Parameters
repo_id_or_pathstr | os.PathLike[str]revisionstr | None- default:
None cache_dirstr | os.PathLike[str] | None- default:
None allow_patternsstr | Sequence[str] | None- default:
None ignore_patternsstr | Sequence[str] | None- default:
None required_filesSequence[str]- default:
() local_files_onlybool | None- default:
None tokenstr | bool | None- default:
None
Returns: Path
def materialize_video_input(video_input,output_dir: Optional[str] = None,filename: str = 'input.mp4',fps: int = 24) -> strworldfoundry.core.materialize_video_inputfrom worldfoundry.core import materialize_video_inputOverview
Return a local video path, materializing in-memory inputs when needed. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: str.
Parameters
video_inputoutput_dirOptional[str]- default:
None filenamestr- default:
'input.mp4' fpsint- default:
24
Returns: str
def maybe_download_hf_repo_on_rank0(repo_id_or_path: str,revision: str | None = None,cache_dir: str | os.PathLike[str] | None = None,allow_patterns: str | Sequence[str] | None = None,ignore_patterns: str | Sequence[str] | None = None,token: str | bool | None = None) -> Noneworldfoundry.core.maybe_download_hf_repo_on_rank0from worldfoundry.core import maybe_download_hf_repo_on_rank0Overview
Download a remote HF repo snapshot from rank 0 when downloads are allowed. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: None.
Source docstring
Download a remote HF repo snapshot from rank 0 when downloads are allowed.
Local paths and explicit offline/local-only modes are no-ops. For remote repositories, rank 0 preloads the snapshot while other distributed ranks wait for its success/failure signal. A filesystem lock serializes independent processes that share the same HF cache directory.
Parameters
repo_id_or_pathstrrevisionstr | None- default:
None cache_dirstr | os.PathLike[str] | None- default:
None allow_patternsstr | Sequence[str] | None- default:
None ignore_patternsstr | Sequence[str] | None- default:
None tokenstr | bool | None- default:
None
Returns: None
def merge_video_audio(video_path: str, audio_path: str) -> Noneworldfoundry.core.merge_video_audiofrom worldfoundry.core import merge_video_audioOverview
Merge video and audio with ffmpeg; overwrite `video_path on success. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: None`.
Parameters
video_pathstraudio_pathstr
Returns: None
open_uri
funcdef open_uri(uri: str | os.PathLike[str],mode: str = 'rb',encoding: str = 'utf-8',**storage_options) -> Generator[BinaryIO | TextIO, None, None]worldfoundry.core.open_urifrom worldfoundry.core import open_uriOverview
Open a local or remote URI. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: Generator[BinaryIO | TextIO, None, None].
Source docstring
Open a local or remote URI.
`fsspec` is used when available. Without it, local files are supported for all modes and HTTP(S) URLs are supported for reads.
Parameters
uristr | os.PathLike[str]modestr- default:
'rb' encodingstr- default:
'utf-8' storage_options
Returns: Generator[BinaryIO | TextIO, None, None]
def package_module_root(package: str) -> Pathworldfoundry.core.package_module_rootfrom worldfoundry.core import package_module_rootOverview
Resolve the source directory for an importable package. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: Path.
Parameters
packagestr
Returns: Path
class ParallelHelper()worldfoundry.core.ParallelHelperfrom worldfoundry.core import ParallelHelperOverview
Distribute video tiles by cost and reconstruct their global ordering. Belongs to Core I/O and media (paths, URIs, images, video, serialization).
Source docstring
Distribute video tiles by cost and reconstruct their global ordering.
In non-distributed execution every tile remains local. With a process group, larger tiles are round-robin balanced across ranks and decoded frame tensors are gathered with explicit count, dtype, and shape metadata.
Methods
split_tile_list(tile_numel_dict: OrderedDict[int, int],parallel_group: torch.distributed.ProcessGroup = None) -> List[int]sourceOverview
Splits the given tile size into a list of sizes that each rank should handle.
Source docstring
Splits the given tile size into a list of sizes that each rank should handle.
This method takes into account the number of ranks in a distributed setting. If the distributed environment is not initialized, it returns a list of integers from 0 to tile_size - 1, representing each tile index.
If the distributed environment is initialized, it calculates the base tile size for each rank and distributes any remaining tiles among the ranks.
Parameters
tile_numel_dictOrderedDict[int, int]- Dict of index and numel of tiles.
parallel_grouptorch.distributed.ProcessGroup- Distributed decoding group. Defaults to None.default:
None
Returns: List[int] — List[int]: A list of tile indices assigned to the current rank. List[int]: A list of global tile indices.
gather_frames(frames: List[torch.Tensor],global_tile_idxs: List[int],parallel_group: torch.distributed.ProcessGroup = None) -> List[torch.Tensor]sourceOverview
Gathers frame data from all ranks in a distributed environment.
Source docstring
Gathers frame data from all ranks in a distributed environment.
This method collects frames from all ranks and combines them into a single list. If the distributed environment is not initialized, it simply returns the input frames.
Parameters
framesList[torch.Tensor]- A list of frames (tensors) from the current rank.
global_tile_idxsList[int]- A list of global tile indices.
parallel_grouptorch.distributed.ProcessGroup- Distributed decoding group. Defaults to None.default:
None
Returns: List[torch.Tensor] — List[torch.Tensor]: A list of frames (tensors) from all ranks.
Overview
Converts a single index into a list of indices, representing the position in a multi-dimensional space.
Source docstring
Converts a single index into a list of indices, representing the position in a multi-dimensional space.
This method takes an integer index and a list of loop sizes, and converts the index into a list of indices that correspond to the position in a multi-dimensional space.
Parameters
indexint- The single index to be converted.
loop_sizeList[int]- A list of integers representing the size of each dimension in the multi-dimensional space.
Returns: List[int] — List[int]: A list of integers representing the position in the multi-dimensional space.
Overview
Converts a list of indices into a single index, representing the position in a multi-dimensional space.
Source docstring
Converts a list of indices into a single index, representing the position in a multi-dimensional space.
This method takes a list of indices and a list of loop sizes, and converts the list of indices into a single index that corresponds to the position in a multi-dimensional space.
Parameters
indexList[int]- A list of integers representing the position in the multi-dimensional space.
loop_sizeList[int]- A list of integers representing the size of each dimension in the multi-dimensional space.
Returns: int — int: A single integer representing the position in the multi-dimensional space.
parse_uri_scheme
funcdef parse_uri_scheme(uri: str | os.PathLike[str]) -> strworldfoundry.core.parse_uri_schemefrom worldfoundry.core import parse_uri_schemeOverview
Return the lowercase URI scheme, using `file for local paths. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: str`.
Parameters
uristr | os.PathLike[str]
Returns: str
project_root
funcdef project_root(start: str | Path | None = None) -> Pathworldfoundry.core.io.paths.project_rootfrom worldfoundry.core.io.paths import project_rootOverview
Walks upward from a starting path to locate the root repository containing pyproject.toml. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: Path.
Source docstring
Walks upward from a starting path to locate the root repository containing pyproject.toml.
This helper provides robust local development support, falling back to a package-relative root if executed from a system-wide python site-packages deployment.
Parameters
startstr | Path | None- File or directory from which to search upward. `
None` starts from this module's installed source path.default:None
Returns: Path — First ancestor containing `pyproject.toml`, or the package-relative fallback when no repository marker is found.
read_binary_uri
funcdef read_binary_uri(uri: str | os.PathLike[str], **storage_options) -> bytesworldfoundry.core.read_binary_urifrom worldfoundry.core import read_binary_uriOverview
Read all bytes from a URI through Core’s storage helpers.
Parameters
uristr | os.PathLike[str]storage_options
Returns: bytes
def read_image_as_video_tensor(image_path: str | Path,resolution: Iterable[int],num_video_frames: int,resize: bool = True)worldfoundry.core.read_image_as_video_tensorfrom worldfoundry.core import read_image_as_video_tensorOverview
Load an image and materialize a `[1,C,T,H,W]` uint8 conditioning video tensor. Belongs to Core I/O and media (paths, URIs, images, video, serialization).
Parameters
image_pathstr | PathresolutionIterable[int]num_video_framesintresizebool- default:
True
read_text_uri
funcdef read_text_uri(uri: str | os.PathLike[str],encoding: str = 'utf-8',**storage_options) -> strworldfoundry.core.read_text_urifrom worldfoundry.core import read_text_uriOverview
Read all text from a URI through Core’s storage helpers.
Parameters
uristr | os.PathLike[str]encodingstr- default:
'utf-8' storage_options
Returns: str
read_video
funcdef read_video(video_path: str | Path, , return_metadata: bool = True)worldfoundry.core.read_videofrom worldfoundry.core import read_videoOverview
Decode a video into frames and optional metadata. Belongs to Core I/O and media (paths, URIs, images, video, serialization).
Parameters
video_pathstr | Pathreturn_metadatabool- default:
True
def resize_video_tensor_to_resolution(video_tensor, resolution: Iterable[int])worldfoundry.core.resize_video_tensor_to_resolutionfrom worldfoundry.core import resize_video_tensor_to_resolutionOverview
Resize and center-crop a `[T,C,H,W] tensor to (target_h, target_w)`. Belongs to Core I/O and media (paths, URIs, images, video, serialization).
Parameters
video_tensorresolutionIterable[int]
def resolve_data_path(parts: str | Path) -> Pathworldfoundry.core.io.paths.resolve_data_pathfrom worldfoundry.core.io.paths import resolve_data_pathOverview
Resolves a subpath under the internal worldfoundry/data asset directory. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: Path.
Parameters
partsstr | Path
Returns: Path
resolve_hf_path
funcdef resolve_hf_path(path: str | PathLike[str] | None) -> str | Anyworldfoundry.core.resolve_hf_pathfrom worldfoundry.core import resolve_hf_pathOverview
Resolve a possibly `hf://-prefixed path to a local filesystem path. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: str | Any`.
Source docstring
Resolve a possibly `hf://`-prefixed path to a local filesystem path.
Accepts either:
* a local path (returned unchanged if it exists), or * `hf://<owner>/<repo>[/<subpath>]` — resolves an already materialized WorldFoundry-local snapshot and returns the requested file or directory.
Runtime I/O is deliberately offline. Repository acquisition belongs to the explicit preparation workflow, never to model inference.
Parameters
pathstr | PathLike[str] | None
Returns: str | Any
def resolve_hf_snapshot_path(value: str | os.PathLike[str],required_files: Sequence[str] = (),local_files_only_env: str = 'WORLDFOUNDRY_HF_LOCAL_FILES_ONLY',local_files_only: bool | None = None) -> Pathworldfoundry.core.resolve_hf_snapshot_pathfrom worldfoundry.core import resolve_hf_snapshot_pathOverview
Resolve a repo id, HF cache repo root, or local path to a usable snapshot. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: Path.
Parameters
valuestr | os.PathLike[str]required_filesSequence[str]- default:
() local_files_only_envstr- default:
'WORLDFOUNDRY_HF_LOCAL_FILES_ONLY' local_files_onlybool | None- default:
None
Returns: Path
def resolve_local_checkpoint_file(model_id_or_path: str | Path,filename: str,env: Mapping[str, str] | None = None) -> Pathworldfoundry.core.resolve_local_checkpoint_filefrom worldfoundry.core import resolve_local_checkpoint_fileOverview
Resolve one checkpoint file from explicit or WorldFoundry-local storage. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: Path.
Source docstring
Resolve one checkpoint file from explicit or WorldFoundry-local storage.
An explicit file path is accepted directly. Directory paths and repository identifiers are resolved through :func:resolve_local_hf_model_path, so incomplete hfd transfers are rejected and this function never contacts a model hub.
Parameters
model_id_or_pathstr | PathfilenamestrenvMapping[str, str] | None- default:
None
Returns: Path
def resolve_local_hf_model_path(model_id_or_path: str | Path,required_files: Sequence[str] = (),env: Mapping[str, str] | None = None) -> Pathworldfoundry.core.resolve_local_hf_model_pathfrom worldfoundry.core import resolve_local_hf_model_pathOverview
Resolve a Hugging Face model strictly from WorldFoundry-local storage. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: Path.
Source docstring
Resolve a Hugging Face model strictly from WorldFoundry-local storage.
The resolver understands direct export directories, hfd-style names such as `owner--repo, and the Hub cache snapshots/<revision>` layout. It never contacts the network, which keeps model initialization deterministic and works in inference environments that do not install PyTorch.
Parameters
model_id_or_pathstr | Pathrequired_filesSequence[str]- default:
() envMapping[str, str] | None- default:
None
Returns: Path
def resolve_worldfoundry_path(value: str | Path,env: Mapping[str, str] | None = None) -> Pathworldfoundry.core.io.paths.resolve_worldfoundry_pathfrom worldfoundry.core.io.paths import resolve_worldfoundry_pathOverview
Expands structural WorldFoundry path tokens (e.g. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: Path.
Source docstring
Expands structural WorldFoundry path tokens (e.g. ${WORLDFOUNDRY_CKPT_DIR}) and home markers (~).
Performs precise regex-free variable mapping replacement while preserving subfolder hierarchies.
Parameters
valuestr | Path- Path containing optional `
$NAMEor${NAME}` tokens. envMapping[str, str] | None- Environment mapping used to build/override WorldFoundry tokens.default:
None
Returns: Path — Expanded `Path`. The target is not created or required to exist.
save_frames
funcdef save_frames(frames, save_path)worldfoundry.core.save_framesfrom worldfoundry.core import save_framesOverview
Write a sequence of PIL frames to numbered PNG files. Belongs to Core I/O and media (paths, URIs, images, video, serialization).
Parameters
framessave_path
def save_image_or_video_tensor(tensor,save_path,fps: int = 24,quality: int | None = None,ffmpeg_params: list[str] | None = None,value_range: str | tuple[float, float] = 'auto',image_format: str = 'JPEG',video_format: str = 'mp4',**kwargs) -> str | Noneworldfoundry.core.save_image_or_video_tensorfrom worldfoundry.core import save_image_or_video_tensorOverview
Save a normalized `[C,T,H,W] or [B,C,T,H,W] tensor as image/video. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: str | None`.
Source docstring
Save a normalized `[C,T,H,W] or [B,C,T,H,W]` tensor as image/video.
A single-frame tensor is saved as an image; multi-frame tensors are saved as videos. Local paths and URI-like targets supported by `worldfoundry.core.io` storage helpers are both accepted.
Parameters
tensorsave_pathfpsint- default:
24 qualityint | None- default:
None ffmpeg_paramslist[str] | None- default:
None value_rangestr | tuple[float, float]- default:
'auto' image_formatstr- default:
'JPEG' video_formatstr- default:
'mp4' kwargs
Returns: str | None
save_video
funcdef save_video(frames,save_path,fps,quality = 9,ffmpeg_params = None)worldfoundry.core.save_videofrom worldfoundry.core import save_videoOverview
Write a sequence of PIL frames to a video file. Belongs to Core I/O and media (paths, URIs, images, video, serialization).
Parameters
framessave_pathfpsquality- default:
9 ffmpeg_params- default:
None
def save_video_frames(video_frames,output_path: str | Path,fps: int = 16,**kwargs) -> Noneworldfoundry.core.save_video_framesfrom worldfoundry.core import save_video_framesOverview
Write a THWC uint8 frame array/list to a video path or URI. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: None.
Parameters
video_framesoutput_pathstr | Pathfpsint- default:
16 kwargs
Returns: None
def save_video_with_audio(frames,save_path,audio_path,fps = 16,quality = 9,ffmpeg_params = None)worldfoundry.core.save_video_with_audiofrom worldfoundry.core import save_video_with_audioOverview
Write PIL frames, then mux an external audio track with ffmpeg. Belongs to Core I/O and media (paths, URIs, images, video, serialization).
Parameters
frames- Iterable of PIL images.
save_path- Destination video path, replaced after muxing.
audio_path- Existing audio file.
fps- Output frame rate.default:
16 quality- ImageIO encoder quality.default:
9 ffmpeg_params- Optional ImageIO ffmpeg arguments.default:
None
Notes
`merge_video_audio` reports ffmpeg failures and removes its temporary file. Use lower-level helpers when the caller needs structured process error handling.
def search_for_images(folder)worldfoundry.core.search_for_imagesfrom worldfoundry.core import search_for_imagesOverview
Return naturally sorted JPG/PNG paths from one image-sequence folder. Belongs to Core I/O and media (paths, URIs, images, video, serialization).
Source docstring
Return naturally sorted JPG/PNG paths from one image-sequence folder.
Embedded digit runs are compared numerically, so `2.png sorts before 10.png`. The search is non-recursive.
Parameters
folder
class TileProcessor(encode_fn,decode_fn,tile_sample_min_height: int = 256,tile_sample_min_width: int = 256,tile_sample_min_length: int = 16,spatial_downsample_factor: int = 8,temporal_downsample_factor: int = 1,spatial_tile_overlap_factor: float = 0.25,temporal_tile_overlap_factor: float = 0,sr_ratio = 1,first_frame_as_image: bool = False,parallel_group: torch.distributed.ProcessGroup = None)worldfoundry.core.TileProcessorfrom worldfoundry.core import TileProcessorOverview
Encode or decode large videos through overlapping spatiotemporal tiles. Belongs to Core I/O and media (paths, URIs, images, video, serialization).
Source docstring
Encode or decode large videos through overlapping spatiotemporal tiles.
The processor derives latent tile sizes from codec downsample factors, schedules tiles locally or across `parallel_group, and linearly blends temporal/vertical/horizontal overlaps to suppress seams. encode_fn and decode_fn` remain model-owned callables.
Parameters
encode_fn- The encoding function used for tile sampling.
decode_fn- The decoding function used for tile reconstruction.
tile_sample_min_heightint- default:
256 tile_sample_min_widthint- default:
256 tile_sample_min_lengthint- The minimum length of the sampled tiles. Defaults to 16.default:
16 spatial_downsample_factorint- The actual spataial downsample factor of given encode_fn. Defaults to 8.default:
8 temporal_downsample_factorint- The actual temporal downsample factor of the latent space tiles. Defaults to 1.default:
1 spatial_tile_overlap_factorfloat- default:
0.25 temporal_tile_overlap_factorfloat- default:
0 sr_ratio- default:
1 first_frame_as_imagebool- default:
False parallel_grouptorch.distributed.ProcessGroup- Distributed decoding group. Defaults to None.default:
None
Methods
Overview
Public method on this type.
Parameters
atorch.Tensorbtorch.Tensorblend_extentint
Returns: torch.Tensor
Overview
Public method on this type.
Parameters
atorch.Tensorbtorch.Tensorblend_extentint
Returns: torch.Tensor
Overview
Public method on this type.
Parameters
atorch.Tensorbtorch.Tensorblend_extentint
Returns: torch.Tensor
Overview
Public method on this type.
Parameters
xtorch.FloatTensorverbosebool- default:
False
Overview
Public method on this type.
Parameters
ztorch.FloatTensorverbosebool- default:
False
def video_tensor_to_uint8_frames(video_tensor,value_range: str | tuple[float, float] = 'auto') -> 'object'worldfoundry.core.video_tensor_to_uint8_framesfrom worldfoundry.core import video_tensor_to_uint8_framesOverview
Convert a normalized torch video tensor to uint8 THWC frames. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: 'object'.
Source docstring
Convert a normalized torch video tensor to uint8 THWC frames.
`value_range="auto" treats tensors with negative values as [-1, 1] and non-negative floating tensors as [0, 1]`.
Parameters
video_tensorvalue_rangestr | tuple[float, float]- default:
'auto'
Returns: 'object'
VideoData
clsclass VideoData(video_file = None,image_folder = None,height = None,width = None,**kwargs)worldfoundry.core.VideoDatafrom worldfoundry.core import VideoDataOverview
Lazy video or image-folder dataset with optional resize. Belongs to Core I/O and media (paths, URIs, images, video, serialization).
Parameters
video_file- default:
None image_folder- default:
None height- default:
None width- default:
None kwargs
Methods
Overview
Public method on this type.
Overview
Public method on this type.
def worldfoundry_path_tokens(env: Mapping[str, str] | None = None) -> dict[str, str]worldfoundry.core.io.paths.worldfoundry_path_tokensfrom worldfoundry.core.io.paths import worldfoundry_path_tokensOverview
Generates the dictionary of logical path-token replacements used across the system. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: dict[str, str].
Source docstring
Generates the dictionary of logical path-token replacements used across the system.
Builds dynamic mappings for artifact, checkpoint, data, conda, and repo paths. Prioritizes explicit environment overrides (such as WORLDFOUNDRY_HOME or WORLDFOUNDRY_CACHE_DIR) and falls back to user-home cache directories when variables are unset.
Parameters
envMapping[str, str] | None- Environment mapping to resolve instead of `
os.environ`. Passing a mapping makes resolution deterministic in tests.default:None
Returns: dict[str, str] — Token name to expanded path-string mapping.
write_binary_uri
funcdef write_binary_uri(uri: str | os.PathLike[str],data: bytes | bytearray | memoryview | io.BytesIO,**storage_options) -> Noneworldfoundry.core.write_binary_urifrom worldfoundry.core import write_binary_uriOverview
Write bytes to a URI, creating local parent directories as needed. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: None.
Parameters
uristr | os.PathLike[str]databytes | bytearray | memoryview | io.BytesIOstorage_options
Returns: None
write_text_uri
funcdef write_text_uri(uri: str | os.PathLike[str],data: str,encoding: str = 'utf-8',**storage_options) -> Noneworldfoundry.core.write_text_urifrom worldfoundry.core import write_text_uriOverview
Write text to a URI, creating local parent directories as needed. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: None.
Parameters
uristr | os.PathLike[str]datastrencodingstr- default:
'utf-8' storage_options
Returns: None
write_video
funcdef write_video(video_frames,output_path: str | Path,fps: int = 16,quality: int | None = None,format: str | None = None,**kwargs) -> Noneworldfoundry.core.write_videofrom worldfoundry.core import write_videoOverview
Write a THWC video array/list to a local path or remote URI. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: None.
Parameters
video_framesoutput_pathstr | Pathfpsint- default:
16 qualityint | None- default:
None formatstr | None- default:
None kwargs
Returns: None
def write_video_torchvision(filename: str | Path,video_array: Any,fps: float,*args: Any,**kwargs: Any) -> Noneworldfoundry.core.write_video_torchvisionfrom worldfoundry.core import write_video_torchvisionOverview
Write RGB video frames with a `torchvision.io.write_video-compatible signature. Belongs to Core I/O and media (paths, URIs, images, video, serialization). Annotated return type: None`.
Parameters
filenamestr | Pathvideo_arrayAnyfpsfloatargsAnykwargsAny
Returns: None