Command line segmentation for multimodal/multichannel 3D volume data
Command line running a multimodal/channel image segmentation, based on:
- Principal Component Analysis (PCA), using itk library (https://www.itk.org)
- Support Vector Machines (SVM), using libsvm (https://www.csie.ntu.edu.tw/~cjlin/libsvm)
- Extended Random Walker (ERW), using vtk (http://www.vtk.org/) /eigen (http://eigen.tuxfamily.org)
Building
svmerw requires CMake (https://cmake.org/) for setting up the build environment, as well as the libraries mentioned above. Download and build above libraries (see e.g. the build instructions from our open_iA tool).
Syntax
svmerw Mode (SeedFileName Flags MaskParams OutputFileName {InputFileName} AlgorithmParameters [GADParameters] | InputDirectory)
with
Mode = "RW" | "ERW" (| "Norm")
Flag = "true" | "false"
The different Mode
values stand for:
RW
for the Random Walker algorithmERW
for a segmentation pipeline employing PCA, SVM and ERWNorm
for a normalization of the input
Modes RW
and ERW
share the following settings:
OutputFileName
the output file. Currently supported is only the MetaImage format (*.mha / *.mhd){InputFileName}
a list of input files; an arbitrary number of files can be specified, currently in either MetaImage (*.mha / *.mhd) or the custom Volume Stack (*.volstack) format (see separate section below). The first parameter that is interpretable as double is considered to be the first from theAlgorithmParameters
set. Note that svmerw supports both both multimodal and multichannel data. Every input is considered a separate modality; if the input is given as Volume Stack, each volume in that stack is considered one channel of that modality. The total number of input channels is the sum of the number of channels for each modality (each modality can have a different number of channels).SeedFile
the filename of an XML file with a format like in this example:
<?xml version="1.0" encoding="UTF-8"?>
<Labels>
<Label id="0" name="Background">
<Seed x="1" y="1" z="0"/>
</Label>
<Label id="1" name="Object1">
<Seed x="10" y="1" z="0"/>
</Label>
<Label id="2" name="Object2">
<Seed x="1" y="4" z="4"/>
</Label>
</Labels>
Here, the pixel values from the input images will be considered.
Optionally, for the ERW pipeline, per Seed a value for each input channel can be specified, such as:
<Seed x="1" y="1" z="0">
<Value modality="0" component="0" value="2984"/>
<Value modality="0" component="1" value="3880"/>
<Value modality="1" component="0" value="4062"/>
</Seed>
When seeds are specified like this, the ERW pipeline will not use the given x,y,z indices to look values in the input images, instead it will directly consider the values specified.
Note that the RW mode always requires seed coordinates in the given input image and will therefore not consider such given values.
RW
Mode Flags = StoreRWProb UseGAD
Each of those is a Flag as defined above (taking a value of "true" or "false")AlgorithmParameters = RWBeta {ModalityParameters}
RWBeta
determines the power in the Gaussian kernel used for distance calculation in the Random Walker, and typically takes values between 0.00001 and 10000
ModalityParameters = PCAComponents Weight DistanceFunction
These parameters need to be specified for each modality (that is, input file) given.PCAComponents
is the number of PCA components to consider. Valid values: 1 to the number of channels for that modality.Weight
the weight given to this particular modalityDistanceFunction = "l1" | "l2" | "linf" | "sq" | "cos" | "js" | "kl" | "cs" | "em"
determines the distance function used in the extended random walker for that modality:l1
: "Manhatten" / "Taxicab" Distancel2
: Euclidean Distancelinf
: L-Infinity Norm (maximum distance of single component)sq
: the original distance function from Random walks (Grady [1]).cos
: cosine similarity (only meaningful for multichannel data)js
: Jensen-Shannon divergence (only meaningful for multichannel data)kl
: Kullback-Leibler divergence (only meaningful for multichannel data)cs
: Chi-Square distance (only meaningful for multichannel data)em
: Earth Mover's Distance
ERW
Mode Flags = StoreSVMProb StoreRWProb UseGAD
Each of those is a Flag as defined above (taking a value of "true" or "false")AlgorithmParameters = ERWBeta ERWGamma ERWMaxIter SVMC SVMGamma SVMChannels ModalityParameters
- for
ERWBeta
, see description ofRWBeta
in modeRW
ERWGamma
determines the weight of the prior model in comparison to the edge weights in the neighbourhood graph, useful values are in the range of 0.01 to 100.ERWMaxIter
limits the number of iterations that are performed during iterative solving of linear equations in the extended random walker, useful values range from 100 to 10000.SVMC
determines the penalty for misclassification. Smaller values try to maximize the separation, even if it means that more values are misclassified. Values found useful so far range from 0.01 to 10000.SVMGamma
is the free parameter for the radial basis function used as kernel in SVM. Values found useful so far range from 1e-12 to 10.SVMChannels
is the number of input channels to consider in the SVM. Should be at least one, and below the number of input channels over all modalities.
- for
ModalityParameters
are defined the same as forRW
mode
Masking
MaskParams = UseMask [MaskFileName]
UseMask = Flag
You can specify a foreground mask (see UseMask / MaskFileName parameters above). If UseMask is "true", then a MaskFileName parameter will be expected. The volume given by that filename is expected to be binary and of the same dimension as the other input datasets, and all parts of the output where the mask is 0 are also set to 0 in the output.
Gradient Anisotropic Diffusion (GAD)
GADParameters = Iterations Step Conductance
As preprocessing filter to reduce noise, gradient anisotropic diffusion can be applied. For an explanation of the parameters please refer to the documentation of the used GradientAnisotropicDiffusionImageFilter by ITK.
Examples:
To run the ERW pipeline on a simple, single-modality, single-channel dataset, with no probability output:
svmerw ERW "seeds.xml" false false false false output.mhd input.mhd 10 1 1000 1 0.00001 1 1 1 sq
Normalize
Mode The only parameter this mode requires is an input directory. The (*.mhd) image files starting with "prob" in that directory will be "normalized", that is, in each pixel, a factor is applied such that the sum of the images in that pixel is 1.
Volume Stack Format
This file format describes a collection of files, it is very simple and best explained with an example:
file_names_base: stack
extension: .mhd
number_of_digits_in_index: 3
minimum_index: 0
maximum_index: 199
So it considers each number between minimum_index
and maximum_index
(inclusive),
and pads the number with leading zeros such that it has at least number_of_digits_in_index
.
Each number is appended to the file_names_base
, then extension
is appended at the end.
So given above example file, svmerw would load the files stack001.mhd
, stack002.mhd
, stack003.mhd
up to stack199.mhd
.
References
[1] L. Grady. Random walks for image segmentation. IEEE Trans. Pattern Analysis and Machine Intelligence, 28(11):1768–1783, Nov. 2006. doi: 10.1109/TPAMI.2006.233