Usage

GUI (recommended)

The simplest way to use ClearMap is through the Graphical User Interface:

conda activate ClearMap3.1
clearmap-ui

The GUI guides you through every pipeline step — sample configuration, stitching, registration, cell detection, and vasculature analysis — and writes all results to a workspace directory.

See GUI usage for a full walkthrough.

Scripted / headless use

For batch processing or HPC environments, use the new-API scripts.

conda activate ClearMap3.1

# Cell detection
python -m ClearMap.Scripts.cell_map_new_api /path/to/experiment

# Vasculature
python -m ClearMap.Scripts.tube_map_new_api /path/to/experiment

Both scripts call init_sample_manager_and_processors() to initialise the experiment, then run stitching, registration, and pipeline-specific steps. Edit the YAML config files in your experiment folder to control parameters rather than editing the scripts themselves.

Cell detection (CellMap)

Listing 1 ClearMap/Scripts/cell_map_new_api.py

"""
cell_map_new_api
================

Headless entry point for the CellMap pipeline (cell detection and density mapping).

This script replaces the deprecated :mod:`ClearMap.Scripts.CellMap`.
It initialises a sample from the experiment directory, runs stitching and
atlas registration, then detects cells, filters them, aligns coordinates to
atlas space, and produces voxelized density maps for every CellMap channel.

Usage
-----

.. code-block:: bash

    conda activate ClearMap3.1
    python -m ClearMap.Scripts.cell_map_new_api /path/to/experiment

The experiment directory must contain a ``sample.yml`` config file (created
by the GUI or by copying from ``~/.clearmap/defaults/``).  All pipeline
parameters are read from the YAML files in that directory; no editing of
this script is required.

Steps performed
---------------
1. **Stitching** — assembles tiles into a single volume for each channel.
2. **Registration** — resamples the autofluorescence channel and aligns it
   to the atlas via Elastix.
3. **Cell detection** (per CellMap channel) —

   a. :meth:`~ClearMap.pipeline_orchestrators.cell_map.CellDetector.run_cell_detection`
      — background subtraction, maxima detection, shape-based watershed.
   b. :meth:`~ClearMap.pipeline_orchestrators.cell_map.CellDetector.post_process_cells`
      — intensity/size filtering and atlas-space coordinate alignment.
   c. :meth:`~ClearMap.pipeline_orchestrators.cell_map.CellDetector.voxelize`
      — rasterise cell positions into a density volume.
   d. Plots the density map and a 3-D scatter of cells coloured by atlas region.

Outputs (written to the experiment directory via the workspace)
---------------------------------------------------------------
* ``cells_raw.npy`` — raw detected cell table per channel
* ``cells_filtered.npy`` — filtered cell table
* ``cells.feather`` — atlas-annotated cell table (coordinates + region labels)
* ``cells_stats.csv`` — per-structure cell counts and average sizes
* ``density_counts.tif`` — voxelized cell density in atlas space

See also
--------
:class:`~ClearMap.pipeline_orchestrators.cell_map.CellDetector` :
    The worker class that implements each detection step.
:func:`~ClearMap.pipeline_orchestrators.utils.init_sample_manager_and_processors` :
    Convenience factory used to initialise all standard workers.
:doc:`/cellmap` :
    Full CellMap pipeline documentation.
"""
import sys

from ClearMap.pipeline_orchestrators.utils import init_sample_manager_and_processors
from ClearMap.pipeline_orchestrators.cell_map import CellDetector

from ClearMap.Scripts.align_new_api import plot_registration_results, register, stitch


