apairo-preprocess 0.2.0__tar.gz

apairo_preprocess-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Augustin BRESSET
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

apairo_preprocess-0.2.0/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: apairo-preprocess
+Version: 0.2.0
+Summary: Preprocessing for apairo datasets: odometry, ground segmentation, projection, traversability labels
+Author-email: Augustin Bresset <augustin.bresset@gmail.com>
+License: MIT
+Project-URL: Homepage, https://apairo-robotics.github.io/
+Project-URL: Repository, https://github.com/apairo-robotics/apairo_preprocess
+Project-URL: Issues, https://github.com/apairo-robotics/apairo_preprocess/issues
+Keywords: apairo,lidar,point-cloud,traversability,ground-segmentation,robotics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy
+Requires-Dist: pyyaml
+Requires-Dist: tqdm
+Requires-Dist: cloth-simulation-filter
+Requires-Dist: apairo>=0.9
+Requires-Dist: apairo-transform>=0.3
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# apairo-preprocess
+
+Preprocessing pipelines for [apairo](https://github.com/apairo-robotics/apairo) datasets — LiDAR odometry, ground segmentation, camera projection, and traversability ground truth generation.
+
+---
+
+## Installation
+
+```bash
+pip install apairo-preprocess
+```
+
+It brings `apairo` (≥ 0.9) and `apairo-transform` (≥ 0.3).
+
+### Optional dependencies
+
+| Preprocessor | Dependency | Install |
+|---|---|---|
+| `KissICPOdometry` | KISS-ICP | `pip install kiss-icp` |
+| `GICPOdometry` | Open3D | `pip install open3d` |
+| `GroundSegmentationCSF` / `GroundHeightFromLabels` (CSF backend) | CSF | `pip install cloth-simulation-filter` |
+
+Requires Python ≥ 3.11.
+
+---
+
+## Preprocessors
+
+### Odometry
+
+| Class | Output channel | Backend | Output |
+|---|---|---|---|
+| `KissICPOdometry` | `kissicp_poses` | [KISS-ICP](https://github.com/PRBonn/kiss-icp) | `(4, 4)` float64 pose per scan |
+| `GICPOdometry` | `gicp_poses` | Open3D GICP | `(4, 4)` float64 pose per scan |
+
+### Ground segmentation
+
+Binary ground/non-ground labels (0 = ground, 1 = non-ground). All three algorithms share the same label convention and can be compared directly.
+
+| Class | Output channel | Method | Extra dep |
+|---|---|---|---|
+| `GroundSegmentationCSF` | `ground_csf` | Cloth Simulation Filter — accurate on uneven terrain | `CSF` |
+| `GroundSegmentationRANSAC` | `ground_ransac` | RANSAC plane fitting — fast, assumes flat ground | — |
+| `GroundSegmentationFromLabels` | `ground_labels` | Maps existing semantic class IDs to ground/non-ground | — |
+
+### Priors
+
+Scalar per-point features used as traversability priors. Depend on previously computed channels.
+
+| Class | Output channel | Input channels | Output |
+|---|---|---|---|
+| `GroundHeightFromLabels` | `ground_height` | any ground segmentation + `voxelised` | float32 height above nearest ground point (m) |
+| `TrajectoryDistance` | `trajectory_distance` | `voxelised` + `poses` | float32 distance to nearest trajectory waypoint (m) |
+
+### Traversability
+
+Binary traversability labels (1 = traversable, 0 = not).
+
+| Class | Output channel | Method |
+|---|---|---|
+| `TraversabilityFromLabels` | `trav_label` | Maps semantic class IDs to binary traversable/non-traversable |
+| `TraversabilityFromTrajectory` | `trav_traj` | Labels points inside the robot's forward footprint along the trajectory |
+
+### Camera projection
+
+Atomic bridges between the point cloud and image spaces.  All outputs are
+**row-aligned** with the lidar scan, so any per-point channel composes with
+the projection by row index.
+
+| Class | Output channel | Input channels | Output |
+|---|---|---|---|
+| `LidarCameraProjection` | `lidar_uv` | lidar only (extrinsics/intrinsics are static) | `(N, 3)` float32 `[u, v, depth]`, NaN outside the frustum |
+| `PointFeaturesFromImage` | `point_features` | `lidar_uv` + image | `(N, C)` image values per point (e.g. RGB) — image → cloud |
+| `ImageMaskFromPointLabels` | `trav_mask` | `trav_traj` + `lidar_uv` | `(H, W)` uint8 label mask, 255 = no data — cloud → image |
+
+Pixel conflicts resolve to the nearest point (depth ordering); an optional
+occlusion filter (`occlusion_bin_px`) drops points hidden behind nearer
+returns so ground behind an obstacle does not bleed onto its pixels.
+Both halves of the projection come from the dataset calibration: the
+extrinsic via `ds.calibration.get_tf(lidar_frame, camera_frame)`, the
+intrinsics via `ds.calibration.get_intrinsics(camera_frame)`.
+
+**Asynchronous datasets:** `LidarCameraProjection` streams a single channel
+and runs anywhere.  The two multi-channel preprocessors run via
+`run_preprocess` on synchronous (profiled) datasets only; on an async dataset
+(TartanDrive, raw rigs) run them over a `synchronize()` view and persist with
+`ChannelWriter` — see
+[`examples/traversability_image_mask.py`](examples/traversability_image_mask.py).
+
+---
+
+## Quickstart
+
+### Ground segmentation
+
+```python
+from apairo.dataset.rellis import Rellis3DDataset
+from apairo_preprocess import GroundSegmentationCSF, GroundSegmentationFromLabels, GroundSegmentationRANSAC
+
+dataset_dir = "/data/Rellis-3D/00000"
+
+Rellis3DDataset.run_preprocess(GroundSegmentationRANSAC(), dataset_dir)
+Rellis3DDataset.run_preprocess(GroundSegmentationCSF(), dataset_dir)   # requires: pip install CSF
+
+# From existing semantic labels (default ground IDs are for RELLIS-3D)
+Rellis3DDataset.run_preprocess(GroundSegmentationFromLabels(), dataset_dir)
+
+# writes ground_ransac/, ground_csf/, ground_labels/  (uint8: 0=ground, 1=non-ground)
+```
+
+### Height above ground (prior)
+
+Ground segmentation must be computed first.
+
+```python
+from apairo_preprocess import GroundSegmentationCSF, GroundHeightFromLabels
+
+Rellis3DDataset.run_preprocess(GroundSegmentationCSF(), dataset_dir)
+Rellis3DDataset.run_preprocess(
+    GroundHeightFromLabels(ground_key="ground_csf"),
+    dataset_dir,
+)
+# writes ground_height/  (float32, metres above nearest ground point)
+```
+
+`GroundHeightFromLabels` accepts any ground key — swap `"ground_csf"` for `"ground_ransac"` or `"ground_labels"` to change the backend without re-running CSF.
+
+### Traversability from semantic labels
+
+```python
+from apairo_preprocess import TraversabilityFromLabels
+
+# Default traversable IDs for RELLIS-3D: {dirt, grass, asphalt, concrete, puddle, mud}
+Rellis3DDataset.run_preprocess(TraversabilityFromLabels(), dataset_dir)
+# writes trav_label/  (uint8: 1=traversable, 0=not)
+```
+
+Custom IDs for SemanticKITTI:
+
+```python
+from apairo.dataset.semantic_kitti import SemanticKittiDataset
+from apairo_preprocess import TraversabilityFromLabels
+
+SemanticKittiDataset.run_preprocess(
+    TraversabilityFromLabels(traversable_ids=frozenset({40, 44, 48, 49, 60, 72})),
+    "/data/sequences/00",
+)
+```
+
+### Traversability ground truth from trajectory
+
+Requires poses to be computed first (e.g. with `KissICPOdometry`).
+
+```python
+from apairo.dataset.goose import Goose3DDataset
+from apairo_preprocess import KissICPOdometry, TraversabilityFromTrajectory
+
+Goose3DDataset.run_preprocess(KissICPOdometry(voxel_size=1.0), "/data/goose/seq_001")
+Goose3DDataset.run_preprocess(
+    TraversabilityFromTrajectory(poses_key="kissicp_poses", robot_radius=0.75),
+    "/data/goose/seq_001",
+)
+# writes trav_traj/  (uint8: 1=traversable, 0=not)
+```
+
+### Traversability mask in image space
+
+Projects the trajectory ground truth into the camera: `trav_traj` labels the
+points, `lidar_uv` places them in the image, `ImageMaskFromPointLabels`
+paints the mask.
+
+```python
+from apairo_preprocess import ImageMaskFromPointLabels, LidarCameraProjection
+
+cal = Rellis3DDataset(dataset_dir, keys=["lidar"]).calibration
+cam = cal.get_intrinsics("camera")               # K, distortion, image size
+T = cal.get_tf("lidar", "camera")                # lidar -> camera optical frame
+
+Rellis3DDataset.run_preprocess(
+    LidarCameraProjection(intrinsics=cam, extrinsics=T),
+    dataset_dir,
+)
+Rellis3DDataset.run_preprocess(
+    ImageMaskFromPointLabels(image_size=(cam.height, cam.width), radius=2, occlusion_bin_px=8),
+    dataset_dir,
+)
+# writes lidar_uv/  (float32 [u, v, depth] per point)
+#    and trav_mask/ (uint8 per pixel: 1=traversable, 0=not, 255=no data)
+```
+
+To sanity-check calibration and projection first, colour the cloud with
+camera RGB and inspect it in a 3-D viewer (projector, apairo_rr):
+
+```python
+from apairo_preprocess import PointFeaturesFromImage
+
+Rellis3DDataset.run_preprocess(
+    PointFeaturesFromImage(image_key="image", output_key="lidar_rgb"),
+    dataset_dir,
+)
+```
+
+---
+
+## Examples
+
+Ready-to-run scripts in [`examples/`](examples/):
+
+```bash
+python examples/kissicp_odometry.py /data/Rellis-3D/00000 --dataset rellis
+python examples/traversability_from_labels.py /data/Rellis-3D/00000
+python examples/traversability_from_trajectory.py /data/goose/seq_001
+python examples/traversability_image_mask.py /data/tartan/seq --lidar-frame velodyne --camera-frame multisense_left --rgb
+
+# no dataset needed — synthetic scene, renders every pipeline stage (needs matplotlib)
+python examples/projection_pipeline_demo.py --out-dir /tmp/projection_demo
+```
+
+---
+
+## License
+
+MIT

apairo_preprocess-0.2.0/README.md

@@ -0,0 +1,223 @@
+# apairo-preprocess
+
+Preprocessing pipelines for [apairo](https://github.com/apairo-robotics/apairo) datasets — LiDAR odometry, ground segmentation, camera projection, and traversability ground truth generation.
+
+---
+
+## Installation
+
+```bash
+pip install apairo-preprocess
+```
+
+It brings `apairo` (≥ 0.9) and `apairo-transform` (≥ 0.3).
+
+### Optional dependencies
+
+| Preprocessor | Dependency | Install |
+|---|---|---|
+| `KissICPOdometry` | KISS-ICP | `pip install kiss-icp` |
+| `GICPOdometry` | Open3D | `pip install open3d` |
+| `GroundSegmentationCSF` / `GroundHeightFromLabels` (CSF backend) | CSF | `pip install cloth-simulation-filter` |
+
+Requires Python ≥ 3.11.
+
+---
+
+## Preprocessors
+
+### Odometry
+
+| Class | Output channel | Backend | Output |
+|---|---|---|---|
+| `KissICPOdometry` | `kissicp_poses` | [KISS-ICP](https://github.com/PRBonn/kiss-icp) | `(4, 4)` float64 pose per scan |
+| `GICPOdometry` | `gicp_poses` | Open3D GICP | `(4, 4)` float64 pose per scan |
+
+### Ground segmentation
+
+Binary ground/non-ground labels (0 = ground, 1 = non-ground). All three algorithms share the same label convention and can be compared directly.
+
+| Class | Output channel | Method | Extra dep |
+|---|---|---|---|
+| `GroundSegmentationCSF` | `ground_csf` | Cloth Simulation Filter — accurate on uneven terrain | `CSF` |
+| `GroundSegmentationRANSAC` | `ground_ransac` | RANSAC plane fitting — fast, assumes flat ground | — |
+| `GroundSegmentationFromLabels` | `ground_labels` | Maps existing semantic class IDs to ground/non-ground | — |
+
+### Priors
+
+Scalar per-point features used as traversability priors. Depend on previously computed channels.
+
+| Class | Output channel | Input channels | Output |
+|---|---|---|---|
+| `GroundHeightFromLabels` | `ground_height` | any ground segmentation + `voxelised` | float32 height above nearest ground point (m) |
+| `TrajectoryDistance` | `trajectory_distance` | `voxelised` + `poses` | float32 distance to nearest trajectory waypoint (m) |
+
+### Traversability
+
+Binary traversability labels (1 = traversable, 0 = not).
+
+| Class | Output channel | Method |
+|---|---|---|
+| `TraversabilityFromLabels` | `trav_label` | Maps semantic class IDs to binary traversable/non-traversable |
+| `TraversabilityFromTrajectory` | `trav_traj` | Labels points inside the robot's forward footprint along the trajectory |
+
+### Camera projection
+
+Atomic bridges between the point cloud and image spaces.  All outputs are
+**row-aligned** with the lidar scan, so any per-point channel composes with
+the projection by row index.
+
+| Class | Output channel | Input channels | Output |
+|---|---|---|---|
+| `LidarCameraProjection` | `lidar_uv` | lidar only (extrinsics/intrinsics are static) | `(N, 3)` float32 `[u, v, depth]`, NaN outside the frustum |
+| `PointFeaturesFromImage` | `point_features` | `lidar_uv` + image | `(N, C)` image values per point (e.g. RGB) — image → cloud |
+| `ImageMaskFromPointLabels` | `trav_mask` | `trav_traj` + `lidar_uv` | `(H, W)` uint8 label mask, 255 = no data — cloud → image |
+
+Pixel conflicts resolve to the nearest point (depth ordering); an optional
+occlusion filter (`occlusion_bin_px`) drops points hidden behind nearer
+returns so ground behind an obstacle does not bleed onto its pixels.
+Both halves of the projection come from the dataset calibration: the
+extrinsic via `ds.calibration.get_tf(lidar_frame, camera_frame)`, the
+intrinsics via `ds.calibration.get_intrinsics(camera_frame)`.
+
+**Asynchronous datasets:** `LidarCameraProjection` streams a single channel
+and runs anywhere.  The two multi-channel preprocessors run via
+`run_preprocess` on synchronous (profiled) datasets only; on an async dataset
+(TartanDrive, raw rigs) run them over a `synchronize()` view and persist with
+`ChannelWriter` — see
+[`examples/traversability_image_mask.py`](examples/traversability_image_mask.py).
+
+---
+
+## Quickstart
+
+### Ground segmentation
+
+```python
+from apairo.dataset.rellis import Rellis3DDataset
+from apairo_preprocess import GroundSegmentationCSF, GroundSegmentationFromLabels, GroundSegmentationRANSAC
+
+dataset_dir = "/data/Rellis-3D/00000"
+
+Rellis3DDataset.run_preprocess(GroundSegmentationRANSAC(), dataset_dir)
+Rellis3DDataset.run_preprocess(GroundSegmentationCSF(), dataset_dir)   # requires: pip install CSF
+
+# From existing semantic labels (default ground IDs are for RELLIS-3D)
+Rellis3DDataset.run_preprocess(GroundSegmentationFromLabels(), dataset_dir)
+
+# writes ground_ransac/, ground_csf/, ground_labels/  (uint8: 0=ground, 1=non-ground)
+```
+
+### Height above ground (prior)
+
+Ground segmentation must be computed first.
+
+```python
+from apairo_preprocess import GroundSegmentationCSF, GroundHeightFromLabels
+
+Rellis3DDataset.run_preprocess(GroundSegmentationCSF(), dataset_dir)
+Rellis3DDataset.run_preprocess(
+    GroundHeightFromLabels(ground_key="ground_csf"),
+    dataset_dir,
+)
+# writes ground_height/  (float32, metres above nearest ground point)
+```
+
+`GroundHeightFromLabels` accepts any ground key — swap `"ground_csf"` for `"ground_ransac"` or `"ground_labels"` to change the backend without re-running CSF.
+
+### Traversability from semantic labels
+
+```python
+from apairo_preprocess import TraversabilityFromLabels
+
+# Default traversable IDs for RELLIS-3D: {dirt, grass, asphalt, concrete, puddle, mud}
+Rellis3DDataset.run_preprocess(TraversabilityFromLabels(), dataset_dir)
+# writes trav_label/  (uint8: 1=traversable, 0=not)
+```
+
+Custom IDs for SemanticKITTI:
+
+```python
+from apairo.dataset.semantic_kitti import SemanticKittiDataset
+from apairo_preprocess import TraversabilityFromLabels
+
+SemanticKittiDataset.run_preprocess(
+    TraversabilityFromLabels(traversable_ids=frozenset({40, 44, 48, 49, 60, 72})),
+    "/data/sequences/00",
+)
+```
+
+### Traversability ground truth from trajectory
+
+Requires poses to be computed first (e.g. with `KissICPOdometry`).
+
+```python
+from apairo.dataset.goose import Goose3DDataset
+from apairo_preprocess import KissICPOdometry, TraversabilityFromTrajectory
+
+Goose3DDataset.run_preprocess(KissICPOdometry(voxel_size=1.0), "/data/goose/seq_001")
+Goose3DDataset.run_preprocess(
+    TraversabilityFromTrajectory(poses_key="kissicp_poses", robot_radius=0.75),
+    "/data/goose/seq_001",
+)
+# writes trav_traj/  (uint8: 1=traversable, 0=not)
+```
+
+### Traversability mask in image space
+
+Projects the trajectory ground truth into the camera: `trav_traj` labels the
+points, `lidar_uv` places them in the image, `ImageMaskFromPointLabels`
+paints the mask.
+
+```python
+from apairo_preprocess import ImageMaskFromPointLabels, LidarCameraProjection
+
+cal = Rellis3DDataset(dataset_dir, keys=["lidar"]).calibration
+cam = cal.get_intrinsics("camera")               # K, distortion, image size
+T = cal.get_tf("lidar", "camera")                # lidar -> camera optical frame
+
+Rellis3DDataset.run_preprocess(
+    LidarCameraProjection(intrinsics=cam, extrinsics=T),
+    dataset_dir,
+)
+Rellis3DDataset.run_preprocess(
+    ImageMaskFromPointLabels(image_size=(cam.height, cam.width), radius=2, occlusion_bin_px=8),
+    dataset_dir,
+)
+# writes lidar_uv/  (float32 [u, v, depth] per point)
+#    and trav_mask/ (uint8 per pixel: 1=traversable, 0=not, 255=no data)
+```
+
+To sanity-check calibration and projection first, colour the cloud with
+camera RGB and inspect it in a 3-D viewer (projector, apairo_rr):
+
+```python
+from apairo_preprocess import PointFeaturesFromImage
+
+Rellis3DDataset.run_preprocess(
+    PointFeaturesFromImage(image_key="image", output_key="lidar_rgb"),
+    dataset_dir,
+)
+```
+
+---
+
+## Examples
+
+Ready-to-run scripts in [`examples/`](examples/):
+
+```bash
+python examples/kissicp_odometry.py /data/Rellis-3D/00000 --dataset rellis
+python examples/traversability_from_labels.py /data/Rellis-3D/00000
+python examples/traversability_from_trajectory.py /data/goose/seq_001
+python examples/traversability_image_mask.py /data/tartan/seq --lidar-frame velodyne --camera-frame multisense_left --rgb
+
+# no dataset needed — synthetic scene, renders every pipeline stage (needs matplotlib)
+python examples/projection_pipeline_demo.py --out-dir /tmp/projection_demo
+```
+
+---
+
+## License
+
+MIT

apairo_preprocess-0.2.0/apairo_preprocess/__init__.py

@@ -0,0 +1,27 @@
+from apairo_preprocess.traversability import TraversabilityFromLabels, TraversabilityFromTrajectory
+from apairo_preprocess.ground import GroundSegmentationCSF, GroundSegmentationFromLabels, GroundSegmentationRANSAC
+from apairo_preprocess.priors import GroundHeightFromLabels, TrajectoryDistance
+from apairo_preprocess.odometry import GICPOdometry, KissICPOdometry
+from apairo_preprocess.pointcloud import VoxeliseCoords, VoxeliseLabels, VoxelisePointCloud, RemoveRobotPoints
+from apairo_preprocess.projection import BEVRasterisation, ImageMaskFromPointLabels, LidarCameraProjection, PointFeaturesFromImage, to_uint8_image
+
+__all__ = [
+    "TraversabilityFromLabels",
+    "TraversabilityFromTrajectory",
+    "GroundSegmentationCSF",
+    "GroundSegmentationFromLabels",
+    "GroundSegmentationRANSAC",
+    "GroundHeightFromLabels",
+    "TrajectoryDistance",
+    "GICPOdometry",
+    "KissICPOdometry",
+    "VoxelisePointCloud",
+    "VoxeliseLabels",
+    "VoxeliseCoords",
+    "RemoveRobotPoints",
+    "LidarCameraProjection",
+    "PointFeaturesFromImage",
+    "ImageMaskFromPointLabels",
+    "BEVRasterisation",
+    "to_uint8_image",
+]

apairo_preprocess-0.2.0/apairo_preprocess/ground/__init__.py

@@ -0,0 +1,9 @@
+from apairo_preprocess.ground.csf import GroundSegmentationCSF
+from apairo_preprocess.ground.from_labels import GroundSegmentationFromLabels
+from apairo_preprocess.ground.ransac import GroundSegmentationRANSAC
+
+__all__ = [
+    "GroundSegmentationCSF",
+    "GroundSegmentationFromLabels",
+    "GroundSegmentationRANSAC",
+]

apairo_preprocess-0.2.0/apairo_preprocess/ground/csf.py

@@ -0,0 +1,95 @@
+"""Ground segmentation via Cloth Simulation Filter (CSF)."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+import numpy as np
+
+from apairo.core.preprocessor import FramePreprocessor
+from apairo.core.sample import Sample
+
+
+def _run_csf(
+    xyz: np.ndarray,
+    cloth_resolution: float,
+    class_threshold: float,
+    rigidness: int,
+) -> tuple[list[int], list[int]]:
+    """Run CSF and return (ground_indices, non_ground_indices).
+
+    Requires ``pip install CSF``.
+    """
+    try:
+        import CSF  # type: ignore[import-untyped]
+    except ImportError as exc:
+        raise ImportError(
+            "GroundSegmentationCSF requires the CSF package: pip install CSF"
+        ) from exc
+
+    csf = CSF.CSF()
+    csf.params.bSloopSmooth = False
+    csf.params.cloth_resolution = cloth_resolution
+    csf.params.rigidness = rigidness
+    csf.params.time_step = 0.65
+    csf.params.class_threshold = class_threshold
+    csf.params.interations = 500
+
+    csf.setPointCloud(xyz.tolist())
+    ground_idx = CSF.VecInt()
+    non_ground_idx = CSF.VecInt()
+    csf.do_filtering(ground_idx, non_ground_idx)
+    return list(ground_idx), list(non_ground_idx)
+
+
+class GroundSegmentationCSF(FramePreprocessor):
+    """Per-point ground/non-ground labels via Cloth Simulation Filter.
+
+    Runs CSF on the voxelised point cloud.  More accurate than RANSAC on
+    uneven terrain; requires ``pip install CSF``.
+
+    Output labels: **0 = ground, 1 = non-ground**.
+
+    Args:
+        voxelised_key:    Input channel (voxelised point cloud, shape (N, D≥3)).
+        cloth_resolution: CSF cloth resolution (metres).  Default 0.5 m.
+        class_threshold:  CSF point-to-cloth distance threshold (metres).
+                          Default 0.5 m.
+        rigidness:        CSF cloth rigidness (1–3).  3 = flat terrain.
+                          Default 3.
+        output_key:       Override the default channel name ``"ground_csf"``.
+    """
+
+    output_key: ClassVar[str] = "ground_csf"
+    input_keys: ClassVar[list[str]] = ["voxelised"]
+    timestamps_from: ClassVar[str] = "voxelised"
+    sources: ClassVar[list[str]] = ["voxelised"]
+
+    def __init__(
+        self,
+        voxelised_key: str = "voxelised",
+        cloth_resolution: float = 0.5,
+        class_threshold: float = 0.5,
+        rigidness: int = 3,
+        output_key: str | None = None,
+    ) -> None:
+        self._voxelised_key = voxelised_key
+        self._cloth_resolution = cloth_resolution
+        self._class_threshold = class_threshold
+        self._rigidness = rigidness
+        self.input_keys = [voxelised_key]
+        self.sources = [voxelised_key]
+        if output_key is not None:
+            self.output_key = output_key
+
+    def __call__(self, sample: Sample) -> np.ndarray:
+        xyz = np.asarray(sample.data[self._voxelised_key], dtype=np.float64)[:, :3]
+        ground_idx, _ = _run_csf(
+            xyz,
+            cloth_resolution=self._cloth_resolution,
+            class_threshold=self._class_threshold,
+            rigidness=self._rigidness,
+        )
+        labels = np.ones(len(xyz), dtype=np.uint8)
+        labels[ground_idx] = 0
+        return labels

apairo_preprocess-0.2.0/apairo_preprocess/ground/from_labels.py

@@ -0,0 +1,55 @@
+"""Ground segmentation from semantic class IDs."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+import numpy as np
+
+from apairo.core.preprocessor import FramePreprocessor
+from apairo.core.sample import Sample
+
+_RELLIS_GROUND_IDS: frozenset[int] = frozenset({1, 3, 10, 23, 31, 33})
+
+
+class GroundSegmentationFromLabels(FramePreprocessor):
+    """Per-point ground/non-ground labels from semantic class IDs.
+
+    Each point is labelled ground (0) if its semantic class ID is in
+    ``ground_ids``, non-ground (1) otherwise.
+
+    Output labels: **0 = ground, 1 = non-ground** — same convention as
+    ``GroundSegmentationCSF`` and ``GroundSegmentationRANSAC``.
+
+    Default ground IDs for RELLIS-3D::
+
+        {1: dirt, 3: grass, 10: asphalt, 23: concrete, 31: puddle, 33: mud}
+
+    Args:
+        labels_key: Input channel for per-point semantic labels.
+        ground_ids: Set of semantic class IDs considered ground.
+                    Defaults to the RELLIS-3D ground classes.
+        output_key: Override the default channel name ``"ground_labels"``.
+    """
+
+    output_key: ClassVar[str] = "ground_labels"
+    input_keys: ClassVar[list[str]] = ["labels"]
+    timestamps_from: ClassVar[str] = "lidar"
+    sources: ClassVar[list[str]] = ["labels"]
+
+    def __init__(
+        self,
+        labels_key: str = "labels",
+        ground_ids: frozenset[int] | None = None,
+        output_key: str | None = None,
+    ) -> None:
+        self._labels_key = labels_key
+        self._ground_ids = ground_ids if ground_ids is not None else _RELLIS_GROUND_IDS
+        self.input_keys = [labels_key]
+        self.sources = [labels_key]
+        if output_key is not None:
+            self.output_key = output_key
+
+    def __call__(self, sample: Sample) -> np.ndarray:
+        labels = np.asarray(sample.data[self._labels_key])
+        return (~np.isin(labels, list(self._ground_ids))).astype(np.uint8)