Core I/O 与媒体
逻辑路径、本地和远程 URI、序列化、图像视频规范化以及分块媒体处理。
Core I/O 为模型接入提供统一的“数据在哪里、以什么形态存在”契约。路径 helper 解析 WorldFoundry 逻辑位置；storage helper 操作本地路径和受支持的 URI scheme；序列化根据显式格式或后缀选择实现；媒体 helper 在进入模型专属预处理之前规范化常见图像和视频输入。
解析逻辑路径，不要写死机器路径
worldfoundry_path_tokens 会计算 checkpoint、dataset、model、artifact、cache、源码仓库和 Conda 环境根目录。显式环境变量优先，否则使用可预测的 WorldFoundry cache 或仓库相邻目录。
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)传入 env mapping 可以在不修改进程环境的情况下测试路径解析。resolve_data_path 的职责不同：它指向 package 自带的静态数据，不应该用于下载的数据集。
序列化往返示例
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"] == 42没有传 file_format 时，文件后缀会选择 JSON、YAML、JSONL、pickle/gzip、NumPy、Torch、图像、视频、CSV/Pandas 或 tar。没有传文件时，文本和二进制格式会直接返回序列化结果。Pickle 和不受限制的 Torch checkpoint 是可执行格式，不要从不可信来源加载。
视频形状边界
coerce_video_frames 是路径、Torch tensor、NumPy array、PIL frame list 和 tensor frame list 的统一规范化入口，返回 T × H × W × C 布局的 uint8 NumPy array。video_tensor_to_uint8_frames 处理规范化的 C × T × H × W 或单 batch tensor，并明确 value range。read_video 还会返回 decoder metadata，load_frames_from_video 则适合只读取指定 frame index。
当 subprocess 或外部 runtime 必须得到本地文件名时，使用 materialize_video_input。只有 codec 或模型函数明确支持重叠时空 tile 时才使用 TileProcessor；它会改变执行布局，但最后把重叠区融合回单一输出。
完整参考
以下为该类别的生成签名。可用本页符号索引跳转；源码链接指向各惰性导出背后的具体实现。
73 个公开符号
def checkpoint_root_path(*parts: str | Path,specific_env: str | None = None,env: Mapping[str, str] | None = None) -> Path简介
checkpoint_root_path — Resolves a target model checkpoint directory path with nested subfolders. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：Path。
源码 docstring
Resolves a target model checkpoint directory path with nested subfolders.
Avoids host-specific hardcoding by querying general and model-specific variables.
参数
partsstr | Pathspecific_envstr | None默认值 NoneWORLDFOUNDRY_CKPT_DIR`.envMapping[str, str] | None默认值 Noneos.environ`.返回值
def coerce_video_frames(video_input,max_frames: int | None = None,from_end: bool = False)简介
coerce_video_frames — Normalize video inputs to uint8 THWC, optionally keeping a prefix/tail. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
源码 docstring
Normalize video inputs to uint8 THWC, optionally keeping a prefix/tail.
File inputs use the same ImageIO decoder as the full reader. Prefix reads stop early; tail reads retain only the requested frame count while reading to EOF. Array/tensor inputs retain whole-input range detection before slicing, so truncation does not change automatic value normalization.
参数
video_inputmax_framesint | None默认值 Nonefrom_endbool默认值 Falsedef copy_uri(src: str | os.PathLike[str],dst: str | os.PathLike[str],**storage_options) -> str简介
copy_uri — Copy one URI to another using storage-aware byte streams. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：str。
源码 docstring
Copy one URI to another using storage-aware byte streams.
Remote transfers stream in bounded chunks instead of buffering the whole object in memory; this is the byte mover underneath the download caches, where objects are multi-GB checkpoints.
参数
srcstr | os.PathLike[str]dststr | os.PathLike[str]storage_options返回值
def crop_and_resize(image: Image.Image,height: int,width: int) -> Image.Imagecrop_and_resize — Center-crop and resize a PIL image to `(width, height). 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：Image.Image`。
参数
imageImage.Imageheightintwidthint返回值
def dump_serialized(obj: Any,file: str | Path | IO[Any] | None = None,file_format: str | None = None,encoding: str = 'utf-8',**kwargs: Any) -> str | bytes | Nonedump_serialized — Dump an object to a URI, file object, or string when `file is None. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：str | bytes | None`。
参数
objAnyfilestr | Path | IO[Any] | None默认值 Nonefile_formatstr | None默认值 Noneencodingstr默认值 'utf-8'kwargsAny返回值
def exists_uri(uri: str | os.PathLike[str],**storage_options) -> bool判断 WorldFoundry URI（本地或远程协议）当前是否存在。
参数
uristr | os.PathLike[str]storage_options返回值
def extract_frames_from_video_url(video_url: str)extract_frames_from_video_url — Decode a remote video URL and return RGB PIL frames. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
参数
video_urlstrdef extract_video_frames_to_directory(video_path: str | Path,output_dir: str | Path,prefix: str = 'frames_',suffix: str = '.png',ffmpeg_path: str | Path | None = None,threads: int = 1,timeout_seconds: float | None = None,overwrite: bool = False) -> tuple[Path, ...]extract_video_frames_to_directory — Extract every source frame with bounded, deterministic ffmpeg settings. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：tuple[Path, ...]。
参数
video_pathstr | Pathoutput_dirstr | Pathprefixstr默认值 'frames_'suffixstr默认值 '.png'ffmpeg_pathstr | Path | None默认值 Nonethreadsint默认值 1timeout_secondsfloat | None默认值 Noneoverwritebool默认值 False返回值
def file_sha256(path: str | os.PathLike[str],chunk_size: int = 1024 * 1024) -> strfile_sha256 — Compute a file's SHA-256 digest without loading the whole artifact into memory. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：str。
参数
pathstr | os.PathLike[str]chunk_sizeint默认值 1024 * 1024返回值
def get_video_details(video_path: str | Path) -> tuple[int, float, float]get_video_details — Return `(total_frames, fps, duration_seconds) for a local video. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：tuple[int, float, float]`。
参数
video_pathstr | Path返回值
def hf_download_or_fpath(path: str | PathLike[str] | None) -> str | Anyhf_download_or_fpath — Backwards-compatible alias for :func:resolve_hf_path. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：str | Any。
参数
pathstr | PathLike[str] | None返回值
def hfd_root_path(*parts: str | Path,env: Mapping[str, str] | None = None) -> Pathhfd_root_path — Resolves the hfd-style local downloader checkpoint directory. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：Path。
参数
partsstr | PathenvMapping[str, str] | None默认值 None返回值
class IdentityVideoPostProcessor()IdentityVideoPostProcessor — Zero-copy processor used to exercise the production integration path. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
方法
start — Open a passthrough session that still enforces flush-then-reject.
参数
specVideoSpecdef infer_serialization_format(file: str | Path | IO[Any] | None,file_format: str | None = None) -> strinfer_serialization_format — Infer a normalized serialization format key. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：str。
参数
filestr | Path | IO[Any] | Nonefile_formatstr | None默认值 None返回值
def inspect_rtx_vfx_capability(, device: int = 0) -> RTXVFXCapabilityinspect_rtx_vfx_capability — Inspect static prerequisites without creating a VFX effect. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：RTXVFXCapability。
参数
deviceint默认值 0def is_remote_uri(uri: str | os.PathLike[str]) -> boolis_remote_uri — Return whether a path needs a non-local storage backend. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：bool。
参数
uristr | os.PathLike[str]返回值
def jsonable(value: Any) -> Anyjsonable — Recursively convert common runtime objects into JSON-safe values. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：Any。
参数
valueAnyto_dict object, path, mapping, sequence, tensor/ array-like object with tolist`, callable, primitive, or fallback object.返回值
说明
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.
def load_frames_from_video(video_path: str | Path,indices: Iterable[int],video_decode_backend: str = 'decord',eval_: bool = True)load_frames_from_video — Load selected RGB frames into a torch tensor using decord or OpenCV. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
参数
video_pathstr | PathindicesIterable[int]video_decode_backendstr默认值 'decord'eval_bool默认值 Truedef load_serialized(file: str | Path | IO[Any],file_format: str | None = None,encoding: str = 'utf-8',allow_pickle: bool = False,**kwargs: Any) -> Any简介
load_serialized — Load a structured object from a URI or file object. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：Any。
源码 docstring
Load a structured object from a URI or file object.
Pickle and gzip-pickle payloads are rejected by default because unpickling executes arbitrary code. Trusted callers must pass `allow_pickle=True. Torch formats independently default to weights_only=True. .gz` is treated as gzip-compressed pickle for backward compatibility; use an explicit non-gzip format for other compressed data.
参数
filestr | Path | IO[Any]file_formatstr | None默认值 Noneencodingstr默认值 'utf-8'allow_picklebool默认值 FalsekwargsAny返回值
def load_video_frames(video_path: str | Path,max_frames: int | None = None,from_end: bool = False)load_video_frames — Decode a video, optionally bounding its prefix/tail without changing RGB conversion. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
参数
video_pathstr | Pathmax_framesint | None默认值 Nonefrom_endbool默认值 Falsedef local_model_root_path(env: Mapping[str, str] | None = None) -> Pathlocal_model_root_path — Resolves the root directory containing local model weights, configs, and adapters. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：Path。
参数
envMapping[str, str] | None默认值 None返回值
class LowMemoryImageFolder(folder,file_list = None)LowMemoryImageFolder — Lazy image-folder reader that loads frames on demand. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
参数
folderfile_list默认值 Noneclass LowMemoryVideo(file_name: str)LowMemoryVideo — Lazy video reader that loads frames on demand. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
参数
file_namestrdef 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) -> Path简介
materialize_hf_snapshot — Return a local snapshot for either a path or Hugging Face repo id. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：Path。
源码 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.
参数
repo_id_or_pathstr | os.PathLike[str]revisionstr | None默认值 Nonecache_dirstr | os.PathLike[str] | None默认值 Noneallow_patternsstr | Sequence[str] | None默认值 Noneignore_patternsstr | Sequence[str] | None默认值 Nonerequired_filesSequence[str]默认值 ()local_files_onlybool | None默认值 Nonetokenstr | bool | None默认值 None返回值
def materialize_video_input(video_input,output_dir: Optional[str] = None,filename: str = 'input.mp4',fps: int = 24) -> strmaterialize_video_input — Return a local video path, materializing in-memory inputs when needed. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：str。
参数
video_inputoutput_dirOptional[str]默认值 Nonefilenamestr默认值 'input.mp4'fpsint默认值 24返回值
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) -> None简介
maybe_download_hf_repo_on_rank0 — Download a remote HF repo snapshot from rank 0 when downloads are allowed. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：None。
源码 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.
参数
repo_id_or_pathstrrevisionstr | None默认值 Nonecache_dirstr | os.PathLike[str] | None默认值 Noneallow_patternsstr | Sequence[str] | None默认值 Noneignore_patternsstr | Sequence[str] | None默认值 Nonetokenstr | bool | None默认值 None返回值
def merge_video_audio(video_path: str,audio_path: str) -> None简介
merge_video_audio — Merge video and audio with ffmpeg; overwrite `video_path on success. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：None`。
源码 docstring
Merge video and audio with ffmpeg; overwrite `video_path` on success.
Raises on failure (missing inputs, ffmpeg errors). The temporary mux output is always removed, so a failed merge leaves the original video untouched. Historically this function swallowed its own errors and returned normally, which made callers treat missing audio tracks as success.
参数
video_pathstraudio_pathstr返回值
def open_uri(uri: str | os.PathLike[str],mode: str = 'rb',encoding: str = 'utf-8',**storage_options) -> Generator[BinaryIO | TextIO, None, None]简介
open_uri — Open a local or remote URI. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：Generator[BinaryIO | TextIO, None, None]。
源码 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.
参数
uristr | os.PathLike[str]modestr默认值 'rb'encodingstr默认值 'utf-8'storage_options返回值
def package_module_root(package: str) -> Pathpackage_module_root — Resolve the source directory for an importable package. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：Path。
参数
packagestr返回值
class ParallelHelper()简介
ParallelHelper — Distribute video tiles by cost and reconstruct their global ordering. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
源码 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.
方法
split_tile_list(tile_numel_dict: OrderedDict[int, int],parallel_group: torch.distributed.ProcessGroup = None) -> List[int]源码简介
split_tile_list — Splits the given tile size into a list of sizes that each rank should handle.
源码 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.
参数
tile_numel_dictOrderedDict[int, int]parallel_grouptorch.distributed.ProcessGroup默认值 None返回值
gather_frames(frames: List[torch.Tensor],global_tile_idxs: List[int],parallel_group: torch.distributed.ProcessGroup = None) -> List[torch.Tensor]源码简介
gather_frames — Gathers frame data from all ranks in a distributed environment.
源码 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.
参数
framesList[torch.Tensor]global_tile_idxsList[int]parallel_grouptorch.distributed.ProcessGroup默认值 None返回值
简介
index_undot — Converts a single index into a list of indices, representing the position in a multi-dimensional space.
源码 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.
参数
indexintloop_sizeList[int]返回值
简介
index_dot — Converts a list of indices into a single index, representing the position in a multi-dimensional space.
源码 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.
参数
indexList[int]loop_sizeList[int]返回值
def parse_uri_scheme(uri: str | os.PathLike[str]) -> strparse_uri_scheme — Return the lowercase URI scheme, using `file for local paths. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：str`。
参数
uristr | os.PathLike[str]返回值
def probe_rtx_vfx_runtime(device: int = 0,config: RTXVideoSuperResolutionConfig | None = None,input_spec: VideoSpec | None = None,run_inference: bool = True) -> RTXVFXCapabilityprobe_rtx_vfx_runtime — Load the native effect and optionally process one representative frame. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：RTXVFXCapability。
参数
deviceint默认值 0run_inferencebool默认值 Truedef project_root(start: str | Path | None = None) -> Path简介
project_root — Walks upward from a starting path to locate the root repository containing pyproject.toml. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：Path。
源码 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.
参数
startstr | Path | None默认值 NoneNone` starts from this module's installed source path.返回值
pyproject.toml`, or the package-relative fallback when no repository marker is found.def read_binary_uri(uri: str | os.PathLike[str],**storage_options) -> bytes通过 Core 存储辅助，从 URI 读取全部字节。
参数
uristr | os.PathLike[str]storage_options返回值
def read_image_as_video_tensor(image_path: str | Path,resolution: Iterable[int],num_video_frames: int,resize: bool = True)read_image_as_video_tensor — Load an image and materialize a `[1,C,T,H,W]` uint8 conditioning video tensor. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
参数
image_pathstr | PathresolutionIterable[int]num_video_framesintresizebool默认值 Truedef read_text_uri(uri: str | os.PathLike[str],encoding: str = 'utf-8',**storage_options) -> str通过 Core 存储辅助，从 URI 读取全部文本。
参数
uristr | os.PathLike[str]encodingstr默认值 'utf-8'storage_options返回值
def read_video(video_path: str | Path,return_metadata: bool = True)read_video — Decode a video into frames and optional metadata. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
参数
video_pathstr | Pathreturn_metadatabool默认值 Truedef read_video_window_rgb(video_path: str | Path,start_frame: int = 0,frame_count: int)简介
read_video_window_rgb — Decode up to `frame_count` RGB frames without decoding the tail. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
源码 docstring
Decode up to `frame_count` RGB frames without decoding the tail.
Frame offsets are decoded sequentially from the beginning, preserving PyAV/torchvision frame ordering and RGB conversion, including variable frame-rate inputs. A window that reaches EOF returns its available frames; an empty window raises `ValueError`. The decoder and any temporary local copy of a remote input are closed even when decoding fails.
参数
video_pathstr | Pathstart_frameint默认值 0frame_countintdef require_rtx_vfx_runtime(device: int = 0,config: RTXVideoSuperResolutionConfig | None = None,input_spec: VideoSpec | None = None,run_inference: bool = True) -> RTXVFXCapabilityrequire_rtx_vfx_runtime — Fully probe the selected RTX runtime and fail with an actionable message. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：RTXVFXCapability。
参数
deviceint默认值 0run_inferencebool默认值 Truedef resize_video_tensor_to_resolution(video_tensor,resolution: Iterable[int])resize_video_tensor_to_resolution — Resize and center-crop a `[T,C,H,W] tensor to (target_h, target_w)`. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
参数
video_tensorresolutionIterable[int]def resolve_data_path(parts: str | Path) -> Pathresolve_data_path — Resolves a subpath under the internal worldfoundry/data asset directory. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：Path。
参数
partsstr | Path返回值
def resolve_hf_path(path: str | PathLike[str] | None) -> str | Any简介
resolve_hf_path — Resolve a possibly `hf://-prefixed path to a local filesystem path. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：str | Any`。
源码 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>]` — reuses an already materialized WorldFoundry-local snapshot, otherwise downloads only the requested subtree through the configured Hugging Face endpoint.
Set `HF_HUB_OFFLINE=1` when runtime I/O must remain strictly offline.
参数
pathstr | PathLike[str] | None返回值
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) -> Pathresolve_hf_snapshot_path — Resolve a repo id, HF cache repo root, or local path to a usable snapshot. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：Path。
参数
valuestr | os.PathLike[str]required_filesSequence[str]默认值 ()local_files_only_envstr默认值 'WORLDFOUNDRY_HF_LOCAL_FILES_ONLY'local_files_onlybool | None默认值 None返回值
def resolve_local_checkpoint_file(model_id_or_path: str | Path,filename: str,env: Mapping[str, str] | None = None) -> Path简介
resolve_local_checkpoint_file — Resolve one checkpoint file from explicit or WorldFoundry-local storage. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：Path。
源码 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.
参数
model_id_or_pathstr | PathfilenamestrenvMapping[str, str] | None默认值 None返回值
def resolve_local_hf_model_path(model_id_or_path: str | Path,required_files: Sequence[str] = (),revision: str | None = None,env: Mapping[str, str] | None = None) -> Path简介
resolve_local_hf_model_path — Resolve a Hugging Face model strictly from WorldFoundry-local storage. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：Path。
源码 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.
参数
model_id_or_pathstr | Pathrequired_filesSequence[str]默认值 ()revisionstr | None默认值 NoneenvMapping[str, str] | None默认值 None返回值
def resolve_worldfoundry_path(value: str | Path,env: Mapping[str, str] | None = None) -> Path简介
resolve_worldfoundry_path — Expands structural WorldFoundry path tokens (e.g. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：Path。
源码 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.
参数
valuestr | Path$NAME or ${NAME}` tokens.envMapping[str, str] | None默认值 None返回值
Path`. The target is not created or required to exist.def rtx_postprocessor_from_preset(preset: str,scale: float | None = None,output_width: int | None = None,output_height: int | None = None,quality: RTXVideoSuperResolutionQuality | None = None,device: int | None = None,non_blocking: bool | None = None,use_current_stream: bool | None = None) -> RTXVideoSuperResolutionPostProcessor简介
rtx_postprocessor_from_preset — Resolve a stable named preset, then apply explicit operator overrides. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：RTXVideoSuperResolutionPostProcessor。
参数
presetstrscalefloat | None默认值 Noneoutput_widthint | None默认值 Noneoutput_heightint | None默认值 NonequalityRTXVideoSuperResolutionQuality | None默认值 Nonedeviceint | None默认值 Nonenon_blockingbool | None默认值 Noneuse_current_streambool | None默认值 Noneclass RTXVFXCapability(available: bool,device: int,reason: str,package_version: str | None = None,gpu_name: str | None = None,compute_capability: tuple[int, int] | None = None,driver_library: str | None = None,probe_status: RTXVFXProbeStatus = 'not-run',backend_error: str | None = None)RTXVFXCapability — Read-only diagnosis for the optional proprietary runtime. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
属性
availablebooldeviceintreasonstrpackage_versionstr | None默认值 Nonegpu_namestr | None默认值 Nonecompute_capabilitytuple[int, int] | None默认值 Nonedriver_librarystr | None默认值 Noneprobe_statusRTXVFXProbeStatus默认值 'not-run'backend_errorstr | None默认值 None方法
to_payload — JSON-safe diagnosis; `compute_capability` is a list so manifests need no encoder.
返回值
class RTXVideoSuperResolutionConfig(scale: float = 2.0,output_width: int | None = None,output_height: int | None = None,quality: RTXVideoSuperResolutionQuality = 'HIGH',device: int = 0,clamp_input: bool = True,non_blocking: bool = False,use_current_stream: bool = True,float_range: RTXVideoFloatRange = 'minus-one-one')简介
RTXVideoSuperResolutionConfig — Configuration for one RTX VSR processor factory. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
源码 docstring
Configuration for one RTX VSR processor factory.
Floating-point input is interpreted using `float_range and emitted in the same range and dtype. uint8 input is interpreted and emitted as display-ready RGB in [0, 255]`.
属性
scalefloat默认值 2.0output_widthint | None默认值 Noneoutput_heightint | None默认值 NonequalityRTXVideoSuperResolutionQuality默认值 'HIGH'deviceint默认值 0clamp_inputbool默认值 Truenon_blockingbool默认值 Falseuse_current_streambool默认值 Truefloat_rangeRTXVideoFloatRange默认值 'minus-one-one'方法
output_spec — Return the layout-independent stream specification emitted by VSR.
参数
input_specVideoSpec返回值
简介
output_dimensions — Resolve explicit size or `scale`; same-resolution qualities cannot resize.
源码 docstring
Resolve explicit size or `scale`; same-resolution qualities cannot resize.
Standard / high-bitrate modes refuse downscale and cap at 4x so a mis-set Studio override cannot ask VFX for an unsupported geometry.
参数
input_specVideoSpec返回值
class RTXVideoSuperResolutionPostProcessor(config: RTXVideoSuperResolutionConfig | None = None,**overrides: Any)RTXVideoSuperResolutionPostProcessor — Preserve WorldFoundry video contracts while applying NVIDIA RTX VSR. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
参数
overridesAny方法
name — Stable chain id; presets share this name so telemetry stays one series.
参数
self返回值
processing_device — Use the configured VFX device instead of the caller's current GPU.
参数
self返回值
output_spec — Delegate geometry to the config so the chain can size the sink first.
参数
input_specVideoSpec返回值
start — Open a session; the native effect is created later in `prepare`.
参数
specVideoSpecdef save_frames(frames,save_path)save_frames — Write a sequence of PIL frames to numbered PNG files. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
参数
framessave_pathdef 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 | None简介
save_image_or_video_tensor — Save a normalized `[C,T,H,W] or [B,C,T,H,W] tensor as image/video. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：str | None`。
源码 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.
参数
tensorsave_pathfpsint默认值 24qualityint | None默认值 Noneffmpeg_paramslist[str] | None默认值 Nonevalue_rangestr | tuple[float, float]默认值 'auto'image_formatstr默认值 'JPEG'video_formatstr默认值 'mp4'kwargs返回值
def save_video(frames,save_path,fps,quality = 9,ffmpeg_params = None)save_video — Write a sequence of PIL frames to a video file. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
参数
framessave_pathfpsquality默认值 9ffmpeg_params默认值 Nonedef save_video_frames(video_frames,output_path: str | Path,fps: int = 16,**kwargs) -> Nonesave_video_frames — Write a THWC uint8 frame array/list to a video path or URI. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：None。
参数
video_framesoutput_pathstr | Pathfpsint默认值 16kwargs返回值
def save_video_with_audio(frames,save_path,audio_path,fps = 16,quality = 9,ffmpeg_params = None)save_video_with_audio — Write PIL frames, then mux an external audio track with ffmpeg. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
参数
framessave_pathaudio_pathfps默认值 16quality默认值 9ffmpeg_params默认值 None说明
`merge_video_audio raises on ffmpeg failures after removing its temporary file, so an exception here means save_path` still holds the silent video.
def search_for_images(folder)简介
search_for_images — Return naturally sorted JPG/PNG paths from one image-sequence folder. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
源码 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.
参数
folderclass 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)简介
TileProcessor — Encode or decode large videos through overlapping spatiotemporal tiles. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
源码 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.
参数
encode_fndecode_fntile_sample_min_heightint默认值 256tile_sample_min_widthint默认值 256tile_sample_min_lengthint默认值 16spatial_downsample_factorint默认值 8temporal_downsample_factorint默认值 1spatial_tile_overlap_factorfloat默认值 0.25temporal_tile_overlap_factorfloat默认值 0sr_ratio默认值 1first_frame_as_imagebool默认值 Falseparallel_grouptorch.distributed.ProcessGroup默认值 None方法
blend_t — Linear-ramp overlap along time so adjacent temporal tiles do not seam.
参数
atorch.Tensorbtorch.Tensorblend_extentint返回值
blend_v — Linear-ramp overlap along height (vertical tile seams).
参数
atorch.Tensorbtorch.Tensorblend_extentint返回值
blend_h — Linear-ramp overlap along width (horizontal tile seams).
参数
atorch.Tensorbtorch.Tensorblend_extentint返回值
tiled_encode — Encode *x* tile-by-tile and blend overlaps in latent space.
参数
xtorch.FloatTensorverbosebool默认值 Falsetiled_decode — Decode latent tiles and blend overlaps in pixel space.
参数
ztorch.FloatTensorverbosebool默认值 Falsedef video_tensor_to_uint8_frames(video_tensor,value_range: str | tuple[float, float] = 'auto',max_frames: int | None = None,from_end: bool = False) -> 'object'简介
video_tensor_to_uint8_frames — Convert a normalized torch video tensor to uint8 THWC frames. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：'object'。
源码 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]`.
参数
video_tensorvalue_rangestr | tuple[float, float]默认值 'auto'max_framesint | None默认值 Nonefrom_endbool默认值 False返回值
class VideoChunk(frames: Any,layout: VideoTensorLayout = 'frame-list',metadata: dict[str, Any] = <dict factory>)VideoChunk — One segment exchanged between a generator, processors, and a sink. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
属性
framesAnylayoutVideoTensorLayout默认值 'frame-list'metadatadict[str, Any]默认值 <dict factory>方法
frame_count — Count frames from the declared layout; empty chunks are valid (buffering).
参数
self返回值
class VideoData(video_file = None,image_folder = None,height = None,width = None,**kwargs)VideoData — Lazy video or image-folder dataset with optional resize. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
参数
video_file默认值 Noneimage_folder默认值 Noneheight默认值 Nonewidth默认值 Nonekwargs方法
raw_data — Materialize every frame (defeats laziness; used by small debug clips).
set_length — Cap or override reported length without truncating the underlying reader.
参数
lengthset_shape — Set the optional crop-resize target; `None` keeps native size.
参数
heightwidthshape — Return `(H, W)`; probes frame 0 when no explicit size was set.
save_images — Dump every frame as `{i}.png` (0-based) under *folder*.
参数
folderclass VideoPostprocessChain(processors: tuple[VideoPostProcessor, ...] = ())VideoPostprocessChain — Ordered processor factories applied to each generated video stream. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
属性
方法
names — Ordered processor ids for telemetry; empty when the chain is a no-op.
参数
self返回值
output_spec — Compose declared specs left-to-right so the sink can size buffers first.
参数
input_specVideoSpec返回值
start — Open one session per factory, feeding each the previous output spec.
参数
input_specVideoSpecclass VideoPostProcessor()VideoPostProcessor — Factory for per-stream processor sessions. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
方法
name — Stable telemetry id; subclasses override when the class name is not the preset.
参数
self返回值
processing_device — Declare an explicit GPU device for optional stream profiling.
参数
self返回值
output_spec — Declare the spec this processor emits; default is identity (no resize).
参数
input_specVideoSpec返回值
start — Create isolated state for a new output stream.
参数
specVideoSpecclass VideoPostProcessorSession()VideoPostProcessorSession — State owned by one logical output stream. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
方法
process — Consume one chunk and return zero or more ordered output chunks.
参数
chunkVideoChunk返回值
flush — Emit buffered tail frames and transition to a closed state.
返回值
class VideoPostprocessStepStats(elapsed_ms: float,input_frames: int,output_frames: int,buffering: bool,gpu_elapsed_ms: float | None = None)VideoPostprocessStepStats — Host dispatch, optional CUDA stream time, and frame-count telemetry. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
属性
elapsed_msfloatinput_framesintoutput_framesintbufferingboolgpu_elapsed_msfloat | None默认值 None方法
to_payload — JSON-safe receipt; `buffering` is True when the stage emitted no frames.
返回值
class VideoPostprocessStream(chain: VideoPostprocessChain | None = None,fps: float | None = None,profile_cuda: bool = False)VideoPostprocessStream — Own one stateful processor chain across autoregressive chunks. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
参数
方法
processor_names — Chain ids for Studio overlays; empty when the default identity chain is used.
参数
self返回值
chunk_index — Number of `process calls completed; used as autoregressive_index`.
参数
self返回值
process(frames: Any,layout: VideoTensorLayout,metadata: dict[str, Any] | None = None) -> list[VideoChunk]源码简介
process — Run one AR chunk; the first call freezes the input spec for the stream.
源码 docstring
Run one AR chunk; the first call freezes the input spec for the stream.
A later chunk whose inferred spec differs is rejected so a processor cannot silently resize mid-stream. `finish is terminal until :meth:reset`.
参数
framesAnylayoutVideoTensorLayoutmetadatadict[str, Any] | None默认值 None返回值
finish — Flush buffered tails once; later calls return an empty list.
返回值
reset — Discard buffered output, release state, and accept a fresh stream.
返回值
class VideoSpec(height: int,width: int,fps: float | None = None,channels: int = 3,dtype: str | None = None)VideoSpec — Static dimensions and cadence for one processor stream. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。
属性
heightintwidthintfpsfloat | None默认值 Nonechannelsint默认值 3dtypestr | None默认值 Nonedef worldfoundry_path_tokens(env: Mapping[str, str] | None = None) -> dict[str, str]简介
worldfoundry_path_tokens — Generates the dictionary of logical path-token replacements used across the system. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：dict[str, str]。
源码 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.
参数
envMapping[str, str] | None默认值 Noneos.environ`. Passing a mapping makes resolution deterministic in tests.返回值
def write_binary_uri(uri: str | os.PathLike[str],data: bytes | bytearray | memoryview | io.BytesIO,**storage_options) -> Nonewrite_binary_uri — Write bytes to a URI, creating local parent directories as needed. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：None。
参数
uristr | os.PathLike[str]databytes | bytearray | memoryview | io.BytesIOstorage_options返回值
def write_text_uri(uri: str | os.PathLike[str],data: str,encoding: str = 'utf-8',**storage_options) -> Nonewrite_text_uri — Write text to a URI, creating local parent directories as needed. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：None。
参数
uristr | os.PathLike[str]datastrencodingstr默认值 'utf-8'storage_options返回值
def write_video(video_frames,output_path: str | Path,fps: int = 16,quality: int | None = None,format: str | None = None,**kwargs) -> None简介
write_video — Write a THWC video array/list to a local path or remote URI. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：None。
源码 docstring
Write a THWC video array/list to a local path or remote URI.
The ordinary local MP4 path streams RGB bytes straight to FFmpeg. This avoids importing and initializing ImageIO's plugin after inference while retaining its effective default x264 CRF (23). Custom ImageIO options, explicit quality settings, non-MP4 containers, and remote targets keep the general ImageIO path.
参数
video_framesoutput_pathstr | Pathfpsint默认值 16qualityint | None默认值 Noneformatstr | None默认值 Nonekwargs返回值
def write_video_torchvision(filename: str | Path,video_array: Any,fps: float,*args: Any,**kwargs: Any) -> Nonewrite_video_torchvision — Write RGB video frames with a `torchvision.io.write_video-compatible signature. 属于 Core I/O 与媒体（路径、URI、图像、视频、序列化）。 标注返回类型：None`。
参数
filenamestr | Pathvideo_arrayAnyfpsfloatargsAnykwargsAny