def main(src_directory):
    orchestrators = init_sample_manager_and_processors(src_directory)
    sample_manager = orchestrators['sample_manager']
    stitcher = orchestrators['stitcher']
    registration_processor = orchestrators['registration_processor']

    stitch(stitcher)
    stitcher.plot_stitching_results(mode='overlay')

    register(registration_processor)
    plot_registration_results(registration_processor, sample_manager.alignment_reference_channel)

    for channel in sample_manager.get_channels_by_pipeline('CellMap', as_list=True):
        cell_detector = CellDetector(sample_manager, config_coordinator=sample_manager.cfg_coordinator,
                                     channel=channel, registration_processor=registration_processor)
        # TEST CELL DETECTION
        # slicing = (
        #    slice(*cell_detector.processing_config['test_set_slicing']['dim_0']),
        #    slice(*cell_detector.processing_config['test_set_slicing']['dim_1']),
        #    slice(*cell_detector.processing_config['test_set_slicing']['dim_2'])
        # )
        # cell_detector.create_test_dataset(slicing=[......])
        # print('Cell detection preview')
        # cell_detector.run_cell_detection(tuning=True)
        # dvs = cell_detector.preview_cell_detection(arrange=True, sync=True)
        # link_dataviewers_cursors(dvs, RedCross)

        print('Starting cell detection')
        cell_detector.run_cell_detection(tuning=False)
        cell_detector.post_process_cells()
        cell_detector.voxelize()
        cell_detector.plot_voxelized_counts(arrange=True)
        print('Cell detection done')

        cell_detector.plot_cells_3d_scatter_w_atlas_colors()


if __name__ == '__main__':
    main(sys.argv[1])

Vasculature (TubeMap)

Listing 2 ClearMap/Scripts/tube_map_new_api.py

"""
tube_map_new_api
================

Headless entry point for the TubeMap pipeline (vasculature binarization,
graph construction, and annotation).

This script replaces the deprecated :mod:`ClearMap.Scripts.TubeMap`.
It initialises a sample from the experiment directory, runs stitching and
atlas registration, then binarizes each vessel channel, merges the binary
masks, and builds an annotated vasculature graph.

Usage
-----

.. code-block:: bash

    conda activate ClearMap3.1
    python -m ClearMap.Scripts.tube_map_new_api /path/to/experiment

The experiment directory must contain a ``sample.yml`` config file (created
by the GUI or by copying from ``~/.clearmap/defaults/``).  All pipeline
parameters are read from the YAML files in that directory; no editing of
this script is required.

Steps performed
---------------
1. **Stitching** — assembles tiles into a single volume for each channel.
2. **Registration** — resamples the autofluorescence channel and aligns it
   to the atlas via Elastix.
3. **Binarization** (per TubeMap channel) —

   a. :meth:`~ClearMap.pipeline_orchestrators.tube_map.BinaryVesselProcessor.binarize_channel`
      — multi-path thresholding.
   b. :meth:`~ClearMap.pipeline_orchestrators.tube_map.BinaryVesselProcessor.smooth_channel`
      — topology-preserving binary smoothing.
   c. :meth:`~ClearMap.pipeline_orchestrators.tube_map.BinaryVesselProcessor.fill_channel`
      — parallel 3-D binary hole filling.
   d. :meth:`~ClearMap.pipeline_orchestrators.tube_map.BinaryVesselProcessor.deep_fill_channel`
      — CNN-based hollow-tube filling (requires GPU with ≥ 24 GB VRAM).

4. :meth:`~ClearMap.pipeline_orchestrators.tube_map.BinaryVesselProcessor.combine_binary`
   — logical-OR merge of all channel masks into a single combined binary.
5. **Graph construction** —

   a. :meth:`~ClearMap.pipeline_orchestrators.tube_map.VesselGraphProcessor.pre_process`
      — skeletonize → build raw graph → clean → reduce → register to atlas.
   b. :meth:`~ClearMap.pipeline_orchestrators.tube_map.VesselGraphProcessor.post_process`
      — iterative artery/vein tracing and capillary removal (if artery channel present).
   c. :meth:`~ClearMap.pipeline_orchestrators.tube_map.VesselGraphProcessor.voxelize`
      — rasterise graph vertices into a branch density volume.

Outputs (written to the experiment directory via the workspace)
---------------------------------------------------------------
* ``binary.npy`` / ``binary_smoothed.npy`` / … — intermediate binary masks
* ``binary_combined.npy`` — merged vessel mask
* ``skeleton.npy`` — skeletonized binary
* ``graph_raw.gt`` / ``graph_cleaned.gt`` / ``graph_reduced.gt`` / ``graph_annotated.gt``
  — graph at each construction stage
* ``density_branches.tif`` — voxelized vessel density in atlas space
* ``vertices.feather`` — vertex table with coordinates, radii, and atlas labels

See also
--------
:class:`~ClearMap.pipeline_orchestrators.tube_map.BinaryVesselProcessor` :
    Binarization worker.
:class:`~ClearMap.pipeline_orchestrators.tube_map.VesselGraphProcessor` :
    Graph construction and annotation worker.
:func:`~ClearMap.pipeline_orchestrators.utils.init_sample_manager_and_processors` :
    Convenience factory used to initialise all standard workers.
:doc:`/tubemap` :
    Full TubeMap pipeline documentation.
"""
import sys

