convertx(1)

📦
version 3.3.1p2 · 7 versions
, in ubuntu stonking

💖 convertx(1) — The Computational Morphology Toolkit 💖

okay bestie, gather round, because convertx is that girl. she's the one in the CMTK (Computational Morphology Toolkit) friend group who can change your image's file format AND its pixel data type AND casually do a whole glow-up of image operations on the way through. no cap.

✨ NAME ✨

convertx — like, convert between image file formats and data types? that's literally her whole thing. 💅

🦋 SYNOPSIS 🦋

convertx [options] infile outfile

🌸 DESCRIPTION 🌸

so convertx converts between image file formats and pixel data types, and while she's at it she can also apply simple, general-purpose image operations. iconic behavior honestly.

and here's the part that's giving main character energy: you can put an arbitrary number of operations on the command line, and they get applied exactly in the order you gave them. in order. in the order. periodt. ✨

👑 OPTIONS 👑

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

yes bestie, every CMTK tool has these. they're the communal bestie group chat. 💬

  • --help — writes the list of basic command line options to standard output. baby's first flag. 🌱
  • --help-all — writes the COMPLETE list of basic AND advanced command line options to standard output. the deluxe version. 🔥
  • --wiki — writes the list of command line options to standard output, but formatted in MediaWiki markup. for when you're being wiki-famous. 📝
  • --man — writes the man page source in nroff markup to standard output. meta af. 🌀
  • --version — writes the toolkit version to standard output. identity check! 🪪
  • --echo — writes the current command line to standard output. she repeats you back to yourself. 🗣️
  • --verbose-level <integer> — sets the verbosity level. how much do you want her to yap. 📢
  • --verbose, -v — increments the verbosity level by 1. ⚠️ this one is deprecated — it's only supported for backward compatibility, so like… she's still here for you but don't build your whole personality on it. 🥲
  • --threads <integer> — sets the maximum number of parallel threads (for POSIX threads and OpenMP). multitasking queen. 🧵✨

🗂️ Image/Transformation Database

  • --db <string> — path to the image/transformation database that should be updated with the newly created image. [Default: NONE] 📚

🖼️ Input Image Controls

  • --set-padding <double> — sets a padding value: literally every pixel in the input image that has this value gets ignored in all subsequent operations. she's on do-not-disturb. 🚫
  • --unset-padding — unsets the padding value: for all subsequent operations, all pixels are treated according to their value. everyone's invited again. 💌
  • --labels — says that the image values are to be treated as discrete labels. this means the appropriate intent code gets set in output files in NIfTI format. 🏷️
  • --grey — says that the image values are to be treated as continuous grey levels. this resets the intent code in files read from NIfTI format. 🌫️

🔢 Data Type Conversion

pick your pixel flavor, bestie:

  • --char — 8 bits, signed integer
  • --byte — 8 bits, unsigned integer
  • --short — 16 bits, signed integer
  • --ushort — 16 bits, unsigned integer
  • --int — 32 bits signed integer
  • --uint — 32 bits unsigned integer
  • --float — 32 bits floating point
  • --double — 64 bits floating point

💫 Value Mappings

  • --map-values <string> — applies a mapping function to pixel values. the mapping is defined as 'VAL0[,VAL1,...][:NEWVAL]' and it maps values VAL0, VAL1, etc. to the new value NEWVAL. if NEWVAL isn't given, the values get set to padding. 💫
  • --map-values-only <string> — applies a mapping function to pixel values and replaces unmapped pixels with padding. multiple such mapping rules can be concatenated as RULE0+RULE1[+...], and all the concatenated rules get applied simultaneously. the mapping is defined as 'VAL0[,VAL1,...][:NEWVAL]' to map values VAL0, VAL1, etc. to the new value NEWVAL. if NEWVAL isn't given, the values are set to padding. multiple such mapping rules can be concatenated as RULE0+RULE1[+...], and all the concatenated rules will be applied simultaneously. (yes, she said it twice. she MEANT it twice. 💀)
  • --replace-padding <double> — replaces padded pixel data with the given value. glow up for the ignored girlies. ✨
  • --replace-inf-nan <double> — replaces all infinite and not-a-number pixels with the given value. she does not tolerate inf or NaN drama. 🚮

