mincresample - resamples a minc file along new spatial dimensions

       Peter Neelin

       Copyright © 1993 by Peter Neelin

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.

       The default is to preserve the original dimension order.

       -transverse
              Write out transverse slices.

       -sagittal
              Write out sagittal slices.

       -coronal
              Write out coronal slices.

       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

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

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

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

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

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

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

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

       mincresample - resamples a minc file along new spatial dimensions

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

       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.

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

       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 -likefile.mnc-znelements34-zstep2
       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.

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

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

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

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

       -unitsstring
              Set the units of the output space.

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

       -nelementsnxnynz
              Number of elements along each of the world dimensions.

       -xnelementsnx
              Number of elements along the xspace dimension.

       -ynelementsny
              Number of elements along the yspace dimension.

       -znelementsnz
              Number of elements along the zspace dimension.

       -stepxstepystepzstep
              Step between voxels along each of the world dimensions.

       -xstepxstep
              Step between voxels along the xspace dimension.

       -ystepystep
              Step between voxels along the yspace dimension.

       -zstepzstep
              Step between voxels along the zspace dimension.

       -startxstartystartzstart
              Position of centre of first voxel along each of the world dimensions.

       -xstartxstart
              Position of centre of first voxel along the xspace dimension.

       -ystartystart
              Position of centre of first voxel along the yspace dimension.

       -zstartzstart
              Position of centre of first voxel along the zspace dimension.

       -dircosx1x2x3y1y2y3z1z2z3
              Direction cosines for each of the world axes.

       -xdircosx1x2x3
              Direction cosines for the xspace dimension.

       -ydircosy1y2y3
              Direction cosines for the yspace dimension.

       -zdircosz1z2z3
              Direction cosines for the zspace dimension.

mincreshape(1)

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

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

       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.