Man Linux: Main Page and Category List

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 $