MINC - Medical Image NetCDF

INTRODUCTION
------------
The MINC file format is a highly flexible medical image file format
built on 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).

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

MINC requires that NetCDF and HDF5 are installed.


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

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 from:

   http://www.hdfgroup.org/

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

This is implemented 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".


DOCUMENTATION
-------------

http://en.wikibooks.org/wiki/MINC


PROGRAMMING WITH THE MINC API
-----------------------------

1) NetCDF and HDF5 are basis, providing a C callable
library for accessing data structures in a file at a low-level.

2) The low-level MINC library is used to do medical-image specific 
things. It provides some enhancements to NetCDF and HDF5
as well as image conversion routines for dealing with image pixel
value issues as well as image size and orientation. Documentation
consists of a programmer's guide and reference (minc_user.tex and
minc_reference.tex in the doc directory).  Example C programs exist
in progs/mincexample.

3) A high-level C library called volume_io provides a Volume data
type, with functions like input_volume to give simple access to data
while handling issues of pixel range conversion and voxel-to-world
coordinate conversion. Documentation consists of a programmer's
reference volume_io/Documentation/volume_io.tex.  Example programs
exist in volume_io/Testing.

The LaTeX documentation is not built by default.  You can build these
documents using

    cd doc; make docs
    cd volume_io/Documentation; make docs

latex and dvips are required.


Applications that use MINC alone need to #include <minc.h> and
link with "-lminc2 -lnetcdf -lhdf5 -lz -lm".

Applications built with VolumeIO need to #include <volume_io.h>
and link with "-lvolume_io2 -lminc2 -lnetcdf -lhdf5 -lz -lm".