ATROPOS(1)

✨ ATROPOS(1) · User Commands ✨

🌸 NAME 🌸

Okay bestie, Atropos is part of the ANTS registration suite 🦋

💖 DESCRIPTION 💖

💅 COMMAND: Atropos 👑

So Atropos is a finite mixture modeling (FMM) segmentation approach ✨ and it's giving prior constraints energy. You can feed it a prior label image, prior probability images (one for each class), and/or an MRF prior to keep the labels spatially smooth 🫶 All segmentation images, including priors and masks, must be in the same voxel and physical space 🚨 Similar algorithms are FAST and SPM. The reference is Avants BB, Tustison NJ, Wu J, Cook PA, Gee JC. An open source multivariate framework for n-tissue segmentation with evaluation on public data. Neuroinformatics. 2011 Dec;9(4):381-400. 📚

🎀 OPTIONS: 🎀

• -d, --image-dimensionality 2/3/4 — Ngl this one lets you force the image to be treated as a specific dimensionality 🌈 If you don't set it, Atropos tries to figure out the dimensionality from the first input image on its own.
• -a, --intensity-image [intensityImage,<adaptiveSmoothingWeight>] — This is how you hand Atropos one or more scalar images to segment with 💖 If you have no prior info, the first scalar image on the command line is used to order the labels, so the class with the smallest intensity signature becomes class 1 through class N, which means the voxels with the biggest intensity values 👑 The optional adaptive smoothing weight only matters when you're using prior label or probability images. It's a scalar between [0,1] that smooths each labeled region separately and blends the intensity at each voxel between the original value and its smoothed version 🦋 The smoothness is controlled by the -b/--bspline option, so go check that one too 🧚
• -b, --bspline [<numberOfLevels=6>,<initialMeshResolution=1x1x...>,<splineOrder=3>] — If the adaptive smoothing weights are greater than 0, the intensity images get smoothed when Atropos calculates the likelihood values. This accounts for subtle intensity differences across the same tissue regions 🌸
• -i, --initialization — You have to pick one of these to initialize the FMM parameters, no skipping 🙅‍♀️ If you don't have prior label or probability images, the move is to use kmeans, because it's usually faster than otsu and works with multivariate initialization too 💅 Heads up though: kmeans uses a Euclidean distance on the inter-cluster distances, so you might need to scale your extra input images appropriately ⚠️ Random initialization is purely for intellectual curiosity 🤓 The prior weighting (in the range [0,1]) modulates how posterior probabilities get calculated, mixing likelihood*mrfprior with likelihood*mrfprior*prior ✨ If you're specifying lots of prior probability images for a multi-label segmentation, there's a minimize usage option (see -m). With that option you can set a prior probability threshold, so only the pixels above it get stored in memory 🧠

-i, --initialization Random[numberOfClasses]
Otsu[numberOfTissueClasses]
KMeans[numberOfTissueClasses,<clusterCenters(in ascending order and for first intensity image only)>]
PriorProbabilityImages[numberOfTissueClasses,fileSeriesFormat(index=1 to numberOfClasses) or vectorImage,priorWeighting,<priorProbabilityThreshold>]
PriorLabelImage[numberOfTissueClasses,labelImage,priorWeighting]

• -s, --partial-volume-label-set label1xlabel2xlabel3 — Partial volume estimation is the move when you want to model mixtures of classes inside a single voxel 🌈 Atropos currently lets you model two class mixtures per partial volume class. You give it a set of class labels for each partial volume class you want. Say you're doing a classic 3-tissue segmentation (csf, gm, wm) with kmeans initialization, and you also want to model partial voluming between csf/gm and gm/wm. You'd use -i kmeans[3] and -s 1x2 -s 2x3 🧚 In that example you'd end up with 3 tissue classes and 2 partial volume classes. You can also optionally limit partial volume handling to MRF considerations only, so the output is just the three tissues 💜
• --use-partial-volume-likelihoods 1/(0) true/(false) — You decide whether or not to use partial volume likelihoods 🦋 If you do, the partial volume class is treated as separate from the tissue classes. If you don't, the MRF handles partial volume by itself, and partial volume voxels aren't treated as separate classes 🫶
• -p, --posterior-formulation — There are a bunch of posterior probability formulations, plus different update options to play with 💅 To get the theoretical convergence properties, a proper formulation of the well-known iterated conditional modes (ICM) uses an asynchronous update step that's modulated by an annealing temperature 🔥 If you set AnnealingTemperature > 1 in the posterior formulation, you get a traditional code set for a proper ICM update. Otherwise, a synchronous update step happens at every iteration 🌸 The annealing temperature, T, turns posteriorProbability into posteriorProbability^(1/T) over the course of optimization. The formulation options are below ✨

Socrates[<useMixtureModelProportions=1>,<initialAnnealingTemperature=1>,<annealingRate=1>,<minimumTemperature=0.1>]
Plato[<useMixtureModelProportions=1>,<initialAnnealingTemperature=1>,<annealingRate=1>,<minimumTemperature=0.1>]
Aristotle[<useMixtureModelProportions=1>,<initialAnnealingTemperature=1>,<annealingRate=1>,<minimumTemperature=0.1>]
Sigmoid[<useMixtureModelProportions=1>,<initialAnnealingTemperature=1>,<annealingRate=1>,<minimumTemperature=0.1>]]

And here's how each one computes things:

