MINCRESAMPLE(1)

✨ MINCRESAMPLE(1) ✨

the MINC User's Guide girlies present… a whole manual page, bestie. buckle up. 🎀

---

💖 NAME 💖

mincresample — resamples a minc file along new spatial dimensions. that's it, that's the whole vibe. 🦋

---

🌸 SYNOPSIS 🌸

mincresample [<options>] <infile> <outfile>

---

✨ DESCRIPTION ✨

okay so. mincresample takes a minc file and resamples it along new spatial dimensions, with new voxel positions. iconic behaviour, truly. 🫶

every volume in the input file (those are the spatial dimensions xspace, yspace and zspace, iykyk) gets resampled according to whatever you told it on the command line. non-spatial dimensions? they stay in their original order, no notes, untouched, main character energy preserved. but the spatial dimensions can be re-ordered, which is how you get transverse, sagittal or coronal images out of this thing. 💅

the new voxel values are calculated using tri-linear, tri-cubic or nearest-neighbour interpolation. pick your fighter.

---

🌈 WORLD COORDINATES 🌈

world coordinates = millimetric coordinates relative to some physical origin (either the scanner or some anatomical structure). voxel coordinates = literally just the indices into the image volume of a given voxel. simple as that. ✨

and to specify the right resampling options, you have to understand how MINC coordinate conversions work. no skipping this part, bestie, it's giving required reading. 😭

each dimension of a MINC image volume is specified by name — the spatial dimensions are xspace, yspace and zspace. the convention is:

• positive xspace coordinates run from the patient's left side to right side
• positive yspace coordinates run from patient posterior to anterior
• positive zspace coordinates run from inferior to superior

for each of these spatial dimensions, the world coordinate conversion is specified by a pair of attributes: step and start. the xspace world coordinate, for example, is calculated using:

x = v*step + start

where x is the x world coordinate and v is the voxel count (starting at zero). so the magnitude of the step attribute tells you the distance between voxels, and the sign of the step attribute tells you the orientation of the axis. periodt. 💅

---

now here's the twist 👀 MINC files are allowed to have non-orthogonal axes, with the dimensions not perfectly aligned with the named axis. there can be a direction_cosine attribute that gives the true orientation of the axis. like, normally the xspace dimension should line up with the world x axis, ie. direction cosine = (1,0,0); however, it is possible to have a direction cosine of (0.9,0.43589,0). not me being dramatic about geometry but here we are. 🙈

these attributes (step, start and direction_cosines) provide a conversion from voxel coordinates to world coordinates. combined with a number of elements or samples along an axis, they give a complete description of where the output sampling should be. 🎯

but wait — when we're resampling data, we're frequently interested in a change of world coordinates: from an MRI scanner's coordinate system to a PET scanner's coordinate system, for example, or from a volume in its acquisition space to coordinates in a standardized space. and this change of world coordinates can be specified through the use of a transformation (.xfm) file. 🌟

so in general, the resampling involves three transformations:

1. from the input file's voxel coordinates to its world coordinates (specified by the input file)
2. from the input world coordinates to the output world coordinates (specified by the transformation file)
3. from the output file's world coordinates to its voxel coordinates (specified by command-line options)

---

