Table Of Contents

Previous topic

Reconstruction analysis API

Next topic

4-D Reconstruction User Guide

This Page

Asclepios Reference Guide

The Asclepios subpackage serves as a swiss-army toolkit for MARS ALT as it implements many image processing routines used throughout the pipeline. The code is contributed by the INRIA Asclepios Team.

Registration

baladin(ref, flo, inivox=None, inireel=None, vsf=None, vsr=None, ltf=None, htf=None, ltr=None, htr=None, fbr=None, fbf=None, transformation=None, estimator=None, ltscut=None, similarity_measure=None, tsi=None, nbiter=None, rms=None, bld=None, blp=None, blb=None, bldv=None, blpv=None, v=None, vd=None, vs=None, nov=None, pyn=None, pys=None, pyfilt=None, auto=None, inv=None, stop=None, only_register=False)[source]

It processes to an automated linear registration method using a block-matching based method.

The principle of this method is to pair sub-images (or blocks) between both images to be registered and then to compute a transformation that explains the obtained pairings. Pairing is achieved by maximizing the correlation coefficient between blocks of the two images, while the rigid transformation that best superimposes them is computed by minimizing the squared distances between the paired blocks centers. This is iterated until convergence, and embedded into a multi-scale strategy.

Controling the output:
 

By default an image is resampled (either the floating or the reference depending on the inv. If you just want only to compute the transformation, pass only_register=True. (The returned value will still be a tuple, but the first element will be None instead of an image).

By default too the returned matrix is inverted - from (floating_image)’ to floating_image. This is undesired if you want to use the matrix in a matrix composition. If you want the direct matrix pass direct_matrix=True.

Parameters :
  • ref (SpatialImage) - reference image

  • flo (SpatialImage) - floating image

  • inivox (numpy.ndarray) - initial matrix : name of the initial transformation (voxel coordinates) from reference to floating

  • inireel (numpy.ndarray) - initial real matrix : name of the initial transformation (coordinates of the ‘real world’)

  • vsf (float,float,float) - voxel size of the floating image overrides the one given in the image header (if any)

  • vsr (float,float,float) - voxel size of the reference image overrides the one given in the image header (if any)

  • ltf (int) - low threshold for the floating image

  • htf (int) - high threshold for the floating image

    points of the floating image that will be considered have a value strictly superior to the low threshold and strictly inferior to the high threshold

  • ltr (int) - low threshold for the reference image

    points of the reference image that will be considered have a value strictly superior to the low threshold and strictly inferior to the high threshold

  • htr (int) - high threshold for the reference image

  • fbr (float) - fraction block reference : A block of the reference image will be considered if it contains at least

    this fraction of voxels with an intensity between the low and the high threshold (default is 0.5)

  • fbf (float) - fraction block floating : A block of the floating image will be considered if it contains at least

    this fraction of voxels with an intensity between the low and the high threshold

  • transformation (str) - type of transformation, choices are :
    • rigi[d],
    • simi[litude],
    • affi[ne
  • estimator (str) - type of estimator, choices are :
    • ltsw: Weighted Least Trimmed Squares
    • lts: Least Trimmed Squares
    • lsw: Weighted Least Squares
    • ls: Least Squares
  • ltscut (float) - cutting value for (weighted) least trimmed squares

  • similarity_measure (str) - type of similarity measure, choices are
    • cc: correlation coefficient
    • ecc: extended correlation coefficient
  • tsi (float) - threshold on the similarity measure : pairings below that threshold will not be considered

  • nbiter (int) - maximum number of iterations at one level of the pyramid

  • rms (bool) - use the RMS as an end condition at each pyramid level

  • bld (int,int,int) - block sizes : sizes of the blocks along X, Y, Z

  • blp (int,int,int) - block-spacing : block spacing in the floating image

  • blb (int,int,int) - blocks borders: to be added twice at each dimension for statistics computation

  • bldv (int,int,int) - block neighborhood sizes : sizes of the exploration neighborhood around a block

  • blpv (int,int,int) - block-steps : progression-step in the exploration neighborhood

  • v (float) - fraction variance blocks : consider only a fraction of all the blocks (the ones with the highest variance) at the coarser

    level of the pyramid

  • vd (float) - decrement fraction variance blocks : the decrement of this fraction from one level of the pyramid to the next (default is 0.2)

  • vs (float) - minimum fraction variance blocks : the minimum admissible value of this fraction

  • nov (bool) - no fraction variance blocks : do not decrease the initial value of this fraction.

    The constant value of the fraction is set to 1.0 but can be changed afterwards with ‘-fraction-variance-blocks’

  • pyn (int) - pyramid levels : number of levels of the pyramid (default is 3)

  • pys (int) - pyramid finest level : stop at the level “pys” of the pyramid (default is 0, ie stop at the finest level)

  • pyfilt (int) - pyramid built by Gaussian (recursive) filtering

  • auto (bool) - automated version : set parameters to standard for automated version

    warning : override the parameters already set by previous options

  • inv (bool) - after matching, resample reference image instead of floating one

  • `stop`(bool) - just resample : do not match the images. Just compute the transformation matrix from voxel sizes (and eventually input matrices)

  • only_register - does not create a resampled image, only computes the transformation. The returned image will be None

Returns :
  • im_res (SpatialImage) - result image
  • mat (numpy.ndarray) - result matrix
superbaloo(reference, floating, initial_trsfs=None, start_level=3, end_level=1, max_iterations=10, highest_fraction=0.5, minimal_variance=0.0, blockSize=None, neighborhood=None, similarity='cc', outlier_sigma=3, threads=1, use_binary=False)[source]

Compute a non-linear transformation that places voxels from “floating” over those of “reference”.

SuperBaloo in an image registration algorithm based on a similar block-matching and pyramidal registration algorithm as Baladin. The main difference is that SuperBaloo estimates a dense deformation field instead of a linear or affine matrix.

Parameters :
  • reference (SpatialImage) - The image to use as a reference for the registration

  • floating (SpatialImage) - The image to register.

  • initial_trsfs (list-of-vectorfields-and-affinematrices) - List of transformations (numpy.matrix / SpatialImage) to

    “apply” to the floating image before computing a finer registration. These transforms must be in ref->flo direction and in voxel space (from ref_space to flo_space, not real_space to real_space). This also means that the last initial deformation comes first in the list.

  • start_level (int) - level of the pyramid to start at (the bigger the smaller the image will be at the highest level)

  • end_level (int) - level of the pyramid to stop at.

  • max_iterations (int) - number of iterations per level of pyramid (the actual number of iterations can be smaller:

    if their is no difference between two iterations, it will stop iterating.

  • highest_fraction (float) - fraction of the highest variance blocks to take into consideration.

  • minimal_variance (float) - value of variance below which blocks are disregarded.

  • blockSize (tuple of ints) - Size of a block (in voxels).

  • neighborhood (tuple of ints) - Size of the neighborhood to visit (in voxels).

  • similarity (str) - Similarity measure to use:
    • ssd : sum of quare differences
    • cc : correlation coefficient
    • scc : no idea
    • tcc : trimmed correlation coefficient?
    • tscc : no idea
  • outlier_sigma (float) - value beyond which estimator prunes pairings

  • threads (int) - number of threads to use

  • use_binary (bool) - use the SuperBaloo executable instead of the CTypes wrapper.

Resampling

reech3d(img, mat=None, mat_before=None, deformation=None, gain=1.0, bias=0.0, interpolation='linear', iso=1.0, output_shape=None, vin=None, vout=None, inv=False, inv_before=False, swap=False)[source]

This function allows 2D or 3D image resampling using a 4x4 matrix. The value of a point in the result image is estimated :

  • either by [bi|tri]linear interpolation,
  • or by using the value of the nearest point.

: Parameters : - image (numpy.ndarray) - input image

  • mat (numpy.ndarray, optional) - Transformation matrix (4x4)

    from ‘image-out’ to ‘image-in’ : M(in) = MAT * M(out).

  • mat_before (numpy.ndarray, optional) - Other transformation matrix (4x4),

    in case of deformation field which is applied BEFORE the deformation field.

  • deformation (numpy.ndarray) - vector field based shape deformation applied before “matrix” :

    M(in) = MAT * ( M(out) + deformation ) and after “matrix_before” : M(in) = MAT * ( MATB*M(out) + deformation )

  • gain and bias (floats, optional) - The intensity is transformed by i*gain*bias

    (only with “deformation” and “linear”)

  • interpolation (str, optional) - Type of interpolation according to given mode :
    • “linear” (Default),
    • “nearest”,
    • “cspline”.
  • `output_shape`(tuple, optional) - dimension of output image

  • iso (float, optional) - isotropic mode

  • vin (tuple, optional) - voxel size of input image

  • vout (tuple, optional) - voxel size of output image

  • inv (bool, optional) - inverse “matrix”

  • inv_before (bool, optional) - inverse “matrix_before”

reech3d_voxels(img, mat=None, mat_before=None, deformation=None, gain=1.0, bias=0.0, interpolation='linear', iso=1.0, output_shape=None, vin=None, vout=None, inv=False, inv_before=False, swap=False)[source]

This function allows 2D or 3D image resampling using a 4x4 matrix. The value of a point in the result image is estimated :

  • either by [bi|tri]linear interpolation,
  • or by using the value of the nearest point.

: Parameters : - image (numpy.ndarray) - input image

  • mat (numpy.ndarray, optional) - Transformation matrix (4x4)

    from ‘image-out’ to ‘image-in’ : M(in) = MAT * M(out).

  • mat_before (numpy.ndarray, optional) - Other transformation matrix (4x4),

    in case of deformation field which is applied BEFORE the deformation field.

  • deformation (numpy.ndarray) - vector field based shape deformation applied before “matrix” :

    M(in) = MAT * ( M(out) + deformation ) and after “matrix_before” : M(in) = MAT * ( MATB*M(out) + deformation )

  • gain and bias (floats, optional) - The intensity is transformed by i*gain*bias

    (only with “deformation” and “linear”)

  • interpolation (str, optional) - Type of interpolation according to given mode :
    • “linear” (Default),
    • “nearest”,
    • “cspline”.
  • `output_shape`(tuple, optional) - dimension of output image

  • iso (float, optional) - isotropic mode

  • vin (tuple, optional) - voxel size of input image

  • vout (tuple, optional) - voxel size of output image

  • inv (bool, optional) - inverse “matrix”

  • inv_before (bool, optional) - inverse “matrix_before”

Segmentation

watershed(image_markers, image_gradient, labelchoice='first', memory=-1, iterations=0, verbose=False)[source]

Applies the Watershed algorithm

Parameters :
  • image_markers (SpatialImage) - labeled markers image

  • image_gradient (SpatialImage) - gradient image (unsigned char or unsigned short int)

  • labelchoice (str, optional) - method to choose the label in case of conflicts (“first”, “min”, “most”)
    • “first” : the label of the point that puts the actual point in the list

    (historical (and default) behavior) * “min” : the label of smallest value * “most” : the label that is the most represented in the neighborhood

  • memory (int, optional) - size of the bunch of points to be allocated when required

    setting it low allows a better memory management (at the detriment of speed) setting it high allows a better computational times (at the detriment of speed)

  • iterations (int, optional) - maximal number of iterations to be performed

Morphology

dilation(img, iterations=1, connectivity=26, radius=0, mode2D=False)[source]
erosion(img, iterations=1, connectivity=26, radius=0, mode2D=False)[source]

Filtering

recfilters(img, filter_type='sigma', filter_value=None, xyz=None, cont=None, edges=False, inv=False, swap=False)[source]
  • image (SpatialImage) - input image

  • filter_type (str, optional) - type of filtering :
    • “alpha” for Deriche recursive filter
    • “sigma” for Gaussian filter
    • “gradient”
    • “gradient_extrema”
    • “laplacian”
    • “gradient_laplacian”
    • “hessian”
    • “gradient_hessian”
    • “neg”
    • “pos”
  • filter_value (float or (float,float,float), required for “alpha” and “sigma”) - standard deviation of the Gaussian according to X,Y or Z

  • xyz ( (int,int,int), optional) - derivation order according to X, Y or Z :
    • 0 : smoothing,
    • 1 : derivative of order 1
    • 2 : derivative of order 2
    • 3 : derivative of order 3

    default : no derivative (no filtering)

  • cont (int or (int,int,int), optional) - added points to the edges

Local Minima

regionalmax(image, h_minima, hm=1.0, inv=False)[source]

Extraction of local minima of the input image.

Parameters :
  • image (SpatialImage) - input image

  • h_minima (int) - minima height

  • hm (float, optional) - coefficient multiplicateur

    actif uniquement pour type UCHAR et USHORT la recherche du maximum se fait en dilatant MIN( distance*hm , distance-h ) ‘en-dessous’ de l’image originale, puis en soutrayant.

  • inv (bool, optional) - inverse of the image (default = False)

  • `swap : swap ‘image-in’ (si elle est codee sur 2 octets)

Connexity

connected_components(image, low_threshold, connectivity=26, tcc=1, ncc=-1)[source]
hysteresis(image, low_threshold, high_threshold, connectivity=26, tcc=1, ncc=-1)[source]

Applies a hysteresis thresholding and cast the result image.

Such a thresholding keeps the connected components, made of points whose value is larger or equal to “low_threshold”, and which contains at least one (or some, see parameters) point whose value is larger or equal to “high_threshold”.

Parameters :
  • image (SpatialImage) - input image

  • low_threshold (float) - low threshold (to binarize input image)

  • high_threshold (float) - high threshold for hysteresis thresholding (binary input)

  • connectivity (int, optional) - connectivity (4, 6, 8, 10, 18, 26=default)

  • tcc (int, optional) - minimal size of connected components

  • ncc (int, optional) - maximal number of connected components

    if the number of valid connected components is larger than this one the components are sorted with respect to their size, and the largest ones are retained.