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.

  MIunits

Specifies the units of the variable values as a string -- units should be compatible with the udunits library.

  MIlong_name

A string giving a textual description of the variable for human consumption.

  MIvalid_range

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.

  MIvalid_max

A number giving the valid maximum for the variable.

  MIvalid_min

A number giving the valid minimum for the variable.

  MI_FillValue

Number to be used for filling in values in the variable that are not explicitly written.

  MItitle

A global string that provides a description of what is in the file.

  MIhistory

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.

  MIvartype

A string identifying the type of variable. Should be one of MI_GROUP, MI_DIMENSION, MI_DIM_WIDTH or MI_VARATT.

  MIvarid

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.

  MIsigntype

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.

  MIparent

A string identifying by name the parent variable of this variable (either in the data hierarchy or as the parent of this variable attribute).

  MIchildren

A newline-separated list of the children of this variable (in the data hierarchy).

  MIcomments

Any text that should be included with this variable.

  MIversion

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.

  MIxspace

Dimension and coordinate variable for x axis.

  MIyspace

Dimension and coordinate variable for y axis.

  MIzspace

Dimension and coordinate variable for z axis.

  MItime

Dimension and coordinate for variable time axis.

  MItfrequency

Dimension and coordinate variable for temporal frequency.

  MIxfrequency

Dimension and coordinate variable for spatial frequency along the x axis.

  MIyfrequency

Dimension and coordinate variable for spatial frequency along the y axis.

  MIzfrequency

Dimension and coordinate variable for spatial frequency along the z axis.

  MIvector_dimension

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.

  MIxspace_width

Width of samples along x axis.

  MIyspace_width

Width of samples along y axis.

  MIzspace_width

Width of samples along z axis.

  MItime_width

Width of samples along time axis.

  MItfrequency_width

Width of samples along temporal frequency axis.

  MIxfrequency_width

Width of samples along x spatial frequency axis.

  MIyfrequency_width

Width of samples along y spatial frequency axis.

  MIzfrequency_width

Width of samples along z spatial frequency axis.

The attributes associated with dimension and dimension width variables are given below:

  MIspacing

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.

  MIstep

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.

  MIstart

The coordinate of the index 0 of the dimension. Applies only to dimension variables.

  MIspacetype

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.

  MIalignment

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.

  MIdirection_cosines

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

  MIwidth

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.

  MIfiltertype

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.

  MIimagemax

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.

  MIimagemin

Like MIimagemax, but stores the real value minimum for the image. MIimagemax should not be present without MIimagemin and vice-versa.

  MIcomplete

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.

  MIfull_name

A string specifying the full name of the patient.

  MIother_names

A string giving other names for the patient.

  MIidentification

A string specifying identification information for the patient.

  MIother_ids

A string giving other id's.

  MIbirthdate

A string specifying the patient's birthdate.

  MIsex

A string specifying the patient's sex: MI_MALE, MI_FEMALE or MI_OTHER.

  MIage

A number giving the patient's age.

  MIweight

The patient's weight in kilograms.

  MIsize

The patient's height or length in metres.

  MIaddress

A string giving the patient's address.

  MIinsurance_id

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.

  MIstart_time

String giving time (and date) of start of the study.

  MIstart_year

Integer giving year of start.

  MIstart_month

Integer giving month (1-12) of start.

  MIstart_day

Integer giving day (1-31) of start.

  MIstart_hour

Integer giving hour (0-23) of start.

  MIstart_minute

Integer giving minute (0-59) of start.

  MIstart_seconds

Floating-point value giving seconds of start.

  MImodality

Imaging modality : one of MI_PET, MI_SPECT, MI_GAMMA, MI_MRI, MI_MRS, MI_MRA, MI_CT, MI_DSA, MI_DR.

  MImanufacturer

String giving name of device manufacturer.

  MIdevice_model

String identifying device model.

  MIinstitution

String identifying institution.

  MIdepartment

