tube_map

Vasculature binarization, graph construction, and vessel-type annotation.

Two pipeline workers are defined here:

BinaryVesselProcessor

Converts raw fluorescence volumes into a binary vascular mask. Steps (configurable order via the GUI pipeline widget):

1. Binarize — multi-path thresholding (Vasculature).

2. Smooth — topology-preserving binary smoothing.

3. Fill — parallel 3-D binary hole filling.

4. Deep fill — CNN-based hollow-tube filling (vessel_filling).

Multiple channels (e.g. all-vessels + arteries) are merged by combine_binary(). Step state is tracked by BinaryVesselProcessorSteps.

VesselGraphProcessor

Converts the combined binary mask into an annotated vascular graph:

1. Skeletonize — topology-preserving 3-D thinning.

2. Build — raw graph from skeleton, radius measurement, artery/vein expression sampling.

3. Clean — clique removal.

4. Reduce — degree-2 vertex contraction; edge geometry stored.

5. Register — atlas-space transform, radius scaling, annotation, distance-to-surface labelling.

6. Post-process — iterative artery/vein hysteresis tracing.

Step state is tracked by VesselGraphProcessorSteps.

Radius units

The graph processor handles three legacy precision levels (VesselGraphProcessor.RadiusLevel):

• FULL — spacing + per-axis µm radii (current).

• SCALAR_UM — spacing + scalar µm radii (intermediate legacy).

• VOXELS — voxel-space radii only (old graphs, DeprecationWarning emitted).

Typical usage

Both workers are accessed via ExperimentController:

binary = exp_ctrl.get_worker('vasculature', substep='binary')
graph  = exp_ctrl.get_worker('vasculature', substep='graph')

binary.binarize()
binary.postprocess('vessels')
binary.combine_binary()

graph.skeletonize_and_build_graph(binary_processor=binary)
graph.clean_graph()
graph.reduce_graph()
graph.register()
graph.post_process()

See also

ClearMap.ImageProcessing.Experts.Vasculature : Binarization algorithms. ClearMap.ImageProcessing.machine_learning.vessel_filling : CNN vessel filling. ClearMap.Analysis.graphs.graph_processing : Graph construction and reduction. Graph : Graph data structure. [Kirst2020].

class BinaryVesselProcessor(sample_manager: SampleManager | None = None, config_coordinator: ConfigCoordinator | None = None)

Bases: PipelineOrchestrator

static setup_channel_operation(operation)

assert_input_shapes_match()

Ensure that the input shapes (stitched images of the different color channels) match before starting the binarization process since they must overlap.

Warning

stitched may not exist when processor is created. if not, check again in the run/binarize method

assets_to_binarize() → list[Any]

binarize()

binarize_channel(channel)

channels_to_binarize()

combine_binary()

Merge the binary images of the different vascular network components into a single mask

deep_fill_channel(channel)

fill_channel(channel)

plot_binarization_result(parent=None, channel='', arrange=False)

channel str:

The channel to plot

plot_combined(parent=None, arrange=False)

plot_results(steps, channels=None, side_by_side=True, arrange=True, parent=None)

plot_vessel_filling_results(parent=None, channel='', arrange=False)

post_process_binary_combined()

Postprocess the combined binary image (typically smooth and fill)

postprocess(channel: str) → None

Run post-processing steps (smooth, fill, deep_fill) for channel in the order declared by step_order in the config.

Binarize is always the first step and is excluded here — it runs via binarize() / binarize_channel() before postprocess is called.

run()

Execute the full processing pipeline for this orchestrator.

Raises:

NotImplementedError – Must be implemented by every concrete subclass.

setup(sample_manager=None)

Attach a sample manager and mark this processor as ready.

Parameters:

sample_manager (SampleManager, optional) – If provided, replaces the currently stored sample manager. When None, the previously stored instance is reused.

Raises:

ValueError – If the config section identified by config_name is absent.

smooth_channel(channel)

config_name = 'vasculature'

class BinaryVesselProcessorSteps(workspace, channel, config_provider: Callable[[], dict] | None = None)

Bases: ProcessorSteps

asset_from_step_name(step)

Return the on-disk asset that corresponds to step_name.

Parameters:

step_name (str) – A member of steps.

Returns

Asset

The asset associated with that step.

Raises:

NotImplementedError – Must be implemented by every concrete subclass.

consume_and_cleanup() → None

Delete the pending temp file once the next step has consumed its input.

get_last_output() → Path | str

Return the last available output path, used by combine_binary.

get_source(current_asset: str) → Path | str

Walk backward from current_asset through the configured (non-lifecycle) step order and return the first available backing path.

