Skip to content

pointcloud

Point cloud label files: pre-labelling and writing labels into LAS/LAZ.

The app's point cloud annotator saves labels in the project keyed by each point's stable identity: the source node key (a COPC octree key such as "2-1-0-1", or "file" for a LAS/LAZ loaded whole) and the point's index within that node. This module connects those keys to a file on disk:

  • point_node_ranges maps node keys to the file's point order (COPC points are stored node by node, in the order of their chunks);
  • prelabel_point_cloud runs a Whitebox classifier on a local file and returns the changed classes as project labels, like the app's Pre-label;
  • write_labeled_point_cloud rewrites a LAS/LAZ/COPC file with the project's labels (and instance ids) applied, streaming chunk by chunk so files larger than memory work.

laspy[lazrs] (and whitebox-workflows for pre-labelling) come with the geolibre[pointcloud] extra.

PRELABEL_TOOLS module-attribute 

PRELABEL_TOOLS = {'ground': ('improved_ground_point_filter', {'classify': True}), 'ground-vegetation': ('classify_lidar', {})}

Pre-label tools: ground separates ground (2) from everything else (1); ground-vegetation also marks vegetation.

point_node_ranges 

point_node_ranges(path: str | Path) -> list[tuple[str, int, int]]

Map a point cloud file's node keys to its point order.

Parameters:

Name Type Description Default
path str | Path

A LAS, LAZ or COPC file.

 required

Returns:

Type Description
list[tuple[str, int, int]]

(node_key, first_point, point_count) for each node, in file order.
list[tuple[str, int, int]]

A plain LAS/LAZ is one "file" node holding every point.

encode_point_label_node 

encode_point_label_node(edits: dict[int, int], wide: bool = False) -> str

Encode one node's edits the way the app's label store does.

Parameters:

Name Type Description Default
edits dict[int, int]

Point index within the node -> class code (or instance id).

 required
wide bool

Encode values as varints (instance ids) instead of class bytes.

 False

Returns:

Type Description
str

base64 of raw-DEFLATE compressed (delta-varint index, value) pairs.

prelabel_point_cloud 

prelabel_point_cloud(path: str | Path, tool: str = 'ground', *, current: dict[str, dict[int, int]] | None = None, only_unclassified: bool = True, protected_classes: tuple[int, ...] = ()) -> dict[str, dict[int, int]]

Run a Whitebox classifier on a local file and return project labels.

Mirrors the app's Pre-label: the tool classifies every point in place (same count, same order), and the points it changed become label edits.

Parameters:

Name Type Description Default
path str | Path

The LAS/LAZ/COPC file the labels are for (a local copy of the project's point cloud source).

 required
tool str

"ground" or "ground-vegetation" (see PRELABEL_TOOLS).

 'ground'
current dict[str, dict[int, int]] | None

The project's existing labels for this source (node key -> {index: class}); they count as the points' current classes, so points the user already labelled are respected.

 None
only_unclassified bool

Only relabel points still 0 or 1.

 True
protected_classes tuple[int, ...]

Classes whose points keep their class.

 ()

Returns:

Type Description
dict[str, dict[int, int]]

Node key -> {index within node: new class} for the points that change.

Raises:

Type Description
ValueError

For an unknown tool, or a tool result with a different number of points.
ImportError

When whitebox-workflows or laspy is missing.

write_labeled_point_cloud 

write_labeled_point_cloud(path: str | Path, output: str | Path, labels: dict[str, dict[int, int]], instances: dict[str, dict[int, int]] | None = None, *, chunk_size: int = 1000000) -> dict[str, int]

Rewrite a point cloud file with project labels applied.

Streams the file chunk by chunk, so it works on files larger than memory. A COPC input is written as plain LAS/LAZ (by output's extension); a legacy point format (0-5) is upgraded to LAS 1.4 (6, 7, or 9/10 for the waveform formats) when a label needs a class above 31. Instance ids add a uint32 instance extra dimension, like the app's LAS export.

Parameters:

Name Type Description Default
path str | Path

The source LAS/LAZ/COPC file.

 required
output str | Path

The .las or .laz file to write.

 required
labels dict[str, dict[int, int]]

Node key -> {index within node: class}.

 required
instances dict[str, dict[int, int]] | None

Node key -> {index within node: instance id}, optional.

 None
chunk_size int

Points read and written per step.

 1000000

Returns:

Type Description
dict[str, int]

{"points", "relabelled", "instanced"} counts.

labels_for_source 

labels_for_source(project: dict[str, Any], url: str) -> tuple[dict, dict]

The labels and instance ids a project holds for one source URL.

Parameters:

Name Type Description Default
project dict[str, Any]

A project dict.

 required
url str

The point cloud's source URL.

 required

Returns:

Type Description
tuple[dict, dict]

(labels, instances), each node key -> {index within node: value}.