String identifying department.

  MIstation_id

String identifying machine that generated the images.

  MIreferring_physician

Name of patient's primary physician.

  MIattending_physician

Physician administering the examination.

  MIradiologist

Radiologist interpreting the examination.

  MIoperator

Name of technologist operating scanner.

  MIadmitting_diagnosis

String description of admitting diagnosis.

  MIprocedure

String description of the procedure employed.

  MIstudy_id

String identifying study.

Acquisition variable

Information about the acquisition itself is stored as attributes of the MIacquisition variable (again, no dimensions and no values).

  MIprotocol

String description of the protocol for image acquisition.

  MIscanning_sequence

String description of type of data taken (eg. for MR -- IR, SE, PS, etc.).

  MIrepetition_time

Time in seconds between pulse sequences.

  MIecho_time

Time in seconds between the middle of a 90 degree pulse and the middle of spin echo production.

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

  MInum_averages

Number of times a given pulse sequence is repeated before any parameter is changed.

  MIimaging_frequency

Precession frequency in Hz of the imaged nucleus.

  MIimaged_nucleus

String specifying the nucleus that is resonant at the imaging frequency.

  MIradionuclide

String specifying the isotope administered.

  MIcontrast_agent

String identifying the contrast or bolus agent.

  MIradionuclide_halflife

Half-life of radionuclide in seconds.

  MItracer

String identifying tracer labelled with radionuclide that was injected.

  MIinjection_time

String giving time (and date) of injection.

  MIinjection_year

Integer giving year of injection.

  MIinjection_month

Integer giving month (1-12) of injection.

  MIinjection_day

Integer giving day (1-31) of injection.

  MIinjection_hour

Integer giving hour (0-23) of injection.

  MIinjection_minute

Integer giving minute (0-59) of injection.

  MIinjection_seconds

Floating-point value giving seconds of injection.

  MIinjection_length

Length of time of injection (in seconds).

  MIinjection_dose

Total dose of radionuclide or contrast agent injected (in units specified by MIdose_units).

  MIdose_units

String giving units of dose.

  MIinjection_volume

Volume of injection in mL.

  MIinjection_route

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

  ncopts = NC_VERBOSE | NC_FATAL;

which means print error messages and exit when an error occurs. To get error messages without having fatal errors, set

  ncopts = NC_VERBOSE;

For neither error messages nor fatal errors, set

  ncopts = 0;

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.

  int nccreate(char* path,int cmode);

ncopen : Open the file specified by path. mode must have value NC_NOWRITE or NC_WRITE. The return value is a NetCDF file identifier.

  int ncopen(char* path,int mode);

ncredef : Put an open file into define mode.

  int ncredef(int cdfid);

ncendef : Put file into data mode.

  int ncendef(int cdfid);

ncclose : Close a NetCDF file.

  int ncclose(int cdfid);

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.

  int ncinquire(int cdfid,int* ndims,int* nvars,int* natts,int* recdim);

ncsync : Synchronize an open file to disk.

  int ncsync(int cdfid);

ncabort : Abort any changes to the file if it is in define mode.

  int ncabort(int cdfid);

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

  int ncsetfill(int cdfid,int fillmode);

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.

  int ncdimdef(int cdfid,char* name,long length);

ncdimid : Get a dimension id from a name.

  int ncdimid(int cdfid,char* name);

ncdiminq : Inquire about a dimension (name or length).

  int ncdiminq(int cdfid,int dimid,char* name,long* length);

ncdimrename : Rename a dimension.

  int ncdimrename(int cdfid,int dimid,char* name);

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.

  int ncvardef(int cdfid,char* name,nc_type datatype,int ndims,int dim[]);

