AUTOCROP(1)

📦 version 0.99.70-unstable-2024-10, in nixos 26.05, nixpkgs unstable

okay bestie, this is autocrop from MNI AutoReg 0.98 — the AUTOCROP(1) page, and we’re gonna make bounds of MINC files make sense together 💖

✨ NAME ✨

autocrop — a tool for extracting and manipulating the bounds of a MINC file 🎀

🦋 SYNOPSIS 🦋

autocrop [options] in_volume out_volume

autocrop [options] in_volume

Form one is the default, or it kicks in if options includes an explicit -resample or -reshape. Form two only applies if options includes -noresample or -noreshape. slay, that’s the whole vibe check 💅

🌸 DESCRIPTION 🌸

okay so autocrop is a tool for specifying and manipulating the bounds of a MINC file, where the bounds are defined as the start and extent of the volume in each dimension. Start and extent are both always defined in world coordinates, and given in millimetres. the way that works is very much giving “spatial receipts” ✨

The bounds of a volume can be extracted from any MINC file, or from a specially-formatted tag file, or from the already-known volume covered by the brain in Talairach space. Operations that can be performed on these bounds include spatial transformations and various ways of increasing/decreasing the extent of the sampling volume in the three spatial dimensions. iconic behavior, no cap 🧚

autocrop uses either of mincresample or mincreshape for the actual processing of data. You can force it to use one or the other, or let it pick the appropriate one. (It will always pick mincreshape, unless you have asked for a different step size in your output volume. Also, if you attempt to force use of mincreshape and have asked for different steps, autocrop will complain and die.) also, you can make autocrop simply print out command line options for one of the two utilities, and apply them later at your leisure. very “do it yourself but with a helper” energy 🫶

💜 OPTIONS 💜

This section is provided for quick reference once you know the rest of this man page cold. You’ll probably want to skip it on a first reading. (Also, you can always get an up-to-date version of this option summary with the command autocrop -help.) iykyk 👑

🎀 Basic behaviour options 🎀

  • -verbose — print status information and command lines of subprograms [default; opposite is -quiet]
  • -execute — actually execute planned commands [default]
  • -clobber — blithely overwrite files (and make subprograms do as well) [default: -noclobber]
  • -debug — spew lots of debugging info (and make subprograms do so as well) [default: -nodebug]
  • -tmpdir — set the temporary working directory
  • -keeptmp — don’t delete temporary files when finished [default: -nokeeptmp]

🦋 Action-to-take options 🦋

  • -resample — force autocrop to use mincresample, and also ensure that resampling is actually performed
  • -noresample — don’t actually do anything, but compute parameters for mincresample
  • -reshape — force autocrop to use mincreshape if possible, and also ensure that reshaping is actually performed
  • -noreshape — don’t actually do anything, but compute parameters for mincreshape
  • -params — print out parameters to run mincresample/mincreshape [default: on if not running them, -noparams otherwise]

🌈 Bounds specification options 🌈

  • -from <file> — take the bounds from that file (either a tag or MINC file) [default: input volume]
  • -bbox <file> — compute the bounding box of the data in that file, and use that for the bounds
  • -bbox_threshold — threshold value to use when running mincbbox [default: 0]
  • -talairach — take the bounds from the (approximate) extent of the brain in Talairach space

🫶 Bounds transformation options 🫶

  • -transform <xfm> — apply <xfm> to the bounds to get them into the space of the input volume
  • -invert — invert the <xfm> supplied with -transform before applying it

🍓 Bounds modification options 🍓

  • -expand — set the (x,y,z) expansion (increase volume extent symmetrically at each end of an axis) parameters
  • -isoexpand — set the same expansion parameter for all three axes
  • -extend — set the (x,y,z) extension (increase volume extent independently at each end of an axis) parameters
  • -isoextend — set the same extension parameter for all three axes

⭐ Resampling options ⭐

  • -step <xstep> <ystep> <zstep> — set the x, y, and z step (voxel size) for the output sampling
  • -isostep — set the step (same in all three dimensions) for the output sampling

🔥 ACTION TAKEN 🔥

With no options, autocrop is simply a front-end to mincreshape; the two commands

autocrop foo.mnc bar.mnc
mincreshape foo.mnc bar.mnc

are equivalent. literally same energy 💀

However, you can force autocrop to use mincresample with the -resample option:

autocrop -resample foo.mnc bar.mnc

Or, you can tell it to merely think about using mincreshape or mincresample with the -noreshape and -noresample options. Each of these has several side effects: they tell autocrop to not actually perform the desired crop, but merely to print out the arguments for whichever program is implied by the option. for instance,

