.\"                                      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/rawtominc/rawtominc.man1,v 6.6 2005-02-09 19:27:18 bert Exp $
.\"
.TH RAWTOMINC 1 "$Date: 2005-02-09 19:27:18 $" "" "MINC User's Guide"

.SH NAME
rawtominc - converts a stream of binary image data to a minc format file

.SH SYNOPSIS 
.B rawtominc 
[\fIoptions\fR] \fIoutput.mnc\fR [[\fIsz4\fR] \fIsz3\fR] \fIsz2\fR \fIsz1\fR

.SH DESCRIPTION
.I Rawtominc
reads a stream of binary data (byte, short, long, float or double) from
standard input (unless the \fB\-input\fR option is used) and
writes it into the minc format file \fIoutput.mnc\fR. The user specifies the
dimension sizes from slowest varying to fastest varying. At least two
dimensions must be given (an image) but there can be up to four.
Options give the user control over dimension names, data types and
voxel to world coordinate conversion. Vector type data (such as RGB
pixel data) can be read in as well.

.SH PIXEL VALUE SPECIFICATION
Pixel values are specified by a type and a sign (e.g. signed short
integer). They are also characterized by a range of legal values. For
example, many scanners produce images stored with short integer pixel
values. Some have values in the range 0 to 4095, others 0 to 32000,
others -32768 to 32767. This range is the valid range, specified by
the \fB\-range\fR option (for floating point values, the valid range is the
maximum and minimum of the whole dataset). \fIRawtominc\fR allows the user
to specify both the input type, sign and range as well as the output
type, sign and range (read short values, store byte values, for
example).
.P
There is a further twist. Integer pixel values are generally taken to
be simply scaled pixel representations of real (meaningful) physical
values. Floating point values are taken to be the real value itself.
Thus floating point values are scanned for the maximum and minimum,
since they could be anything (they are stored in the MINC variables
\fBimage-max\fR and \fBimage-min\fR). Integer values, however, are not 
scanned by default, since their range can be given by an option. To 
force scanning of integer values when the maximum and minimum are not 
known (some scanners produce files with variable ranges), use the 
option \fB\-scan_range\fR.

.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.
It is worth describing briefly how MINC coordinate conversions work
since this will affect how successful the new MINC file will be. 

Each dimension of MINC image is specified by name - the spatial
dimensions are \fIxspace\fR, \fIyspace\fR and \fIzspace\fR. The
convention is that positive \fIxspace\fR coordinates run from the
patient's left side to right side, positive \fIyspace\fR coordinates
run from patient posterior to anterior and positive \fIzspace\fR
coordinates run from inferior to superior. For each of these spatial
dimensions, the world coordinate conversion is specified by a pair of
attributes: \fIstep\fR and \fIstart\fR.  The \fIxspace\fR 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 \fIstep\fR attribute specifies the
distance between voxels and the sign of the \fIstep\fR attribute
specifies the orientation of the axis. Programs will use this
information to display images with the correct aspect ratio and
orientation, so make sure that you get it right. Many scanners store
transverse images with the first pixel at the patient's anterior/right
side, so it would be necessary to give negative x and y step values.
Other conventions have the opposite: first pixel at patient's
posterior/left, so step values are positive. Sometimes the first slice
is inferior, so the z step should be positive. Other times it is
superior, so z step is negative.

The image axes do not have to be aligned with the world coordinate
axes. The axis directions are recorded in the file as direction
cosines - unit vectors - one for each spatial axis. In this case, the
\fIstep\fR and \fIstart\fR attributes described in the previous
paragraph refer to distances along the axis, not to coordinates of the
first voxel. This makes them invariant under a change of axis
direction (the whole coordinate system can in fact be rotated just by
changing the direction cosines). If the coordinate of the first voxel
is known, then it can be converted (projected) to a set of start
values by using the \fB\-origin\fR option.

.SH OPTIONS