from ClearMap.pipeline_orchestrators.utils import init_sample_manager_and_processors
from ClearMap.pipeline_orchestrators.tube_map import BinaryVesselProcessor, VesselGraphProcessor

from ClearMap.Scripts.align_new_api import stitch, register, plot_registration_results


def main(src_directory):
    orchestrators = init_sample_manager_and_processors(src_directory)
    sample_manager = orchestrators['sample_manager']
    stitcher = orchestrators['stitcher']
    registration_processor = orchestrators['registration_processor']

    stitch(stitcher)
    stitcher.plot_stitching_results(mode='overlay')

    register(registration_processor)
    plot_registration_results(registration_processor, sample_manager.alignment_reference_channel)

    binary_vessel_processor = BinaryVesselProcessor(sample_manager,
                                                    config_coordinator=sample_manager.cfg_coordinator)

    for channel in sample_manager.get_channels_by_pipeline('TubeMap', as_list=True):
        binary_vessel_processor.binarize_channel(channel)
        binary_vessel_processor.smooth_channel(channel)
        binary_vessel_processor.fill_channel(channel)
        binary_vessel_processor.deep_fill_channel(channel)

    binary_vessel_processor.combine_binary()
    # binary_vessel_processor.plot_combined(arrange=True)

    vessel_graph_processor = VesselGraphProcessor(sample_manager, config_coordinator=sample_manager.cfg_coordinator,
                                                  registration_processor=registration_processor)
    vessel_graph_processor.pre_process()
    # TODO: slice
    vessel_graph_processor.post_process()
    vessel_graph_processor.voxelize()
    # vessel_graph_processor.plot_voxelization(None)


if __name__ == '__main__':
    main(sys.argv[1])

See CellMap and TubeMap for pipeline-specific documentation.

Interactive / console use

For exploratory analysis in IPython, Jupyter, or an IDE, import only what you need:

# IO — read and write any supported format
import ClearMap.IO.IO as io

data   = io.read('volume.npy')
source = io.as_source('volume.tif', slicing=(slice(0, 100),))
print(source.shape, source.dtype)
io.write('output.tif', data)

# Workspace and sample manager
from ClearMap.pipeline_orchestrators.sample_info_management import build_sample_manager

sm  = build_sample_manager('/path/to/experiment')
raw = sm.get('raw', channel='cfos')
print(raw.is_tiled, raw.tile_grid_shape)

# Graph analysis
from ClearMap.Analysis.graphs.graph_gt import Graph

g = Graph.load('/path/to/graph.gt')
print(g.n_vertices, g.n_edges)

# 3-D visualisation
import ClearMap.Visualization.Qt.Plot3d as plot_3d

plot_3d.plot('volume.tif')

Note

On first run, Cython sub-modules are compiled on demand. This takes 10–30 minutes but only happens once per installation.

Deprecated since version 3.1.0: from ClearMap.Environment import * (the old convenience namespace) is no longer recommended. Wildcard imports from large packages make dependencies opaque and break static analysis tools. Use explicit imports as shown above.

Deprecated scripts

Deprecated since version 2.1.0: The monolithic scripts below are retained for reference but will be removed in a future release. Use the new-API scripts or the GUI instead.

Script	Documentation	Replacement
CellMap	CellMap	cell_map_new_api
TubeMap	TubeMap	tube_map_new_api

See Migrating from ClearMap 2 for a full comparison of the old and new APIs.