# Dimension variable and attribute names

Of all of the variables, dimensions and attributes described here, only the variable MIimage and its dimensions are required to be present in a MINC file. Additional variables, dimensions and attributes may be present in the file -- unrecognised variables and attributes should be ignored.
A word on attribute conventions. All numeric values should be stored in one of the numeric types (NC_BYTE, NC_SHORT, NC_INT, NC_FLOAT or NC_DOUBLE). Some numeric attributes must be specified in a definite unit -- time attributes (such as MIrepetition_time and MIradionuclide_halflife) are given in seconds. Other attributes have an associated attribute that gives the unit -- e.g. MIinjection_dose and MIdose_units.

## NetCDF standard attributes

These attributes can be used with any variable. Fuller descriptions can be obtained from the NetCDF user's guide.
Specifies the units of the variable values as a string -- units should be compatible with the udunits library.
A string giving a textual description of the variable for human consumption.
A vector of two numbers specifying the minimum and maximum valid values in the variable. For the MINC routines the order is not important. For the MIimage variable, this attribute (or MIvalid_max and MIvalid_min) should always be present unless the defaults of full range for integer types and [0.0,1.0] for floating point types is correct.
A number giving the valid maximum for the variable.
A number giving the valid minimum for the variable.
Number to be used for filling in values in the variable that are not explicitly written.
A global string that provides a description of what is in the file.
A global string that should store one line for each program that has modified the file. Each line should contain the program name and arguments.

## MINC general attributes

These attributes apply to any variable in the file.
A string identifying the type of variable. Should be one of MI_GROUP, MI_DIMENSION, MI_DIM_WIDTH or MI_VARATT.
A string that identifies the origin of the variable. All standard MINC variables should have this attribute with value MI_STDVAR. Variables created by users should have a distinctive name that will not be the same as the names used by other applications.
The NetCDF format does not need to know the sign of variables since it does not interpret values -- it is left up to the invoking program to worry about the signs of integers. Because the MINC interface translates variables, it must have this information. MIsigntype is a string with value MI_SIGNED or MI_UNSIGNED. The default values are MI_UNSIGNED for bytes and MI_SIGNED for all other types.
A string identifying by name the parent variable of this variable (either in the data hierarchy or as the parent of this variable attribute).
A newline-separated list of the children of this variable (in the data hierarchy).
Any text that should be included with this variable.
A string identifying the file version. The current version is MI_CURRENT_VERSION. Each version can be identified by a constant of the form MI_VERSION_1_0.
The constants MI_TRUE and MI_FALSE are provided for boolean attributes.

## Dimensions and dimension variable

The following are the names of dimensions and their corresponding dimension variables. Only MIvector_dimension does not have a corresponding dimension variable.
Dimension and coordinate variable for x axis.
Dimension and coordinate variable for y axis.
Dimension and coordinate variable for z axis.
Dimension and coordinate for variable time axis.
Dimension and coordinate variable for temporal frequency.
Dimension and coordinate variable for spatial frequency along the x axis.
Dimension and coordinate variable for spatial frequency along the y axis.
Dimension and coordinate variable for spatial frequency along the z axis.
Dimension only for components of a vector field.
In addition to dimension variables, we can have dimension width variables that specify the FWHM width of the sample at each point.
Width of samples along x axis.
Width of samples along y axis.
Width of samples along z axis.
Width of samples along time axis.
Width of samples along temporal frequency axis.
Width of samples along x spatial frequency axis.
Width of samples along y spatial frequency axis.
Width of samples along z spatial frequency axis.
The attributes associated with dimension and dimension width variables are given below:
A string with value MI_REGULAR (for a regularly spaced grid) or MI_IRREGULAR (for irregular spacing of samples). If the value is MI_REGULAR, then the variable is permitted to be a scalar instead of a vector varying with the dimension of the same name. Can be used for both dimension and dimension width variables.
A number indicating the step between samples for regular spacing. This value may be negative to indicate orientation (to specify that MIxspace runs from patient right to left, for example). If the spacing is irregular, then the value can be an average step size. Applies only to dimension variables.
The coordinate of the index 0 of the dimension. Applies only to dimension variables.
A string identifying the type of coordinate space. Currently one of MI_NATIVE (the coordinate system of the scanner), MI_TALAIRACH (a standardized coordinate system), or MI_CALLOSAL (another standardized coordinate system). Applies only to dimension variables.
A string indicating the position of the coordinates relative to each sample (remembering that each sample has a width). Can be one of MI_START, MI_CENTRE or MI_END. Applies only to dimension variables.
A vector with MI_NUM_SPACE_DIMS(=3) elements giving the direction cosines of the axes. Although axes are labelled x, y and z, they may in fact have a significantly different direction -- this attribute allows the direction relative to the true axes to be specified exactly. Applies only to dimension variables. Note that the dot product of the direction cosine with the corresponding axis <function>(1,0,0), (0,1,0) or (0,0,1)</function> should be positive so that the sign of the attribute MIstep contains the orientation information.
For regularly dimension widths, this numeric attribute gives the FWHM width of all samples. It can be used for irregular widths to specify the average width. Applies only to dimension width variables.
A string specifying the shape of the convolving filter. Currently, can be one of MI_SQUARE, MI_GAUSSIAN or MI_TRIANGULAR. Applies only to dimension width variables.

