segment-lidar documentation

segment-lidar projects a LiDAR point cloud to a 2D image, finds object instances with Meta’s SAM 3, and assigns the image labels back to the original 3D points. It supports top and pinhole views, automatic masks, text and box prompts, optional ground filtering, cached rasters, and LAS/LAZ output.

The current API is the 0.3 series. SAM 3 replaces the SAM 1 checkpoint workflow described in documentation published before 0.3. See Migrating from the earlier documentation when updating an older script.

Start here

1. Installation and model access — install the package, request SAM 3 model access, and set up a token.

2. Top view tutorial — complete top view workflows, prompts, filtering, and saved rasters.

3. Pinhole camera guide — camera geometry and worked projection and segmentation examples.

4. API reference — constructor, method, and view reference.

Documentation

• Installation and model access
  • Requirements
  • SAM 3 access
  • Docker
  • Building this documentation
• Top view tutorial
  • Input and output
  • Automatic instance masks
  • Text and box prompts
  • Ground filtering
  • Saved raster and label workflows
• Pinhole camera guide
  • Coordinate convention
  • Numerical example
  • Segmentation of a real cloud
  • Visibility and label transfer
  • Reuse a pinhole label raster
• API reference
  • SamLidar configuration
  • I/O and processing methods
  • Projection views
• Migrating from the earlier documentation
• Troubleshooting
• Citation
• License and support

How the pipeline works

read loads XYZ or XYZRGB points. An optional csf call removes ground points. segment projects the remaining points with TopView or PinholeView, runs SAM 3 or reads saved labels, and transfers the labels to points. write stores a signed 32 bit segment_id extra dimension in LAS/LAZ.

The image label 0 is background. Point label -1 means background or outside the image; positive values identify instances. When several points project to one pixel, they can receive the same instance label.

from segment_lidar import SamLidar, TopView

model = SamLidar(resolution=0.25)
points = model.read("pointcloud.las")
ids, labels, image = model.segment(points, view=TopView(), prompt="tree")
model.write(points, ids, save_path="segmented.las")

The repository includes a sample animation and data provenance and a GitHub issue tracker.