API Reference

Generated from the ll_clouds package source. Each symbol links to its definition on GitHub.

class PointCloud(BaseModel)

Source: ll_clouds/ll_clouds/datamodel.py:17

An (optionally attributed) 3D point cloud.

Attributes: points: [N, 3] float coordinates (required). normals: [N, 3] per-point unit normals (optional). colors: [N, 3] per-point RGB in [0, 1] (optional). labels: [N] per-point integer labels (optional). metadata: free-form dictionary of provenance/extra info.

class RegistrationResult(BaseModel)

Source: ll_clouds/ll_clouds/datamodel.py:85

Result of a point-cloud registration (e.g. ICP).

Attributes: transformation: [4, 4] homogeneous transform mapping source -> target. fitness: fraction of source points with a correspondence (0..1). inlier_rmse: RMSE over inlier correspondences. iterations: number of iterations performed. converged: whether the convergence criterion was met.

class SegmentationResult(BaseModel)

Source: ll_clouds/ll_clouds/datamodel.py:113

Result of a segmentation/clustering.

Attributes: labels: [N] per-point integer labels (-1 = noise/unassigned). num_segments: number of distinct non-noise segments. metadata: free-form extra info (e.g. plane coefficients).

bounding_box

bounding_box(pc: PointCloud) -> tuple[np.ndarray, np.ndarray]

Source: ll_clouds/ll_clouds/features.py:67

Axis-aligned bounding box as (min_xyz, max_xyz).

centroid

centroid(pc: PointCloud) -> np.ndarray

Source: ll_clouds/ll_clouds/features.py:72

Mean position of the cloud.

estimate_curvature

estimate_curvature(pc: PointCloud, k: int = 16) -> np.ndarray

Source: ll_clouds/ll_clouds/features.py:60

Estimate per-point surface variation (curvature proxy) in [0, 1/3].

estimate_normals

estimate_normals(pc: PointCloud, k: int = 16, as_cloud: bool = False) -> np.ndarray | PointCloud

Source: ll_clouds/ll_clouds/features.py:32

Estimate unit surface normals via k-NN PCA.

Args: pc: input point cloud. k: neighbourhood size. as_cloud: if True, return a PointCloud with the normals attached; otherwise return the [N, 3] normals array.

euclidean_cluster

euclidean_cluster(pc: PointCloud, eps: float = 0.5, min_points: int = 10) -> SegmentationResult

Source: ll_clouds/ll_clouds/segmentation.py:112

Density-based (DBSCAN) Euclidean clustering.

Points are labelled by cluster id (0..K-1); isolated points that never join a dense region are labelled -1 (noise).

extent

extent(pc: PointCloud) -> np.ndarray

Source: ll_clouds/ll_clouds/features.py:77

Per-axis size (max - min) of the bounding box.

farthest_point_downsample

farthest_point_downsample(pc: PointCloud, k: int) -> PointCloud

Source: ll_clouds/ll_clouds/preprocess.py:106

Downsample to k well-spread points via farthest-point sampling.

Returns the whole cloud unchanged when k >= num_points.

icp

icp(source: PointCloud, target: PointCloud, max_iterations: int = 50, tolerance: float = 1e-08, max_correspondence_distance: float = np.inf) -> RegistrationResult

Source: ll_clouds/ll_clouds/registration.py:35

Align source to target with point-to-point ICP.

Args: source: cloud to be transformed. target: reference cloud. max_iterations: hard cap on iterations. tolerance: stop when the RMSE improvement between iterations drops below this value. max_correspondence_distance: correspondences farther than this are excluded from the reported fitness.

Returns: RegistrationResult with the cumulative source->target transform.

normalize

normalize(pc: PointCloud) -> PointCloud

Source: ll_clouds/ll_clouds/preprocess.py:27

Center on the centroid and scale to the unit sphere (max radius 1).

Idempotent: re-normalizing an already-normalized cloud is a no-op. Normals are directions, so they are passed through unchanged. An empty cloud is returned unchanged (avoids NaNs from mean/max over zero points).

ransac_plane

ransac_plane(pc: PointCloud, distance_threshold: float = 0.05, num_iterations: int = 200, seed: int = 0, min_inliers: int = 3) -> tuple[SegmentationResult, np.ndarray]

Source: ll_clouds/ll_clouds/segmentation.py:40

RANSAC plane segmentation.

Returns a SegmentationResult whose labels are 1 for plane inliers and 0 for the rest, plus the refined plane coefficients (a, b, c, d).

A plane is only reported when its inlier set is larger than min_inliers — the 3 sampled points always lie on their own candidate plane, so a genuine consensus must exceed that minimal sample. Clouds with fewer than 3 points, or with no consensus beyond the sample, yield num_segments == 0 and num_inliers == 0 (labels all 0, default plane).

read_point_cloud

read_point_cloud(path: str) -> PointCloud

Source: ll_clouds/ll_clouds/io.py:39

Read a PointCloud from path (format chosen by extension).

remove_statistical_outliers

remove_statistical_outliers(pc: PointCloud, k: int = 16, std_ratio: float = 2.0) -> PointCloud

Source: ll_clouds/ll_clouds/preprocess.py:117

Remove points whose mean distance to their k nearest neighbours is more than std_ratio standard deviations above the global mean.

sample_from_mesh

sample_from_mesh(mesh: Any, n: int, with_normals: bool = False, method: str = 'surface') -> PointCloud

Source: ll_clouds/ll_clouds/io.py:223

Sample n points from a mesh (a trimesh.Trimesh or a file path).

Args: mesh: a trimesh.Trimesh object or a path to a mesh file. n: number of points to sample. with_normals: also return the face normal at each sampled point. method: "surface" for uniform area-weighted surface sampling.

Returns: A PointCloud with n points (and normals when requested).

voxel_downsample

voxel_downsample(pc: PointCloud, voxel_size: float) -> PointCloud

Source: ll_clouds/ll_clouds/preprocess.py:51

Keep one centroid point per occupied voxel of side voxel_size.

Normals/colors are averaged per voxel (normals re-normalized); labels are dropped since they cannot be meaningfully aggregated.

write_point_cloud

write_point_cloud(pc: PointCloud, path: str) -> None

Source: ll_clouds/ll_clouds/io.py:26

Write a PointCloud to path (format chosen by extension).