eclise 0.1.0__py3-none-any.whl

eclise/clips/__init__.py

@@ -0,0 +1,97 @@
+"""A shared on-disk contract for video clips with per-frame state labels.
+
+Sits between anything that *produces* clips (a simulator, a download of a
+published dataset, eventually a real-video ingest) and anything that *consumes*
+them (a training project). Producers and consumers live in separate conda envs
+and never import each other; they agree on this package instead.
+
+    from eclise.clips import ClipDataset
+
+    data = ClipDataset("data/phyworld/data/collision_30K")
+    item = data[0]
+    item["pixels"]    # [3, T, H, W] float32 in [-1, 1]
+    item["positions"] # [T, n_objects, 2] world units, y up
+    item["velocity"]  # [2] px/frame, y down (image convention)
+    data.source_fps   # 1 / frame_dt -- authoritative, not the mp4 header
+
+Upstream phyworld's published HDF5 carries no metadata, so it needs its family
+named:
+
+    from eclise.clips.readers import phyworld_hdf5
+
+    shards = phyworld_hdf5.open_shard_set("collision_30K.hdf5", family="collision")
+    data = ClipDataset(shards, velocity_object=0)
+
+Writing is the mirror image: declare a
+:class:`~eclise.clips.schema.ShardMeta`, then append clips.
+
+    from eclise.clips import ShardMeta, ShardWriter, position_spec
+
+    meta = ShardMeta(
+        family="uniform_motion", num_clips=0, clip_len=32,
+        image_size=(256, 256), frame_dt=0.1, world_scale=10.0,
+        labels={"positions": position_spec()},
+    )
+    with ShardWriter("shard_000.hdf5", meta) as w:
+        w.append(frames, positions=positions)
+
+Torch is needed only for :class:`~eclise.clips.dataset.ClipDataset`; the schema,
+shard, and reader layers are pure numpy.
+"""
+
+from __future__ import annotations
+
+from .codec import decode_mp4, encode_mp4
+from .labels import (
+    collision_frame,
+    positions_to_pixels,
+    velocities_per_frame,
+    velocity_from_state,
+)
+from .schema import (
+    LABEL_GROUP,
+    META_ATTR,
+    SCHEMA_VERSION,
+    VIDEO_DATASET,
+    LabelSpec,
+    SchemaError,
+    ShardMeta,
+    object_attrs_spec,
+    params_spec,
+    position_spec,
+    velocity_field_spec,
+)
+from .shards import ShardReader, ShardSet, ShardWriter, write_shard
+
+__all__ = [
+    "LABEL_GROUP",
+    "META_ATTR",
+    "SCHEMA_VERSION",
+    "VIDEO_DATASET",
+    "LabelSpec",
+    "SchemaError",
+    "ShardMeta",
+    "ShardReader",
+    "ShardSet",
+    "ShardWriter",
+    "collision_frame",
+    "decode_mp4",
+    "encode_mp4",
+    "object_attrs_spec",
+    "params_spec",
+    "position_spec",
+    "positions_to_pixels",
+    "velocities_per_frame",
+    "velocity_field_spec",
+    "velocity_from_state",
+    "write_shard",
+]
+
+
+def __getattr__(name: str):
+    """Expose :class:`~eclise.clips.dataset.ClipDataset` without importing torch eagerly."""
+    if name in ("ClipDataset", "iter_clip_batches", "PIXEL_RANGES"):
+        from . import dataset
+
+        return getattr(dataset, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

eclise/clips/codec.py

@@ -0,0 +1,85 @@
+"""In-memory mp4 encode/decode for clip bytestreams.
+
+Upstream phyworld carries a copy of this logic in every generator script (four
+copies of ``convert_frames_to_mp4_bytestream_wo_disk``, plus disk-roundtripping
+variants that were left behind after the in-memory version replaced them). This
+is the one home for it.
+
+Encoding is lossy. H.264 on synthetic content -- flat backgrounds with a few
+hard-edged coloured circles -- is close to visually lossless at sane bitrates,
+but "close" is not "exact", and every consumer of a decoded clip is looking at
+compression artifacts. That is a property of the storage format we inherit, not
+something this module can fix; it is why
+``data/phyworld/scripts/verify_shards.py`` measures state recovery *after* a
+decode round-trip rather than trusting the pre-encode frames.
+"""
+
+from __future__ import annotations
+
+from io import BytesIO
+
+import numpy as np
+
+#: Encoder quality knob. imageio/ffmpeg's default CRF is 23, visibly soft on
+#: hard synthetic edges; 18 is near-transparent for this content at a modest
+#: size increase. Applies only to clips this package writes.
+DEFAULT_CRF = 18
+
+
+def encode_mp4(frames: np.ndarray, *, crf: int = DEFAULT_CRF, fps: float = 24.0) -> np.ndarray:
+    """Encode ``[T, H, W, 3]`` uint8 frames to an mp4 bytestream as ``[n] uint8``.
+
+    ``fps`` lands in the container header only. It is *not* the physics frame
+    rate -- that is :attr:`eclise.clips.schema.ShardMeta.frame_dt`, recorded
+    separately. A value is passed anyway so the header is at least a valid,
+    deliberate number rather than an encoder default (upstream passes nothing,
+    which is how its stored clips ended up with a meaningless rate).
+
+    H.264 requires even frame dimensions; odd ones are rejected here rather than
+    silently rescaled, since a resized clip would invalidate every pixel-unit
+    label in the shard.
+    """
+    import imageio.v3 as iio
+
+    arr = np.asarray(frames)
+    if arr.ndim != 4 or arr.shape[-1] != 3:
+        raise ValueError(f"expected frames [T, H, W, 3], got {arr.shape}")
+    if arr.dtype != np.uint8:
+        raise ValueError(f"expected uint8 frames, got {arr.dtype}")
+    h, w = arr.shape[1:3]
+    if h % 2 or w % 2:
+        raise ValueError(
+            f"H.264 needs even frame dimensions; got {h}x{w}. Render at an even "
+            "size rather than resizing here, which would invalidate pixel labels."
+        )
+    with BytesIO() as buffer:
+        iio.imwrite(
+            buffer,
+            arr,
+            extension=".mp4",
+            fps=fps,
+            codec="libx264",
+            # The pixel format goes through imageio's own keyword, not
+            # output_params: the ffmpeg plugin always emits a -pix_fmt of its own,
+            # so passing a second one makes ffmpeg warn once per encoded clip --
+            # millions of stderr lines on a full generation run, for a flag that
+            # was already set to the same value.
+            pixelformat="yuv420p",
+            output_params=["-crf", str(crf)],
+        )
+        payload = buffer.getvalue()
+    return np.frombuffer(payload, dtype=np.uint8)
+
+
+def decode_mp4(stream: np.ndarray | bytes) -> np.ndarray:
+    """Decode an mp4 bytestream to ``[T, H, W, 3]`` uint8 frames."""
+    import imageio.v3 as iio
+
+    payload = stream.tobytes() if isinstance(stream, np.ndarray) else stream
+    frames = iio.imread(payload, index=None, extension=".mp4")
+    arr = np.asarray(frames)
+    if arr.ndim == 3:  # a single-frame clip decodes without the leading axis
+        arr = arr[None]
+    if arr.shape[-1] == 4:  # some decoders hand back RGBA
+        arr = arr[..., :3]
+    return arr

eclise/clips/dataset.py

@@ -0,0 +1,237 @@
+"""Torch ``Dataset`` over clip shards.
+
+This is the consumer-facing end of the contract. A training project points
+:class:`ClipDataset` at a directory of shards -- generated by a sim, downloaded
+from upstream, or (later) holding real video -- and gets pixel clips plus labels,
+without knowing which.
+
+``torch`` is imported lazily: :mod:`eclise.clips.schema`, :mod:`.shards`, and
+:mod:`.readers` are pure numpy so a generator-side env need not install torch at
+all, while consumers bring their own pinned version.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from .labels import velocity_from_state
+from .schema import SchemaError, ShardMeta
+from .shards import ShardSet
+
+#: How decoded uint8 pixels are mapped to floats.
+#:
+#: - ``"tanh"``: ``[-1, 1]``. The default, because it is what latent video
+#:   encoders (Wan VAE and friends) consume, and what
+#:   ``video_world_models``' own procedural stimuli already produce.
+#: - ``"unit"``: ``[0, 1]``.
+#: - ``"uint8"``: untouched ``0..255``, dtype preserved.
+PIXEL_RANGES = ("tanh", "unit", "uint8")
+
+
+def _to_pixels(frames: np.ndarray, pixel_range: str) -> Any:
+    import torch
+
+    if pixel_range not in PIXEL_RANGES:
+        raise ValueError(
+            f"pixel_range must be one of {PIXEL_RANGES}; got {pixel_range!r}"
+        )
+    arr = np.ascontiguousarray(frames)
+    tensor = torch.from_numpy(arr)  # [T, H, W, 3] uint8
+    tensor = tensor.permute(3, 0, 1, 2)  # -> [3, T, H, W]
+    if pixel_range == "uint8":
+        return tensor.contiguous()
+    tensor = tensor.to(torch.float32) / 255.0
+    if pixel_range == "tanh":
+        tensor = tensor * 2.0 - 1.0
+    return tensor.contiguous()
+
+
+class ClipDataset:
+    """Clips from one or more shards, as ``[3, T, H, W]`` tensors plus labels.
+
+    Each item is a dict:
+
+    - ``"pixels"``: ``[3, T, H, W]``, float32 in the configured range (or uint8).
+    - ``"index"``: global clip index, so a batched metric can be bucketed by any
+      per-clip property after the fact. Labels that are strings or ragged cannot
+      survive the default collate; an index always can.
+    - ``"velocity"``: ``[2]`` ``(vx, vy)`` px/frame, present when the shard has
+      positions and the family has one object (see ``velocity_object``).
+    - one entry per stored label, e.g. ``"positions"`` ``[T, n_obj, 2]``,
+      ``"params"`` ``[K]``.
+
+    ``meta`` (family, ``frame_dt``, ``world_scale``, ...) is a dataset-level
+    attribute, not per item -- it is identical for every clip, and putting it in
+    the item would multiply it by the batch size through the collate.
+
+    Args:
+        source: a shard directory, a single shard file, a list of files, or an
+            already-built :class:`~eclise.clips.shards.ShardSet`.
+        pixel_range: see :data:`PIXEL_RANGES`.
+        labels: which stored labels to include; ``None`` includes all.
+        velocity: emit a ``"velocity"`` entry derived from positions when that
+            label exists. Shards without positions (real video) omit it rather
+            than erroring, so a consumer can point ``ClipDataset`` at either
+            family without a flag.
+        velocity_object: which object's velocity to use for multi-object
+            families. Required there, since a mean over a head-on collision is
+            ~0 (see :func:`eclise.clips.labels.velocity_from_state`).
+        opener: reader class for non-canonical shards, e.g.
+            ``functools.partial(phyworld_hdf5.open_shard, family="collision")``.
+    """
+
+    def __init__(
+        self,
+        source: str | Path | Sequence[str | Path] | ShardSet,
+        *,
+        pixel_range: str = "tanh",
+        labels: Sequence[str] | None = None,
+        velocity: bool = True,
+        velocity_object: int | None = None,
+        opener: Any = None,
+    ) -> None:
+        if pixel_range not in PIXEL_RANGES:
+            raise ValueError(
+                f"pixel_range must be one of {PIXEL_RANGES}; got {pixel_range!r}"
+            )
+        self.shards = _resolve_source(source, opener=opener)
+        self.pixel_range = pixel_range
+        self.meta: ShardMeta = self.shards.meta
+
+        available = set(self.shards.label_names())
+        if labels is None:
+            self.labels = tuple(sorted(available))
+        else:
+            missing = set(labels) - available
+            if missing:
+                raise SchemaError(
+                    f"requested labels {sorted(missing)} are not in these shards; "
+                    f"available: {sorted(available)}"
+                )
+            self.labels = tuple(labels)
+
+        self._velocity_object = velocity_object
+        # Real-video shards (OpenVid ingest) have no positions. ``velocity=True``
+        # then simply omits the derived entry rather than requiring every caller
+        # to pass velocity=False -- ``open_clip_dataset`` in video_world_models
+        # stays unchanged. Multi-object families that *do* record positions
+        # still require ``velocity_object`` below, because averaging is ambiguous.
+        self.emits_velocity = bool(velocity and "positions" in available)
+        if self.emits_velocity:
+            num_objects = int(self.meta.extra.get("num_objects", 1) or 1)
+            if num_objects > 1 and velocity_object is None:
+                raise SchemaError(
+                    f"family {self.meta.family!r} has {num_objects} objects, so a "
+                    "single per-clip velocity is ambiguous. Pass velocity_object=, "
+                    "or velocity=False and derive from the 'positions' label."
+                )
+
+    @property
+    def source_fps(self) -> float:
+        """``1 / frame_dt``, for a latent encoder's FPS-aware path."""
+        return self.meta.source_fps
+
+    def manifest_key(self, *, length: int = 16) -> str:
+        """Stable hash of the underlying shard set, for addressing derived caches."""
+        return self.shards.manifest_key(length=length)
+
+    def manifest(self) -> dict[str, Any]:
+        return self.shards.manifest()
+
+    def __len__(self) -> int:
+        return len(self.shards)
+
+    def __getitem__(self, index: int) -> dict[str, Any]:
+        import torch
+
+        item: dict[str, Any] = {
+            "pixels": _to_pixels(self.shards.frames(index), self.pixel_range),
+            "index": index,
+        }
+        for name in self.labels:
+            value = np.asarray(self.shards.label(name, index))
+            item[name] = torch.from_numpy(np.ascontiguousarray(value)).to(torch.float32)
+        if self.emits_velocity:
+            positions = np.asarray(self.shards.label("positions", index))
+            item["velocity"] = torch.from_numpy(
+                velocity_from_state(
+                    positions,
+                    self.shards.spec("positions"),
+                    image_size=self.meta.image_size,
+                    world_scale=self.meta.world_scale,
+                    object_index=self._velocity_object,
+                )
+            )
+        return item
+
+    def close(self) -> None:
+        self.shards.close()
+
+    def __enter__(self) -> ClipDataset:
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return (
+            f"ClipDataset(family={self.meta.family!r}, split={self.meta.split!r}, "
+            f"clips={len(self)}, clip_len={self.meta.clip_len}, "
+            f"image_size={self.meta.image_size}, frame_dt={self.meta.frame_dt}, "
+            f"pixel_range={self.pixel_range!r})"
+        )
+
+
+def _resolve_source(
+    source: str | Path | Sequence[str | Path] | ShardSet, *, opener: Any
+) -> ShardSet:
+    if isinstance(source, ShardSet):
+        return source
+    if isinstance(source, (str, Path)):
+        path = Path(source)
+        if path.is_dir():
+            return ShardSet.from_dir(path, opener=opener)
+        return ShardSet([path], opener=opener)
+    return ShardSet(list(source), opener=opener)
+
+
+def iter_clip_batches(
+    dataset: ClipDataset,
+    *,
+    batch_size: int = 8,
+    velocity_fallback: bool = True,
+) -> Any:
+    """Yield ``(clips [B, 3, T, H, W], velocities [B, 2])`` batches.
+
+    The shape a frozen latent encoder wants. Kept here rather than in the
+    consumer so that "render a clip grid" and "read clips off disk" present the
+    same interface to an encode loop.
+
+    With ``velocity_fallback`` and no velocity available, zeros are emitted --
+    appropriate when velocity is only a diagnostic label, not a training target.
+    """
+    import torch
+
+    clips: list[Any] = []
+    vels: list[Any] = []
+    for index in range(len(dataset)):
+        item = dataset[index]
+        clips.append(item["pixels"])
+        if "velocity" in item:
+            vels.append(item["velocity"])
+        elif velocity_fallback:
+            vels.append(torch.zeros(2, dtype=torch.float32))
+        else:
+            raise SchemaError(
+                "dataset emits no velocity; pass velocity_fallback=True to get "
+                "zeros, or construct the ClipDataset with velocity=True"
+            )
+        if len(clips) == batch_size:
+            yield torch.stack(clips), torch.stack(vels)
+            clips, vels = [], []
+    if clips:
+        yield torch.stack(clips), torch.stack(vels)

eclise/clips/labels.py

@@ -0,0 +1,198 @@
+"""Deriving training targets from stored state labels.
+
+Stored labels describe the *simulation*: object centres in world units, on a
+y-up axis. Training code wants quantities in *pixel* terms on the image's y-down
+axis. The conversion is three multiplications and a sign flip, and getting any
+of them wrong produces plausible-looking numbers that are quietly rescaled or
+mirrored -- so it lives here once, driven off the
+:class:`~eclise.clips.schema.LabelSpec` rather than off a caller's assumption.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .schema import LabelSpec, SchemaError
+
+
+def positions_to_pixels(
+    positions: np.ndarray,
+    spec: LabelSpec,
+    *,
+    image_size: tuple[int, int],
+    world_scale: float | None,
+) -> np.ndarray:
+    """Convert stored positions to pixel coordinates with rows increasing downward.
+
+    Args:
+        positions: ``[..., 2]`` in the units ``spec`` declares.
+        spec: the label's spec; supplies ``units`` and ``y_axis_up``.
+        image_size: ``(height, width)`` of the rendered frames.
+        world_scale: world extent, required when ``spec.units == "world"``.
+
+    Returns:
+        The same shape, in pixels, y measured downward from the top row.
+    """
+    arr = np.asarray(positions, dtype=np.float64)
+    if arr.shape[-1] != 2:
+        raise SchemaError(f"expected a trailing xy axis, got shape {arr.shape}")
+    height, width = image_size
+
+    if spec.units == "world":
+        if not world_scale:
+            raise SchemaError(
+                f"label {spec.name!r} is in world units, so world_scale is "
+                "required to convert to pixels"
+            )
+        scale = np.array([width / world_scale, height / world_scale])
+    elif spec.units == "normalized":
+        scale = np.array([float(width), float(height)])
+    elif spec.units == "pixel":
+        scale = np.array([1.0, 1.0])
+    else:
+        raise SchemaError(
+            f"label {spec.name!r} has units {spec.units!r}, which has no defined "
+            "mapping to pixels; expected 'world', 'normalized', or 'pixel'"
+        )
+
+    out = arr * scale
+    if spec.y_axis_up:
+        # Rows increase downward, so a y measured upward from the bottom becomes
+        # (height - y). Rendering reverses the row axis after drawing, which is
+        # what puts the stored coordinates on the opposite convention.
+        out[..., 1] = height - out[..., 1]
+    return out
+
+
+def velocity_from_state(
+    positions: np.ndarray,
+    spec: LabelSpec,
+    *,
+    image_size: tuple[int, int],
+    world_scale: float | None,
+    frame_dt: float | None = None,
+    per_second: bool = False,
+    object_index: int | None = None,
+) -> np.ndarray:
+    """Mean velocity over a clip, in pixels per frame (or per second).
+
+    Args:
+        positions: ``[frame, object, 2]`` for one clip, as
+            :meth:`~eclise.clips.shards.ShardReader.label` returns.
+        spec: the positions label's spec.
+        image_size: ``(height, width)``.
+        world_scale: world extent, for ``units == "world"``.
+        frame_dt: required only when ``per_second`` is set.
+        per_second: return px/s instead of px/frame.
+        object_index: velocity of one object; ``None`` averages over objects.
+            Averaging is only meaningful for single-object families -- for a
+            head-on collision the two balls move oppositely and the mean is near
+            zero, which is why this defaults to erroring on ambiguity rather than
+            silently averaging. Pass an index for multi-object families.
+
+    Returns:
+        ``[2]`` ``(vx, vy)`` with y increasing downward, matching image rows.
+
+    The estimate is the total displacement divided by the number of steps, i.e.
+    the mean over the clip. For uniform motion that is exact. For a collision or
+    a parabola it is the *average*, not an instantaneous velocity, and is not a
+    meaningful summary; use :func:`velocities_per_frame` for those.
+    """
+    arr = np.asarray(positions, dtype=np.float64)
+    if arr.ndim == 2:  # [frame, xy] -- object axis elided
+        arr = arr[:, None, :]
+    if arr.ndim != 3:
+        raise SchemaError(
+            f"expected positions [frame, object, xy] for one clip, got {arr.shape}"
+        )
+    if arr.shape[0] < 2:
+        raise SchemaError("need at least 2 frames to estimate a velocity")
+
+    px = positions_to_pixels(
+        arr, spec, image_size=image_size, world_scale=world_scale
+    )
+    num_objects = px.shape[1]
+    if object_index is None:
+        if num_objects > 1:
+            raise SchemaError(
+                f"positions hold {num_objects} objects; a single velocity is "
+                "ambiguous (for a head-on collision the mean is ~0). Pass "
+                "object_index=, or use velocities_per_frame()."
+            )
+        object_index = 0
+
+    track = px[:, object_index, :]
+    steps = track.shape[0] - 1
+    velocity = (track[-1] - track[0]) / steps
+    if per_second:
+        if not frame_dt:
+            raise SchemaError("per_second=True requires frame_dt")
+        velocity = velocity / frame_dt
+    return velocity.astype(np.float32)
+
+
+def velocities_per_frame(
+    positions: np.ndarray,
+    spec: LabelSpec,
+    *,
+    image_size: tuple[int, int],
+    world_scale: float | None,
+    frame_dt: float | None = None,
+    per_second: bool = False,
+) -> np.ndarray:
+    """Per-step velocities, ``[frame - 1, object, 2]`` in px/frame (or px/s).
+
+    Finite differences between consecutive stored frames. This is what a
+    collision or parabola needs, where velocity changes within the clip.
+    """
+    arr = np.asarray(positions, dtype=np.float64)
+    if arr.ndim == 2:
+        arr = arr[:, None, :]
+    px = positions_to_pixels(
+        arr, spec, image_size=image_size, world_scale=world_scale
+    )
+    diffs = np.diff(px, axis=0)
+    if per_second:
+        if not frame_dt:
+            raise SchemaError("per_second=True requires frame_dt")
+        diffs = diffs / frame_dt
+    return diffs.astype(np.float32)
+
+
+def collision_frame(
+    positions: np.ndarray,
+    spec: LabelSpec,
+    *,
+    radii: np.ndarray | None = None,
+    tolerance: float = 1e-3,
+) -> int | None:
+    """Index of the first frame where two objects are in contact, if any.
+
+    Contact means centre distance <= sum of radii (plus ``tolerance``). Without
+    ``radii``, falls back to the frame of maximum approach speed change, which is
+    where a discrete elastic bounce shows up. Returns ``None`` when the objects
+    never meet -- a legitimate outcome, since the generator's rejection sampling
+    does not guarantee a collision lands inside the recorded window.
+
+    Units are whatever ``positions`` and ``radii`` share; no conversion is done,
+    so pass both in world units or both in pixels.
+    """
+    arr = np.asarray(positions, dtype=np.float64)
+    if arr.ndim != 3 or arr.shape[1] < 2:
+        raise SchemaError(
+            f"collision detection needs positions [frame, >=2 objects, xy], got "
+            f"{arr.shape}"
+        )
+    gap = np.linalg.norm(arr[:, 1, :] - arr[:, 0, :], axis=-1)
+    if radii is not None:
+        threshold = float(np.sum(np.asarray(radii, dtype=np.float64)[:2])) + tolerance
+        hits = np.flatnonzero(gap <= threshold)
+        return int(hits[0]) if hits.size else None
+    if gap.size < 3:
+        return None
+    # Approach rate flips sign at an elastic bounce; the largest jump in its
+    # derivative is the contact frame.
+    curvature = np.abs(np.diff(gap, n=2))
+    if not np.any(curvature > tolerance):
+        return None
+    return int(np.argmax(curvature)) + 1

eclise/clips/readers/__init__.py

@@ -0,0 +1,24 @@
+"""Format adapters.
+
+A reader turns some on-disk layout into the :class:`~eclise.clips.shards.ShardReader`
+interface -- ``len()``, ``frames(i)``, ``label(name, i)``, and a
+:class:`~eclise.clips.schema.ShardMeta`. Everything downstream
+(:class:`~eclise.clips.dataset.ClipDataset`, the label helpers) is written against
+that interface alone, so adding a format never touches the consumer.
+
+Canonical shards need no adapter -- :class:`~eclise.clips.shards.ShardReader`
+reads them directly. Adapters exist for layouts we do not control:
+
+- :mod:`.phyworld_hdf5` -- upstream phyworld's published HDF5 files, which carry
+  no metadata.
+
+Real video will land here too (a directory of mp4s with a sidecar manifest, or
+webdataset tars), which is what lets a training project consume generated and
+real clips through one code path.
+"""
+
+from __future__ import annotations
+
+from . import phyworld_hdf5
+
+__all__ = ["phyworld_hdf5"]