MINC/SoftwareDevelopment/MINC1-programmers-reference

=Dimension variable and attribute names= Of all of the variables, dimensions and attributes described here, only the variable 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 (, , ,   or  ). Some numeric attributes must be specified in a definite unit -- time attributes (such as and  )  are given in seconds. Other attributes have an associated attribute that gives the unit -- e.g. and.

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 variable, this attribute (or  and ) 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 , ,  or.

A string that identifies the origin of the variable. All standard MINC variables should have this attribute with value. 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. is a string with value  or . The default values are for bytes and  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 . Each version can be identified by a constant of the form.

The constants  and   are provided for boolean attributes.

Dimensions and dimension variable
The following are the names of dimensions and their corresponding dimension variables. Only 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  (for a regularly spaced grid) or  (for irregular spacing of samples). If the value is, 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  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 (the coordinate system of the scanner), (a standardized coordinate system), or (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 , or. Applies only to dimension variables.

A vector with (=3) elements giving the direction cosines of the axes. Although axes are labelled x, y and z, they may in fact have a signficantly 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 (1,0,0), (0,1,0) or (0,0,1) should be positive so that the sign of the attribute 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,  or . Applies only to dimension width variables.

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

Image variable
The variable  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, but stores the real value minimum for the image. should not be present without and vice-versa.

A boolean attribute (with values  or ) 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 :  is set to   at the beginning and changed to  at the end of processing.

Patient variable
The variable  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: , or.

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 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,  , ,,  , ,  ,  ,.

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 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 ).

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, then an error has occurred. The value of the global variable  gives more information on the type of error (see file  for error codes).

NetCDF file operations
The argument  must have a  value of either or. The return value is an identifier for the NetCDF file and is used by subsequent NetCDF function calls.

must have value   or . The return value is a NetCDF file identifier.







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.





are filled with a fill value by default. To turn this off, call this routine with set to  (to turn it back on, use  ).

Dimension operations
The return value is a dimension id to be used in subsequent calls.







Variable operations
Returns a variable id to be used in subsequent calls.



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.





starting at   with edge lengths given by . For the C interface, the last dimension varies fastest. Values must be of the correct type.

starting at   with edge lengths given by . For the C interface, the last dimension varies fastest. Values must be of the correct type.





Attribute operations
. The type and length of the attribute must be specified.

Can get either type or length.





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.





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

General convenience functions
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 is not compressed, then its name is returned. 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  is TRUE, then the routine will expand only enough of the file to read the header.

uncompress files (compress, pack, gzip, zip) opened with mode .

May be enhanced in the future.

and.

specifies the desired numeric type and maximum number of values to get. Type is specified with  (the sign is the default for the type:  for   and  otherwise). gives the maximum number of values to get and  returns the number of values actually read. An error will occur if the attribute type is not numeric.

If there is more than one value, an error occurs.

gives the maximum number of characters to be returned (including the terminating ). The string is written to the array specified by value and a pointer to the string is returned.







specifies the desired numeric type and sign (either  or ).

specifies the desired numeric type and sign.

specifies the numeric type and sign of the values being passed.

specifies the numeric type and sign of the values being passed.

vector  to. A pointer to is returned.

for subscripting variable  of file to vector  for subscripting variable. This is useful when two variables have similar dimensions, but not necessarily the same order of dimensions. If has a dimension that is not in , then the corresponding coordinate is ignored. If  has a dimension that is not in, then the corresponding coordinate is not modified. A pointer to is returned.



from one file to another. must be in define mode. The id of the newly created variable is returned.

and  must be in data mode.

The list of  variable id's is given in. must be in define mode.

The list of  variable id's is given in. must be in data mode.

MINC specific convenience functions
variable. Signed data is indicated by setting  to ; unsigned by.

and sign.

variable. This function handles potential type differences between the attribute and the image data. These differences (particularly float images with double ) could otherwise lead to problems in properly identifying invalid data.

variable. This function follows the NetCDF convention of having both variable data and attribute with the same type.

based on the image-min and image-max variables.

Returns true if the variable exists.

.

of variable.

to the  attribute of variable   and set the attribute of variable  to the name of variable . If the attributes do not exist, they are created. The names in the attribute  are separated by newlines.