Precedence per previous step:

1. In-memory result stored by record_output (is-not-None guard)

2. On-disk asset

3. Raw binary (fallback)

Callers reconstruct the Source with clearmap_io.

record_output(asset: str, output: Any, temp_path: str = '', keep: bool = False) → None

Store the backing path of a completed step.

Source objects are serialisable path handles — we extract .path so _outputs holds only plain Paths, never live Source instances. clearmap_io reconstructs on demand.

binary = 'binary'

combined = 'combined'

deep_filled = 'deep_filled'

filled = 'filled'

final = 'final'

smoothed = 'smoothed'

property steps: tuple[str, ...]

Compute step order fresh on each access — reflects any GUI reordering committed to config since construction.

stitched = 'stitched'

class VesselGraphProcessor(sample_manager: SampleManager | None = None, config_coordinator: ConfigCoordinator | None = None, registration_processor: RegistrationProcessor | None = None)

Bases: PipelineOrchestrator

The graph contains the following edge properties:

• artery_raw

• artery_binary

• artery

• vein

• radii

• distance_to_surface

class RadiusLevel(value)

Bases: Enum

FULL = 'full'

SCALAR_UM = 'scalar_um'

VOXELS = 'voxels'

static reload_processing_config(operation)

static requires_binary(asset_sub_type)

static requires_graph(step)

clean_graph(graph_cfg=None)

get_filter(graph_step, filter_type, property_name, value)

Get a filter object for the graph step

Parameters:

• graph_step (str) – The graph step to filter (e.g. ‘annotated’, ‘reduced’)

• filter_type (str) – The type of filter to apply (e.g. ‘vertex’, ‘edge’)

• property_name (str) – The property name to filter on (e.g. ‘artery’, ‘vein’, ‘radii’)

• value (int | float | bool | str | tuple) –

  The value to filter by. Can be:

  • int/float: exact match

  • str: string match (e.g. ‘artery’, ‘vein’)

  • bool: ‘True’ or ‘False’ for boolean properties

  • tuple: range (min, max) for numerical properties. None means open-ended range.

Returns

GraphFilter

A filter object for the graph step

get_registration_sequence_channels()

get_structure_sub_graph(structure_id)

plot_graph_chunk(graph_chunk, plot_type='mesh', title='sub graph', region_color=None, show=True, n_max_vertices=300000)

plot_graph_structure(structure_id, plot_type)

plot_voxelization(parent)

post_process()

Iteratively refine arteries and veins based on one another.

Delegates to VesselClassifier which encapsulates the full iterative classification algorithm.

pre_process()

reduce_graph(vertex_to_edge_mapping=None, edge_to_edge_mappings=None, graph_cfg=None)

register(graph_cfg=None)

run()

Execute the full processing pipeline for this orchestrator.

Raises:

NotImplementedError – Must be implemented by every concrete subclass.

save_graph(base_name)

setup(sample_manager=None, registration_processor=None)

Attach a sample manager and mark this processor as ready.

Parameters:

sample_manager (SampleManager, optional) – If provided, replaces the currently stored sample manager. When None, the previously stored instance is reused.

Raises:

ValueError – If the config section identified by config_name is absent.

skeletonize(binary_processor=None)

skeletonize_and_build_graph(graph_cfg=None, binary_processor=None)

unload_temporary_graphs()

To free up memory

Returns

visualize_graph_annotations(chunk_range, plot_type='mesh', graph_step='reduced', show=True)

voxelize(weight_by_radius=False, vertex_degrees=None, filters=None, operators=None)

write_vertex_table()

Write a table with vertex coordinates and properties

property arteries_channel: str

property binary_shape

config_name = 'vasculature'

property graph_annotated

property graph_cleaned

property graph_raw

property graph_reduced

property graph_traced

registration_processor: RegistrationProcessor | None

property resampled_shape

sample_manager: SampleManager | None

steps: VesselGraphProcessorSteps

property use_arteries_for_graph

property veins_channel: str

workspace: Workspace2 | None

class VesselGraphProcessorSteps(workspace: ClearMap.IO.workspace2.Workspace2, channel: str | Sequence[str] = '', step_order_provider: Callable[[], tuple[str, ...]] | None = None)

Bases: ProcessorSteps

asset_from_step_name(step)

Return the on-disk asset that corresponds to step_name.

Parameters:

step_name (str) – A member of steps.

Returns

Asset

The asset associated with that step.

Raises:

NotImplementedError – Must be implemented by every concrete subclass.

graph_annotated = 'annotated'

graph_cleaned = 'cleaned'

graph_raw = 'raw'

graph_reduced = 'reduced'