.SH Dimension ordering
.TP
\fB\-transverse\fR
Transverse images   : [[time] z] y x (Default)
.TP
\fB\-sagittal\fR
Sagittal images     : [[time] x] z y
.TP
\fB\-coronal\fR
Coronal images      : [[time] y] z x
.TP
\fB\-time\fR
Time ordered images : [[z] time] y x
.TP
\fB\-xyz\fR
Dimension order     : [[time] x] y z
.TP
\fB\-xzy\fR
Dimension order     : [[time] x] z y
.TP
\fB\-yxz\fR
Dimension order     : [[time] y] x z
.TP
\fB\-yzx\fR
Dimension order     : [[time] y] z x
.TP
\fB\-zxy\fR
Dimension order     : [[time] z] x y
.TP
\fB\-zyx\fR
Dimension order     : [[time] z] y x
.TP
\fB\-dimorder\fR\ \fIdim1\fR,\fIdim2\fR[,\fIdim3\fR[,\fIdim4\fR]]
Specify an arbitrary dimension order, given by an comma-separated list
of between 2 and 4 dimension names.
.TP
\fB\-vector\fR\ \fIsize\fR
Gives the size of a vector dimension (always the fastest varying
dimension). Default is no vector dimension.

.SH Input data type and range
.TP
\fB-byte\fR
8-bit integer values (default).
.TP
\fB\-short\fR
16-bit integer values.
.TP
\fB\-int\fR
32-bit integer values.
.TP
\fB\-long\fR
Superseded by \fB\-int\fR.
.TP
\fB\-float\fR
Single-precision floating point values.
.TP
\fB\-double\fR
Double-precision floating point values.
.TP
\fB\-signed\fR
Values are signed integers (default for short and long). Ignored for
floating point types.
.TP
\fB\-unsigned\fR
Values are unsigned integers (default for byte). Ignored for
floating point types.
.TP
\fB\-range\fR\ \fImin\fR \fImax\fR
specifies the valid range of pixel values. Default is the full range
for the type and sign. This option is ignored for floating point
values.
.TP
\fB\-real_range\fR\ \fImin\fR \fImax\fR
specifies the real range of image values that corresponds to the pixel
values of option \fB\-range\fR. Default is to not store the real image
minimum and maximum. If \fB\-scan_range\fR is used, then the image minimum
and maximum corresponding to the scanned pixel minimum and maximum are
calculated and stored. This option is ignored for floating point values.
.TP
\fB\-swap_bytes\fR
Input values (either \fB\-short\fR or \fB\-int\fR) need to be converted 
between
Motorola (big-endian) and Intel (little-endian) data format.  If
"short" input is specified, adjacent bytes are swapped.  If "int"
input is specified, inner and outer byte pairs are swapped.  This
option has no effect with other input types.

.SH Output data type and range
.TP
\fB\-obyte\fR
Store 8-bit integer values (default is input type).
.TP
\fB\-oshort\fR
Store 16-bit integer values (default is input type).
.TP
\fB\-oint\fR
Store 32-bit integer values (default is input type).
.TP
\fB\-olong\fR
Superseded by \fB\-oint\fR.
.TP
\fB\-ofloat\fR
Single-precision floating point values (default is input type).
.TP
\fB\-odouble\fR
Double-precision floating point values (default is input type).
.TP
\fB\-osigned\fR
Values are signed integers (default for short and long). Ignored for
floating point types. If output type is not specified, then default
is input sign type.
.TP
\fB\-ounsigned\fR
Values are unsigned integers (default for byte). Ignored for
floating point types. If output type is not specified, then default
is input sign type.
.TP
\fB\-orange\fR\ \fImin\fR \fImax\fR
specifies the valid range of pixel values. Default is the full range
for the type and sign. This option is ignored for floating point
values. If output type and sign are not specified, then the default
is the input range.

.SH Scanning integers for range
.TP
\fB\-noscan_range\fR
Do not scan integer values for their minimum and maximum - assume that
the -range option gives the appropriate range of pixel values (default). 
No rescaling of pixel values is done (unless the output type differs
from the input type) and the created images are assumed to have a real
(not pixel value) minimum and maximum of zero and one.
.TP
\fB\-scan_range\fR
Integer values are scanned for their minimum and maximum. Pixel values
are rescaled to give the full range of pixel values and the real
minimum and maximum are set to the pixel minimum and maximum (unless
-real_range is used). This should be equivalent to converting the
input to a floating point type and reading it in with -float -oshort
(for example) assuming that -real_range is not used.

.SH Writing output file
.TP
\fB\-2\fR
Create MINC 2.0 format output files.
.TP
\fB\-clobber\fR
Overwrite existing minc file (default).
.TP
\fB-noclobber\fR
Don't overwrite existing minc file.