autocrop -noresample foo.mnc

would print out the part of a mincresample command-line that specifies the same sampling grid as found in foo.mnc. (Of course, the whole point of autocrop is to change that sampling grid in some way. That bit comes later.) 👀

For example, a typical PET volume at the MNI has 128x128x15 (x,y,z) voxels, with steps of 2mm, 2mm, and 6.5mm. For concreteness, assume the start coordinates for a given volume are (0,0,-7.9). Then the extent of this volume is (256mm,256mm,97.5mm), and the command

autocrop -noresample foo.mnc

would print out

-start 0 0 -7.9 -step 2 2 6.5 -nelements 128 128 15

while

autocrop -noreshape foo.mnc

would give you

-start 0,0,0 -count 15,128,128

Note that the parameters are specified to mincresample in canonical x,y,z order; for mincreshape, though, the parameters are reordered according to the volume at hand. In this case, the volume is transverse, so the dimensions are z,y,x. the way that detail matters is so real 😭

Another minor point about the -noresample and -noreshape options: if you want to use their output in another program, you’ll most likely either redirect autocrop’s output to a file, or open a pipe to read its output. In either case, autocrop does not print a newline at the end of the mincresample/mincreshape arguments, like it does when output is to a terminal. This is often convenient. tiny detail, big slay ✨

One important option that deserves mention here (because I couldn’t think of where else to put it) is -step. Although the step size isn’t strictly part of the volume bounds, it is certainly relevant when resampling data, and can be relevant when reshaping data. (For instance, if any step is changed by more than a sign, you can’t use mincreshape!) 🚨

As a simple example, let’s say you want to change the direction of sampling in the z axis. In this case, you simply supply -step with the desired new steps:

autocrop foo.mnc foo_negative_z.mnc -step 2 2 -6.5

(Yes, you have to know the old steps in order to supply the new ones in this case.) In this case, autocrop is smart enough to use mincreshape for the reordering. she ate that 💅

Another possibility is that you might want to resample a volume to have isotropic voxel sizes—say, 2x2x2mm. This can be done as follows:

autocrop foo.mnc foo_cubic.mnc -step 2 2 2

In this case, of course, autocrop must use mincresample. A handy shortcut option exists for the case of isotropic sampling: -isostep. You can save a few keystrokes on the above command with this:

autocrop foo.mnc foo_cubic.mnc -isostep 2

💅 BOUNDS SPECIFICATION 💅

okay so bestie, to pin down the bounds of a three-dimensional volume you need six numbers — yeah, autocrop is a lil prejudiced towards working with 3-D data, we don't make the rules 🫶. You need the start and extent in each of the x, y, and z dimensions.

The "start" parameters are literally just what you're picturing from your previous MINC adventures: (start_x,start_y,start_z) is the real-world coordinate for the first voxel in the volume. And the "extent" of a dimension? It's simply the step (voxel size) multiplied by the "length" or "count" (number of voxels). math queen behavior ✨

Lowkey important: both the start and extent are sensitive to the sign of the step. For instance, if data is sampled left-to-right, then the x step and extent will both be positive, and the start will be the smallest x-coordinate. But if data is sampled right-to-left, the x step and extent will be negative, and the start will be the largest x-coordinate. Similarly, posterior-to-anterior (back-to-front, for the Latin-challenged 💀) sampling implies positive y step and extent, and inferior-to-superior (bottom-to-top) sampling implies positive z step. This doesn't really concern you when you're specifying the bounds of a volume, but it's handy to keep in mind. iykyk 🧠

Obviously, it's easy to extract the bounds of a volume straight from a MINC file. In fact, autocrop's default mode is to take the start and extent straight from the input volume, which makes perfect sense most of the time. But you can also take the bounds from another MINC file, from the data in another MINC file, or from a tag file that follows a convention explained below 👇

First, consider a possible scenario where you'd want the bounds from one volume to apply to another. One example is a label volume that covers only a fraction of the brain, where you want to extract only the MRI image data that corresponds to the labels. Let's say the image data is in smith_john_mri.mnc, and structure foobar has been painted with the labels saved in smith_john_foobar.mnc. (This label volume should be tightly cropped to encompass only the structure of interest. Recent versions of Display do this automatically.) Then you could crop the image data down to the size of the structure like this:

autocrop smith_john_mri.mnc smith_john_crop.mnc \
  -from smith_john_foobar.mnc