set some attributes. Called in the manner of. The id of the newly created variable is returned. For all variables, attributes ,  and are all set. For dimension and dimension width variables, is set to  if the number of dimensions is zero and   otherwise. For dimension variables,  is set to   unless the variable is, then it is set to . As well,  MIcomments is set to a string describing the direction of the world coordinates of spatial dimensions. For dimension width variables, is set to. For and for  and , dimensions are checked to ensure that the last two do not vary over image dimensions and attribute pointers from  are created to point to the other two.

, but  is always set to zero and the datatype is. The id of the newly created variable is returned.

Image conversion variable functions
defaults -- an icv identifier is returned for later use (or if an error occurs). The old limit of  icv's that can exist at one time has been removed, although the definition remains.











points to the double precision variable in which the value should be returned.

points to the integer variable in which the value should be returned.

points to the long integer variable in which the value should be returned.

points to the character array in which the value should be returned. The calling routine must allocate enough space for the return string.

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 must be in data mode.

This avoids linking in all of the dimension conversion routines when they are not needed (for machines where memory may be a concern).







=Image conversion variable properties= (type ) : Specifies the type of values that the user wants. Modifying this property automatically causes and  to be set to their default values. Default =.

(type ) :  Specifies the sign of values that the user wants (irrelevant for floating point types). Modifying this property automatically causes  and to be set to their default values. Default = .

(type ) : When , range conversions (for valid max and min and for value normalization) are done. When, values are not modified. Default = .

(type ) : Valid maximum value (ignored for floating point types). Default = maximum legal value for type and sign (1.0 for floating point types).

(type ) : Valid minimum value (ignored for floating point types). Default = minimum legal value for type and sign (1.0 for floating point types).

(type ) : If, then normalization of values is done (see user guide for details of normalization). Default =.

(type ) : If, then the user specifies the normalization maximum and minimum. If, values are taken as maximum and minimum for whole image variable. Default =.

(type ) : Image maximum for user normalization. Default = 1.0.

(type ) : Image minimum for user normalization. Default = 0.0.

(type ) : Read-only value giving the user image maximum when doing normalization (either the maximum in the variable or the user specified maximum).

(type ) : Read-only value giving the user image minimum when doing normalization (either the minimum in the variable or the user specified minimum).

(type ) : If set to , then range checking is done on input and values that are out of range (value in the file less than   or greater than ) are set to the value of .  Default =.

(type ) : 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 =.

(type ) : If set to , then dimension conversions may be done. Default = .

(type ) : If, then if   is the fastest varying dimension of the variable, elements are averaged and the icv behaves as though this dimension did not exist. Default =.

(type ) : Indicates the desired orientation of the x image dimensions ( and ). Values can be one of  , or. A positive orientation means that the  attribute of the dimension is positive. means that no flipping is done. Default = .

(type ) : Indicates the desired orientation of the y image dimensions. Default =.

(type ) : Indicates the desired orientation of the z image dimensions. Default =.

(type ) : Specifies the desired size of the fastest varying image dimension. A value of means that the actual size of the dimension should be used. Default = .

(type ) : Specifies the desired size of the second image dimension. Default =.

(type ) : If, then image dimensions are resized by the same amount so that aspect ratio is maintained. Default =.

(type ) : Read-only property that gives the equivalent of attribute  for the first (fastest varying) image dimension after dimension conversion.

(type ) : Read-only property that gives the equivalent of attribute  for the second image dimension after dimension conversion.

(type ) : Read-only property that gives the equivalent of attribute  for the first (fastest varying) image dimension after dimension conversion.

(type ) : Read-only property that gives the equivalent of attribute  for the second image dimension after dimension conversion.

(type ) : Specifies the number of image dimensions used in dimension conversions. Default = 2.

(type ) : 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 = .

(type ) : Read-only property that gives the equivalent of attribute  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).

(type ) : Read-only property that gives the equivalent of attribute  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).

(type ) : Read-only property that gives the number of dimensions of the image variable, taking into account the conversion of vector images into scalar images.

(type ) : Read-only property that gives the id of the currently attached NetCDF file, or  if no file is attached.

(type ) : Read-only property that gives the id of the currently attached NetCDF variable, or  if no variable is attached.

(type ) : String property specifying the name of the variable that gives the image maximum. Default = .

(type ) : String property specifying the name of the variable that gives the image minimum. Default = .

=Known bugs= For dimension conversion with image conversion variables, the values of,  and are computed assuming that is equal to.