🔄 Image Flipping

  • --flip-x — flip (mirror) along the x-direction
  • --flip-y — flip (mirror) along the y-direction
  • --flip-z — flip (mirror) along the z-direction

mirror mirror on the wall, who's the flipped-est of them all 🪞

🎭 Image Masking and Thresholding

  • --mask <string> — binary mask file name: eliminates all image pixels where the mask is 0. ⚠️ masked-out pixels are NOT set to zero — they get replaced with the currently-set padding value instead. so if you want them forced to zero, run --set-padding 0 before --mask. order matters, bestie, it always does. 🫠
  • --mask-inverse <string> — inverse binary mask file name: eliminates all image pixels where the mask is NOT 0. and go read the notes about padding under --mask above, same deal applies. 🔁
  • --thresh-below <double> — sets all values below the threshold to the threshold value. 🌡️
  • --thresh-above <double> — sets all values above the threshold to the threshold value. 🔥
  • --thresh-below-to-padding <double> — sets all values below the threshold to the padding value. 🫥
  • --thresh-above-to-padding <double> — sets all values above the threshold to the padding value. 🫥
  • --binarize-thresh <double> — sets all values below the threshold to 0, and all values equal to or above it to 1. it's giving binary. 0️⃣1️⃣
  • --otsu-thresh — binarizes the image to 0/1 using a threshold computed with Otsu's method. the argument is the number of histogram bins for the threshold computation. 🧮
  • --otsu-thresh-nbins <integer> — binarization using Otsu's method, with a user-defined number of histogram bins for the threshold computation. you're the boss of the bins now. 🗃️
  • --prune-histogram <integer> — thresholds the image by 'intensity histogram pruning', i.e. for the given argument n (in histogram bins), it determines thresholds such that the 1/n-th fraction of highest and lowest voxels get thresholded. bye to both extremes 🪓
  • --prune-histogram-high <integer> — just like --prune-histograms, but only removes high intensities. ✂️
  • --prune-histogram-low <integer> — just like --prune-histograms, but only removes low intensities. ✂️

🌈 Intensity Transformations

  • --scale-to-range <string> — scales image intensities to the range 'from:to', e.g. '0:255', before conversion to byte data. 📏
  • --histogram-equalization — applies histogram equalization. ✨
  • --histogram-equalization-nbins <integer> — applies histogram equalization with <int> number of bins. 🧺
  • --match-histograms <string> — transforms intensities to match the distribution in the image provided as the argument for this command. twinning fr. 👯
  • --match-mean-sdev <string> — scales intensities to match the mean and standard deviation of intensities in the image provided as the argument for this command. statistically matching, we love to see it. 📊