.SH Reading from input file
.TP
\fB\-input\fR\ \fIinputfile\fR
Read input data from \fIinputfile\fR instead of standard input.
.TP
\fB\-skip\fR\ \fIlength\fR
Skip the first \fIlength\fR bytes of the input.

.SH World coordinate conversion
.TP
\fB\-xstep\fR\ \fIxstep\fR
Step size for x dimension (default = none).
.TP
\fB\-ystep\fR\ \fIystep\fR
Step size for y dimension (default = none).
.TP
\fB\-zstep\fR\ \fIzstep\fR
Step size for z dimension (default = none).
.TP
\fB\-xstart\fR\ \fIxstart\fR
Starting coordinate for x dimension (default = none). This is a
distance parallel to the axis.
.TP
\fB\-ystart\fR\ \fIystart\fR
Starting coordinate for y dimension (default = none). This is a
distance parallel to the axis.
.TP
\fB\-zstart\fR\ \fIzstart\fR
Starting coordinate for z dimension (default = none). This is a
distance parallel to the axis.
.TP
\fB\-xdircos\fR\ \fIx1\fR\ \fIx2\fR\ \fIx3\fR
Direction cosines for x dimension (default = none).
.TP
\fB\-ydircos\fR\ \fIy1\fR\ \fIy2\fR\ \fIy3\fR
Direction cosines for y dimension (default = none).
.TP
\fB\-zdircos\fR\ \fIz1\fR \fIz2\fR\ \fIz3\fR
Direction cosines for z dimension (default = none).
.TP
\fB\-origin\fR \fIo1\fR\ \fIo2\fR\ \fIo3\fR
Specify the spatial coordinates of the first voxel. If the direction
cosines are not given or are the default ones, this option will
give the same results as using the -start options. Otherwise, the
coordinate is projected parallel to the axes to determine the
appropriate start values.

.SH Frame time and length specification
.TP
\fB\-frame_times\fR \fIt1\fR,\fIt2\fR,\fIt3\fR,...
Specify the start of each time frame. The number of values given must
be equal to the length of the time dimension specified on the command
line. All of the values given must be in one argument (no spaces
between them, or the string must be quoted). Separation by spaces
instead of commas is permitted.
.TP
\fB\-frame_widths\fR\ \fIw1\fR,\fIw2\fR,\fIw3\fR,...
Specify the length of each time frame. The comments for \fI-frame_times\fR
apply here as well.

.P
To set the start and step values for a functional file with a constant
frame times, use the \fI\-dattribute\fR\ flag described below 
as follows:

    -dattribute time:step=1 -dattribute time:start=0

.SH Imaging modality
.TP
\fB-nomodality\fR
Do not store modality type in file (default).
.TP
\fB\-pet\fR
PET data.
.TP
\fB\-mri\fR
MRI data.
.TP
\fB\-spect\fR
SPECT data.
.TP
\fB\-gamma\fR
Data from a gamma camera.
.TP
\fB\-mrs\fR
MR spectroscopy data.
.TP
\fB\-mra\fR
MR angiography data.
.TP
\fB\-ct\fR
CT data.
.TP
\fB-dsa\fR
DSA data
.TP
\fB\-dr\fR
Digital radiography data.

.SH Attribute specification
.TP
\fB\-sattribute\fR \fIvariable\fR:\fIattribute\fR=\fIvalue\fR
Specify that \fIvariable\fR should be created with string
\fIattribute\fR set to \fIvalue\fR. The complete specification,
including \fIvariable\fR, \fIattribute\fR and \fIvalue\fR, should be
contained in only one argument to the program - quoting may be needed
for strings containing blanks.
.TP
\fB\-dattribute\fR\ \fIvariable\fR:\fIattribute\fR=\fIvalue\fR :
Like \fB\-sattribute\fR, but for specifying double-precision attribute 
values.
.TP
\fB\-attribute\fR\ \fIvariable\fR:\fIattribute\fR=\fIvalue\fR
Like \fB\-sattribute\fR or \fB\-dattribute\fR, except that the type is
chosen by first trying to interpret the value as double precision - if
that fails, then the value is assumed to be a string.

.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 AUTHOR
Peter Neelin

.SH COPYRIGHTS
Copyright \(co 1993 by Peter Neelin