Vasculature

Expert vasculature image processing pipeline.

This module provides the basic routines for processing vasculature data. The routines are used in the ClearMap.Scripts.TubeMap pipeline.

binarize(source, sink=None, binarization_parameter={'adaptive': {'interpolate': 1, 'save': False, 'selem': (250, 250, 3), 'spacing': (50, 50, 3)}, 'binary_status': None, 'clip': {'clip_range': (400, 60000), 'save': False}, 'deconvolve': {'save': False, 'sigma': 10, 'threshold': 750}, 'equalize': {'interpolate': 1, 'percentile': (0.4, 0.975), 'save': False, 'selem': (200, 200, 5), 'spacing': (50, 50, 5), 'threshold': 1.1}, 'fill': None, 'lightsheet': {'background': {'interpolate': 1, 'selem': (200, 200, 1), 'spacing': (25, 25, 1), 'step': (2, 2, 1)}, 'lightsheet': {'selem': (150, 1, 1)}, 'lightsheet_vs_background': 2, 'percentile': 0.25, 'save': False}, 'max_bin': 4096, 'median': {'save': False, 'selem': (3, 3, 3)}, 'smooth': None, 'vesselize': {'background': {'percentile': 0.5, 'selem': ('disk', (30, 30, 1))}, 'save': False, 'threshold': 120, 'tubeness': {'gamma12': 0.0, 'sigma': 1.0}}}, processing_parameter={'axes': [2], 'optimization': True, 'optimization_fix': 'all', 'overlap': 0, 'processes': None, 'size_max': 40, 'size_min': 5, 'verbose': None})

Multi-path binarization of iDISCO+ cleared vasculature data.

Arguments

sourcesource specification

The source of the stitched raw data.

sinksink specification or None

The sink to write the result to. If None, an array is returned.

binarization_parameterdict

Parameter for the binarization. See below for details.

processing_parameterdict

Parameter for the parallel processing. See ClearMap.ParallelProcessing.BlockProcesing.process() for description of all the parameter.

verbosebool

If True, print progress output.

Returns

sinkSource

The result of the binarization.

Notes

• The binarization pipeline is composed of several steps. The parameters for each step are passed as sub-dictionaries to the binarization_parameter dictionary.

• If None is passed for one of the steps this step is skipped.

• Each step also has an additional parameter ‘save’ that enables saving of the result of that step to a file to inspect the pipeline.

General parameter

binary_statusstr or None

File name to save the information about which part of the multi-path binarization contributed to the final result.

max_binint

Number of intensity levels to use for the data after preprocessing. Higher values will increase the intensity resolution but slow down processing.

For the vasculature a typical value is 2**12.

Clipping

clipdict or None

Clipping and mask generation step parameter.

clip_rangetuple

The range to clip the raw data as (lowest, highest) Voxels above lowest define the foregournd mask used in the following steps.

For the vasculature a typical value is (400,60000).

savestr or None

Save the result of this step to the specified file if not None.

See also ClearMap.ImageProcessing.Clipping.Clipping

Lightsheet correction

lightsheetdict or None

Lightsheet correction step parameter.

percentilefloat

Percentile in [0,1] used to estimate the lightshieet artifact.

For the vasculature a typical value is 0.25.

lightsheetdict

Parameter for the ligthsheet artifact percentile estimation. See ClearMap.ImageProcessing.LightsheetCorrection.correct_lightsheet() for list of all parameters. The crucial parameter is

selemtuple

The structural element shape used to estimate the stripe artifact. It should match the typical lenght, width, and depth of the artifact in the data.

For the vasculature a typical value is (150,1,1).

backgrounddict

Parameter for the background estimation in the light sheet correction. See ClearMap.ImageProcessing.LightsheetCorrection.correct_lightsheet() for list of all parameters. The crucial parameters are

selemtuple

The structural element shape used to estimate the background. It should be bigger than the largest vessels,

For the vasculature a typical value is (200,200,1).

spacingtuple

The spacing to use to estimate the background. Larger spacings speed up processing but become less local estimates.

For the vasculature a typical value is (25,25,1)

steptuple

This parameter enables to subsample from the entire array defined by the structural element using larger than single voxel steps.

For the vasculature a typical value is (2,2,1).

interpolateint

The order of the interpoltation used in constructing the full background estimate in case a non-trivial spacing is used.

For the vasculature a typical value is 1.

lightsheet_vs_backgroundfloat

The background is multiplied by this weight before comparing to the lightsheet artifact estimate.

For the vasculature a typical value is 2.

savestr or None

Save the result of this step to the specified file if not None.

Median filter

mediandict or None

Median correction step parameter. See ClearMap.ImageProcessing.Filter.Rank.median() for all parameter. The important parameters are

selemtuple

The structural element size for the median filter.

For the vascualture a typical value is (3,3,3).

savestr or None

Save the result of this step to the specified file if not None.

Pseudo Deconvolution

deconvolvedict

