warpx(1)

📦
version 3.3.1p2 · 7 versions
, in ubuntu stonking

🎀 warpx 🎀

pssst bestie, you landed on the man page for warpx, which lives in The Computational Morphometry Toolkit (CMTK — that's the manual name, say it with me). it does B-spline nonrigid registration and it does it with main character energy. let's go 💖

💖 NAME 💖

warpx — B-spline nonrigid registration. short, sweet, iconic, no notes.

🌸 SYNOPSIS 🌸

warpx ReferenceImage FloatingImage InitialXform

🦋 DESCRIPTION 🦋

okay so here's the whole tea: this program performs nonrigid image registration. it does that with multi-resolution optimization of voxel-based image similarity measures, plus a multi-resolution B-spline transformation model. so it's not just nudging your images around like a sticker on a laptop, it's bending them. respectfully. ✨

💅 OPTIONS 💅

👑 Global Toolkit Options (these are shared by all CMTK tools)

bestie these ones show up in every CMTK tool, that's the whole point of them. 🫶

  • --help — writes the list of basic command line options to standard output. your little starter pack.
  • --help-all — writes the complete list of basic and advanced command line options to standard output. the extended director's cut.
  • --wiki — writes the list of command line options to standard output in MediaWiki markup.
  • --man — writes the man page source in 'nroff' markup to standard output.
  • --xml — writes the command line syntax specification in XML markup (this one exists for Slicer integration).
  • --version — writes the toolkit version to standard output.
  • --echo — writes the current command line to standard output.
  • --verbose-level <integer> — sets the verbosity level.
  • --verbose, -v — increments the verbosity level by 1. it's deprecated, but it's supported for backward compatibility, so it still works if you need it.
  • --threads <integer> — sets the maximum number of parallel threads (for POSIX threads and OpenMP).

🔄 Transformation import/export

  • --initial <transformation-path> — initialize the transformation from the given path. [Default: NONE]
  • --invert-initial — invert the (affine) initial transformation you handed over.
  • --write-itk-xform <transformation-path> — output path for the final transformation, in ITK format. [Default: NONE]
  • --write-reformatted <image-path> — write the reformatted floating image. [Default: NONE]

🧵 Transformation parameters

  • --grid-spacing <double> — control point grid spacing. [Default: 10]
  • --grid-refine <integer> — number of refinements (aka control point grid resolution levels). [Default: 0]
  • --delay-refine — delay the control point grid refinement; first switch to the next higher image resolution.
  • --exact-spacing — use the exact control point spacing; do not modify the spacing to fit the reference image bounding box.
  • --ignore-edge <integer> — ignore n control point layers along each image face. [Default: 0]
  • --restrict <string> — restrict the deformation to coordinate dimension(s) [one or more of 'x','y','z']. [Default: NONE]
  • --no-adaptive-fix — disable adaptive fixing of control points; optimize all the deformation parameters.
  • --adaptive-fix-thresh <float> — threshold factor for the entropy criterion used to fix local control points. [Default: 0.5]
  • --accurate — accurate computation mode: may give slightly better results after substantially longer computation. [This is the default]
  • --fast — fast computation mode: may give slightly worse results than accurate mode, but it saves substantial CPU time.

🧘 Regularization parameters

  • --jacobian-constraint-weight <float> — weight for the Jacobian-based local volume preservation constraint. [Default: 0]
  • --smoothness-constraint-weight <float> — weight for the smoothness constraint, which is based on second-order grid bending energy. [Default: 0]
  • --inverse-consistency-weight <float> — weight for the inverse consistency constraint. [Default: 0]
  • --constraint-relaxation-factor <float> — weight relaxation factor for alternating under-constrained iterations. [Default: -1]
  • --relax-to-unfold — before each resolution level, regularize the negative-Jacobian areas of the deformation so they unfold.

🎯 Optimization parameters

  • --max-stepsize <double> — maximum optimizer step size, which determines search space exploration. [Default: -1]
  • --min-stepsize <double> — minimum optimizer step size, which determines precision. [Default: -1]
  • --stepfactor <double> — factor for search step size reduction. must be > 0.0 and < 1.0 [default: 0.5] [Default: 0.5]
  • --delta-f-threshold <double> — optional threshold to terminate optimization (level) if the relative change of the target function drops below this value. [Default: 0]
  • --no-maxnorm — use the Euclid norm for gradient normalization in optimization, rather than the maximum norm.

🔍 Image resolution parameters

  • --sampling <double>, -s <double> — image sampling (the finest resampled image resolution). [Default: -1]
  • --coarsest <double> — upper limit for image sampling in the multiresolution hierarchy. [Default: -1]
  • --omit-original-data — do not use the original data at full resolution for the final registration stage.

🖼️ Image data

  • --registration-metric — registration metric for motion estimation by image-to-image registration. supported values are "nmi", "mi", "cr", "rms", "msd", "ncc", where the default is "nmi", or use one of the following:
    • --nmi — Normalized Mutual Information metric. [This is the default]
    • --mi — Standard Mutual Information metric.
    • --cr — Correlation Ratio metric.
    • --rms — Root of Mean Squares metric (this is the square root of MSD).
    • --msd — Mean Squared Difference metric.
    • --ncc — Normalized Cross Correlation metric.

🧚 Floating Image Interpolation Options

  • --interpolation — interpolation method for floating image sampling. supported values are "nearest-neighbor", "linear", "cubic", "cosine-sinc", "partial-volume", "automatic", where the default is "automatic", or use one of the following:
    • --nearest-neighbor — nearest neighbor interpolation (for intensity and label data).
    • --linear — trilinear interpolation.
    • --cubic — tricubic interpolation.
    • --cosine-sinc — cosine-windowed sinc interpolation (most accurate but slowest).
    • --partial-volume — partial volume interpolation (for label data).
    • --automatic — select the interpolation automatically based on the data type: linear for grey-level data, nearest neighbor for label data. [This is the default]
  • --match-histograms — match the floating image histogram to the reference image histogram.
  • --repeat-match-histograms — repeat the histogram matching after every level of the registration, to account for volume changes. when you're registering masked data, it's advisable to also use the --force-outside-value option so you don't end up with poorly matched histograms.
  • --force-outside-value <double> — force values outside the field of view to this value rather than dropping incomplete pixel pairs. [Default: disabled]

🌸 Reference Image Preprocessing

  • --class-ref <string> — data class: grey (default) or label. [Default: NONE]
  • --pad-ref <double> — padding value. [Default: disabled]
  • --thresh-min-ref <double> — minimum value truncation threshold. [Default: disabled]
  • --thresh-max-ref <double> — maximum value truncation threshold. [Default: disabled]
  • --prune-histogram-ref <integer> — number of bins for histogram-based pruning. [Default: disabled]
  • --histogram-equalization-ref — apply histogram equalization.
  • --median-filter-radius-ref <integer> — apply a median filter with the given radius. [Default: 0]
  • --sobel-filter-ref — apply the Sobel edge detection filter.
  • --crop-index-ref <string> — cropping region in pixel index coordinates [parsed as %d,%d,%d,%d,%d,%d for i0,j0,k0,i1,j1,k1]. [Default: NONE]
  • --crop-world-ref <string> — cropping region in world coordinates [parsed as %f,%f,%f,%f,%f,%f for x0,y0,z0,x1,y1,z1]. [Default: NONE]
  • --crop-thresh-ref <double> — automatic cropping based on threshold. [Default: disabled]

🦋 Floating Image Preprocessing

  • --class-flt <string> — data class: grey (default) or label. [Default: NONE]
  • --pad-flt <double> — padding value. [Default: disabled]
  • --thresh-min-flt <double> — minimum value truncation threshold. [Default: disabled]
  • --thresh-max-flt <double> — maximum value truncation threshold. [Default: disabled]
  • --prune-histogram-flt <integer> — number of bins for histogram-based pruning. [Default: disabled]
  • --histogram-equalization-flt — apply histogram equalization.
  • --median-filter-radius-flt <integer> — apply a median filter with the given radius. [Default: 0]
  • --sobel-filter-flt — apply the Sobel edge detection filter.
  • --crop-index-flt <string> — cropping region in pixel index coordinates [parsed as %d,%d,%d,%d,%d,%d for i0,j0,k0,i1,j1,k1]. [Default: NONE]
  • --crop-world-flt <string> — cropping region in world coordinates [parsed as %f,%f,%f,%f,%f,%f for x0,y0,z0,x1,y1,z1]. [Default: NONE]
  • --crop-thresh-flt <double> — automatic cropping based on threshold. [Default: disabled]

📤 Output parameters

  • --outlist <string>, -o <string> — output path for the final transformation. [Default: NONE]
  • --time <string>, -t <string> — computation time statistics output file name. [Default: NONE]
  • --output-intermediate — write the transformation for each level [default: only write final transformation].

🗄️ Image/Transformation Database

  • --db <string> — path to the image/transformation database that should be updated with the new registration and/or reformatted image. [Default: NONE]

🫶 AUTHORS 🫶

Torsten Rohlfing, with contributions from Michael P. Hasak, Greg Jefferis, Calvin R. Maurer, Daniel B. Russakoff, and Yaroslav Halchenko. legends, all of them. 💜

📜 LICENSE 📜

http://www.fsf.org/licensing/licenses/gpl.html

🐛 BUGS 🐛

report bugs at http://nitrc.org/projects/cmtk/. not me manifesting a bug-free run for you though 🙈

🌈 ACKNOWLEDGMENTS 🌈

CMTK is developed with support from the NIAAA under Grant AA021697, National Consortium on Alcohol and Neurodevelopment in Adolescence (N-CANDA): Data Integration Component. from April 2009 through September 2011, CMTK development and maintenance was supported by the NIBIB under Grant EB008381.

and that's the whole page, bestie 💖 you just read the warpx(1) manual from CMTK 3.3.1p2, dated Jun 24 2026. go register something nonrigidly. periodt. 👑

📦 where this page comes from