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 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 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 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 $c_{ij}$ to indicate the component $i$ of the axis in the $j$ direction, the cosine vector $c^{&rarr;}_{i}$ for the axis $i$ can be written:

Using $c^{&rarr;}_{i} =( c^{&rarr;}_{ix}, c^{&rarr;}_{iy}, <VAR>c</VAR>^{&rarr;}_{iz})$ to represent the value of the step attribute for spatial axis $<VAR>step</VAR>_{i}$, and defining $<VAR>i</VAR>$ similarly for the start attribute, the vector $<VAR>start</VAR>_{i}$ between adjacent elements along that axis is:

and the origin $<VAR>v</VAR>^{&rarr;}_{i}$ in voxel coordinates is located at world coordinates $<VAR>v</VAR>^{&rarr;}_{i} = <VAR>step</VAR>_{i} * <VAR>c</VAR>^{&rarr;}_{i}$ as given by:

$$\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} $$

Any homogeneous coordinate in voxel space $(<VAR>0,0,0</VAR>)$ can be transformed to its equivalent in world space using the following scaling, rotation and translation transformations: $$\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} $$ Which, composed, give the following equation: $$\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} $$ The inverse transformation from world to voxel space can be performed using the following equation: $$\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} $$

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 $(<VAR>o_{x},o_{y},o_{z}</VAR>)$ axis increases from patient left to right, the positive $(<VAR>v_{x},v_{y},v_{z}</VAR>, 1)$ axis increases from patient posterior to anterior, and the positive $<VAR>x</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.

=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 ' '.  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

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)