extract_habitat_nodes

Note

This page is a reference documentation. It only explains the function signature, and not how to use it. Please refer to the Habitat Guide and Python API guide (v2.0) for usage.

extract_habitat_nodes(label_array: ndarray, connectivity: str = 'full', min_region_voxels: int = 1, erosion_radius: int = 0, subdivide_region_voxels: int = 0, block_size: int = 8, block_min_coverage: float = 0.2, node_method: Literal['uniform_grid', 'component'] = 'uniform_grid') → HabitatNodeExtractionResult[source]

Convert a habitat label map into graph nodes.

Default node_method='uniform_grid' paints a global axis-aligned lattice of cubes with edge block_size (default 8 voxels, not millimetres) over the tumour VOI. Cubes whose occupied fraction exceeds block_min_coverage (default 0.2) are kept; each connected subregion inside a kept cube becomes its own node at that subregion’s voxel-index centroid (several habitats and/or several components of one habitat can share a cube). Pass node_method='component' for the older connected-component nodes, optionally split when a component exceeds subdivide_region_voxels.

Parameters:

  • label_array – Integer habitat label map. Background must be encoded as 0.

  • connectivity – Connected-component neighborhood rule. Default "full" is 8-connected in 2D / 26-connected in 3D. Pass "face" for 4-connected / 6-connected neighborhoods. Used by component mode and by optional erosion in both modes.

  • min_region_voxels – Components / residual nodes smaller than this voxel count are ignored.

  • erosion_radius – Optional binary erosion iterations applied per habitat before node extraction. The default is 0.

  • subdivide_region_voxels – In component mode, split components larger than this into grid blocks. 0 disables splitting. Ignored by uniform_grid.

  • block_size – Cube edge length in voxels (default 8), not millimetres. With the default distance_threshold=5, face-adjacent 8-cubes connect (closest voxels are one hop apart). One empty lattice cell between cubes is closest-voxel distance about 8 and stays disconnected.

  • block_min_coverage – Minimum occupied fraction of a cube to keep the cell (default 0.2; a cube is kept when coverage is strictly greater than this value). Applied per cell, not per subregion. Tiny in-cell fragments are dropped by min_region_voxels.

  • node_method – "uniform_grid" (default) or "component".

Returns:

Nodes grouped by habitat label plus component maps used by contact-based edge builders. uniform_grid also fills grid_origin / grid_block_size for dashed overlays. Node centroids / grid_origin are in the original index space. label_array and component_maps are the VOI crop (bbox of non-zero labels plus one voxel of pad); crop_offset maps them back. Cropping does not change topology or pairwise distances.

Return type:

HabitatNodeExtractionResult