apairo-transform

Runtime transforms and augmentations for apairo datasets — applied lazily at access time, with no data written to disk.

Unlike apairo-preprocess (offline, disk-bound), transforms are registered on a dataset and executed on every __getitem__ call.

Installation

pip install apairo-transform
pip install "apairo-transform[image]"   # Resize, with OpenCV
pip install "apairo-transform[torch]"   # to_torch_collate, to_tensors

Requires Python ≥ 3.11, numpy and apairo ≥ 0.9. No other hard dependencies.

Transforms

Point cloud — filter & downsample

Point cloud — temporal accumulation

Accumulation is a window of frames reduced to one sample. The window is computed by index, so the result stays correct under shuffling, with several DataLoader workers, and never mixes two sequences:

from apairo_transform import StackByPose

ds = ds.window(size=5, stride=1, reduce=StackByPose(lidar="lidar", pose="pose"))

On an asynchronous dataset, synchronize the scan and the pose first (ds.synchronize(reference="lidar", method={"pose": Se3Interp()})).

AccumulateFrames is deprecated (0.3). It kept a rolling buffer, so it only worked on a sequential pass and needed .reset() between sequences. Replace ds.transform(AccumulateFrames(lidar, pose, num_frames=5, stride=1)) with ds.window(size=5, stride=1, reduce=StackByPose(lidar, pose)): same cloud, no state. It will be removed in a later release.

Point cloud — augmentation

Pose

Label

Interpolation — for ds.synchronize()

Value-level strategies implementing the apairo.Interpolator contract: instead of matching an existing event, the value is synthesized at the reference instant from its two bracketing events. Continuous signals only.

from apairo_transform.interp import LinearInterp, Se3Interp

ds_sync = ds.synchronize(
    reference="velodyne_0",
    method={
        "gicp_poses": Se3Interp(),     # pose interpolated at each lidar instant
        "cmd":        LinearInterp(),
    },                                  # unlisted channels -> "latest"
)

Quickstart

Registering transforms on a dataset

Transforms are registered on a dataset channel and applied lazily on every __getitem__.

from apairo.dataset.rellis import Rellis3DDataset
from apairo_transform import RangeFilter, RandomSubsample, ChannelSelect

ds = Rellis3DDataset("/data/RELLIS/00000", keys=["lidar"])

ds = ds.transform("lidar", RangeFilter(max=50.0))
ds = ds.transform("lidar", RandomSubsample(8192))
ds = ds.transform("lidar", ChannelSelect([0, 1, 2]))   # xyz only

sample = ds[0]
# sample.data["lidar"] -> np.ndarray (N, 3), N ≤ 8192, range < 50 m

Multiple calls on the same key compose in order, and each returns the dataset to use next: assign it (ds = ds.transform(...)).

Chain transform() calls to build a dataset. Use Compose from apairo core to name an operation made of several transforms, so it can be reused as one step, in a dataset or on a bare array:

from apairo.core import Compose
from apairo_transform import RangeFilter, RandomSubsample, ChannelSelect

clean_lidar = Compose([
    RangeFilter(max=50.0),
    RandomSubsample(8192),
    ChannelSelect([0, 1, 2]),
])

ds = ds.transform("lidar", clean_lidar)
points = clean_lidar(raw_points)        # the same operation, outside a dataset

Augmentation pipeline for training

from apairo.core import Compose
from apairo.dataset.rellis import Rellis3DDataset
from apairo_transform import (
    RangeFilter, RandomRotation, RandomFlip,
    RandomScale, GaussianNoise, RandomPointDrop,
)

ds = Rellis3DDataset("/data/RELLIS/00000", keys=["lidar"])

ds = ds.transform("lidar", Compose([
    RangeFilter(max=50.0),
    RandomRotation(axis="z"),           # yaw-only for outdoor LiDAR
    RandomFlip(axis="x", p=0.5),
    RandomScale(range=(0.95, 1.05)),
    GaussianNoise(sigma=0.01),
    RandomPointDrop(p=0.05),
]))

Points with per-point labels

A transform registered on one channel sees that channel only. A step that drops or reorders points (RangeFilter, HeightFilter, BoxFilter, RandomSubsample, RandomPointDrop, ShufflePoints, VoxelDownsample) registered on "lidar" leaves a per-point "labels" channel untouched: the cloud loses points and the labels do not, so label i no longer describes point i. Apply one selection to both, in a sample-level step:

in_range = RangeFilter(max=50.0)

def keep_in_range(sample):
    keep = in_range.compute_mask(sample.data["lidar"])
    sample.data["lidar"] = sample.data["lidar"][keep]
    sample.data["labels"] = sample.data["labels"][keep]
    return sample

ds = ds.transform(keep_in_range)

examples/compose.py does this with a subsample as well.

Label remapping

from apairo.dataset.rellis import Rellis3DDataset
from apairo_transform import RemapLabels, MaskLabels

ds = Rellis3DDataset("/data/RELLIS/00000", keys=["labels"])

# Collapse 35 Rellis classes to 4 coarse categories
COARSE = {1: 0, 3: 0, 10: 0, 23: 0,   # ground
          4: 1, 7: 1, 19: 1,            # vegetation
          8: 2, 12: 2, 15: 2, 18: 2,   # obstacle
          9: 3}                          # sky

ds = ds.transform("labels", RemapLabels(COARSE, default=255))
ds = ds.transform("labels", MaskLabels(keep={0, 1, 2, 3}, ignore_value=255))

Pose conversion

from apairo.dataset.rellis import Rellis3DDataset
from apairo_transform import PoseTo4x4, InvertPose

ds = Rellis3DDataset("/data/RELLIS/00000", keys=["poses"])

# poses channel: (3, 4) → pad to (4, 4) and invert
ds = ds.transform("poses", PoseTo4x4())
ds = ds.transform("poses", InvertPose())

Voxel downsampling at access time

Unlike VoxelisePointCloud in apairo-preprocess (which saves to disk once), VoxelDownsample runs in memory on every access — useful for dynamic voxel sizes or when disk space is constrained.

from apairo_transform import VoxelDownsample

ds = ds.transform("lidar", VoxelDownsample(voxel_size=0.1, max_range=50.0))

Examples

Ready-to-run scripts in examples/:

# Filter + subsample a LiDAR channel
python examples/pointcloud.py /data/RELLIS/00000

# Remap or mask semantic labels
python examples/labels.py /data/RELLIS/00000 --mode remap

# Full multi-channel pipeline with Compose
python examples/compose.py /data/RELLIS/00000

# Augmentation pipeline — prints before/after statistics per frame
python examples/augmentation.py /data/RELLIS/00000 --rotation-axis z --drop-p 0.05

Relationship to apairo-preprocess

Both packages are complementary: run apairo-preprocess once to produce derived channels (odometry, traversability, voxelised coordinates), then use apairo-transform at training time to augment and normalise the data.

License

MIT