# SDK reference

> Classes and methods in the rayform Python package.

Source: https://rayform.world/docs/sdk/reference
Last updated: 2026-10-18
Status: Rayform is in private preview. APIs, formats and the SDK described here may change before general availability.

## Client

```python
rayform.Client(api_key=None, base_url=None, cache_dir=None, cache_max_gb=200, offline=False, timeout_s=60)
```

The entry point. Resource namespaces hang off it: `client.sessions`, `client.segments`, `client.slices`, `client.exports`, `client.assets`. List methods return lazy iterators that fetch pages as you go.

## Sessions

### `client.sessions.upload`

```python
client.sessions.upload(path, *, site, device=None, notes=None, part_size=64 * 2**20, wait=False, timeout=None) -> Session
```

Uploads a file, resuming if an earlier attempt was interrupted, and completes the session. With `wait=True` it blocks until processing finishes and raises `ProcessingError` if the session fails.

### `client.sessions.get`, `list`, `delete`

```python
client.sessions.get(id) -> Session
client.sessions.list(site=None, status=None) -> Iterator[Session]
client.sessions.delete(id) -> None
```

### `Session`

| Member | Type | Description |
| --- | --- | --- |
| `id`, `site`, `status` | `str` | As in the [session object](https://rayform.world/docs/api/sessions#the-session-object) |
| `issues` | `list[Issue]` | Problems found while processing |
| `segments()` | `list[Segment]` | Segments produced from this session |
| `wait(timeout=None)` | `Session` | Block until `processed` or `failed` |
| `refresh()` | `Session` | Re-read from the API |

## Segments

### `client.segments.search`

```python
client.segments.search(
    *, site=None, event=None, object=None, text=None, near=None, context=None,
    recorded=None, quality_min=None, has_channels=None, session=None,
) -> SegmentResults
```

Arguments accept a value or a list. `SegmentResults` is iterable, sliceable, and has `total`.

### `client.segments.get`

```python
client.segments.get(id, version=None) -> Segment
```

### `Segment`

| Member | Returns | Description |
| --- | --- | --- |
| `id`, `version`, `session`, `site` | `str` | Identifiers |
| `t0_ns`, `t1_ns`, `duration_s` | `int`, `int`, `float` | Time window |
| `events()` | `pyarrow.Table` | Interaction events, time-ordered |
| `entities()` | `list[Entity]` | People, objects and robots |
| `channel(name, t0_ns=None, t1_ns=None, frame="rayform")` | `pyarrow.Table` | One channel's samples |
| `frames(camera, every=1)` | `Iterator[Frame]` | Decoded images with timestamps |
| `scene_at(t_ns)` | `Scene` | The scene with moving objects posed at `t_ns` |
| `quality`, `context` | `dict` | Scores and labels |

## Scenes

### `Scene`

| Member | Returns | Description |
| --- | --- | --- |
| `splats` | `dict[str, numpy.ndarray]` | `means`, `scales`, `quats` (wxyz), `opacities`, `sh` |
| `collision_mesh()` | `trimesh.Trimesh` | Requires `trimesh` |
| `to_usd(path)` | `None` | Write OpenUSD for Isaac Sim (`rayform[usd]`) |
| `to_mjcf(dir)` | `None` | Write MJCF for MuJoCo (`rayform[mujoco]`) |

## Slices

```python
client.slices.create(*, query=None, segments=None, exclude=None, name=None) -> Slice
client.slices.get(id) -> Slice
client.slices.list(name=None) -> Iterator[Slice]
```

### `Slice`

| Member | Returns | Description |
| --- | --- | --- |
| `id`, `hash`, `name` | `str` | Identifiers |
| `segment_count`, `duration_s` | `int`, `float` | Size |
| `segments()` | `Iterator[Segment]` | Exact versions in the slice |
| `pull(workers=8)` | `None` | Download everything into the cache |

## Exports

```python
client.exports.create(slice, *, format, options=None, destination=None) -> Export
client.exports.get(id) -> Export
```

### `Export`

| Member | Returns | Description |
| --- | --- | --- |
| `status`, `progress` | `str`, `float` | State and fraction done |
| `wait(timeout=None)` | `Export` | Block until finished; raises `ExportError` on failure |
| `files()` | `Iterator[ExportFile]` | Paths, sizes and signed URLs |
| `download(dir)` | `None` | Download files kept in Rayform storage |

## Assets

```python
client.assets.get(id) -> Asset             # metadata and a signed URL
client.assets.load(id) -> dict | bytes     # decoded content, verified against the ID
```

## PyTorch

### `rayform.torch.EpisodeDataset`

```python
rayform.torch.EpisodeDataset(
    slice, *, obs, action=None, fps=None, horizon=1, frame="rayform",
    quat_order="wxyz", image_size=None, transform=None, seed=0,
)
```

A map-style `torch.utils.data.Dataset`. See [Training with PyTorch](https://rayform.world/docs/guides/pytorch) for the sample layout. `set_epoch(epoch)` fixes the order for distributed training.

## Visualisation

### `rayform.rerun.show`

```python
rayform.rerun.show(segment, *, channels=None, with_scene=True, spawn=True)
```

Logs a segment's cameras, poses, events and scene to the Rerun viewer.