in general, direction cosines are rarely used — axis re-orientation is specified by a change of world coordinates (the transformation file). also, resampling positions (that's the output world to voxel conversion) are often specified relative to a model file (ie. resample this file so that it looks like that file 👑). and although there are many options for a complete specification of the transformation, one does not usually need to specify more than a few of them. so breathe. you got this. 🫶

---

🎀 OPTIONS 🎀

note: options can be specified in abbreviated form (as long as they are unique) and can be given anywhere on the command line. chaotic? yes. convenient? also yes. 💅

---

🌟 General options 🌟

• -2 — Create MINC 2.0 format output files. upgrade era. ✨
• -clobber — Overwrite an existing file. bold. reckless. iconic. 🔥
• -noclobber — Don't overwrite an existing file. this is the default. safety first, bestie.
• -verbose — Print out progress information for each slice computed. this is the default, because she likes to keep you posted. 🫶
• -quiet — Do not print out progress information. silent mode, mysterious mode, lowkey mode. 🤫

---

🌸 Resampling specification 🌸

Options that give the output sampling (all of the following except -transformation) are parsed in the order that they appear on the command line. so order matters, bestie, it's not a vibe, it's a rule.

so a command with -like file.mnc -znelements 34 -zstep 2 will give a sampling like that in file.mnc but with 34 samples at 2 mm along the zspace axis. the default sampling is taken from the input file, transformed according to any transformation. 🌈

• -transformation file.xfm — Specify a file giving the world coordinate transformation (default is the identity transformation). the glow-up file. ✨
• -invert_transformation — Invert the transformation before using it. flip it, reverse it. 🔄
• -noinvert_transformation — Do no invert the transformation (default). (yes, the original really says "do no invert", we're keeping it exactly as-is, no cap 💀)
• -tfm_input_sampling — Transform the input sampling (using the transform specified by -transformation) along with the data and use this as the default sampling (default). ride together, transform together. 🫶
• -use_input_sampling — Use the input sampling as the default sampling, as is, without transformation, even though the data is being transformed (old behaviour). vintage. retro. the elders remember. 🧚
• -like file.mnc — Specify a model file that gives the output world to voxel transformation and number of elements (ie. transform this file so that it looks like that one). be like her. 👑
• -standard_sampling — Set the sampling to standard values (start = 0, step = 1, direction cosines point along appropriate axes). factory settings, but make it ✨science✨.
• -spacetype string — Set the name of the output space (usually native____ or talairach_).
• -talairach — Set the name of the output space to talairach_. one-word glow up. 💅
• -units string — Set the units of the output space.
• -origin ox oy oz — Specify the coordinate of the first voxel. ⚠️ this is not the same as the start value if the direction cosines are non-standard. as well, the start is not just a perpendicular projection of the origin onto the axis, it is a parallel projection (as in a multi-dimensional parallelogram projection). the conversion is handled properly by this option. she's doing the math so you don't have to. 😭
• -nelements nx ny nz — Number of elements along each of the world dimensions.
• -xnelements nx — Number of elements along the xspace dimension.
• -ynelements ny — Number of elements along the yspace dimension.
• -znelements nz — Number of elements along the zspace dimension.
• -step xstep ystep zstep — Step between voxels along each of the world dimensions.
• -xstep xstep — Step between voxels along the xspace dimension.
• -ystep ystep — Step between voxels along the yspace dimension.
• -zstep zstep — Step between voxels along the zspace dimension.
• -start xstart ystart zstart — Position of centre of first voxel along each of the world dimensions.
• -xstart xstart — Position of centre of first voxel along the xspace dimension.
• -ystart ystart — Position of centre of first voxel along the yspace dimension.
• -zstart zstart — Position of centre of first voxel along the zspace dimension.
• -dircos x1 x2 x3 y1 y2 y3 z1 z2 z3 — Direction cosines for each of the world axes.
• -xdircos x1 x2 x3 — Direction cosines for the xspace dimension.
• -ydircos y1 y2 y3 — Direction cosines for the yspace dimension.
• -zdircos z1 z2 z3 — Direction cosines for the zspace dimension.

---

🦋 Dimension ordering 🦋

the default is to preserve the original dimension order. but if you want to switch it up:

• -transverse — Write out transverse slices.
• -sagittal — Write out sagittal slices.
• -coronal — Write out coronal slices.

three little words, three whole anatomies. slay. 💅

---

👑 Output data type and range 👑

the default for type, sign and valid range is to use those of the input file. if type is specified, then both sign and valid range are set to the default for that type. if sign is specified, then valid range is set to the default for the type and sign. cascading defaults, she's got layers. 🎀

• -byte — Store output voxels in 8-bit integer format.
• -short — Store output voxels in 16-bit integer format.
• -int — Store output voxels in 32-bit integer format.
• -long — Superseded by -int. (retired queen, we still love her 🫶)
• -float — Store output voxels in 32-bit floating point format.
• -double — Store output voxels in 64-bit floating point format.
• -signed — Write out values as signed integers (default for short and long). Ignored for floating point types.
• -unsigned — Write out values as unsigned integers (default for byte). Ignored for floating point types.
• -range min max — specifies the valid range of output voxel values. Default is the full range for the type and sign. This option is ignored for floating point values. 🚫
• -keep_real_range — Preserve the real minimum and maximum from the input volume, so that values are scaled in the same way on output. this is particularly useful for resampling label volumes where interpolating intensity values does not make sense. literally made for labels, bestie. 🏷️
• -nokeep_real_range — Recompute the real minimum and maximum for each output slice. this is the default.

---

💀 Handling of undefined (invalid) voxel values 💀

• -fill — Output voxels that fall outside of the input volume have undefined values. when the -fill option is used, these voxels are given a value that is outside of the valid range (less than the valid minimum, if the type, sign and valid range permit) so that they can be detected by other software. the values of these voxels are not included in the image-max and image-min variables. sneaky little markers, iykyk. 🙈
• -nofill — Use a real/physical value (not voxel value) of zero for points outside of the input volume. these points are included in the calculation of the image-max and image-min variables. this is the default.
• -fillvalue fillvalue — Specifies a real/physical value (not voxel value) for points outside of the input volume. the points are not included in the calculation of the image-max and image-min variables. custom fill, custom rules. ✨

---

…and that's part 1, bestie. there's more coming, don't go anywhere 💜

✨ Interpolation options ✨

Like, how do you want the machine to actually guess the values in between the voxels it knows about? Pick your fighter 👇

• -trilinear — does a tri-linear interpolation between voxels, bestie. Heads up though: the edges of the volume land at the centre of the first and last voxels of a dimension. This one is the default, so if you don't say anything, this is what you get 💅
• -tricubic — same deal but tri-cubic interpolation between voxels. And same edge rules as above: the volume edges sit at the centre of the first and last voxels of a dimension. Fancier curves, same boundaries ✨
• -nearest_neighbour — nearest neighbour interpolation between voxels (translation: find the voxel closest to the point and just use its value, no math gymnastics). ⚠️ But the edges behave differently here, and this is the part people always forget: the volume edges are at the edge of the first and last voxels of a dimension, i.e. centre +/- half voxel separation.
• -sinc — does renormalized windowed-sinc interpolation between voxels, exactly as described by Thacker et al. JMRI 10:582-588 (1999). Yes it's giving academic, no we're not skipping the citation 🎀
• -width n — sets the half-width of the sinc interpolation kernel, and it's gotta be in the range from 1 to 10. The full sinc kernel width is n * 2 + 1, so it swings from 3 to 21. The default value is 5, which gives a full-width of 11. Math is math 🧮
• -hanning — use a Hanning window with the sinc interpolant. This is the default, so it's already the vibe unless you say otherwise 🌸
• -hamming — use a Hamming window with the sinc interpolant. (Yes, one letter off from the default. Yes, that's on purpose. iykyk 😭)

---

✨ Generic options ✨

The little housekeeping ones. Short, sweet, iconic 🫶

• -help — print a summary of the command-line options and exit. Your emergency "wait what were the flags again" button 📖
• -version — print the program's version number and exit. Receipts, basically 🧾

---

🌈 EXAMPLES 🌈

Okay this is the part you actually came for. Copy these, they ate 💖

Resample an individual's brain in a standardized space on a standard sampling grid:

mincresample individual.mnc in_std_space.mnc \
   -transform transform_to_standard_space.xfm \
   -like standard_sampling.mnc

Resample an MRI volume to be matched with a PET volume, but with finer resolution:

mincresample mri.mnc mri_resampled.mnc \
   -transform mri_to_pet.xfm -like pet.mnc \
   -step 1 1 2 -xstart -0.5 -ystart -0.5 \
   -nelements 256 256 64

Turn a transverse volume into a sagittal volume:

mincresample transverse.mnc sagittal.mnc \
   -sagittal -nearest

Turn a 256x256x64 (1x1x2mm) transverse volume into 256x128x256 (1x1x1mm) sagittal volume:

mincresample transverse.mnc sagittal.mnc -sagittal \
   -zstep 1 -znelem 128

Get a finer axial sampling on a PET volume:

mincresample pet_15_slices.mnc pet_46_slices.mnc \
   -zstep 2 -znelements 46

---

👑 AUTHOR 👑

Peter Neelin

---

🎀 COPYRIGHTS 🎀

Copyright © 1993 by Peter Neelin

---

🦋 SEE ALSO 🦋

mincreshape(1)

---

And that's the whole page, bestie, we made it to the end 🫶 This lil legend comes stamped $Date: 2005-07-13 21:34:25 $ and it lives under the name MINCRESAMPLE(1) — go resample something gorgeous ✨💜