usdz_metadata – USDZ Scene-Bundle Manifest¶

USDZ scene-bundle manifest (metadata.yaml).

Every scene USDZ produced by 3dgs_io.save_scene_usdz() writes a metadata.yaml at the archive root as a stability commitment to downstream consumers. It carries at least a uuid, scene_id and version_string — the identity card downstream tools rely on to route or tag an asset.

Schema¶

Required keys (all non-empty strings):

uuid — globally unique identifier for this scene asset.
scene_id — human-readable scene identifier (typically the dataset or run name).
version_string — free-form identifier of the producing pipeline (e.g. the 3dgs_io release, or the parent pipeline’s own version).

Additional keys may be present; downstream consumers should ignore keys they don’t recognise.

Encoding¶

The file is written as JSON, which is a subset of YAML 1.2, so consumers may parse it with yaml.safe_load and get an ordinary dict:

with zipfile.ZipFile(usdz_file, "r") as zf, zf.open("metadata.yaml") as f:
    data = yaml.safe_load(f)
    uuid = data["uuid"]
    scene_id = data["scene_id"]
    version = data.get("version_string", "unknown")

Writing JSON avoids pulling PyYAML into 3dgs_io’s own dependency set while remaining a valid metadata.yaml for downstream tools.

class 3dgs_io.usdz_metadata.UsdzMetadata(uuid, scene_id, version_string, training_date=None, dataset_hash=None, is_resumable=None, sensors=None, logger=None, time_range=None, extras=<factory>)¶

Bases: object

Identity card written at the root of every USDZ scene bundle.

Parameters:

uuid (str) – Globally unique identifier for this scene asset. Non-empty string.
scene_id (str) – Human-readable scene identifier (typically the dataset or run name). Non-empty string.
version_string (str) – Free-form identifier of the producing pipeline (e.g. the 3dgs_io release, or the parent pipeline’s own version). Non-empty string.
training_date (Optional[str]) – Optional alpasim scene_metadata fields. When set (not None) they are emitted at the top level of the metadata dict, in the same slot extras uses. Structure is not validated — alpasim owns the schema. Producers that don’t care about alpasim can leave these at None; the emitted dict is unchanged in that case.
dataset_hash (Optional[str]) – Optional alpasim scene_metadata fields. When set (not None) they are emitted at the top level of the metadata dict, in the same slot extras uses. Structure is not validated — alpasim owns the schema. Producers that don’t care about alpasim can leave these at None; the emitted dict is unchanged in that case.
is_resumable (Optional[bool]) – Optional alpasim scene_metadata fields. When set (not None) they are emitted at the top level of the metadata dict, in the same slot extras uses. Structure is not validated — alpasim owns the schema. Producers that don’t care about alpasim can leave these at None; the emitted dict is unchanged in that case.
sensors (Optional[Any]) – Optional alpasim scene_metadata fields. When set (not None) they are emitted at the top level of the metadata dict, in the same slot extras uses. Structure is not validated — alpasim owns the schema. Producers that don’t care about alpasim can leave these at None; the emitted dict is unchanged in that case.
logger (Optional[str]) – Optional alpasim scene_metadata fields. When set (not None) they are emitted at the top level of the metadata dict, in the same slot extras uses. Structure is not validated — alpasim owns the schema. Producers that don’t care about alpasim can leave these at None; the emitted dict is unchanged in that case.
time_range (Optional[Any]) – Optional alpasim scene_metadata fields. When set (not None) they are emitted at the top level of the metadata dict, in the same slot extras uses. Structure is not validated — alpasim owns the schema. Producers that don’t care about alpasim can leave these at None; the emitted dict is unchanged in that case.
extras (dict[str, Any]) – Free-form additional fields written alongside the required trio and the alpasim block. Values must be JSON-serialisable (str / int / float / bool / list / dict / None). Extras must not shadow the required keys or any alpasim key that is also set on the dataclass; use the typed field instead.

to_dict()¶

Return a JSON-serialisable dictionary of all fields.

Return type:: dict[str, Any]

classmethod from_dict(data)¶

Reconstruct a UsdzMetadata from a plain dictionary.

Raises ValueError if any required key is missing.

Return type:: UsdzMetadata

3dgs_io.usdz_metadata.default_uuid()¶

Return a fresh random UUID4 string suitable for UsdzMetadata.uuid.

Return type:: str

3dgs_io.usdz_metadata.encode_usdz_metadata(metadata)¶

Serialise metadata as UTF-8 bytes for metadata.yaml.

Output is JSON, which is a subset of YAML 1.2 — yaml.safe_load on the written bytes yields the same document, so consumers relying on PyYAML are unaffected.

Return type:: bytes

3dgs_io.usdz_metadata.load_usdz_metadata(raw)¶

Parse metadata.yaml bytes back into a UsdzMetadata.

Only the JSON-flavoured output produced by encode_usdz_metadata() is understood; hand-written block-style YAML would need PyYAML, which is intentionally not a runtime dependency of this package.

Return type:: UsdzMetadata

3dgs_io.usdz_metadata.make_default_metadata(*, out_path, uuid=None, scene_id=None, version_string=None, training_date=None, dataset_hash=None, is_resumable=None, sensors=None, logger=None, time_range=None, extras=None)¶

Build a UsdzMetadata filling unset fields with sensible defaults.

Defaults are: :rtype: UsdzMetadata

uuid → a fresh random UUID4.
scene_id → the output USDZ filename stem (out_path.stem).
version_string → "3dgs_io/<installed-package-version>".

The alpasim scene_metadata fields (training_date, dataset_hash, is_resumable, sensors, logger, time_range) are passed through unchanged and are omitted from the emitted dict when left at their default None.