MINC - Medical Image NetCDF

INTRODUCTION
------------
The MINC file format is a highly flexible medical image file format
built on top of the HDF5 generalized data format. The format is
simple, self-describing, extensible, portable and N-dimensional, with
programming interfaces for both low-level data access and high-level
volume manipulation. On top of the libraries is a suite of generic
image-file manipulation tools. The format, libraries and tools are
designed for use in a medical-imaging research environment : they are
simple and powerful and make no attempt to provide a pretty interface
to users.

Here's a list of some of the tools:

 * rawtominc, minctoraw, mincextract - format conversion
 * mincheader, mincdiff, mincinfo, minchistory - file information
 * mincedit, minc_modify_header - header manipulation
 * mincresample - arbitrary volume resampling
 * mincreshape - extraction of volume sub-cubes, image flipping,
      dimension re-ordering, type conversion
 * mincconcat - concatenating or interleaving images from multiple
      files
 * mincmath - perform simple math on files
 * minccalc - perform more complicated math on files through an expression
 * mincaverage - average minc files
 * mincstats - calculate statistics across voxels of a file
 * minclookup - lookup table operations for arbitrary re-mappings of
      intensities
 * worldtovoxel, voxeltoworld - coordinate conversion
 * xfmconcat, xfminvert - generalized transformation utilities
 * mincview - simple image display using xv or ImageMagick
 * mincpik - generate picture from slice through volume


Additional tools are available from the Montreal Neurological
Institute (MNI). These include register, a program designed for
manual, landmark-based volume registration using a tri-plane interface
that allows the user to roam simultaneously through two data volumes
plus the combined volume that overlays the data of the other two. Emma
is a minc interface to matlab (from The MathWorks) with functions to
facilitate image processing and display.  mni_autoreg provides automated
registration, both linear and nonlinear.


GETTING MINC
------------
The minc package is available from

    http://packages.bic.mni.mcgill.ca/tgz

Minc requires that the NetCDF and HDF5 packages be built and installed first.
It is available from the Unidata Program centre at
the University Corporation for Atmospheric Research (unidata.ucar.edu). 

For building and installation instructions, refer to the files
INSTALL.minc and INSTALL.


SUPPORT FOR HDF5 "MINC 2.0" FORMAT FILES
----------------------------------------

1.1 HDF5

This change requires that HDF5 must be installed before MINC can be
built.  The latest version of HDF5 is 1.6.2.  You can obtain HDF5
here:

http://hdf.ncsa.uiuc.edu/HDF5/release/obtain5.html

You should NOT need to become an HDF5 expert to use MINC 2.0.
However, two tools included with HDF5 may prove useful, "h5dump" and
"h5ls".  h5dump is roughly equivalent to netCDF's ncdump utility.
There is no exact netCDF tool analogous to h5ls.  h5ls is useful for
exploring and extracting bits of the HDF5 hierarchy.

1.2 New command Line options

All MINC tools which produce output MINC files now take a "-2" option
which will tell the tool to output a MINC 2.0 format file.  All MINC tools
also take a "-version" flag.

1.3 Compatibility

To the extent possible, the core MINC tools should operate "correctly"
on MINC 1.0 and 2.0 files.  There are a few notable exceptions.
Scripts such as "mincdiff", "mincedit", and "mincheader" may not
work, or will produce odd results since they depend on the ASCII
format of the netCDF "ncdump" and "ncgen" utility.  I'm open to
suggestions for the best way to handle this.  We have an unfinished
"mincdump" tool which replaces "ncdump", but we do not yet have a
replacement for "ncgen".

1.4 Conversion

There is a new conversion utility called "mincconvert".  This is just
a trivial library wrapper that can copy a file from the input to the
output while performing a conversion.

2. REVISED ERROR MESSAGE HANDLING.

I have somewhat revised the ways in which MINC decides when and how to
print error messages, with the hope to gradually improve the readability
and usefulness of these messages.  In some cases I have probably been too
aggressive, and messages will now appear which really don't belong.  Please
let me know which ones are most annoying, and I'll try to get rid of them.

3. TENTATIVE ".mincrc" AND ENVIRONMENT VARIABLE SUPPORT

I've implemented this as a way to control certain behaviors of the library
which are not readily available through other means. These variables may
be defined either in your environment, or in the .mincrc file in your
home directory.  The value in the environment should override the one in
.mincrc. 

Here's what exists so far:

# Force output files to MINC 2.0 format, regardless of the "-2" option.
#
MINC_FORCE_V2 = {1, 0}

# Desired ZLIB compression level.  Zero implies no compression, a value
# of 4 gives a good tradeoff of compression and performance.
#
MINC_COMPRESS = {0..9} 

# Desired HDF5 chunking dimension.  This controls the size of the
# "hypercube" used by HDF5 to store the file.  If set to zero, the
# file will not be stored in a chunked format, unless compression is
# enabled.  The chunk size will automatically be reduced if it exceeds
# any actual dimension of the volume.  If chunking is enabled
# automatically because of compression, the default chunk dimension is
# 32.
#
MINC_CHUNKING = {0..N}

# Log file - path to the desirned output file for messages.  The default
# is the standard error (stderr) stream.  To redirect to standard output,
# set this variable to "stdout" or "-".  Otherwise the variable is taken
# to be the path to the desired log file.  If the path name begins with
# a '+' character, the log file should be appended rather than recreated.
#
MINC_LOGFILE = [+]<pathname>|stdout|-

# Logging level.  Not really useful yet, but intended to allow setting
# of 'verbosity' of messages.  A value of zero would inhibit all but
# fatal messages, a value of 4 would allow debugging messages.
#
MINC_LOGLEVEL = 0-4

4. NEW PROGRAMMING INTERFACE

4.1. New MINC 1.0 calls

A couple of new things have been added to libminc:

 /* Returns a printable library version string */
const char * miget_version();

/* Appends "new_history" to the file's history attribute. */
int miappend_history(int fd, const char *new_history);

4.2. New MINC 2.0 calls

This is a new set of calls, defined in "minc2.h" and the assorted source
files found in the libsrc2 directory.

The general philosophy is to provide a higher level interface than "libminc",
but without some of the constraints and memory management of "volume_io".

The library is largely implemented but is still incomplete.  In general
functions which are most obviously useful and standard have been implemented,
while some of the more esoteric features have not been finished.  I would
appreciate all comments and criticisms both of the overall design and
the specific implementation.

Documentation for the new calls can be found at:

http://www.bic.mni.mcgill.ca/software/minc2/api_doc/index.html