.\"                                      Hey, EMACS: -*- nroff -*-
.\" Copyright 1993 Peter Neelin, McConnell Brain Imaging Centre,
.\" Montreal Neurological Institute, McGill University.
.\" Permission to use, copy, modify, and distribute this
.\" software and its documentation for any purpose and without
.\" fee is hereby granted, provided that the above copyright
.\" notice appear 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.
.\"
.\" $Header: /private-cvsroot/minc/progs/mincresample/mincresample.man1,v 6.4 2005-07-13 21:34:25 bert Exp $
.\"
.TH MINCRESAMPLE 1 "$Date: 2005-07-13 21:34:25 $" "" "MINC User's Guide"

.SH NAME
mincresample - resamples a minc file along new spatial dimensions

.SH SYNOPSIS
.B mincresample
[<options>] <infile> <outfile>

.SH DESCRIPTION
\fIMincresample\fR
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.

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

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

.SH General options
.TP
\fB\-2\fR
Create MINC 2.0 format output files.
.TP
\fB\-clobber\fR
Overwrite an existing file.
.TP
\fB\-noclobber\fR
Don't overwrite an existing file (default).
.TP
\fB-verbose\fR
Print out progress information for each slice computed (default).
.TP
\fB\-quiet\fR
Do not print out progress information.

.SH Resampling specification
Options that give the output sampling (all of the following except
\fB\-transformation\fR) are parsed in the order that they appear on the
command line. Thus a command with \fB\-like file.mnc \-znelements 34
\-zstep 2\fR will give a sampling like that in file in \fIfile.mnc\fR but with
34 samples at 2 mm along the \fIzspace\fR axis. The default sampling is
taken from the input file, transformed according to any transformation.
.TP
\fB\-transformation\fR\ \fIfile.xfm\fR
Specify a file giving the world coordinate transformation (default is
the identity transformation).
.TP
\fB\-invert_transformation\fR
Invert the transformation before using it.
.TP
\fB\-noinvert_transformation\fR
Do no invert the transformation (default).
.TP
\fB\-tfm_input_sampling\fR
Transform the input sampling (using the transform specified by
\fB\-transformation\fR) along with the data and use this as the default 
sampling (default).
.TP
\fB\-use_input_sampling\fR
Use the input sampling as the default sampling, as is, without
transformation, even though the data is being transformed (old
behaviour). 
.TP
\fB\-like\fR\ \fIfile.mnc\fR
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).
.TP
\fB\-standard_sampling\fR
Set the sampling to standard values (start = 0, step = 1, direction
cosines point along appropriate axes).
.TP
\fB\-spacetype\fR\ \fIstring\fR
Set the name of the output space (usually \fBnative____\fR or \fBtalairach_\fR).
.TP
\fB\-talairach\fR
Set the name of the output space to talairach_.
.TP
\fB\-units\fR\ \fIstring\fR
Set the units of the output space.
.TP
\fB\-origin\fR\ \fIox\ oy\ oz\fR
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.
.TP
\fB\-nelements\fR\ \fInx\ ny\ nz\fR
Number of elements along each of the world dimensions.
.TP
\fB\-xnelements\fR\ \fInx\fR
Number of elements along the xspace dimension.
.TP
\fB\-ynelements\fR\ \fIny\fR
Number of elements along the yspace dimension.
.TP
\fB\-znelements\fR\ \fInz\fR
Number of elements along the zspace dimension.
.TP
\fB\-step\fR\ \fIxstep\ ystep\ zstep\fR
Step between voxels along each of the world dimensions.
.TP
\fB\-xstep\fR\ \fIxstep\fR
Step between voxels along the xspace dimension.
.TP
\fB\-ystep\fR\ \fIystep\fR
Step between voxels along the yspace dimension.
.TP
\fB\-zstep\fR\ \fIzstep\fR
Step between voxels along the zspace dimension.
.TP
\fB\-start\fR\ \fIxstart\ ystart\ zstart\fR
Position of centre of first voxel along each of the world dimensions.
.TP
\fB\-xstart\fR\ \fIxstart\fR
Position of centre of first voxel along the xspace dimension.
.TP
\fB\-ystart\fR\ \fIystart\fR
Position of centre of first voxel along the yspace dimension.
.TP
\fB\-zstart\fR\ \fIzstart\fR
Position of centre of first voxel along the zspace dimension.
.TP
\fB\-dircos\fR\ \fIx1\ x2\ x3\ y1\ y2\ y3\ z1\ z2\ z3\fR
Direction cosines for each of the world axes.
.TP
\fB\-xdircos\fR\ \fIx1\ x2\ x3\fR
Direction cosines for the xspace dimension.
.TP
\fB\-ydircos\fR\ \fIy1\ y2\ y3\fR
Direction cosines for the yspace dimension.
.TP
\fB\-zdircos\fR\ \fIz1\ z2\ z3\fR
Direction cosines for the zspace dimension.