Socrates: posteriorProbability = (spatialPrior)^priorWeight*(likelihood*mrfPrior)^(1-priorWeight)
Plato: posteriorProbability = 1.0
Aristotle: posteriorProbability = 1.0
Sigmoid: posteriorProbability = 1.0

• -x, --mask-image maskImageFilename — The image mask is required 🚨 It defines the region that the Atropos algorithm labels 👑
• -c, --convergence numberOfIterations — Convergence is checked by calculating the mean maximum posterior probability over the region of interest at each iteration ✨ When that value goes up or down by less than the specified threshold compared to the previous iteration, or when the max number of iterations gets exceeded, the program terminates 💖

-c, --convergence numberOfIterations [<numberOfIterations=5>,<convergenceThreshold=0.001>]

• -k, --likelihood-model — Atropos has both parametric and non-parametric options 🌈 The Gaussian parametric option is the one everyone uses (SPM and FAST do this too), where the mean and standard deviation of each class's Gaussian get calculated every iteration 🧠 Other groups go non-parametric, like option 2 here. The advice is to stick with options 1 or 2, since they're pretty standard and the default parameters work fine 🫶

-k, --likelihood-model Gaussian
HistogramParzenWindows[<sigma=1.0>,<numberOfBins=32>]
ManifoldParzenWindows[<pointSetSigma=1.0>,<evaluationKNeighborhood=50>,<CovarianceKNeighborhood=0>,<kernelSigma=0>]
JointShapeAndOrientationProbability[<shapeSigma=1.0>,<numberOfShapeBins=64>, <orientationSigma=1.0>, <numberOfOrientationBins=32>]
LogEuclideanGaussian

• -m, --mrf [<smoothingFactor=0.3>,<radius=1x1x...>] — Markov random field (MRF) theory is the framework that enforces spatially contextual constraints on the segmentation 🦋 The default smoothing factor of 0.3 gives a moderate amount of smoothing 💜 Bump it up for more smoothing, turn it down for less 🌸 The radius sets the MRF neighborhood. There are different update schemes, but only asynchronous updating has theoretical convergence properties 🔥

-m, --mrf [<mrfCoefficientImage>,<radius=1x1x...>]

• -g, --icm [<useAsynchronousUpdate=1>,<maximumNumberOfICMIterations=1>,<icmCodeImage=''>] — Asynchronous updating needs an ICM code image, which is a label image (labels in the range {1,..,MaximumICMCode}) built so that no MRF neighborhood has duplicate ICM code labels 🧚 To update the voxel class labels, you loop through the code labels, and for each code label you loop through the image and update the voxels whose class label matches that ICM code label 💅 You can print out the ICM code image by giving an ITK-compatible image filename ✨
• -r, --use-random-seed 0/(1) — Sets the internal random number generator up with a random seed 🎲 Otherwise it starts from a constant seed number 🌈
• -o, --output [classifiedImage,<posteriorProbabilityImageFileNameFormat>] — The main output is a labeled image where every voxel in the masked region gets a label from 1, 2, ..., N 👑 You can also output the posterior probability images, in the same format as the prior probability images, like posterior%02d.nii.gz (C-style file name formatting) 💖
• -u, --minimize-memory-usage (0)/1 — Memory usage isn't minimized by default 🧠 If you need to save memory, the various probability and distance images get calculated on the fly instead of being stored in memory at every iteration. Also, if you're using prior probability images, only the non-negligible pixel values get stored in memory 💜 <VALUES>: 0
• -w, --winsorize-outliers — To take the sting out of outliers when calculating the weighted mean and weighted covariance, you can remove them using the options below 🫶

-w, --winsorize-outliers
BoxPlot[<lowerPercentile=0.25>,<upperPercentile=0.75>,<whiskerLength=1.5>]
GrubbsRosner[<significanceLevel=0.05>,<winsorizingLevel=0.10>]

• -e, --use-euclidean-distance (0)/1 — This is where part 1 ends, bestie, there's more of this page coming up next 🦋💅

Okay so once you've got your prior label or probability images, Atropos spreads those labels across the whole masked region, which means every single voxel in the mask ends up labeled 🫶 It does this with a signed distance transform of the label, and the geometry is giving precision ✨

Or you can use the fast marching filter instead 🧚 This one is a whole mood because it respects the distance along the shape of the mask, so it's the move for super sinuous stuff like the sulci and gyri of the cortex 🧠

Default: 0.

• -l, --label-propagation whichLabel[lambda=0.0,<boundaryProbability=1.0>] — okay, so each prior label has its own propagation settings, and you can tweak them with lambda and the boundary probability 🎀 The boundary probability is a value in the range [0,1] for how likely the label is on the boundary. It ramps up linearly to a max of 1.0 inside the labeled region 🔥 Lambda controls how fast the probability fades outside the labeled region, starting from that boundary probability, following this formula:

boundaryProbability*exp( -lambda * distance )

Lambda is the main character of the decay 💅

• -v, --verbose (0)/1 — verbose output, aka the chatty mode 🗣️ The (0)/1 notation means the default is 0 and you can switch it to 1 🌈
• -h — print the help menu, short version 📝
• --help — print the full help menu 🌸 Values: 1.

---

And that's a wrap on ATROPOS(1) 🦋 This was written for Atropos 2.6.4+dfsg, the December 2025 drop, and honestly the whole page is giving main character energy 👑💖