## Root variable

The variable MIrootvariable is used as the root of the data hierarchy, with its MIchildren attribute pointing to the first level of group variables (including all of the MINC group variables), and with its MIparent attribute an empty string.

## Image variable

The variable MIimage is used to store the image data.
A variable attribute (ie. an attribute pointing to a variable of the same name) that stores the real value maximum for the image. This variable should not vary over the image dimensions of MIimage. The units of this variable define the units of the image.
Like MIimagemax, but stores the real value minimum for the image. MIimagemax should not be present without MIimagemin and vice-versa.
A boolean attribute (with values MI_TRUE or MI_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 : MIcomplete is set to MI_FALSE at the beginning and changed to MI_TRUE at the end of processing.

## Patient variable

The variable MIpatient is a group variable with no dimensions and no useful value. It serves only to group together information about the patient. Attributes are modelled after ACR-NEMA conventions.
A string specifying the full name of the patient.
A string giving other names for the patient.
A string specifying identification information for the patient.
A string giving other id's.
A string specifying the patient's birthdate.
A string specifying the patient's sex: MI_MALE, MI_FEMALE or MI_OTHER.
A number giving the patient's age.
The patient's weight in kilograms.
The patient's height or length in metres.
A string giving the patient's address.
A string giving the patient's insurance plan id.

## Study variable

Information about the study is grouped together in the MIstudy variable which has no dimensions or values. Attributes are modelled after ACR-NEMA conventions.
String giving time (and date) of start of the study.
Integer giving year of start.
Integer giving month (1-12) of start.
Integer giving day (1-31) of start.
Integer giving hour (0-23) of start.
Integer giving minute (0-59) of start.
Floating-point value giving seconds of start.
Imaging modality : one of MI_PET, MI_SPECT, MI_GAMMA, MI_MRI, MI_MRS, MI_MRA, MI_CT, MI_DSA, MI_DR.
String giving name of device manufacturer.
String identifying device model.
String identifying institution.
String identifying department.
String identifying machine that generated the images.
Name of patient's primary physician.
Physician administering the examination.
Radiologist interpreting the examination.
Name of technologist operating scanner.
String description of admitting diagnosis.
String description of the procedure employed.
String identifying study.

## Acquisition variable

Information about the acquisition itself is stored as attributes of the MIacquisition variable (again, no dimensions and no values).
String description of the protocol for image acquisition.
String description of type of data taken (eg. for MR -- IR, SE, PS, etc.).
Time in seconds between pulse sequences.
Time in seconds between the middle of a 90 degree pulse and the middle of spin echo production.
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.
Number of times a given pulse sequence is repeated before any parameter is changed.
Precession frequency in Hz of the imaged nucleus.
String specifying the nucleus that is resonant at the imaging frequency.
String specifying the isotope administered.
String identifying the contrast or bolus agent.
Half-life of radionuclide in seconds.
String identifying tracer labelled with radionuclide that was injected.
String giving time (and date) of injection.
Integer giving year of injection.
Integer giving month (1-12) of injection.
Integer giving day (1-31) of injection.
Integer giving hour (0-23) of injection.
Integer giving minute (0-59) of injection.
Floating-point value giving seconds of injection.
Length of time of injection (in seconds).
Total dose of radionuclide or contrast agent injected (in units specified by MIdose_units).
String giving units of dose.
Volume of injection in mL.
String identifying administration route of injection.

# NetCDF routines

Because it is necessary to use NetCDF routines to access MINC files, a brief description of all NetCDF routines is provided here. For more information, see the NetCDF User's Guide. Note that the header file netcdf.h is automatically included by the header file minc.h.

## Error handling

If an error occurs, the default behaviour is to print an error message and exit. It is possible to change this behaviour by modifying the value of the global variable ncopts. The default setting is
which means print error messages and exit when an error occurs. To get error messages without having fatal errors, set
For neither error messages nor fatal errors, set
In these last two cases, the calling routine should check the function value returned by each call to a NetCDF function. All routines return an integer value. If the value is -1 (MI_ERROR), then an error has occurred. The value of the global variable ncerr gives more information on the type of error (see file netcdf.h for error codes).

## NetCDF file operations

nccreate : Create the file specified by path. The argument cmode must have a value of either NC_CLOBBER or NC_NOCLOBBER. The return value is an identifier for the NetCDF file and is used by subsequent NetCDF function calls.
ncopen : Open the file specified by path. mode must have value NC_NOWRITE or NC_WRITE. The return value is a NetCDF file identifier.
ncredef : Put an open file into define mode.
ncendef : Put file into data mode.
ncclose : Close a NetCDF file.
ncinquire : Inquire about the number of dimensions in a file, the number of variables, the number of global attributes or the id of the unlimited record dimension. Passing a NULL value for any of the pointers means do not return the associated value.
ncsync : Synchronize an open file to disk.
ncabort : Abort any changes to the file if it is in define mode.
ncsetfill : When ncendef is called, all variables are filled with a fill value by default. To turn this off, call this routine with fillmode set to NC_NOFILL (to turn it back on, use NC_FILL).

## Dimension operations

ncdimdef : Define a dimension with a name and a length. The return value is a dimension id to be used in subsequent calls.
ncdimid : Get a dimension id from a name.
ncdiminq : Inquire about a dimension (name or length).
ncdimrename : Rename a dimension.

## Variable operations

ncvardef : Define a variable by name, giving its datatype, number of dimensions and the dimension id's that subscript the variable. Returns a variable id to be used in subsequent calls.
ncvarid : Get a variable id from a name.
ncvarinq : Inquire about a variable. Any NULL pointers mean do not return the associated value. It is possible to get the variable name, type, number of dimensions, dimension id's and number of attributes.
ncvarput1 : Store a single value at the coordinate specified by coords. value must be of the correct data type.
ncvarget1 : Get a single value from the coordinate specified by coords.
ncvarput : Put a hyperslab (multi-dimensional rectangle) of values starting at start with edge lengths given by count. For the C interface, the last dimension varies fastest. Values must be of the correct type.
ncvarget : Get a hyperslab (multi-dimensional rectangle) of values starting at start with edge lengths given by count. For the C interface, the last dimension varies fastest. Values must be of the correct type.
ncvarrename : Rename a variable.
nctypelen : Get the length (in bytes) of a data type.

## Attribute operations

ncattput : Store an attribute by name with variable varid. The type and length of the attribute must be specified.
ncattinq : Inquire about an attribute by name. Can get either type or length.
ncattget : Get an attribute's value by name.
ncattcopy : Copy an attribute from one variable to another.
ncattname : Get the name of an attribute from its number. The number is not an id, but can change as the number of attributes associated with a variable changes. Attribute numbers run from 0 to natts-1.
ncattrename : Rename an attribute.
ncattdel : Delete an attribute.

# MINC routines

Error handling for MINC routines is the same as for NetCDF functions, with the exception that routines returning pointers will return NULL instead of MI_ERROR when an error occurs. Error codes (returned in ncerr) can be found in the header file minc.h.

## General convenience functions

miexpand_file : Routine to expand a minc file that has been compressed with compress, pack, gzip or zip (using gunzip, zcat or pcat). The name of the temporary minc file is returned -- this string must be freed by the caller. If the file specified by path is not compressed, then its name is returned. *create_tempfile is set to TRUE if a temporary file is created (and the caller needs to delete the file), FALSE if the original file name is returned. If tempfile is NULL, then the routine generates its own temporary file name, otherwise, the user provided name is used. If header_only is TRUE, then the routine will expand only enough of the file to read the header.
miopen : Like ncopen, but will temporarily uncompress files (compress, pack, gzip, zip) opened with mode NC_NOWRITE.
micreate : Like nccreate. May be enhanced in the future.
miclose : Like ncclose, but finishes up for miopen and micreate.
miattget : Like ncattget, but the caller specifies the desired numeric type and maximum number of values to get. Type is specified with datatype (the sign is the default for the type: MI_UNSIGNED for NC_BYTE and MI_SIGNED otherwise). max_length gives the maximum number of values to get and att_length returns the number of values actually read. An error will occur if the attribute type is not numeric.
miattget1 : Like miattget, but only one value is returned. If there is more than one value, an error occurs.
miattgetstr : Gets a string value from an attribute. maxlen gives the maximum number of characters to be returned (including the terminating '\0'). The string is written to the array specified by value and a pointer to the string is returned.
miattputint : Write an integer attribute.
miattputdbl : Write a double precision attribute.
miattputstr : Write a string attribute.
mivarget : Like ncvarget, but the caller specifies the desired numeric type and sign (either MI_SIGNED or MI_UNSIGNED).
mivarget1 : Like ncvarget1, but the caller specifies the desired numeric type and sign.
mivarput : Like ncvarput, but the caller specifies the numeric type and sign of the values being passed.
mivarput1 : Like ncvarput1, but the caller specifies the numeric type and sign of the values being passed.
miset_coords : Set nvals values of the coordinate vector coords to value. A pointer to coords is returned.
mitranslate_coords : Translates the coordinate vector incoords for subscripting variable invar of file cdfid to vector outcoords for subscripting variable outvar. This is useful when two variables have similar dimensions, but not necessarily the same order of dimensions. If invar has a dimension that is not in outvar, then the corresponding coordinate is ignored. If outvar has a dimension that is not in invar, then the corresponding coordinate is not modified. A pointer to outcoords is returned.
micopy_all_atts : Copy all of the attributes of one variable to another (possibly across files).
micopy_var_def : Copy a variable definition (including attributes) from one file to another. outcdfid must be in define mode. The id of the newly created variable is returned.
micopy_var_values : Copy a variable's values from one file to another. incdfid and outcdfid must be in data mode.
micopy_all_var_defs : Copy all variable definitions from one file to another, excluding a list of variables. The list of nexclude variable id's is given in excluded_vars. outcdfid must be in define mode.
micopy_all_var_values : Copy all variable values from one file to another, excluding a list of variables. The list of nexclude variable id's is given in excluded_vars. outcdfid must be in data mode.

## MINC specific convenience functions

miget_datatype : Get the type and sign information for an image variable. Signed data is indicated by setting is_signed to TRUE; unsigned by FALSE.
miget_default_range : Returns the default range for a specified type and sign.
miget_valid_range : Gets the valid range information for an image variable. This function handles potential type differences between the valid_range attribute and the image data. These differences (particularly float images with double valid_range) could otherwise lead to problems in properly identifying invalid data.
miset_valid_range : Sets the valid range information for an image variable. This function follows the NetCDF convention of having both variable data and valid_range attribute with the same type.
miget_image_range : Gets the maximum real range of the image data based on the image-min and image-max variables.
mivar_exists : Tests for the existence of a variable. Returns true if the variable exists.
miattput_pointer : Create an attribute name in the variable varid that points to the variable ptrvarid.
miattget_pointer : Returns the variable id pointed to by attribute name of variable varid.
miadd_child : Add the name of variable child_varid to the MIchildren attribute of variable parent_varid and set the MIparent attribute of variable child_varid to the name of variable parent_varid. If the attributes do not exist, they are created. The names in the attribute MIchildren are separated by newlines.
micreate_std_variable : Create any of the standard MINC variables and set some attributes. Called in the manner of ncvardef. The id of the newly created variable is returned. For all variables, attributes MIvarid, MIvartype and MIversion are all set. For dimension and dimension width variables, MIspacing is set to MI_REGULAR if the number of dimensions is zero and MI_IRREGULAR otherwise. For dimension variables, MIalignment is set to MI_CENTRE unless the variable is MItime, then it is set to MI_START. As well, MIcomments is set to a string describing the direction of the world coordinates of spatial dimensions. For dimension width variables, MIfiltertype is set to MI_SQUARE. For MIimage and for MIimagemax and MIimagemin, dimensions are checked to ensure that the last two do not vary over image dimensions and attribute pointers from MIimage are created to point to the other two.
micreate_group_variable : Like micreate_std_variable, but ndims is always set to zero and the datatype is NC_INT. The id of the newly created variable is returned.

## Image conversion variable functions

miicv_create : Create an image conversion variable and set the defaults -- an icv identifier is returned for later use (or MI_ERROR if an error occurs). The old limit of MI_MAX_NUM_ICV icv's that can exist at one time has been removed, although the definition remains.
miicv_free : Free an image conversion variable.
miicv_setdbl : Set a numeric icv property to a double value.
miicv_setint : Set a numeric icv property to an integer value.
miicv_setlong : Set a numeric icv property to a long integer value.
miicv_setstr : Set a string icv property.
miicv_inqdbl : Inquire about a numeric icv property. value points to the double precision variable in which the value should be returned.
miicv_inqint : Inquire about a numeric icv property. value points to the integer variable in which the value should be returned.
miicv_inqlong : Inquire about a numeric icv property. value points to the long integer variable in which the value should be returned.
miicv_inqstr : Inquire about a string icv property. value points to the character array in which the value should be returned. The calling routine must allocate enough space for the return string.
miicv_attach : Attach a MINC file and image variable to an icv. Note that icv properties cannot be modified while a variable is attached to the icv. If a variable is already attached to the icv, then it is automatically detached. The file icvid must be in data mode.
miicv_ndattach : Like miicv_attach but no dimension conversion facilities are available (much like setting MI_ICV_DO_DIM_CONV to FALSE). This avoids linking in all of the dimension conversion routines when they are not needed (for machines where memory may be a concern).
miicv_detach : Detach a variable from an icv.
miicv_get : Get a hyperslab of values from a variable through an icv.
miicv_put : Put a hyperslab of values to a variable through an icv.

# Image conversion variable properties

MI_ICV_TYPE (type nc_type) : Specifies the type of values that the user wants. Modifying this property automatically causes MI_ICV_VALID_MAX and MI_ICV_VALID_MIN to be set to their default values. Default = NC_SHORT.
MI_ICV_SIGN (type char *) : Specifies the sign of values that the user wants (irrelevant for floating point types). Modifying this property automatically causes MI_ICV_VALID_MAX and MI_ICV_VALID_MIN to be set to their default values. Default = MI_SIGNED.
MI_ICV_DO_RANGE (type int) : When TRUE, range conversions (for valid max and min and for value normalization) are done. When FALSE, values are not modified. Default = TRUE.
MI_ICV_VALID_MAX (type double) : Valid maximum value (ignored for floating point types). Default = maximum legal value for type and sign (1.0 for floating point types).
MI_ICV_VALID_MIN (type double) : Valid minimum value (ignored for floating point types). Default = minimum legal value for type and sign (1.0 for floating point types).
MI_ICV_DO_NORM (type int) : If TRUE, then normalization of values is done (see user guide for details of normalization). Default = FALSE.
MI_ICV_USER_NORM (type int) : If TRUE, then the user specifies the normalization maximum and minimum. If FALSE, values are taken as maximum and minimum for whole image variable. Default = FALSE.
MI_ICV_IMAGE_MAX (type double) : Image maximum for user normalization. Default = 1.0.
MI_ICV_IMAGE_MIN (type double) : Image minimum for user normalization. Default = 0.0.
MI_ICV_NORM_MAX (type double) : Read-only value giving the user image maximum when doing normalization (either the maximum in the variable or the user specified maximum).
MI_ICV_NORM_MIN (type double) : Read-only value giving the user image minimum when doing normalization (either the minimum in the variable or the user specified minimum).
MI_ICV_DO_FILLVALUE (type int) : If set to TRUE, then range checking is done on input and values that are out of range (value in the file less than MIvalid_min or greater than MIvalid_max) are set to the value of MI_ICV_FILLVALUE. Default = FALSE.
MI_ICV_FILLVALUE (type double) : Value to use when pixels are out of range (on input only). This value is written to user's buffer directly without any scaling. Default = -DBL_MAX.
MI_ICV_DO_DIM_CONV (type int) : If set to TRUE, then dimension conversions may be done. Default = FALSE.
MI_ICV_DO_SCALAR (type int) : If TRUE, then if MIvector_dimension is the fastest varying dimension of the variable, elements are averaged and the icv behaves as though this dimension did not exist. Default = TRUE.
MI_ICV_XDIM_DIR (type int) : Indicates the desired orientation of the x image dimensions (MIxspace and MIxfrequency). Values can be one of MI_ICV_POSITIVE, MI_ICV_NEGATIVE or MI_ICV_ANYDIR. A positive orientation means that the MIstep attribute of the dimension is positive. MI_ICV_ANYDIR means that no flipping is done. Default = MI_ICV_POSITIVE.
MI_ICV_YDIM_DIR (type int) : Indicates the desired orientation of the y image dimensions. Default = MI_ICV_POSITIVE.
MI_ICV_ZDIM_DIR (type int) : Indicates the desired orientation of the z image dimensions. Default = MI_ICV_POSITIVE.
MI_ICV_ADIM_SIZE (type long) : Specifies the desired size of the fastest varying image dimension. A value of MI_ICV_ANYSIZE means that the actual size of the dimension should be used. Default = MI_ICV_ANYSIZE.
MI_ICV_BDIM_SIZE (type long) : Specifies the desired size of the second image dimension. Default = MI_ICV_ANYSIZE.
MI_ICV_KEEP_ASPECT (type int) : If TRUE, then image dimensions are resized by the same amount so that aspect ratio is maintained. Default = TRUE.
MI_ICV_ADIM_STEP (type double) : Read-only property that gives the equivalent of attribute MIstep for the first (fastest varying) image dimension after dimension conversion.
MI_ICV_BDIM_STEP (type double) : Read-only property that gives the equivalent of attribute MIstep for the second image dimension after dimension conversion.
MI_ICV_ADIM_START (type double) : Read-only property that gives the equivalent of attribute MIstart for the first (fastest varying) image dimension after dimension conversion.
MI_ICV_BDIM_START (type double) : Read-only property that gives the equivalent of attribute MIstart for the second image dimension after dimension conversion.
MI_ICV_NUM_IMGDIMS (type int) : Specifies the number of image dimensions used in dimension conversions. Default = 2.
MI_ICV_DIM_SIZE (type long) : Specifies the desired size of an image dimension. The number of the dimension to be changed should be added to the property (adding zero corresponds to the fastest varying dimension). Default = MI_ICV_ANYSIZE.
MI_ICV_DIM_STEP (type double) : Read-only property that gives the equivalent of attribute MIstep for the an image dimension after dimension conversion. The number of the dimension to be queried should be added to the property (adding zero corresponds to the fastest varying dimension).
MI_ICV_DIM_START (type double) : Read-only property that gives the equivalent of attribute MIstart for an image dimension after dimension conversion. The number of the dimension to be queried should be added to the property (adding zero corresponds to the fastest varying dimension).
MI_ICV_NUM_DIMS (type int) : Read-only property that gives the number of dimensions of the image variable, taking into account the conversion of vector images into scalar images.
MI_ICV_CDFID (type int) : Read-only property that gives the id of the currently attached NetCDF file, or MI_ERROR if no file is attached.
MI_ICV_VARID (type int) : Read-only property that gives the id of the currently attached NetCDF variable, or MI_ERROR if no variable is attached.
MI_ICV_MAXVAR (type char *) : String property specifying the name of the variable that gives the image maximum. Default = MIimagemax.
MI_ICV_MINVAR (type char *) : String property specifying the name of the variable that gives the image minimum. Default = MIimagemin.

# Known bugs

For dimension conversion with image conversion variables, the values of MI_ICV_DIM_START, MI_ICV_ADIM_START and MI_ICV_BDIM_START are computed assuming that MIalignment is equal to MI_CENTRE.