Provided by: minc-tools_2.3.00+dfsg-10_amd64 bug

NAME

       mincresample - resamples a minc file along new spatial dimensions

SYNOPSIS

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

DESCRIPTION

       Mincresample  will  resample  a  minc  file  along  new  spatial dimensions with new voxel
       positions. Each volume in the input file (given by the spatial dimensions  xspace,  yspace
       and zspace) is resampled according to the command-line options. Non-spatial dimensions are
       preserved in their original order, but  spatial  dimensions  can  be  re-ordered  to  give
       transverse,  sagittal  or  coronal  images. The new voxel values are calculated using tri-
       linear, tri-cubic or nearest-neighbour interpolation.

WORLD COORDINATES

       World coordinates refer to  millimetric  coordinates  relative  to  some  physical  origin
       (either  the  scanner  or  some  anatomical  structure).  Voxel coordinates are simply the
       indices into the image  volume  of  a  given  voxel.   In  order  to  specify  appropriate
       resampling options, it is necessary to understand how MINC coordinate conversions work.

       Each  dimension  of  a MINC image volume is specified by name - the spatial dimensions are
       xspace, yspace and zspace. The convention is that positive xspace coordinates run from the
       patient's  left side to right side, positive yspace coordinates run from patient posterior
       to anterior and 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).  Thus the magnitude of the step attribute specifies the distance between voxels and
       the sign of the step attribute specifies the orientation of the axis.

       There  is  a  further  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. For example, 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).

       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  provide  a  complete  description  of  where  the  output sampling should be.
       However, when we are resampling data, we are 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.  This  change  of  world  coordinates  can  be  specified  through  the  use  of  a
       transformation  (.xfm)  file.  Thus,   in   general,   the   resampling   involves   three
       transformations:  from  the  input  file's  voxel  coordinates  to  its  world coordinates
       (specified by the input file), from the  input  world  coordinates  to  the  output  world
       coordinates  (specified  by  the  transformation  file),  and 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).  As well, resampling positions
       (output world to voxel conversion) are often specified  relative  to  a  model  file  (ie.
       resample this file so that it looks like that file). 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.

OPTIONS

       Note  that  options  can be specified in abbreviated form (as long as they are unique) and
       can be given anywhere on the command line.

General options

       -2     Create MINC 2.0 format output files.

       -clobber
              Overwrite an existing file.

       -noclobber
              Don't overwrite an existing file (default).

       -verbose
              Print out progress information for each slice computed (default).

       -quiet Do not print out progress information.

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. Thus a command with -like
       file.mnc -znelements 34 -zstep 2 will give a sampling like that in file  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).

       -invert_transformation
              Invert the transformation before using it.

       -noinvert_transformation
              Do no invert the transformation (default).

       -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).

       -use_input_sampling
              Use the input sampling as the default sampling, as is, without transformation, even
              though the data is being transformed (old behaviour).

       -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).

       -standard_sampling
              Set the sampling to standard values (start = 0, step = 1, direction  cosines  point
              along appropriate axes).

       -spacetype string
              Set the name of the output space (usually native____ or talairach_).

       -talairach
              Set the name of the output space to talairach_.

       -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.

       -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.

       -transverse
              Write out transverse slices.

       -sagittal
              Write out sagittal slices.

       -coronal
              Write out coronal slices.

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.

       -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.

       -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.

       -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.

       -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.

Interpolation options

       -trilinear
              Do a tri-linear interpolation between voxels. The edges of the volume  are  at  the
              centre of the first and last voxels of a dimension. This is the default.

       -tricubic
              Do  a  tri-cubic  interpolation  between voxels. The edges of the volume are at the
              centre of the first and last voxels of a dimension.

       -nearest_neighbour
              Do nearest neighbour interpolation between voxels (ie. find the  voxel  closest  to
              the  point and use its value). The edges of the volume are at the edge of the first
              and last voxels of a dimension (centre +/- half voxel separation).

       -sinc  Do renormalized windowed-sinc interpolation between voxels, as described by Thacker
              et al. JMRI 10:582-588 (1999).

       -width n
              Specifies  the  half-width of the sinc interpolation kernel, in the range from 1 to
              10. The full sinc kernel width is n * 2 + 1, and therefore varies  from  3  to  21.
              The default value is 5 giving a full-width of 11.

       -hanning
              Use a Hanning window with the sinc interpolant. This is the default.

       -hamming
              Use a Hamming window with the sinc interpolant.

Generic options

       -help  Print summary of command-line options and exit.

       -version
              Print the program's version number and exit.

EXAMPLES

       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)

                                   $Date: 2005-07-13 21:34:25 $                   MINCRESAMPLE(1)