API reference

Public imports are SamLidar, TopView, and PinholeView from segment_lidar. All three can also be imported from their defining modules. The methods below describe the 0.3 series.

LiDAR I/O, image segmentation, and label transfer.

Project point clouds into images and lift image labels back to points.

SamLidar configuration

class segment_lidar.samlidar.SamLidar(resolution=0.25, height=512, width=512, distance_threshold=None, device=None, intrinsics=None, rotation=None, translation=None, hf_token=None, model_id='facebook/sam3')

Segment a point cloud through a top or pinhole raster view.

Model loading is deferred until segment() needs inference. Existing label rasters can therefore be projected without installing a model.

Parameters:

  • resolution (float)

  • height (int)

  • width (int)

  • distance_threshold (float | None)

  • device (str | None)

  • intrinsics (np.ndarray | None)

  • rotation (np.ndarray | None)

  • translation (np.ndarray | None)

  • hf_token (str | None)

  • model_id (str)

Constructor parameters

Parameter

Default

Meaning

resolution

0.25

Top view world units per pixel. Must be positive and finite.

height, width

512, 512

Pinhole output image dimensions when creating a new image.

distance_threshold

None

Optional maximum positive pinhole camera depth.

device

None

PyTorch device; selects CUDA when available, else CPU.

intrinsics

None

Pinhole 3 by 3 camera matrix.

rotation, translation

None

World-to-camera 3 by 3 rotation and three element translation.

hf_token

None

Token for model download; falls back to HF_TOKEN.

model_id

facebook/sam3

Hugging Face model identifier.

Inference settings

Each SamLidar instance exposes model.text_prompt and model.automatic_masks. Their settings apply to the appropriate SAM 3 mode; model loading is deferred until inference. Switching between automatic and prompted modes loads the corresponding model path.

Setting

Default

Meaning

text_prompt.text

None

Default text, overridden by segment(prompt=...).

text_prompt.score_threshold

0.5

Minimum prompted instance score, 0–1.

text_prompt.mask_threshold

0.5

Prompted mask threshold, 0–1.

automatic_masks.points_per_crop

32

Automatic mask sample grid density; positive integer.

automatic_masks.points_per_batch

16

Automatic mask sampling batch size; positive integer.

automatic_masks.pred_iou_thresh

0.65

Automatic predicted IoU threshold, 0–1.

automatic_masks.stability_score_thresh

0.7

Automatic mask stability threshold, 0–1.

I/O and processing methods

SamLidar.read(path, classification=None)

Read LAS/LAZ or NPY into XYZ or XYZRGB (RGB normalized to [0, 1]).

Parameters:

  • path (str)

  • classification (int | None)

Return type:

ndarray

classification filters LAS/LAZ by classification code. The return is an (N, 3) or (N, 6) NumPy array. RGB values from LAS/LAZ are normalized to 0–1. NPY input does not support classification filtering.

SamLidar.csf(points, class_threshold=0.5, cloth_resolution=0.2, iterations=500, slope_smooth=False, csf_path=None, exists=False)

Return points above ground and their indices, plus ground indices.

Parameters:

  • points (ndarray)

  • class_threshold (float)

  • cloth_resolution (float)

  • iterations (int)

  • slope_smooth (bool)

  • csf_path (str | None)

  • exists (bool)

Return type:

tuple[ndarray, ndarray, ndarray]

Returns (cloud, non_ground, ground). cloud is the subset above ground, while both index arrays refer to the original input. csf_path can save a LAS with a ground flag. With exists=True, it reads those saved flags and requires a matching point count.

SamLidar.segment(points, view=None, image_path='raster.tif', labels_path='labeled.tif', image_exists=False, label_exists=False, prompt=None, boxes=None, box_labels=None)

Project points, segment the image, and assign labels to the cloud.

With no prompt, generate masks across the image. Text and image boxes guide SAM 3 toward selected objects. A saved label raster skips model loading. Raster value 0 is background. Points on background or outside the image receive -1. Pinhole views also return the camera intrinsics and pose.

Parameters:

  • points (ndarray)

  • view (TopView | PinholeView | None)

  • image_path (str)

  • labels_path (str)

  • image_exists (bool)

  • label_exists (bool)

  • prompt (str | None)

  • boxes (ndarray | None)

  • box_labels (ndarray | None)

view defaults to TopView(). If image_exists is false, a new RGB GeoTIFF is written to image_path. If label_exists is false, SAM 3 inference writes an integer label GeoTIFF to labels_path. Both flags true reuse the files and skip model inference. prompt is text; boxes has shape (N, 4) in pixel coordinates; box_labels has one 0 or 1 per box. With no prompt or boxes, automatic mask generation is used.

Top view returns (segment_ids, labels, image). Pinhole returns (segment_ids, labels, image, intrinsics, pose). segment_ids has one element per input point. labels has shape (H, W) and image has shape (H, W, 3). The returned pose is world-to-camera. Label 0 in the raster means background; point label -1 means background or out of view.

SamLidar.write(points, segment_ids, non_ground=None, ground=None, save_path='segmented.las', ground_path=None)

Write point labels to a LAS/LAZ extra dimension named segment_id.

Parameters:

  • points (ndarray)

  • segment_ids (ndarray)

  • non_ground (ndarray | None)

  • ground (ndarray | None)

  • save_path (str)

  • ground_path (str | None)

Return type:

None

segment_ids must match points in length, except when ground and non_ground are supplied. In that case, IDs correspond to non_ground; ground points receive -1 and original order is preserved. ground_path can read saved ground flags. The output must end in .las or .laz and contains a signed 32 bit segment_id extra dimension.

Projection views

class segment_lidar.view.TopView

Orthographic top view, with the highest point visible in each pixel.

TopView.cloud_to_image(points, resolution)
Parameters:

  • points (ndarray)

  • resolution (float)

Return type:

ndarray

TopView.image_to_cloud(points, image, resolution, transform=None)
Parameters:

  • points (ndarray)

  • image (ndarray)

  • resolution (float)

Return type:

ndarray

Top view uses minimum X and maximum Y as its raster origin and chooses the highest Z point’s color at each pixel. New top view images have a GeoTIFF transform. Passing that transform to image_to_cloud lets a subset of the original cloud reuse the raster.

class segment_lidar.view.PinholeView(interactive=False)

Pinhole projection using a 4 by 4 world to camera pose and 3 by 3 intrinsics.

Parameters:

interactive (bool)

PinholeView.cloud_to_image(points, resolution=0.1, rotation=None, translation=None, intrinsics=None, distance_threshold=None, width=None, height=None)
Parameters:

  • points (ndarray)

  • resolution (float)

  • rotation (ndarray | None)

  • translation (ndarray | None)

  • intrinsics (ndarray | None)

  • distance_threshold (float | None)

  • width (int | None)

  • height (int | None)

Return type:

tuple[ndarray, ndarray, ndarray]

PinholeView.image_to_cloud(points, image, intrinsics, extrinsics, distance_threshold=None)
Parameters:

  • points (ndarray)

  • image (ndarray)

  • intrinsics (ndarray)

  • extrinsics (ndarray)

  • distance_threshold (float | None)

Return type:

ndarray

The pinhole cloud_to_image method returns (image, K, pose) and uses the nearest positive-depth point for each image pixel. image_to_cloud projects every input point back through the same camera, so points hidden behind a visible point may receive its label. See Pinhole camera guide for camera conventions and runnable examples. Interactive capture is currently not implemented.