Too easy, eh? 😌 If that's not good enough, you can even tell autocrop to do things like add five voxels at one end of the x dimension, or increase the volume by 5% all the way around. (But that's covered later, when we get to bounds modifiers. stay tuned bestie 🎀)

Now, what if the label volume is not tightly cropped to the structure of interest? In that case, you don't want autocrop to take the sampling limits of the whole volume — rather, you're interested in the limits of the data. This can be done with the -bbox option; for instance:

autocrop smith_john_mri.mnc smith_john_crop.mnc \
  -bbox smith_john_foobar.mnc

would compute the bounding box of the data in smith_john_foobar.mnc, and use that to crop the input MRI file. If you want to compute the bounding box of a non-label volume (i.e. something with a noise floor), you can use -bbox_threshold to specify an absolute (real-world) voxel value to use as the cut-off for considering a voxel as "interesting data". 🔥

Another possibility is that you don't have the bounds you want encoded in a handy MINC file — you want to set the start and extent explicitly for each dimension. This can be done by supplying a tag file to the -from option, e.g.

autocrop smith_john_mri.mnc smith_john_crop.mnc \
  -from mybounds.tag

(Note that autocrop distinguishes between MINC and tag files solely by their filename, so you are advised to stick to the standard file naming conventions! 🙈)

The tag file must have eight points, each of which is one corner of the volume's bounding box. You might think it would be easier and more sensible to specify just six points, such as the extrema of each axis within the volume. However, doing that leads to problems when the bounds are transformed with large rotations — corners of the volume tend to get chopped off 😭.

As an example, a typical PET file from the MNI has spatial parameters like this (courtesy of mincinfo):

dimension name         length         step        start
--------------         ------         ----        -----
zspace                     15          6.5         -7.9
yspace                    128            2            0
xspace                    128            2            0

The bounds of this volume could be described as three ordered pairs (start and extent in x,y,z order): (0,256) (0,256) (-7.9,97.5). A tag file describing these bounds would look like this:

MNI Tag Point File
Volumes = 1;
Points =
    0    0   -7.9 ""
    0  256   -7.9 ""
    0    0   89.6 ""
    0  256   89.6 ""
  256    0   -7.9 ""
  256  256   -7.9 ""
  256    0   89.6 ""
  256  256   89.6 "";

It should be pretty clear that these eight points describe the rectangular volume taken from the MINC file. (If not, draw it! 🎨 no seriously, sketch it out, it hits different)

There's one final way to specify the bounds of a volume: -talairach. As the name implies, this option uses a set of hard-coded points in Talairach space that define the volume encompassing the brain and scalp. This volume is from x=-80..+80, y=-120..+90, and z=-80..+95, and was selected by someone (your humble narrator 👑) who has zero formal knowledge of neuroanatomy. (Just so you know. 💀) This option is often useful in conjunction with bounds transformations, which are illuminated below.

🦋 BOUNDS TRANSFORMATION 🦋

Now that you have a bounding box for your data, presumably you want to change it in some way. The first is with a spatial transformation — for instance, your bounds might be in Talairach space, but you wish to apply them to data in native space. (For the historically minded, this was in fact the original impetus for autocrop, before it became the feature-laden behemoth you now find before you. glow-up complete ✨)