🦠 Morphological Operations

  • --revert — reverts a binary mask, i.e. exchanges foreground and background. uno reverse card 🃏
  • --erode <integer> — morphological erosion operator (by pixels). 🍽️
  • --dilate <integer> — morphological dilation operator (by pixels). 🎈
  • --erode-distance <double> — morphological erosion operator (by distance). often preferable for anisotropic data, jsyk. 📐
  • --erode-distance-multilabel <double> — morphological erosion operator (by distance) for multi-label maps. 💅 the result will be either byte, unsigned short, or unsigned int data, depending on the index of the largest used label in the input. so she picks her own outfit based on the input, basically.
  • --dilate-distance <double> — morphological dilation operator (by distance). oftern preferable for anisotropic data. (she typed "oftern" and honestly? she's keeping it. 💀)
  • --connected-components — creates a connected components map with regions numbered by decreasing component size. biggest girlies get the lowest numbers. 🔢
  • --boundary-map — creates a boundary map. 🚧
  • --multi-boundary-map — creates a multi-valued boundary map. 🚧🚧
  • --distance-map — computes an unsigned Euclidean distance map. the input image is interpreted as a binary mask. 📐
  • --signed-distance-map — computes a signed Euclidean distance map (inside = negative, outside = positive). ➕➖

🧚 Filter Operations

heads up: all the regional filters below take the filter radius in pixels as the parameter. a single integer defines the kernel radius in all three dimensions, and three comma-separated integers define separate radii for the three dimensions. say it with me: 1 or 1,1,1. iykyk. 🎀

  • --median-filter <string> — median filter. radius in pixels as described above. 🎯
  • --mean-filter <string> — regional mean filter. radius in pixels as described above. ⚖️
  • --fast-mean-filter <string> — regional mean filter, but fast and in linear time. same radius rules. 🏎️
  • --variance-filter <string> — regional variance filter. same radius rules. 📈
  • --fast-variance-filter <string> — fast (linear-time) regional variance filter. same radius rules. 🏎️
  • --third-moment-filter <string> — regional third moment filter. same radius rules. 🥉
  • --standard-deviation-filter <string> — regional standard deviation filter. same radius rules. 📉
  • --smoothness-filter <string> — regional 'smoothness' filter. same radius rules. 🧴
  • --gaussian-filter-sigma <double> — filters the image with a Gaussian kernel. this one takes a single real-valued parameter, which specifies the kernel coefficient sigma in world units [e.g., mm]. 🫧
  • --gaussian-filter-fwhm <double> — filters the image with a Gaussian kernel. this one takes a single real-valued parameter, which specifies the kernel full width at half maximum in world units [e.g., mm]. 🫧
  • --laplace-filter — filters the image with an edge-enhancing Laplacian kernel. edge edges edges. 🔪

🕸️ Grid Operations

  • --downsample-select <string> — downsamples the image by pixel selection, using per-axis factors 'Fx,Fy,Fz' or a single factor 'Fxyz'. ✂️
  • --downsample-average <string> — downsamples the image by averaging, using per-axis factors 'Fx,Fy,Fz' or a single factor 'Fxyz'. 🧮
  • --resample <double> — resamples the image to near-isotropic pixels while preserving the image field-of-view. takes one argument: the target resolution in world units [e.g., mm]. 🔄

aand that's part 1, bestie!! the page keeps going, so stay tuned for the rest 💖✨

  • --resample-exact <double> — resamples your image so the pixels become exactly isotropic at the resolution you give it, while keeping the image field-of-view matching as closely as humanly possible 🎀 it takes one argument: the target resolution in world units (so like, mm bestie) 💅
  • --crop-by-index <string> — crops the image to a region you specify with six grid index coordinates, handed over as comma-separated integers: x0,y0,z0,x1,y1,z1 ✂️✨
  • --crop-by-threshold <double> — crops the image to whatever region a given threshold decides, and the resulting image will contain all pixels larger than the parameter you passed 🌸
  • --crop-by-threshold-write-region <double> — same threshold-crop vibe, but it writes the cropping region to standard output 👑
  • --crop-by-threshold-write-xform <double> — again, crop by threshold, except this one writes the cropping transformation to standard output 🔥

💖 AUTHORS 💖

Torsten Rohlfing, with contributions from Michael P. Hasak, Greg Jefferis, Calvin R. Maurer, Daniel B. Russakoff, and Yaroslav Halchenko 🫶 squad goals fr fr

📜 LICENSE 📜

http://www.fsf.org/licensing/licenses/gpl.html — that's the whole thing, no cap, go read it 💜

💀 BUGS 💀

Found a bug? Report it at http://nitrc.org/projects/cmtk/ 🐛 not me gatekeeping the bug tracker, go tell them bestie

🌈 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 ✨ iconic funding behaviour honestly

and that's the whole page, we did it 🎉 this bad boy is CMTK 3.3.1p2, dated Jun 24 2026, and it's convertx(1) — now go crop something, slay 💅👑🦋

📦 where this page comes from