.SH Dimension ordering
The default is to preserve the original dimension order.
.TP
\fB\-transverse\fR
Write out transverse slices.
.TP
\fB\-sagittal\fR
Write out sagittal slices.
.TP
\fB\-coronal\fR
Write out coronal slices.

.SH 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.
.TP
\fB\-byte\fR
Store output voxels in 8-bit integer format.
.TP
\fB\-short\fR
Store output voxels in 16-bit integer format.
.TP
\fB\-int\fR
Store output voxels in 32-bit integer format.
.TP
\fB\-long\fR
Superseded by \fB\-int\fR.
.TP
\fB-float\fR
Store output voxels in 32-bit floating point format.
.TP
\fB-double\fR
Store output voxels in 64-bit floating point format.
.TP
\fB\-signed\fR
Write out values as signed integers (default for short and long). Ignored for
floating point types.
.TP
\fB\-unsigned\fR
Write out values as unsigned integers (default for byte). Ignored for
floating point types.
.TP
\fB\-range\fR \fImin max\fR
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.
.TP
\fB\-keep_real_range\fR
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.
.TP
\fB\-nokeep_real_range\fR
Recompute the real minimum and maximum for each output slice. This is
the default.

.SH Handling of undefined (invalid) voxel values
.TP
\fB\-fill\fR
Output voxels that fall outside of the input volume have undefined
values. When the \fB-fill\fR 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
\fIimage-max\fR and \fIimage-min\fR variables.
.TP
\fB\-nofill\fR
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 \fIimage-max\fR and \fIimage-min\fR variables.
This is the default.
.TP
\fB\-fillvalue\fR\ \fIfillvalue\fR
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 \fIimage-max\fR and \fIimage-min\fR variables.

.SH Interpolation options
.TP
\fB\-trilinear\fR
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.
.TP
\fB\-tricubic\fR
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.
.TP
\fB\-nearest_neighbour\fR
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).
.TP
\fB\-sinc\fR
Do renormalized windowed-sinc interpolation between voxels, as described
by Thacker et al. JMRI 10:582-588 (1999).
.TP
\fB\-width\fR \fIn\fR
Specifies the half-width of the sinc interpolation kernel, in the range
from 1 to 10. The full sinc kernel width is \fIn\fR * 2 + 1, and therefore
varies from 3 to 21.  The default value is 5 giving a full-width of 11.
.TP
\fB\-hanning\fR
Use a Hanning window with the sinc interpolant. This is the default.
.TP
\fB\-hamming\fR
Use a Hamming window with the sinc interpolant.

.SH Generic options
.TP
\fB\-help\fR
Print summary of command-line options and exit.
.TP
\fB\-version\fR
Print the program's version number and exit.

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

.SH AUTHOR
Peter Neelin

.SH COPYRIGHTS
Copyright \(co 1993 by Peter Neelin

.SH "SEE ALSO"
.LP
.BR mincreshape (1)