As a concrete example, let's say we have an MRI volume in smith_john_mri.mnc, the transformation to get it into Talairach space in smith_john_mrital.xfm, and a tightly-cropped mask of the brain in Talairach space in average305_t1_tal_lin_mask.mnc. We wish to crop the native MRI volume using the extent of the brain, but first we need to transform the information about that extent back to native space. This can be done using autocrop's -transform option, along with the -invert flag (because we're supplying the native-to-Talairach transform, not Talairach-to-native):

autocrop smith_john_mri.mnc smith_john_crop.mnc \
  -from average305_t1_tal_lin_mask.mnc \
  -transform smith_john_mrital.xfm -invert

(If you happen to have the Talairach-to-native transform handy, you can drop the -invert flag. slay, less typing for you 💅)

As an aside, this is a great place to use the -talairach flag instead of supplying an explicit label volume from which to extract the bounding box. The advantages of -talairach are that you get the same bounds every time, those bounds are symmetric about x and easily reproducible, you don't need a tightly-cropped label volume, and you don't have to type as much. The disadvantage is that you're implicitly trusting one particular guess (mine) at the spatial extent of the brain+scalp in Talairach space. 😬 choose wisely bestie 🫶

💅 BOUNDS MODIFICATION 💅

okay so bestie, at this point your bounds are in the space you want — either because you did a spatial transformation, or because you literally did nothing at all, both valid — and now you probably wanna tweak them a little. same energy. let's go back to the MRI volume example, where you're cropping according to the bounds of a labelled structure. if you just do this:

autocrop smith_john_mri.mnc smith_john_crop.mnc \
  -from smith_john_foobar.mnc

then you've thrown away all the MRI data outside the bounding box of the labelled structure. and if that's a small volume, you've probably cropped way too much and lost all the useful anatomical context 😭. in that case you probably want to expand the bounds by a little bit all the way around, say 10%. this is easily done with the -expand option — or rather its shortcut, -isoexpand:

autocrop smith_john_mri.mnc smith_john_crop.mnc \
  -from smith_john_foobar.mnc -isoexpand 10%

(and not surprisingly, -isoexpand 10% is a shortcut for -expand 10% 10% 10% 💅.) expanding a dimension increases the amount of space covered by an equal amount at either end of the dimension. for instance, if the x dimension covers 200mm from x=0..+200, then expanding it by 10% will decrease the start by 20mm (10% of 200mm), and increase the extent by 40mm — that's 20mm to actually extend the dimension, plus 20mm to make up for the decrease in the start coordinate. the math is mathing ✨.

note that asking for a 10% expansion results in the dimension's extent actually being increased by 20%. this is a feature — it's just because "expand by x" means "expand by x at each end of the dimension." no cap.

expansion factors can also be specified in millimetres or voxels; just append mm or v in place of %. if no unit is specified, millimetres are used. also note that a percentage is always a percentage of the dimension's extent in world coordinates, not of the number of samples in that dimension. and expansion factors may be negative — that will cause the dimension to be reduced by the given amount at both ends 👀.

now, let's say you want to change the amount of space covered by a dimension differently at the two ends. this is called — for want of a better word — dimension extension. extension factors look a lot like expansion factors, except there have to be two of them for each dimension: the first covers the "low" end of an axis, and the second covers the "high" end. low and high here are in the world coordinate sense, so:

  • "low x" is patient left
  • "low y" is patient posterior
  • "low z" is patient superior

…and this is independent of the sampling direction. periodt.

a very real-world example is needing to chop off the bottom of a volume before registration. this is common with MRI data acquired coronally or sagittally; typically, the z extent in these cases is 256mm, which extends well into the neck. if this data is not removed, automatic registration to a model brain can be very dodgy indeed 😬. also, removing a chunk of unneeded data is a big win for processing time and space. for example, to remove 25% of the data at the low end of the z axis:

autocrop smith_john_mri.mnc smith_john_crop.mnc \
  -extend 0,0 0,0 -25%,0

note that we supplied separate extension pairs for each dimension, but the extensions to x and y don't do anything. for z, the negative extension factor means remove data — 25% of it, to be specific. at the high end of the z axis, we do nothing. (and if your MRI data consistently has >5mm of empty space, you might save a little more time and space by shaving this off with -extend 0,0 0,0 -25%,-5mm. note the nifty mixing of units in one extension pair; this is perfectly legal and conceivably useful 🎀.)

🌈 MORE EXAMPLES 🌈

(Nothing yet.) — yes bestie, literally nothing yet. blank canvas. no invented examples here 🙈.

🔥 SEE ALSO 🔥

  • mincresample
  • mincreshape

go read those if you're feeling nosy 💅.

👑 AUTHOR 👑

Greg Ward, <greg@bic.mni.mcgill.ca>; inspired by the needs of fully-automated MRI-PET and MRI-Talairach registration. (hence see also mritotal and mritopet — and yes, mritopet doesn't actually have a man page yet 😭.)

🦋 AVAILABILITY 🦋

currently part of the MNI AutoReg package, available from:

http://packages.bic.mni.mcgill.ca/

so the legal tea is: Copyright (c) 1994-96 Greg Ward, McConnell Brain Imaging Centre, Montreal Neurological Institute, McGill University. you have permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee — provided that the above copyright notice appears in all copies. the author and McGill University make no representations about the suitability of this software for any purpose. it is provided "as is" without express or implied warranty. no promises, bestie 🫶.

also note that the programs mincreshape and mincresample are written and copyrighted by Peter Neelin, McConnell Brain Imaging Centre, with the same terms as above.

and that's the whole AUTOCROP(1) page, bestie! ✨ this icon is from the 3rd Berkeley Distribution, version MNI AutoReg 0.98, and the footer is serving AUTOCROP(1) realness — go crop something cute 💅🎀

📦 where this page comes from