View source for MINC/SoftwareDevelopment/MINC2.0 File Format Reference

=The MINC 2.0 File Format=

The MINC (Medical Imaging NetCDF) 1.0 file format was designed as a
file format for medical imaging data building upon the NetCDF (Network
Common Data Format) standard [http://www.unidata.ucar.edu/downloads/netcdf NETCDF].  
MINC was designed specifically to provide the medical-imaging research 
community with a modality-neutral way to store medical images 
along with a rich and flexible set of supporting data.

While the MINC 1.0 file format has been found to be both powerful
and useful over the last decade, a number of limitations have been
identified by its users.  In particular, three of these limitations
have driven the design of MINC 2.0, the next step in MINC's evolution.

The first of these limitations is the lack of support for files larger
than 2 gigabytes in present versions of NetCDF.  This is proving to be
an important limitation for newer, high-resolution functional and
anatomical imaging applications.

The second is the need to allow a single medical image file to contain
data at several levels of resolution.  This is useful for network
image viewing applications, for example. HDF5's 
[http://www.hdfgroup.org/HDF5 HDF5] hierarchical
organization and larger supported file sizes help to enable this
feature.

The third motivation is the need for internal, transparent data
compression.  The MINC 1.0 library allows files to be compressed using
an external program such as gzip, bzip2, etc. Unfortunately, external
compression requires that the entire file be decompressed even if only
a small portion of the image is to be examined.  In addition,
compression must be applied as an explicit post-processing step after
a file is created.  The impact of these problems increases with file
size.

To address these and other issues, the MINC development team has
chosen to implement support for HDF5 (Hierarchical Data Format 5).
Compared to NetCDF, HDF5 provides enhanced support for
complex file structure, hierarchical name spaces, structured and
enumerated data types, and internal compression.

This document is intended to describe the specifics of the MINC 2.0
file format by defining the specific variables, attributes,
organization, and conventions used by these files, as implemented as a
specialization of the generic HDF5 format.
Much of the information in this document is excerpted from 
the ''[[MINC/Reference/MINC1-programmers-guide|MINC Programmer's Reference Manual]]'' by Peter Neelin.

'''NOTE''': Throughout this document, literal MINC variable names,
attribute names, and predefined values are set in a ''fixed-width''
font.

=Coordinates and Dimensions=


MINC 2.0 associates the dimensions of a medical image with mnemonic
textual names, such as '''xspace''' or '''time'''.  This
association serves both to clarify the interpretation of each
dimension and to specify the relationships among variables that share
the same coordinate space.  The length of a dimension is defined when
the file is created, and cannot be changed once the file has been
written to the storage medium.

==MINC 2.0 coordinate system==

MINC 2.0, like MINC 1.0, defines both a 'voxel' and a 'world'
spatial coordinate system.  Voxel coordinates are analogous to array
indices: The voxel coordinate values are nonnegative integers ranging
from zero to one less than the number of data points along the axis,
with the origin fixed at one corner of the image.

In contrast, the 'world' coordinate system reflects the real world
units and spatial orientation of the image.  MINC world coordinates
are derived from voxel coordinates using the dimension variable
attributes ''direction_cosines'', ''step'', and ''start''.  
The direction cosine vector is a unit
vector which is defined for each spatial dimension.  Using the
notation {{math|<VAR>c</VAR><sub>ij</sub>}}
to indicate the component {{math|<VAR>i</VAR>}} of the  axis in the 
{{math|<VAR>j</VAR>}}
direction, the cosine vector {{math|<VAR>c</VAR><sup>&rarr;</sup><sub>i</sub>}} for the
axis {{math|<VAR>i</VAR>}} can be written:
:{{math|<VAR>c</VAR><sup>&rarr;</sup><sub>i</sub> {{= }}( <VAR>c</VAR><sup>&rarr;</sup><sub>ix</sub>, <VAR>c</VAR><sup>&rarr;</sup><sub>iy</sub>, <VAR>c</VAR><sup>&rarr;</sup><sub>iz</sub>)}}
Using  {{math|<VAR>step</VAR><sub>i</sub>}} to represent the value of the ''step'' attribute for
spatial axis {{math|<VAR>i</VAR>}}, and defining {{math|<VAR>start</VAR><sub>i</sub>}} similarly for the ''start''
attribute, the vector {{math|<VAR>v</VAR><sup>&rarr;</sup><sub>i</sub>}} between adjacent
elements along that axis is:
:{{math|<VAR>v</VAR><sup>&rarr;</sup><sub>i</sub> {{= }} <VAR>step</VAR><sub>i</sub> * <VAR>c</VAR><sup>&rarr;</sup><sub>i</sub> }}
and the origin {{math| (<VAR>0,0,0</VAR>)}} in voxel coordinates is located at world
coordinates {{math| (<VAR>o<sub>x</sub>,o<sub>y</sub>,o<sub>z</sub></VAR>)}} as given by:

<math>\begin{bmatrix}
 o_x \\
 o_y \\ 
 o_z \end{bmatrix} =
\begin{bmatrix}
 c_{xx}  &  c_{yx}  &  c_{zx} \\
 c_{xy}  &  c_{yy}   & c_{zy} \\ 
 c_{xz}  &  c_{yz}   & c_{zz} \end{bmatrix}
\begin{bmatrix}
 start_x \\
 start_y \\ 
 start_z \end{bmatrix}
</math>

Any homogeneous coordinate in voxel space 
{{math| (<VAR>v<sub>x</sub>,v<sub>y</sub>,v<sub>z</sub></VAR>, 1)}}
can be transformed to its equivalent in world space using
the following scaling, rotation and translation transformations:
:
<math>\begin{bmatrix}
 w_x \\
 w_y \\ 
 w_z \\
 w_w \end{bmatrix} =
\begin{bmatrix}
 1  &  0  &  0 & o_x \\
 0  &  1  &  0 & o_y \\ 
 0  &  0  &  1 & o_z \\
 0  &  0  &  0 & 1 \end{bmatrix}
\begin{bmatrix}
 c_{xx}  &  c_{yx}  &  c_{zx} & 0 \\
 c_{xy}  &  c_{yy}  &  c_{zy} & 0 \\ 
 c_{xz}  &  c_{yz}  &  c_{zz} & 0 \\
 0       &  0       &  0      & 1 \end{bmatrix}
\begin{bmatrix}
 step_x  &  0       &  0      & 0 \\
 0       &  step_y  &  0      & 0 \\ 
 0       &  0       &  step_z & 0 \\
 0       &  0       &  0      & 1 \end{bmatrix}
\begin{bmatrix}
 v_x \\
 v_y \\ 
 v_z \\
  1 \end{bmatrix}
</math>
:
Which, composed, give the following equation:
:
<math>\begin{bmatrix}
 w_x \\
 w_y \\ 
 w_z \\
 w_w \end{bmatrix} =
\begin{bmatrix}
 c_{xx} step_x  &  c_{yx} step_y  &  c_{zx} step_z & o_x \\
 c_{xy} step_x  &  c_{yy} step_y  &  c_{zy} step_z & o_y \\ 
 c_{xz} step_x  &  c_{yz} step_y  &  c_{zz} step_z & o_z \\
 0              &  0              &  0             & 1 \end{bmatrix}
\begin{bmatrix}
 v_x \\
 v_y \\ 
 v_z \\
  1 \end{bmatrix}
</math>
:
The inverse transformation from world to voxel space can be performed using the following equation:
:
<math>\begin{bmatrix}
 v_x \\
 v_y \\ 
 v_z \\
 v_w \end{bmatrix} =
\begin{bmatrix}
 c_{xx} / step_x & c_{xy} / step_x & c_{xz} / step_x & \frac{-o_x c_{xx} - o_y c_{xy} - o_z c_{xz}}{step_x} \\ 
 c_{yx} / step_y & c_{yy} / step_y & c_{yz} / step_y & \frac{-o_x c_{yx} - o_y c_{yy} - o_z c_{yz}}{step_y} \\
 c_{zx} / step_z & c_{zy} / step_z & c_{zz} / step_z & \frac{-o_x c_{zx} - o_y c_{zy} - o_z c_{zz}}{step_z} \\
 0               & 0               & 0               & 1 \end{bmatrix}
\begin{bmatrix}
 w_x \\
 w_y \\ 
 w_z \\
  1 \end{bmatrix}
</math>
:

While MINC 2.0 files may store data in any orientation, MINC 2.0
follows common medical imaging practice in defining the orientation of
world spatial coordinates relative to patients.  The convention is
that the positive {{math|<VAR>x</VAR>}} axis increases from patient left to right,
the positive {{math|<VAR>y</VAR>}} axis increases from patient posterior to
anterior, and the positive {{math|<VAR>z</VAR>}} axis increases from patient inferior
to superior.

==Dimension variables==
To represent the full set of attributes associated with a MINC
dimension object, MINC 2.0 defines a 'dimension variable', which is
a variable with the same name as the corresponding dimension object. In
MINC 2.0 these variables, like all other variables, are implemented as
HDF5 'datasets'.

MINC dimensions may have either ''regular'' or ''irregular''
spacing.  Regularly-sampled dimensions are sampled at a constant
interval, while irregularly-sampled dimensions are sampled at
arbitrary positions along the axis.

Because regular dimensions are sampled at a constant interval, they
are fully defined by their origin and step size.  Therefore, the
dimension variable for a regular dimension contains no meaningful
data.

For an irregular dimension, the value of the dimension variable must
be a vector with a length equal to the number of sampled points along
the dimension.  The value of the vector at a given index gives the
value of the dimension at that sample point.

==Associating HDF5 dataspaces with MINC dimensions==

NetCDF defines a named-dimension abstraction which permits a dimension
and its length to be associated with a text symbol.  This dimension
may then be used to define any number of NetCDF variables.  MINC 1.0
relies on this feature to link the dimensionality of related objects.
Unfortunately, HDF5 does not implement a comparable dimension
abstraction.  Instead, all HDF5 data objects (datasets and attributes)
are associated with an HDF5 construct called a 'dataspace'.  A
dataspace in HDF5 may either be of one of two classes, 'scalar' or
'simple'.  Simple dataspaces consist of an ordered list of dimension
lengths. Dataspaces in HDF5 are not global entities, and cannot be
assigned symbolic names - every data object is associated with its own
dataspace.

Since the structure of the dataspace alone is insufficient to allow
software to discover the relationships between the dimensions of
associated data objects, MINC 2.0 defines a ''dimorder'' attribute
that makes these relationships explicit.  Every data object that is
non-scalar must have an associated ''dimorder'' attribute.

The ''dimorder'' attribute's value is a character string which
consists of an ordered, comma-separated list of the mnemonic names
associated with the dimensions.  This provides an adequate, if
imperfect, replacement for the named dimensions of NetCDF.


==Standard dimension names==
MINC defines standard interpretations for the following dimension
names. Specialized applications are free to define either alternative
or supplemental dimensions using other names as desired.


* ''xspace'' - Spatial axis, defined to increase from  patient left to patient right.
* ''yspace'' - Spatial axis, defined to increase from patient posterior to patient anterior.
* ''zspace'' - Spatial axis, defined to increase from patient inferior to patient superior.
* ''time'' - Time axis.
* ''xfrequency'' - Spatial frequency axis.
* ''yfrequency'' - Spatial frequency axis.
* ''zfrequency'' - Spatial frequency axis.
* ''tfrequency'' - Temporal frequency axis.
* ''vector_dimension'' - Axis for vector or complex data.  If present, this must be the last (i.e. the fastest varying) dimension.


=Variables=


MINC variables fall into one of four classes.  The first is the 
''group'' class, which applies to those data objects and names used to
hold actual image data and supporting information.  The second is the
''var-attribute'' class, which contains data qualifying another
variable, for example, by specifying the range of the other variable's
data.  The third and fourth are the ''dimension'' class and the 
''dimension-width'' class, which specify the properties of the dimensions
in a MINC file.

For consistency, all MINC variables are implemented as HDF5 datasets,
including those variables which may not contain useful data.

In MINC 2.0, the ''image'', ''image-max'', and ''image-min''
variables are no longer single objects as in MINC 1.0.  A file may
contain any number of sets of these three variables, corresponding to
the full resolution data and any lower-resolution 'thumbnail' data
which may be associated with the image.

==Standard MINC Variable Names==

* ''image'' - The ''image'' variable is of class ''group''.  It is the variable which actually contains image data in a MINC file, so it is defined using whatever type and dimensions are required to represent the image.  By convention, MINC considers the first spatial dimension of the ''image'' variable to be the 'slice' dimension, and any other spatial dimensions are considered to be 'image' dimensions.  The ''image'' variable is the only variable whose presence in a MINC file is mandatory.

* ''image-min'' - The ''image-min'' variable is of class ''var-attribute''.  If per-slice scaling of the image data is enabled, this variable must contain 64-bit floating-point data which provides the lowest value of the real range for each slice.  The dimensionality of either the ''image-min'' or the ''image-max'' variable corresponds to the first one or two dimensions of the ''image'' variable.  For example, in an fMRI dataset with a dimension ordering of ''time'', ''zspace'', ''yspace'', ''xspace'', the ''image-min''  variable may be a 2D array with dimensions ''time'' and ''zspace''.  It is acceptable for the ''image-min'' to have lower dimensionality.  For example, the variable could be a 1D array array along the ''time'' dimension, or it may be a scalar to specify a global minimum real value.
* ''image-max'' - The ''image-max'' is the counterpart to the ''image-min'' variable, except that it contains the maximum value of the real data range for each data slice.
* ''study'' - This variable is of class ''group''.  It contains no useful data, but serves only to group those attributes which contain information about the study of which this image is a part. Since the variable contains no data, the type is irrelevant.
* ''patient'' - Like the ''study'' variable, this variable is of class ''group'' and contains no data.  It serves to group the attributes which specify the identification and characteristics of the patient.
* ''acquisition'' - The ''acquisition'' variable is of class ''group''.  Like the ''study '' and ''patient'' variables, the ''acquisition'' variable never contains useful data, but serves only to group those attributes which contain information about the image acquisition parameters, modality, etc.
* ''xspace'' - Variable of class ''dimension'' which groups the attributes specifying the X axis.
* ''yspace'' - Variable of class ''dimension'' which groups the attributes specifying the Y axis.
* ''zspace'' - Variable of class ''dimension'' which groups the attributes specifying the Z axis.
* ''time'' - Variable of class ''dimension'' which groups the attributes specifying the time axis.
* ''xfrequency'' - Variable of class ''dimension'' which groups the attributes specifying the spatial frequency axis.
* ''yfrequency'' - Variable of class ''dimension'' which groups the attributes specifying the spatial frequency axis.
* ''zfrequency'' - Variable of class ''dimension'' which groups the attributes specifying the spatial frequency axis.
* ''tfrequency'' - Variable of class ''dimension'' which groups the attributes specifying the temporal frequency axis.
* ''xspace-width'' - Variable of class ''dimension-width'' which groups the attributes specifying the width of samples along the X axis.
* ''yspace-width'' - Variable of class ''dimension-width'' which groups the attributes specifying the width of samples along the Y axis.
* ''zspace-width'' - Variable of class ''dimension-width'' which groups the attributes specifying the width of samples along the Z axis.
* ''time-width'' - Variable of class ''dimension-width'' which groups the attributes specifying the width of samples along the time axis.
* ''xfrequency-width'' - Variable of class ''dimension-width'' which groups the attributes specifying the width of samples along the spatial frequency axis.
* ''yfrequency-width'' - Variable of class ''dimension-width'' which groups the attributes specifying the width of samples along the spatial frequency axis.
* ''zfrequency-width'' - Variable of class ''dimension-width'' which groups the attributes specifying the width of samples along the spatial frequency axis.
* ''tfrequency-width'' - Variable of class ''dimension-width'' which groups the attributes specifying the width of samples along the temporal frequency axis.


==Hierarchy==


MINC 2.0 makes extensive use of the hierarchical capabilities of
HDF5.  HDF5 allows the creation of 'groups', which roughly correspond
to UNIX directories, and 'datasets', which roughly correspond to UNIX
files.  An HDF5 group is a container which may enclose any number of other
groups or datasets.

All HDF5 objects in a file are considered to be children of a
'root' group, similar to the root directory in a UNIX filesystem.

To allow MINC 2.0 data to exist alongside other data structures in a
single HDF5 file, and to help differentiate MINC 2.0 files from other
HDF5 files, a MINC group named ''minc-2.0'' is created within the
HDF5 root group.  This group should be the only entry a MINC program
creates in the HDF5 root group.  All other MINC objects are created
within (or 'below') the ''minc-2.0'' group.

All MINC 2.0 dimension variables are placed in a subgroup called
''dimensions''.  These dimension variables are considered global to
all of the MINC objects in the file.

The MINC 2.0 informational variables (''study'', ''patient'', etc.),
are placed in a subgroup called ''info''.  This subgroup is intended
to be the repository of all ancillary data related to the scan, modality,
study, etc.

The MINC 2.0 image variables are placed in a subgroup called
''image''.  For every resolution stored in the file, there must be a
subgroup which takes the name ''0'', ''1'', ''2'', etc.  The full
resolution data is stored within group ''0'', and each successive
integer corresponds to a factor of 2 reduction in all image
dimensions.  Within each of these subgroups are three datasets,
''image'', ''image-min'', and ''image-max''.

The primary rationale for this hierarchy is to anticipate future
extensions to the MINC file format.  Additional classes of data could
be stored in a group alongside the ''image'' group.  For example, a
'''geometry''' or '''objects''' group might be added to
contain geometric data associated with or derived from the image.
These geometric objects presumably would share the dimensions of the
image.
[http://commons.wikimedia.org/wiki/File:MINC2_hierarchy.png Figure 1: MINC2.0 Hierarchy]

=Attributes=

Attributes are ancillary data objects, normally of a limited size,
associated with another object in the MINC 2.0 file.  These attributes
typically consist of either text or numeric data.  In MINC, attributes
are used to specify additional information about a variable or file.

MINC attributes can be considered to fall into three broad categories:
Those which apply globally to the MINC file itself, those which play a
structural role in defining the MINC file organization, and those
which contain data or parameters associated with a specific group or
data object.

Some string attributes are 'freeform' and may contain any value
without restrictions on format and length.  Other string attributes
are assumed to have a specific format.  Still other string attributes
must contain one of several well-known values.  When this is the case,
the well-known strings are padded with underscore characters to the
length of the longest legal value.  This convention was adopted to
avoid restrictions imposed by NetCDF on increasing the lengths of
existing attributes.  Since this restriction is lifted in HDF5, future
attributes need not follow this convention.

Numeric attributes may be in either integer or floating-point format.
The MINC library provides attribute access routines which
automatically convert a value to the desired type on retrieval.

HDF5 attributes may be attached to any group or dataset.  In MINC 2.0,
two attributes, ''history'' and ''title'', are attached to the
'''minc-2.0''' group.  All other MINC attributes are local to a
specific variable.

==MINC 2.0 Global Attributes==
These two attributes, each consisting of text string, apply to the 
entire MINC file.  They are therefore attached to the
'''minc-2.0''' group.

* ''history'' - A ''global'' string attribute which is used to implement an audit trail. This is a character array with a line for each invocation of a program that has modified the dataset. All MINC applications should append a line containing: date, time of day, user name, program name and command arguments for each processing step. This attribute should be considered mandatory.

* ''title'' - A ''global'' string attribute which provides a description of the MINC file's contents.  In practice this is optional and somewhat rarely used.


==MINC 2.0 Structural Attributes==

Several MINC attributes are used to describe the types of variables
and the relationships among variables.

These variables are considered 'structural' in the sense that they
convey no useful information about the medical image stored in the
MINC file, but instead serve to support the MINC format itself.

Each of these attributes (except for ''comments'') should be
considered mandatory for any MINC standard variable.

* ''comments'' - String giving descriptive information about the  variable or group, provided for informational purposes only.
* ''dimorder'' - String identifying the symbolic dimensions associated with the data object.  This attribute is an ordered, comma-separated list of the names of these dimensions. All non-scalar MINC variables must define this attribute.

* ''vartype'' - String identifying the class of the variable, one of '''group________''', '''dimension____''', '''dim-width____''', or '''var_attribute'''.

* ''varid'' - String which identifies the variable's relationship to the MINC specification.  All MINC standard variables should set this to '<code>MINC standard variable</code>'.  Non-standard variables may either ignore this attribute or set it to some other string value.

* ''version'' - String identifying the version of this variable. This refers to the format of the '''variable''', not the format of the file itself.  In MINC 2.0, this string is always set to '''MINC Version    1.0''' for MINC standard variables.  This value is used for backward compatibility with MINC 1.0 software.

==MINC 2.0 Informational Attributes==
These attributes serve an informational role in that they provide
supporting information about the image data.

Informational attributes in MINC may be either a text string or a number. 

===''image'' variable attributes===
These attributes provide additional information about the state and
type of the image data contained in the MINC 2.0 file.

* ''complete'' - A boolean attribute (with values '''true_''' or '''false''') that indicates whether the variable has been written in its entirety. This can be used to detect program failure when writing out images as they are processed : ''complete'' is set to ''false'' at the beginning and set to ''true_'' when all data has been processed and written to the file.

* ''valid_range'' - A vector of two numbers which specifies both the minimum and maximum valid values for this variable.  Values outside this range must be treated as missing or uninitialized.  In MINC, the order of the two values in the vector is not significant. This attribute should be considered mandatory for the MINC ''image'' variable, unless the variable uses the default range, which is defined to be the full range of an (possibly signed or unsigned) integer type or the interval (0.0, 1.0) for floating point types.  It is not required for any other MINC variable.

===''study'' variable attributes===
These attributes provide ancillary information about the study for
which the image was collected.  The attributes are grouped with the
''study'' variable for purposes of namespace organization, and are
modeled after ACR-NEMA conventions [[ACRNEMA88]]. All of these
attributes are optional, and have no default value defined.


* ''admitting_diagnosis'' - String description of the admitting diagnosis.
* ''attending_physician'' - String giving the name of the physician administering the examination.
* ''department'' - String identifying the department conducting the study.
* ''device_model'' - String specifying the model of the imaging device.
* ''institution'' - String identifying the institution conducting the study.
* ''manufacturer'' - String specifying the name of the imaging device  manufacturer.
* ''modality'' - String that represents the imaging modality used, typically one of: ''PET__'', ''SPECT'', ''GAMMA'', ''MRI__'', ''MRS__'', ''MRA__'', ''CT___'', ''DSA__'', ''DR___'', or ''label''.
* ''operator'' - String giving the name of the operator of the imaging device.
* ''procedure'' - String description of the procedure employed.
* ''radiologist'' - String giving the name of the radiologist  interpreting the examination.
* ''referring_physician'' - String giving the name of the patient's primary physician.
* ''start_year'' - Number giving the year of the start of date the study.
* ''start_day'' - Number giving the day (1-31) of the start date of the study.
* ''start_hour'' - Number giving the hour (0-23) of the start time of the study.
* ''start_minute'' - Number giving the minute (0-59) of the start time of the study.
* ''start_month'' - Number giving the month (1-12) of the start date of the study.
* ''start_seconds'' - Number giving the seconds (including fractions of a second, if required) of the start time of the study.
* ''start_time'' - String giving the time and date of the start of the study, in the format '''YYYYMMDD HHMMSS.FFFFFF''', where '''FFFFFF''' is an string representation of fractional seconds. Either the entire time representation, or the fractional seconds, may be omitted if not required.
* ''station_id'' - String identifying the specific imaging system that generated the image.
* ''study_id'' - String identifying the study.


===''patient'' variable attributes===
These attributes, which provide identifying information about the
patient or subject, are grouped with the ''patient'' variable for
purposes of namespace organization.  They are modeled after ACR-NEMA
[[ACRNEMA88]] conventions for patient identification.  All of
these attributes are optional, and have no default value defined.

* ''address'' - String giving the patient's address.
* ''age'' - Number giving the patient's age in years. 
* ''birthdate'' - String specifying the patient's birthdate in the form '''YYYYMMDD'''.
* ''full_name'' - String specifying the full name of the patient.
* ''identification'' - String specifying identification information for the patient. 
* ''insurance_id'' - String giving the patient's insurance plan id.
* ''other_ids'' - String giving other identification information for the patient. 
* ''other_names'' - String giving other names for the patient.
* ''sex'' - String specifying the patient's sex: '''male__''',  '''female''' or '''other_'''. 
* ''size'' - Number giving patient's height or length in metres.
* ''weight'' - Number patient's weight in kilograms. 


===''acquisition'' variable attributes===
These attributes store parameters about the acquisition. All of these
attributes are optional, and have no default value defined.


* ''contrast_agent'' - String identifying the contrast or bolus agent.
* ''dose_units'' - String giving units of dose.
* ''echo_time'' - Number giving the time in seconds between the  middle of a 90 degree pulse and the middle of spin echo production.
* ''imaged_nucleus'' - String specifying the nucleus that is resonant at the imaging frequency.
* ''imaging_frequency'' - Precession frequency in Hz of the imaged nucleus.
* ''injection_day'' - Integer giving day (1-31) of injection.
* ''injection_hour'' - Integer giving hour (0-23) of injection.
* ''injection_length'' - Number giving the time duration of the injection (in seconds).
* ''injection_minute'' Integer giving minute (0-59) of injection.
* ''injection_month'' - Integer giving month (1-12) of injection.
* ''injection_seconds'' - Floating-point number giving seconds of injection.
* ''injection_time'' - String giving time (and date) of injection.
* ''injection_year'' - Integer giving year of injection.
* ''injection_dose'' - Total dose of radionuclide or contrast agent injected (in units specified by ''dose_units'').
* ''injection_route'' - String identifying administration route of injection.
* ''injection_volume'' - Number giving the volume of injection in milliliters.
* ''inversion_time'' - Time in seconds after the middle of the inverting RF pulse to the middle of the 90 degree pulse to detect the amount of longitudinal magnetization.
* ''num_averages'' - Number of times a given pulse sequence is repeated before any parameter is changed.
* ''protocol'' - String description of the protocol for image acquisition.
* ''radionuclide'' - String specifying the isotope administered. 
* ''radionuclide_halflife'' - Half-life of radionuclide in seconds.
* ''repetition_time'' - Number giving the time in seconds between pulse sequences.
* ''scanning_sequence'' - String description of type of data taken (eg.  for MR - IR, SE, PS, etc.).
* ''tracer'' - String identifying tracer labeled with radionuclide that was injected.


===Dimension variable attributes===


The attributes associated with either dimension or dimension width
variables are given in this section.


* ''alignment'' - String indicating the position of the coordinates relative to each sample, one of '''start_''', '''centre''', or '''end___'''.  When a variable is first created, this attribute is set to ''start_'' for the ''time'' dimension or ''centre'' for spatial dimensions.  Applies only to dimension variables. '''NOTE:''' this attribute is not consulted by the MINC tools or library, and thus should be considered to serve an informational purpose only.

* ''direction_cosines'' - Numeric vector with 3 elements giving the direction cosines of the axes. Although axes are labeled x, y and z, they may in fact have a significantly different orientation - this attribute allows the direction relative to the true axes to be specified exactly. The vectors should be normalized unit vectors.

If these attributes are not present, they are assumed to have the
following default values:

For ''xspace'': (1, 0, 0), for ''yspace'': (0, 1, 0), and for
''zspace'': (0, 0, 1)

The ''direction_cosines'' attributes apply only to dimension variables.

* ''length'' - Integer specifying the length (in samples) of this dimension.

* ''filtertype'' - String specifying the shape of the convolving filter. Currently, can be one of '''square____''', '''gaussian__''' or '''triangular'''. If this attribute is absent, a value of ''square____'' should be assumed.  Applies only to dimension width variables.

* ''spacetype'' - String identifying the type of coordinate space. Currently one of '''native___''' (the coordinate system of the scanner), '''talairach_''' (a standardized coordinate system for brain images), or '''callosal__''' (another standardized coordinate system). If this attribute is absent, the ''spacetype'' should be assumed to be ''native___''.  Applies only to dimension variables.

* ''spacing'' - String having the value '''regular__''' to indicate a regularly spaced grid or '''irregular''' to indicate irregular spacing of samples. If the value of this attribute is '''irregular''', then the dimension variable must be a vector varying with the dimension of the same name. If this attribute is absent, a value of '''regular__''' should be assumed.  Can be used for both dimension and dimension width variables.

* ''start'' - Number specifying the world coordinate of index 0 of the dimension (after applying cosine transforms). If this attribute is absent, a value of 0.0 should be assumed.  Applies only to dimension variables. 

* ''step'' - Number indicating the step size between samples for regular spacing. This value may be negative to reverse orientation (to specify that ''xspace'' runs from patient right to left, for example). If the spacing is ''irregular'', then the value should be the average step size. If this attribute is absent, a value of 1.0 should be assumed. Applies only to dimension variables.

* ''units'' - String that specifies the units of a dimension, if applicable.  The units should be compatible with the UCAR ''udunits'' library.  In MINC 2.0, this attribute is generally included for informational purposes only and is not interpreted by the MINC library code.

* ''width'' - Numeric attribute that gives the full-width half-maximum width of all samples for regularly sampled dimensions. It can be used for irregular widths to specify the average width. If this attribute is absent, a value of 1.0 should be assumed.  Applies only to dimension width variables.



=Functional details=
==Datatypes==
Unlike the presently available versions of NetCDF, HDF5 provides
support for both structured (record) and enumerated data types.

===Structured and complex data types===

As of this version of the specification, the only structured data types 
supported in MINC 2.0 are multidimensional arrays. This allows MINC 2.0
applications to implement vector or tensor datatypes, and in turn allows
these data types to be accessed as 'extra' dimensions, if desired.

Four 'complex' data types are defined by this specification: 16-bit
signed integer, 32-bit signed integer, 32-bit floating point, and
64-bit floating point.  In all cases the real value precedes the
imaginary value in a given voxel.

Any integer-to-real scaling which may occur is calculated uniformly
for all members of a complex or structured data type.  Scaling does
not apply to floating point complex values.

This specification does not define the details of any vector and
tensor implemention, these constructs are application specific for the
present purposes.  

MINC 2.0 continues to support an alternative mechanism for supporting
vector and complex data, via the use of the '''vector_dimension'''
dimension.

===Enumerated data types===
Enumerated data types assign a symbolic name to each legal value taken
by the datatype.  The most obvious application of this feature is
for so- called 'labelled' images, for example, the output of tissue
classification algorithms.

This feature will be implemented using the native support for
enumerated datatypes in the HDF5 library.  The HDF5 library allows any
integer type, signed or unsigned, to be used as the base type of an 
enumeration.

The MINC 2.0 library provides only minimal support for range checking
and conversion between standard integer and custom enumerated data
types.

At this time, no standard enumerated data types are defined by this
specification.  An programmer may define custom enumerations in
whatever manner best suits the application.  In future versions of
this specification we may define the implementation and interpretation
of some common enumerations (for tissue types, e.g.).


==Compression and block structuring==
MINC files are free to use any form of compression supported by the HDF5 1.6.0 library.  This includes two methods of lossless compression: 'gzip' compression, a modified Lempel-Ziv method, and 'szip' a lossless compression method developed by R.F.Rice [[Rice79]].  Compression is normally invisible to the application
programmer, although a programmer may query the compression status of a file.

Compression is applied on a per-dataset basis in HDF5 files, therefore
it is possible to compress certain datasets and leave others
uncompressed.  As a simplification the MINC 2.0 library will apply the
same compression algorithm to all of the image data in a file, and
will not support compression of other datasets.

When compression is enabled in HDF5, the compressed dataset must be
stored using the ''chunked'' layout.  Chunked datasets are stored in
a series of blocks which have the same dimensionality as the dataset.
This storage method may improve average data access times for certain
image processing algorithms, and so the MINC 2.0 library allows
chunking to be specified without requiring compression.

==Multiresolution images==

Multi-resolution images in MINC 2.0 are implemented using a
'multi-thumbnail' approach in which one or more lower-resolution
images are derived from the full-resolution image.  The dimensions of
each successive thumbnail image will be reduced by one-half relative
to the next-higher-resolution image.  This means that, ignoring
storage overhead, thumbnail images should add at most 14.29 percent
(1/7) to the overall size of the full-resolution data.

As described previously, multiresolution
images are stored in a series of separate ''image'', ''image-max'',
and ''image-min'' variables, called ''resolution groups''.
Full-resolution data is stored under the path
''/minc-2.0/image/0/image'', half resolution data is stored under the
path ''/minc-2.0/image/1/image'', and so on.

Only the full resolution image may be modified directly by
applications.  The library recalculates the reduced-resolution
data for all resolution groups defined in the MINC 2.0 file, either
explicitly in response to a request from the programmer, or implicitly
in response to a file close operation.

In the initial implementation of MINC 2.0, thumbnail image voxels will
be calculated using a simple averaging of the voxels of the
next-higher resolution image.  However, the MINC 2.0 library will
provide an extension mechanism for programmers to implement and use
more sophisticated thumbnail calculation if desired.

The use of multiple resolutions is entirely optional.  The MINC
library only recalculates lower-resolution images for which the
resolution group entries have been defined.  Not all intervening
resolution groups need to be present for the file to be valid.  In
addition to the mandatory full-resolution data, a MINC 2.0 file could
define a single 1/8 resolution thumbnail at the path
''/minc-2.0/image/3/image'', and the library must recalculate and
store only that resolution.

All thumbnail images must have the same datatype and dimension
order as the full-resolution image.

The ''complete'' attribute must be used and honored for all
resolutions that are defined.  This attribute is used to
determine the validity each of the images.

=Minimal MINC 2.0 File=
Of all of the variables, dimensions, and attributes described here, only the
'''image''' variable and its associated dimensions are required to define
a valid MINC file.

However, all MINC 2.0 files should contain at least an empty group 
framework consisting of the ''minc-2.0'' group and the three principal
subgroups ''image'', ''info'', and ''dimensions''.

Any missing attributes are assumed to have default values, or to be
undefined.

=Non-Standard Objects=
While MINC specifies the structure and interpretation of a number of
objects, MINC programs must operate gracefully with MINC files
that contain non-standard constructs.  This imposes two requirements
on MINC programs.  First, MINC programs must operate correctly on
files which contain non-standard variables and attributes.  Second,
MINC programs must copy non-standard attributes and variables from the
input file to the resulting output file without alteration.

This behavior allows the addition of arbitrary variables and/or
attributes that extend the standard MINC namespace.  As one small
example, this has proven useful in database applications where a
digital signature is added to the MINC file to provide a redundancy
check on the data.

It is strongly recommended that any additional or non-standard
informational attributes be placed under the '''info''' branch of
the hierarchy.  Specific programming interfaces exist to support this
convention.

=Deprecated Keywords=
A number of object names defined in the MINC 1.0 specification are no
longer used in the MINC 2.0 specification.  However, to avoid
potential errors or confusion, these names should be considered
'reserved' and must not be redefined in future applications.  In
some cases these keywords may be interpreted or emulated by the
library to provide backward compatibility with MINC 1.0.

* ''rootvariable'' - Replaced by HDF5 hierarchy.
* ''parent'' - Replaced by HDF5 hierarchy.
* ''children'' - Replaced by HDF5 hierarchy.
* ''signtype'' - HDF5 defines both signed and unsigned types.
* ''_FillValue'' - HDF5 defines an explicit mechanism for contolling the 'fill value' of a dataset.


=Author=
Robert D. Vincent

{{BookCat}}

Leila Baghdadi
(fixed broken links and uploaded modified hierarchy image 2012/10/19)

Vladimir S. FONOV
(fixed unfixed things left over by previous fixers)

Tarek Sherif
(fixed coordinate conversion equations)