DreamLake
Browse docs

Adapters

Choose an adapter to expose a format as fields, readable payloads and an optional timeline. These readers belong to the existing schema API; check Dataset readers for the recommended new integration path.

Supported datasets

Data layoutadapterMain options
LeRobot v2.0, v2.1 or v3.0lerobotepisode
UMI-style Zarr ReplayBufferumi or zarrpath, episode, fps
Supported Zarr v3 feature-manifest directoryumi or zarrpath
Video and annotation sidecarsegocentricdataset profile or explicit lists
Directory of media and numeric filesfilesystemdir

Choose storage independently. A reader can use a public HuggingFace repository or your application's storage driver.

Choosing an adapter

filesystem — a folder of loose files

Lists one directory. Media fields return URLs, CSV/Parquet become numeric series, and other files remain references. The source has no timeline.

yaml
adapter: filesystem
storage: { driver: http, basePath: /viz-samples/episode_365/ }
dir: ""

dir defaults to ''. Listing uses the storage driver's capabilities; an HTTP folder needs index.json. This adapter's CSV reader handles simple comma-separated numeric files, not quoted CSV fields. It loads the text before selecting a time range or sampling rows. The richer file-preview CSV loader is a separate API.

lerobot — a manifest-indexed episode

Uses meta/info.json for camera and numeric fields. Dimension names appear in meta.dims; task annotations can become cues. Episode metadata supplies duration and frame rate.

yaml
adapter: lerobot
storage: { driver: hf, id: lerobot/aloha_static_coffee }
episode: 0

episode defaults to 0. A vector feature such as action returns named columns; a panel can select one using field: [action, left_waist].

For v3.0 datasets, this schema adapter searches episode metadata only in meta/episodes/chunk-000/file-000.parquet. Episodes indexed elsewhere are not supported by this reader.

umi / zarr — a Zarr ReplayBuffer

Reads concatenated episodes from data/<name> arrays, using meta/episode_ends for boundaries. Numeric arrays yield series; supported camera arrays yield frame sequences.

yaml
adapter: umi
storage: { driver: hf, id: omarrayyann/mv-umi }
path: bottles_rack_data.zarr.zip
episode: 0
fps: 59.94
OptionDefaultMeaning
path''Archive or directory path, or absolute URL.
episode0Episode selected from ReplayBuffer boundaries.
fps60Time-axis frame rate; a v3 feature manifest can override it.
Loading fields…
Loading fields…
Loading fields…
Loading fields…
Code UmiEpisodeSpec.tsx

Archive reads locate entries through the ZIP directory and request chunks. The server must support Range requests and browser access. Camera frames are loaded on demand, including supported JPEG-XL camera chunks. This example uses a public MV-UMI recording.

Folder mode + Zarr v3

A path ending in .zip selects archive access; other paths select a directory. The supported v3 layout uses a root zarr.json with attributes.features, fps and total_frames, with one episode per directory. The reader supports the sharded, zstd-compressed arrays used by the EgoVerse example; it is not a general reader for every Zarr codec or layout.

yaml
adapter: umi
storage: { driver: http, basePath: /viz-samples/egoverse/ }
path: egoverse_sample.zarr
Loading fields…
Loading fields…
Loading fields…
Loading fields…
Loading fields…
Code EgoVerseSpec.tsx

egocentric — media + sidecar annotations

Choose ego4d, egoexo4d or rh20t to discover a supported layout through listable storage, or supply explicit files for a custom recording.

yaml
adapter: egocentric
dataset: ego4d
storage: { driver: http, basePath: /viz-samples/ego4d/ }
Loading fields…
Loading fields…
Code EgocentricSpec.tsx

This example includes illustrative narration data. To inspect another recording, point storage at a copy you can access.

Explicit lists select the files and their meanings. Supplied lists override the corresponding profile result:

yaml
adapter: egocentric
storage: { driver: hf, id: org/my-dataset }
videos: [{ path: clips/a.mp4, label: Camera A }]
annotations: [{ path: narrations.json, format: ego4d-narration }]
series: [{ path: lowdim/tcp_pose.npy, dims: [x, y, z] }]
pose: [{ path: hands.npy }]
frames: [{ paths: [rgb/cam0/0001.jpg, rgb/cam0/0002.jpg], label: Camera 0 }]
fps: 30

Videos become camera tiles, annotations become cues, numeric NPY sidecars become series, and listed images become frame sequences. Pose arrays produce pose3d payloads, which use a metadata placeholder in this schema API.

The Ego-Exo4D example uses synchronized image sequences:

Loading fields…
Code EgoExo4dSpec.tsx

The RH20T example reads joint positions and velocities from numeric sidecars:

Loading fields…
Loading fields…
Code Rh20tSpec.tsx

Writing your own adapter

Register a factory returning Model. This example reads a JSON signal:

ts
import { registerAdapter } from "@dreamlake/viz/schema-viz";
import type { Field, Model, Payload, Storage } from "@dreamlake/viz/schema-viz";

type SignalData = { timestamps: number[]; values: number[] };

class SignalAdapter implements Model {
  constructor(
    private storage: Storage,
    private path: string,
  ) {}

  async fields(): Promise<Field[]> {
    return [{ ref: "signal", kind: "series", label: "Signal" }];
  }

  async read(ref: string): Promise<Payload> {
    if (ref !== "signal") throw new Error(`Unknown field: ${ref}`);
    const response = await fetch(await this.storage.resolveUrl(this.path));
    if (!response.ok) throw new Error(`Read failed: ${response.status}`);
    const data: SignalData = await response.json();
    return {
      kind: "series",
      timestamps: data.timestamps,
      columns: { signal: data.values },
    };
  }

  async timeline() {
    return null;
  }
}

registerAdapter(
  "signal-json",
  (storage, params) => new SignalAdapter(storage, String(params.path)),
);

Input: { "timestamps": [0, 1], "values": [2, 3] }. Validate real inputs and implement caching or ReadQuery hints as needed; the interface does not enforce partial reads or sampling.

A factory returns one model per source. You can also supply factories through extensions.adapters; see the shared registration behavior.