The deconvolution step parameter.

sigmafloat

The std of a Gaussina filter applied to the high intensity pixel image. The number should reflect the scale of the halo effect seen around high intensity structures.

For the vasculature a typical value is 10.

savestr or None

Save the result of this step to the specified file if not None.

thresholdfloat

Voxels above this threshold will be added to the binarization result in the multi-path biniarization.

For the vasculature a typical value is 750.

Adaptive Thresholding

adaptivedict or None

Adaptive thresholding step parameter. A local ISODATA threshold is estimated. See also ClearMap.ImageProcessing.LocalStatistics.

selemtuple

The structural element size to estimate the percentiles. Should be larger than the larger vessels.

For the vasculature a typical value is (200,200,5).

spacingtuple

The spacing used to move the structural elements. Larger spacings speed up processing but become locally less precise.

For the vasculature a typical value is (50,50,5)

interpolateint

The order of the interpoltation used in constructing the full background estimate in case a non-trivial spacing is used.

For the vasculature a typical value is 1.

savestr or None

Save the result of this step to the specified file if not None.

Equalization

equalizedict or None

Equalization step parameter. See also ClearMap.ImageProcessing.LocalStatistics.local_percentile()

precentiletuple

The lower and upper percentiles used to estimate the equalization. The lower percentile is used for normalization, the upper to limit the maximal boost to a maximal intensity above this percentile.

For the vasculature a typical value is (0.4, 0.975).

max_valuefloat

The maximal intensity value in the equalized image.

For the vasculature a typical value is 1.5.

selemtuple

The structural element size to estimate the percentiles. Should be larger than the larger vessels.

For the vasculature a typical value is (200,200,5).

spacingtuple

The spacing used to move the structural elements. Larger spacings speed up processing but become locally less precise.

For the vasculature a typical value is (50,50,5)

interpolateint

The order of the interpoltation used in constructing the full background estimate in case a non-trivial spacing is used.

For the vasculature a typical value is 1.

savestr or None

Save the result of this step to the specified file if not None.

thresholdfloat

Voxels above this threshold will be added to the binarization result in the multi-path biniarization.

For the vasculature a typical value is 1.1.

Tube filter

vesselizedict

The tube filter step parameter.

backgrounddict or None

Parameters to correct for local background. See ClearMap.ImageProcessing.Filter.Rank.percentile(). If None, no background correction is done before the tube filter.

selemtuple

The structural element specification to estimate the percentiles. Should be larger than the largest vessels intended to be boosted by the tube filter.

For the vasculature a typical value is (‘disk’, (30,30,1)) .

percentilefloat

Percentile in [0,1] used to estimate the background.

For the vasculature a typical value is 0.5.

tubnessdict

Parameters used for the tube filter. See ClearMap.ImageProcessing.Differentiation.Hessian.lambda123().

sigmafloat

The scale of the vessels to boos in the filter.

For the vasculature a typical value is 1.0.

savestr or None

Save the result of this step to the specified file if not None.

thresholdfloat

Voxels above this threshold will be added to the binarization result in the multi-path biniarization.

For the vasculature a typical value is 120.

Binary filling

filldict or None

If not None, apply a binary filling the binarized result.

For the vasculature this step is set to None and done globally in the postprocessing step.

Binary smoothing

smoothdict or None

The smoothing parameter passed to ClearMap.ImageProcessing.Binary.Smoothing.smooth_by_configuration().

For the vasculature this step is set to None and done globally in the postprocessing step.

References

[1] C. Kirst et al., “Mapping the Fine-Scale Organization and Plasticity of the Brain Vasculature”, Cell 180, 780 (2020)

binarize_block(source, sink, parameter={'adaptive': {'interpolate': 1, 'save': False, 'selem': (250, 250, 3), 'spacing': (50, 50, 3)}, 'binary_status': None, 'clip': {'clip_range': (400, 60000), 'save': False}, 'deconvolve': {'save': False, 'sigma': 10, 'threshold': 750}, 'equalize': {'interpolate': 1, 'percentile': (0.4, 0.975), 'save': False, 'selem': (200, 200, 5), 'spacing': (50, 50, 5), 'threshold': 1.1}, 'fill': None, 'lightsheet': {'background': {'interpolate': 1, 'selem': (200, 200, 1), 'spacing': (25, 25, 1), 'step': (2, 2, 1)}, 'lightsheet': {'selem': (150, 1, 1)}, 'lightsheet_vs_background': 2, 'percentile': 0.25, 'save': False}, 'max_bin': 4096, 'median': {'save': False, 'selem': (3, 3, 3)}, 'smooth': None, 'vesselize': {'background': {'percentile': 0.5, 'selem': ('disk', (30, 30, 1))}, 'save': False, 'threshold': 120, 'tubeness': {'gamma12': 0.0, 'sigma': 1.0}}})

Binarize a Block.

binary_statistics(source)

Counts the binarization types.

Arguments