ncvarid : Get a variable id from a name.

  int ncvarid(int cdfid,char* 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.

  int ncvarinq(int cdfid,int varid,char* name,nc_type* datatype,int* ndims,
                 int dim[],int* natts);

ncvarput1 : Store a single value at the coordinate specified by coords. value must be of the correct data type.

  int ncvarput1(int cdfid,int varid,long coords[],void* value);

ncvarget1 : Get a single value from the coordinate specified by coords.

  int ncvarget1(int cdfid,int varid,long coords[],void* value);

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.

  int ncvarput(int cdfid,int varid,long start[],long count[],void* value);

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.

  int ncvarget(int cdfid,int varid,long start[],long count[],void* value);

ncvarrename : Rename a variable.

  int ncvarrename(int cdfid,int varid,char* name);

nctypelen : Get the length (in bytes) of a data type.

  int nctypelen(nc_type datatype);

Attribute operations

ncattput : Store an attribute by name with variable varid. The type and length of the attribute must be specified.

  int ncattput(int cdfid,int varid,char* name,nc_type datatype,int len,
                void* value);

ncattinq : Inquire about an attribute by name. Can get either type or length.

  int ncattinq(int cdfid,int varid,char* name,nc_type* datatype,int* len);

ncattget : Get an attribute's value by name.

  int ncattget(int cdfid,int varid,char* name,void* value);

ncattcopy : Copy an attribute from one variable to another.

  int ncattcopy(int incdf,int invar,char* name,int outcdf,int outvar);

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.

  int ncattname(int cdfid,int varid,int attnum,char* name);

ncattrename : Rename an attribute.

  int ncattrename(int cdfid,int varid,char* name,char* newname);

ncattdel : Delete an attribute.

  int ncattdel(int cdfid,int varid,char* name);

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.

  public char *miexpand_file(char *path, char *tempfile, int header_only, 
                             int *created_tempfile);

miopen : Like ncopen, but will temporarily uncompress files (compress, pack, gzip, zip) opened with mode NC_NOWRITE.

  public int miopen(char *path, int mode);

micreate : Like nccreate. May be enhanced in the future.

  public int micreate(char *path, int cmode);

miclose : Like ncclose, but finishes up for miopen and micreate.

  public int miclose(int cdfid);

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.

  public int miattget(int cdfid, int varid, char *name, nc_type datatype,
                      int max_length, void *value, int *att_length);

miattget1 : Like miattget, but only one value is returned. If there is more than one value, an error occurs.

  public int miattget1(int cdfid, int varid, char *name, nc_type datatype,
                      void *value);

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.

  public char *miattgetstr(int cdfid, int varid, char *name, 
                           int maxlen, char *value);

miattputint : Write an integer attribute.

  public int miattputint(int cdfid, int varid, char *name, int value);

miattputdbl : Write a double precision attribute.

  public int miattputdbl(int cdfid, int varid, char *name, double value);

miattputstr : Write a string attribute.

  public int miattputstr(int cdfid, int varid, char *name, char *value);

mivarget : Like ncvarget, but the caller specifies the desired numeric type and sign (either MI_SIGNED or MI_UNSIGNED).

  public int mivarget(int cdfid, int varid, long start[], long count[],
                      nc_type datatype, char *sign, void *values);

mivarget1 : Like ncvarget1, but the caller specifies the desired numeric type and sign.

  public int mivarget1(int cdfid, int varid, long mindex[],
                       nc_type datatype, char *sign, void *value);

mivarput : Like ncvarput, but the caller specifies the numeric type and sign of the values being passed.

  public int mivarput(int cdfid, int varid, long start[], long count[],
                      nc_type datatype, char *sign, void *values);

mivarput1 : Like ncvarput1, but the caller specifies the numeric type and sign of the values being passed.

  public int mivarput1(int cdfid, int varid, long mindex[],
                       nc_type datatype, char *sign, void *value);

miset_coords : Set nvals values of the coordinate vector coords to value. A pointer to coords is returned.

  public long *miset_coords(int nvals, long value, long coords[]);

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.

  public long *mitranslate_coords(int cdfid, 
                                  int invar,  long incoords[],
                                  int outvar, long outcoords[]);

micopy_all_atts : Copy all of the attributes of one variable to another (possibly across files).

  public int micopy_all_atts(int incdfid, int invarid, 
                             int outcdfid, int outvarid);

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.

  public int micopy_var_def(int incdfid, int invarid, int outcdfid);

micopy_var_values : Copy a variable's values from one file to another. incdfid and outcdfid must be in data mode.

  public int micopy_var_values(int incdfid, int invarid, 
                               int outcdfid, int outvarid);

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.

  public int micopy_all_var_defs(int incdfid, int outcdfid, int nexclude,
                                 int excluded_vars[]);

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.

  public int micopy_all_var_values(int incdfid, int outcdfid, int nexclude,
                                   int excluded_vars[]);

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.

  public int miget_datatype(int cdfid, int imgid,
                            nc_type *datatype, int *is_signed);

miget_default_range : Returns the default range for a specified type and sign.

  public int miget_default_range(nc_type datatype, int is_signed,
                                 double default_range[]);

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.

  public int miget_valid_range(int cdfid, int imgid, double valid_range[]);

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.

  public int miset_valid_range(int cdfid, int imgid, double valid_range[]);

miget_image_range : Gets the maximum real range of the image data based on the image-min and image-max variables.

  public int miget_image_range(int cdfid, double image_range[]);

mivar_exists : Tests for the existence of a variable. Returns true if the variable exists.

  public int mivar_exists(int cdfid, char *varname);

miattput_pointer : Create an attribute name in the variable varid that points to the variable ptrvarid.

  public int miattput_pointer(int cdfid, int varid, char *name, int ptrvarid);

miattget_pointer : Returns the variable id pointed to by attribute name of variable varid.

  public int miattget_pointer(int cdfid, int varid, char *name);

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.

  public int miadd_child(int cdfid, int parent_varid, int child_varid);

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.

  public int micreate_std_variable(int cdfid, char *name, nc_type datatype, 
                                   int ndims, int dim[]);

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.

  public int micreate_group_variable(int cdfid, char *name);

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.

  public int miicv_create();

miicv_free : Free an image conversion variable.

  public int miicv_free(int icvid);

miicv_setdbl : Set a numeric icv property to a double value.

  public int miicv_setdbl(int icvid, int icv_property, double value);

miicv_setint : Set a numeric icv property to an integer value.

  public int miicv_setint(int icvid, int icv_property, int value);

miicv_setlong : Set a numeric icv property to a long integer value.

  public int miicv_setlong(int icvid, int icv_property, long value);

miicv_setstr : Set a string icv property.

  public int miicv_set(int icvid, int icv_property, char *value);

miicv_inqdbl : Inquire about a numeric icv property. value points to the double precision variable in which the value should be returned.

  public int miicv_inqdbl(int icvid, int icv_property, double *value);

miicv_inqint : Inquire about a numeric icv property. value points to the integer variable in which the value should be returned.

  public int miicv_inqint(int icvid, int icv_property, int *value);

miicv_inqlong : Inquire about a numeric icv property. value points to the long integer variable in which the value should be returned.

  public int miicv_inqlong(int icvid, int icv_property, long *value);

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.

  public int miicv_inqstr(int icvid, int icv_property, char *value);

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.

  public int miicv_attach(int icvid, int cdfid, int varid);

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

  public int miicv_ndattach(int icvid, int cdfid, int varid);

miicv_detach : Detach a variable from an icv.

  public int miicv_detach(int icvid);

miicv_get : Get a hyperslab of values from a variable through an icv.

  public int miicv_get(int icvid, long start[], long count[], void *values);

miicv_put : Put a hyperslab of values to a variable through an icv.

  public int miicv_put(int icvid, long start[], long count[], void *values);

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.

MINC/SoftwareDevelopment/MINC1-programmers-reference

Contents