pchandler.geometry.splitter

Multiprocessing-based point-cloud splitters keyed on FoV trees.

The FoVTreePointCloudSplitter and the free function split_pc_with_fov_tree() accept a prefer keyword (Literal["auto", "serial", "processes"], default "auto") that controls how the per-FoV filter tasks are dispatched (Phase 4 PERF-03 / D-26 / D-27).

  • "serial" — always run the per-task loop in-process. No joblib.

  • "processes" — always dispatch through joblib.Parallel with the loky backend.

  • "auto" — pick serial when len(fov_list) <= _SERIAL_THRESHOLD and parallel otherwise. The threshold is a module-level constant (_SERIAL_THRESHOLD = 16) picked from a dev-host benchmark on which parallel never won at any tested tree size up to 435 FoVs on 100 k-point PCDs or 128 FoVs on 1 M-point PCDs (RESEARCH.md §”Plan 04-03 D-28”). loky’s per-process startup (~0.5–2.0 s plus pickling the PCD) dominates the per-task FoV-filter cost on that hardware. The default is therefore intentionally conservative.

Override the auto policy explicitly with prefer="processes" to test the parallel path on bigger hardware, or with prefer="serial" to force the inline loop regardless of tree size. The threshold is a maintainable constant — bump it in a future patch release if dev-bench on different hardware suggests another inflection.

Functions

check_number_jobs(n_jobs)

Validate the requested number of parallel jobs against the available CPU count.

split_pc_with_fov_tree(pcd, fov_tree[, ...])

Split a PointCloudData instance using a FoVTree (free-function variant).

Classes

FoVTreePointCloudSplitter

Split a point cloud into smaller subsets based on a field-of-view (FoV) tree.

PointCloudSplitter

Abstract base class for point-cloud splitting algorithms.
pchandler.geometry.splitter.check_number_jobs(n_jobs)

Validate the requested number of parallel jobs against the available CPU count.

Parameters:

n_jobs (int) – Input number of jobs.

Returns:

Validated job count (clamped to the available CPU count).

Return type:

int

class pchandler.geometry.splitter.PointCloudSplitter

Bases: ABC

Abstract base class for point-cloud splitting algorithms.

abstractmethod split(pcd)

Split a point cloud into multiple segments.

Parameters:

pcd (PointCloudData) – Point cloud to split.

Returns:

Split point cloud data. The keys are identifiers for each segment.

Return type:

dict[str, PointCloudData]

class pchandler.geometry.splitter.FoVTreePointCloudSplitter

Bases: PointCloudSplitter

Split a point cloud into smaller subsets based on a field-of-view (FoV) tree.

__init__(fov_tree, remove_empty=True, n_jobs=-1, method='iterative', prefer='auto')

Initialize the splitter with configuration options.

Parameters:

  • fov_tree (FoVTree) – FoV tree structure defining the splits

  • remove_empty (bool, default=True) – Skip tasks that result in an empty point cloud.

  • n_jobs (int, default=-1) – Number of parallel jobs to use. Defaults to all available cores.

  • method (FoVSplitMethodT) – ‘iterative’ or ‘direct’

  • prefer ({"auto", "serial", "processes"}, default="auto") – Dispatch policy for the per-FoV filter tasks (Phase 4 PERF-03 / D-26 / D-27). "auto" runs serially when len(fov_list) <= _SERIAL_THRESHOLD (= 16) and falls back to joblib.Parallel with the loky backend otherwise. "serial" forces the inline loop regardless of tree size; "processes" forces the parallel path regardless of tree size. See the module docstring for the threshold rationale.

split(pcd)

Split the point cloud based on the FoVTree.

Parameters:

pcd (PointCloudData)

Returns:

Split point cloud data. The keys are identifiers for each segment.

Return type:

dict[str, PointCloudData]

pchandler.geometry.splitter.split_pc_with_fov_tree(pcd, fov_tree, remove_empty=True, n_jobs=-1, prefer='auto')

Split a PointCloudData instance using a FoVTree (free-function variant).

This free-function variant honours the same prefer dispatch policy as FoVTreePointCloudSplitter (Phase 4 PERF-03 / D-27). The recursive child-fan-out at each tree level is dispatched either serially or through joblib.Parallel per the same _SERIAL_THRESHOLD-gated rule used by _direct_split / _iterative_split.

Parameters:

  • pcd (PointCloudData) – The point cloud data to be split.

  • fov_tree (FoVTree) – A tree structure defining the field of view regions for splitting the point cloud.

  • remove_empty (bool, default=True) – Whether to remove empty splits (i.e., regions with no points).

  • n_jobs (int, default=-1) – The number of parallel jobs to use. If -1, all available cores are used.

  • prefer ({"auto", "serial", "processes"}, default="auto") – Dispatch policy. Forwards the same semantics as FoVTreePointCloudSplitter: "auto" runs serially when the per-level fan-out has <= _SERIAL_THRESHOLD children, parallel otherwise. "serial" / "processes" force one path unconditionally.

Returns:

A dictionary where keys are FoV identifiers and values are the split PointCloudData objects.

Return type:

dict[str, PointCloudData]