sourcearray

The status array of the binarization process.

Returns

statisticsdict

A dict with entires {description : count}.

clip(source, clip_range=(300, 60000), norm=4096, dtype='uint16')

deconvolve(source, binarized, sigma=10)

equalize(source, percentile=(0.5, 0.95), max_value=1.5, selem=(200, 200, 5), spacing=(50, 50, 5), interpolate=1, mask=None)

postprocess(source, sink=None, postprocessing_parameter={'fill': True, 'smooth': {'iterations': 6}, 'temporary_filename': None}, processing_parameter={'as_memory': True, 'optimization': True, 'optimization_fix': 'all', 'overlap': None, 'size_min': None}, processes=None, verbose=True)

Postprocess a binarized image.

Arguments

sourcesource specification

The binary source.

sinksink specification or None

The sink to write the postprocesses result to. If None, an array is returned.

postprocessing_parameterdict

Parameter for the postprocessing.

processing_parameterdict

Parameter for the parallel processing.

verbosebool

If True, print progress output.

Returns

sinkSource

The result of the binarization.

Notes

• The postporcessing pipeline is composed of several steps. The parameters for each step are passed as sub-dictionaries to the postprocessing_parameter dictionary.

• If None is passed for one of the steps the step is skipped.

Smoothing

smoothdict or None

Smoothing step parameter. See ClearMap.ImageProcessing.Binary.Smoothing.smooth_by_configuration()

iterationsint

Number of smoothing iterations.

For the vasculature a typical value is 6.

Filling

fillbool or None

If True, fill holes in the binary data.

status_to_description(status)

Converts a status int to its description.

Arguments

statusint

The status.

Returns

descriptionstr

The description corresponding to the status.

threshold_adaptive(source, function=<function threshold_isodata>, selem=(100, 100, 3), spacing=(25, 25, 3), interpolate=1, mask=None, step=None)

threshold_isodata(source)

tubify(source, sigma=1.0, gamma12=1.0, gamma23=1.0, alpha=0.25)

BINARY_NAMES = ['High', 'Equalized', 'Deconvolved', 'Adaptive', 'Tube', 'Fill', 'Tracing']

Names for the multi-path binarization steps.

BINARY_STATUS = {'Adaptive': 8, 'Deconvolved': 4, 'Equalized': 2, 'Fill': 32, 'High': 1, 'Tracing': 64, 'Tube': 16}

Binary representation for the multi-path binarization steps.

DTYPE = 'uint16'

Data type for the data after preprocessing.

Note

• The data type should fit numbers as big as the MAX_BIN parameter.

• ‘uint16’ is a good choice for the vasculature data.

MAX_BIN = 4096

Number of intensity levels to use for the data after preprocessing.

Note

• Higher values will increase the intensity resolution but slow down processing.

• 2**12 is a good choice for the vasculature data.

default_binarization_parameter = {'adaptive': {'interpolate': 1, 'save': False, 'selem': (250, 250, 3), 'spacing': (50, 50, 3)}, 'binary_status': None, 'clip': {'clip_range': (400, 60000), 'save': False}, 'deconvolve': {'save': False, 'sigma': 10, 'threshold': 750}, 'equalize': {'interpolate': 1, 'percentile': (0.4, 0.975), 'save': False, 'selem': (200, 200, 5), 'spacing': (50, 50, 5), 'threshold': 1.1}, 'fill': None, 'lightsheet': {'background': {'interpolate': 1, 'selem': (200, 200, 1), 'spacing': (25, 25, 1), 'step': (2, 2, 1)}, 'lightsheet': {'selem': (150, 1, 1)}, 'lightsheet_vs_background': 2, 'percentile': 0.25, 'save': False}, 'max_bin': 4096, 'median': {'save': False, 'selem': (3, 3, 3)}, 'smooth': None, 'vesselize': {'background': {'percentile': 0.5, 'selem': ('disk', (30, 30, 1))}, 'save': False, 'threshold': 120, 'tubeness': {'gamma12': 0.0, 'sigma': 1.0}}}

Parameter for the vasculature binarization pipeline. See binarize() for details.

default_binarization_processing_parameter = {'axes': [2], 'optimization': True, 'optimization_fix': 'all', 'overlap': 0, 'processes': None, 'size_max': 40, 'size_min': 5, 'verbose': None}

Parallel processing parameter for the vasculature binarization pipeline. See ClearMap.ParallelProcessing.BlockProcessing.process(). for details.

default_postprocessing_parameter = {'fill': True, 'smooth': {'iterations': 6}, 'temporary_filename': None}

Parameter for the postprocessing step of the binarized data. See postprocess() for details.

default_postprocessing_processing_parameter = {'as_memory': True, 'optimization': True, 'optimization_fix': 'all', 'overlap': None, 'size_min': None}

Parallel processing parameter for the vasculature postprocessing pipeline. See ClearMap.ParallelProcessing.BlockProcessing.process(). for details.