%
% Copyright 1993 Peter Neelin, McConnell Brain Imaging Centre, 
% Montreal Neurological Institute, McGill University.
% Permission to use, copy, modify, and distribute this
% software and its documentation for any purpose and without
% fee is hereby granted, provided that the above copyright
% notice appear in all copies.  The author and McGill University
% make no representations about the suitability of this
% software for any purpose.  It is provided "as is" without
% express or implied warranty.
%
\documentclass{article}
\title{MINC Programmer's Reference Manual}
\author{Peter Neelin}
\date{November 3, 1993}
\textwidth 6.0in
\oddsidemargin 0.125in
\textheight 8.5in
\topmargin -0.75in
\parindent 0in

\begin{document}

\def\code#1{{\tt #1}}

\maketitle

\tableofcontents

\clearpage

\section{Dimension, variable and attribute names}

Of all of the variables, dimensions and attributes described here, only
the variable \code{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 (\code{NC\_BYTE}, \code{NC\_SHORT},
\code{NC\_INT}, \code{NC\_FLOAT} or \code{NC\_DOUBLE}). Some numeric
attributes must be specified in a definite unit --- time attributes
(such as \code{MIrepetition\_time} and \code{MIradionuclide\_halflife}) 
are given in seconds. Other attributes have an associated attribute that
gives the unit --- e.g. \code{MIinjection\_dose} and \code{MIdose\_units}.

\subsection{NetCDF standard attributes}

These attributes can be used with any variable. Fuller descriptions
can be obtained from the NetCDF user's guide.

\begin{description}
   \item [\code{MIunits}] Specifies the units of the variable values
      as a string --- units should be compatible with the udunits
      library.
   \item [\code{MIlong\_name}] A string giving a textual description of
      the variable for human consumption.
   \item [\code{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 \code{MIimage}
      variable, this attribute (or \code{MIvalid\_max} and
      \code{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.
   \item [\code{MIvalid\_max}] A number giving the valid maximum for
      the variable.
   \item [\code{MIvalid\_min}] A number giving the valid minimum for
      the variable.
   \item [\code{MI\_FillValue}] Number to be used for filling in values in
      the variable that are not explicitly written.
   \item [\code{MItitle}] A global string that provides a description
      of what is in the file.
   \item [\code{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.
\end{description}

\subsection{MINC general attributes}

These attributes apply to any variable in the file. 

\begin{description}
   \item [\code{MIvartype}] A string identifying the type of variable.
      Should be one of \code{MI\_GROUP}, \code{MI\_DIMENSION},
      \code{MI\_DIM\_WIDTH} or \code{MI\_VARATT}.
   \item [\code{MIvarid}] A string that identifies the origin of the
      variable. All standard MINC variables should have this attribute
      with value \code{MI\_STDVAR}. Variables created by users should have a
      distinctive name that will not be the same as the names used by
      other applications.
   \item [\code{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. \code{MIsigntype} is a string with
      value \code{MI\_SIGNED} or \code{MI\_UNSIGNED}. The default values are
      \code{MI\_UNSIGNED} for bytes and \code{MI\_SIGNED} for all other types.
   \item [\code{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).
   \item [\code{MIchildren}] A newline-separated list of the children
      of this variable (in the data hierarchy).
   \item [\code{MIcomments}] Any text that should be included with
      this variable.
   \item [\code{MIversion}] A string identifying the file version. The
      current version is \code{MI\_CURRENT\_VERSION}. Each version can be
      identified by a constant of the form \code{MI\_VERSION\_1\_0}.
\end{description}

The constants \code{MI\_TRUE} and \code{MI\_FALSE} are provided for
boolean attributes. 

\subsection{Dimensions and dimension variables}

The following are the names of dimensions and their corresponding
dimension variables. Only \code{MIvector\_dimension} does not have a
corresponding dimension variable.
\begin{description}
   \item [\code{MIxspace}] Dimension and coordinate variable for x axis.
   \item [\code{MIyspace}] Dimension and coordinate variable for y axis.
   \item [\code{MIzspace}] Dimension and coordinate variable for z axis.
   \item [\code{MItime}] Dimension and coordinate for variable time axis.
   \item [\code{MItfrequency}] Dimension and coordinate variable for
      temporal frequency.
   \item [\code{MIxfrequency}] Dimension and coordinate variable for spatial 
      frequency along the x axis.
   \item [\code{MIyfrequency}] Dimension and coordinate variable for spatial
      frequency along the y axis.
   \item [\code{MIzfrequency}] Dimension and coordinate variable for spatial
      frequency along the z axis.
   \item [\code{MIvector\_dimension}] Dimension only for components of
      a vector field.
\end{description}

In addition to dimension variables, we can have dimension width
variables that specify the FWHM width of the sample at each point.
\begin{description}
   \item [\code{MIxspace\_width}] Width of samples along x axis.
   \item [\code{MIyspace\_width}] Width of samples along y axis.
   \item [\code{MIzspace\_width}] Width of samples along z axis.
   \item [\code{MItime\_width}] Width of samples along time axis.
   \item [\code{MItfrequency\_width}] Width of samples along temporal
      frequency axis.
   \item [\code{MIxfrequency\_width}] Width of samples along x spatial
      frequency axis.
   \item [\code{MIyfrequency\_width}] Width of samples along y spatial
      frequency axis.
   \item [\code{MIzfrequency\_width}] Width of samples along z spatial
      frequency axis.
\end{description}

The attributes associated with dimension and dimension width variables
are given below:
\begin{description}
   \item [\code{MIspacing}] A string with value \code{MI\_REGULAR} (for
      a regularly spaced grid) or \code{MI\_IRREGULAR} (for irregular
      spacing of samples). If the value is \code{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.
   \item [\code{MIstep}] A number indicating the step between samples
      for regular spacing. This value may be negative to indicate
      orientation (to specify that \code{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. 
   \item [\code{MIstart}] The coordinate of the index 0 of the dimension.
      Applies only to dimension variables.
   \item [\code{MIspacetype}] A string identifying the type of
      coordinate space. Currently one of \code{MI\_NATIVE} (the
      coordinate system of the scanner), \code{MI\_TALAIRACH} (a
      standardized coordinate system), or \code{MI\_CALLOSAL} (another
      standardized coordinate system). Applies only to dimension variables.
   \item [\code{MIalignment}] A string indicating the position of the
      coordinates relative to each sample (remembering that each sample
      has a width). Can be one of \code{MI\_START}, \code{MI\_CENTRE} or
      \code{MI\_END}. Applies only to dimension variables.
   \item [\code{MIdirection\_cosines}] A vector with
      \code{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 ($(1,0,0)$, $(0,1,0)$ or $(0,0,1)$)
      should be positive so that the sign of the attribute
      \code{MIstep} contains the orientation information.
   \item [\code{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.
   \item [\code{MIfiltertype}] A string specifying the shape of the
      convolving filter. Currently, can be one of \code{MI\_SQUARE},
      \code{MI\_GAUSSIAN} or \code{MI\_TRIANGULAR}. Applies only to
      dimension width variables.
\end{description}

\subsection{Root variable}

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

\subsection{Image variable}

The variable \code{MIimage} is used to store the image data. 

\begin{description}
   \item [\code{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.
   \item [\code{MIimagemin}] Like \code{MIimagemax}, but stores the
      real value minimum for the image. \code{MIimagemax} should not
      be present without \code{MIimagemin} and vice-versa.
   \item [\code{MIcomplete}] A boolean attribute (with values
      \code{MI\_TRUE} or \code{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 :
      \code{MIcomplete} is set to \code{MI\_FALSE} at the beginning and
      changed to \code{MI\_TRUE} at the end of processing.
\end{description}

\subsection{Patient variable}

The variable \code{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.

\begin{description}
   \item [\code{MIfull\_name}] A string specifying the full name of the
      patient.
   \item [\code{MIother\_names}] A string giving other names for the
      patient. 
   \item [\code{MIidentification}] A string specifying identification
      information for the patient.
   \item [\code{MIother\_ids}] A string giving other id's.
   \item [\code{MIbirthdate}] A string specifying the patient's
      birthdate.
   \item [\code{MIsex}] A string specifying the patient's sex:
      \code{MI\_MALE}, \code{MI\_FEMALE} or \code{MI\_OTHER}.
   \item [\code{MIage}] A number giving the patient's age.
   \item [\code{MIweight}] The patient's weight in kilograms.
   \item [\code{MIsize}] The patient's height or length in metres.
   \item [\code{MIaddress}] A string giving the patient's address.
   \item [\code{MIinsurance\_id}] A string giving the patient's
      insurance plan id.
\end{description}

\subsection{Study variable}

Information about the study is grouped together in the \code{MIstudy}
variable which has no dimensions or values. Attributes are modelled
after ACR-NEMA conventions.

\begin{description}
   \item [\code{MIstart\_time}] String giving time (and date) of start
      of the study.
   \item [\code{MIstart\_year}] Integer giving year of start.
   \item [\code{MIstart\_month}] Integer giving month (1-12) of start.
   \item [\code{MIstart\_day}] Integer giving day (1-31) of start.
   \item [\code{MIstart\_hour}] Integer giving hour (0-23) of start.
   \item [\code{MIstart\_minute}] Integer giving minute (0-59) of start.
   \item [\code{MIstart\_seconds}] Floating-point value giving seconds
      of start.
   \item [\code{MImodality}] Imaging modality : one of \code{MI\_PET},
      \code{MI\_SPECT}, \code{MI\_GAMMA}, \code{MI\_MRI},
      \code{MI\_MRS}, \code{MI\_MRA}, \code{MI\_CT}, \code{MI\_DSA},
      \code{MI\_DR}.
   \item [\code{MImanufacturer}] String giving name of device
      manufacturer.
   \item [\code{MIdevice\_model}] String identifying device model.
   \item [\code{MIinstitution}] String identifying institution.
   \item [\code{MIdepartment}] String identifying department.
   \item [\code{MIstation\_id}] String identifying machine that generated
      the images.
   \item [\code{MIreferring\_physician}] Name of patient's primary
      physician.
   \item [\code{MIattending\_physician}] Physician administering the
      examination.
   \item [\code{MIradiologist}] Radiologist interpreting the examination.
   \item [\code{MIoperator}] Name of technologist operating scanner.
   \item [\code{MIadmitting\_diagnosis}] String description of admitting
      diagnosis. 
   \item [\code{MIprocedure}] String description of the procedure employed.
   \item [\code{MIstudy\_id}] String identifying study.
\end{description}

\subsection{Acquisition variable}

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

\begin{description}
   \item [\code{MIprotocol}] String description of the protocol for
      image acquisition.
   \item [\code{MIscanning\_sequence}] String description of type of data
      taken (eg. for MR --- IR, SE, PS, etc.).
   \item [\code{MIrepetition\_time}] Time in seconds between pulse
      sequences.
   \item [\code{MIecho\_time}] Time in seconds between the middle of a 90
      degree pulse and the middle of spin echo production.
   \item [\code{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.
   \item [\code{MInum\_averages}] Number of times a given pulse sequence
      is repeated before any parameter is changed.
   \item [\code{MIimaging\_frequency}] Precession frequency in Hz of the
      imaged nucleus.
   \item [\code{MIimaged\_nucleus}] String specifying the nucleus that is
      resonant at the imaging frequency.
   \item [\code{MIradionuclide}] String specifying the isotope administered.
   \item [\code{MIcontrast\_agent}] String identifying the contrast or
      bolus agent.
   \item [\code{MIradionuclide\_halflife}] Half-life of radionuclide in
      seconds. 
   \item [\code{MItracer}] String identifying tracer labelled with
      radionuclide that was injected.
   \item [\code{MIinjection\_time}] String giving time (and date) of
      injection.
   \item [\code{MIinjection\_year}]  Integer giving year of injection.
   \item [\code{MIinjection\_month}] Integer giving month (1-12) of
      injection.
   \item [\code{MIinjection\_day}] Integer giving day (1-31) of
      injection.
   \item [\code{MIinjection\_hour}] Integer giving hour (0-23) of
      injection.
   \item [\code{MIinjection\_minute}] Integer giving minute (0-59) of
      injection.
   \item [\code{MIinjection\_seconds}] Floating-point value giving
      seconds of injection. 
   \item [\code{MIinjection\_length}] Length of time of injection (in
      seconds).
   \item [\code{MIinjection\_dose}] Total dose of radionuclide or contrast
      agent injected (in units specified by \code{MIdose\_units}).
   \item [\code{MIdose\_units}] String giving units of dose.
   \item [\code{MIinjection\_volume}] Volume of injection in mL.
   \item [\code{MIinjection\_route}] String identifying administration
      route of injection.
\end{description}

\section{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.

\subsection{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 
\begin{verbatim}
   ncopts = NC_VERBOSE | NC_FATAL;
\end{verbatim}
which means print error messages and exit when an error occurs. To
get error messages without having fatal errors, set 
\begin{verbatim}
   ncopts = NC_VERBOSE;
\end{verbatim}
For neither error messages nor fatal errors, set
\begin{verbatim}
   ncopts = 0;
\end{verbatim}

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$ (\code{MI\_ERROR}), then an
error has occurred. The value of the global variable \code{ncerr}
gives more information on the type of error (see file \code{netcdf.h}
for error codes).

\subsection{NetCDF file operations}

\begin{itemize}

\item \code{nccreate} : Create the file specified by \code{path}.
The argument \code{cmode} must have a 
value of either \code{NC\_CLOBBER} or \code{NC\_NOCLOBBER}. The return
value is an identifier for the NetCDF file and is used by subsequent
NetCDF function calls.
\begin{verbatim}
int nccreate(char* path,int cmode);
\end{verbatim}

\item \code{ncopen} : Open the file specified by \code{path}. \code{mode}
must have value 
\code{NC\_NOWRITE} or \code{NC\_WRITE}. The return value is a NetCDF
file identifier.
\begin{verbatim}
int ncopen(char* path,int mode);
\end{verbatim}

\item \code{ncredef} : Put an open file into define mode. 
\begin{verbatim}
int ncredef(int cdfid);
\end{verbatim}

\item \code{ncendef} : Put file into data mode. 
\begin{verbatim}
int ncendef(int cdfid);
\end{verbatim}

\item \code{ncclose} : Close a NetCDF file. 
\begin{verbatim}
int ncclose(int cdfid);
\end{verbatim}

\item \code{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.
\begin{verbatim}
int ncinquire(int cdfid,int* ndims,int* nvars,int* natts,int* recdim);
\end{verbatim}

\item \code{ncsync} : Synchronize an open file to disk. 
\begin{verbatim}
int ncsync(int cdfid);
\end{verbatim}

\item \code{ncabort} : Abort any changes to the file if it is in define mode. 
\begin{verbatim}
int ncabort(int cdfid);
\end{verbatim}

\item \code{ncsetfill} : When \code{ncendef} is called, all variables are
filled with a fill value by default. To turn this off, call this
routine with \code{fillmode} set to \code{NC\_NOFILL} (to turn it back
on, use \code{NC\_FILL}).
\begin{verbatim}
int ncsetfill(int cdfid,int fillmode);
\end{verbatim}

\end{itemize}

\subsection{Dimension operations}

\begin{itemize}

\item \code{ncdimdef} : Define a dimension with a name and a length. The
return value is a 
dimension id to be used in subsequent calls.
\begin{verbatim}
int ncdimdef(int cdfid,char* name,long length);
\end{verbatim}

\item \code{ncdimid} : Get a dimension id from a name. 
\begin{verbatim}
int ncdimid(int cdfid,char* name);
\end{verbatim}

\item \code{ncdiminq} : Inquire about a dimension (name or length). 
\begin{verbatim}
int ncdiminq(int cdfid,int dimid,char* name,long* length);
\end{verbatim}

\item \code{ncdimrename} : Rename a dimension. 
\begin{verbatim}
int ncdimrename(int cdfid,int dimid,char* name);
\end{verbatim}

\end{itemize}

\subsection{Variable operations}

\begin{itemize}

\item \code{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.
\begin{verbatim}
int ncvardef(int cdfid,char* name,nc_type datatype,int ndims,int dim[]);
\end{verbatim}

\item \code{ncvarid} : Get a variable id from a name. 
\begin{verbatim}
int ncvarid(int cdfid,char* name);
\end{verbatim}

\item \code{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.
\begin{verbatim}
int ncvarinq(int cdfid,int varid,char* name,nc_type* datatype,int* ndims,
               int dim[],int* natts);
\end{verbatim}

\item \code{ncvarput1} : Store a single value at the coordinate specified by
\code{coords}. 
\code{value} must be of the correct data type.
\begin{verbatim}
int ncvarput1(int cdfid,int varid,long coords[],void* value);
\end{verbatim}

\item \code{ncvarget1} : Get a single value from the coordinate specified by
coords. 
\begin{verbatim}
int ncvarget1(int cdfid,int varid,long coords[],void* value);
\end{verbatim}

\item \code{ncvarput} : Put a hyperslab (multi-dimensional rectangle) of
values starting at 
\code{start} with edge lengths given by \code{count}. For the C
interface, the last dimension varies fastest. Values must be of the
correct type.
\begin{verbatim}
int ncvarput(int cdfid,int varid,long start[],long count[],void* value);
\end{verbatim}

\item \code{ncvarget} : Get a hyperslab (multi-dimensional rectangle) of
values starting at 
\code{start} with edge lengths given by \code{count}. For the C
interface, the last dimension varies fastest. Values must be of the
correct type.
\begin{verbatim}
int ncvarget(int cdfid,int varid,long start[],long count[],void* value);
\end{verbatim}

\item \code{ncvarrename} : Rename a variable. 
\begin{verbatim}
int ncvarrename(int cdfid,int varid,char* name);
\end{verbatim}

\item \code{nctypelen} : Get the length (in bytes) of a data type. 
\begin{verbatim}
int nctypelen(nc_type datatype);
\end{verbatim}

\end{itemize}

\subsection{Attribute operations}

\begin{itemize}

\item \code{ncattput} : Store an attribute by name with variable \code{varid}.
The type and 
length of the attribute must be specified.
\begin{verbatim}
int ncattput(int cdfid,int varid,char* name,nc_type datatype,int len,
              void* value);
\end{verbatim}

\item \code{ncattinq} : Inquire about an attribute by name. Can get either
type or length. 
\begin{verbatim}
int ncattinq(int cdfid,int varid,char* name,nc_type* datatype,int* len);
\end{verbatim}

\item \code{ncattget} : Get an attribute's value by name. 
\begin{verbatim}
int ncattget(int cdfid,int varid,char* name,void* value);
\end{verbatim}

\item \code{ncattcopy} : Copy an attribute from one variable to another. 
\begin{verbatim}
int ncattcopy(int incdf,int invar,char* name,int outcdf,int outvar);
\end{verbatim}

\item \code{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.
\begin{verbatim}
int ncattname(int cdfid,int varid,int attnum,char* name);
\end{verbatim}

\item \code{ncattrename} : Rename an attribute. 
\begin{verbatim}
int ncattrename(int cdfid,int varid,char* name,char* newname);
\end{verbatim}

\item \code{ncattdel} : Delete an attribute. 
\begin{verbatim}
int ncattdel(int cdfid,int varid,char* name);
\end{verbatim}

\end{itemize}

\section{MINC routines}

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

\subsection{General convenience functions}

\begin{itemize}

\item \code{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
\code{path} is not compressed, then its name is returned.
\code{*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 \code{header\_only} is TRUE, then the routine will
expand only enough of the file to read the header.
\begin{verbatim}
public char *miexpand_file(char *path, char *tempfile, int header_only, 
                           int *created_tempfile);
\end{verbatim}

\item \code{miopen} : Like \code{ncopen}, but will temporarily
uncompress files (compress, pack, gzip, zip) opened with mode 
\code{NC\_NOWRITE}.
\begin{verbatim}
public int miopen(char *path, int mode);
\end{verbatim}

\item \code{micreate} : Like \code{nccreate}. May be enhanced in the future.
\begin{verbatim}
public int micreate(char *path, int cmode);
\end{verbatim}

\item \code{miclose} : Like \code{ncclose}, but finishes up for \code{miopen}
and \code{micreate}.
\begin{verbatim}
public int miclose(int cdfid);
\end{verbatim}

\item \code{miattget} : Like \code{ncattget}, but the caller specifies
the desired numeric type and maximum number of values to get. Type is
specified with \code{datatype} (the sign is the default for the type:
\code{MI\_UNSIGNED} for \code{NC\_BYTE} and \code{MI\_SIGNED}
otherwise). \code{max\_length} gives the maximum number of values to
get and \code{att\_length} returns the number of values actually read.
An error will occur if the attribute type is not numeric.
\begin{verbatim}
public int miattget(int cdfid, int varid, char *name, nc_type datatype,
                    int max_length, void *value, int *att_length);
\end{verbatim}

\item \code{miattget1} : Like \code{miattget}, but only one value is
returned. If there is more than one value, an error occurs.
\begin{verbatim}
public int miattget1(int cdfid, int varid, char *name, nc_type datatype,
                    void *value);
\end{verbatim}

\item \code{miattgetstr} : Gets a string value from an attribute.
  \code{maxlen} gives the maximum number of characters to be returned
  (including the terminating \verb+'\0'+). The string is written to
  the array specified by value and a pointer to the string is
  returned.
\begin{verbatim}
public char *miattgetstr(int cdfid, int varid, char *name, 
                         int maxlen, char *value);
\end{verbatim}

\item \code{miattputint} : Write an integer attribute.
\begin{verbatim}
public int miattputint(int cdfid, int varid, char *name, int value);
\end{verbatim}

\item \code{miattputdbl} : Write a double precision attribute.
\begin{verbatim}
public int miattputdbl(int cdfid, int varid, char *name, double value);
\end{verbatim}

\item \code{miattputstr} : Write a string attribute.
\begin{verbatim}
public int miattputstr(int cdfid, int varid, char *name, char *value);
\end{verbatim}

\item \code{mivarget} : Like \code{ncvarget}, but the caller specifies
the desired numeric type and sign (either \code{MI\_SIGNED} or
\code{MI\_UNSIGNED}).
\begin{verbatim}
public int mivarget(int cdfid, int varid, long start[], long count[],
                    nc_type datatype, char *sign, void *values);
\end{verbatim}

\item \code{mivarget1} : Like \code{ncvarget1}, but the caller
specifies the desired numeric type and sign.
\begin{verbatim}
public int mivarget1(int cdfid, int varid, long mindex[],
                     nc_type datatype, char *sign, void *value);
\end{verbatim}

\item \code{mivarput} : Like \code{ncvarput}, but the caller specifies
the numeric type and sign of the values being passed.
\begin{verbatim}
public int mivarput(int cdfid, int varid, long start[], long count[],
                    nc_type datatype, char *sign, void *values);
\end{verbatim}

\item \code{mivarput1} : Like \code{ncvarput1}, but the caller specifies
the numeric type and sign of the values being passed.
\begin{verbatim}
public int mivarput1(int cdfid, int varid, long mindex[],
                     nc_type datatype, char *sign, void *value);
\end{verbatim}

\item \code{miset\_coords} : Set \code{nvals} values of the coordinate
vector \code{coords} to \code{value}. A pointer to \code{coords} is
returned.
\begin{verbatim}
public long *miset_coords(int nvals, long value, long coords[]);
\end{verbatim}

\item \code{mitranslate\_coords} : Translates the coordinate vector
\code{incoords} for subscripting variable \code{invar} of file
\code{cdfid} to vector \code{outcoords} for subscripting variable
\code{outvar}. This is useful when two variables have similar
dimensions, but not necessarily the same order of dimensions. If
\code{invar} has a dimension that is not in \code{outvar}, then the
corresponding coordinate is ignored. If \code{outvar} has a dimension
that is not in \code{invar}, then the corresponding coordinate is not
modified. A pointer to \code{outcoords} is returned.
\begin{verbatim}
public long *mitranslate_coords(int cdfid, 
                                int invar,  long incoords[],
                                int outvar, long outcoords[]);
\end{verbatim}

\item \code{micopy\_all\_atts} : Copy all of the attributes of one
variable to another (possibly across files).
\begin{verbatim}
public int micopy_all_atts(int incdfid, int invarid, 
                           int outcdfid, int outvarid);
\end{verbatim}

\item \code{micopy\_var\_def} : Copy a variable definition (including
attributes) from one file to another. \code{outcdfid} must be in
define mode. The id of the newly created variable is returned.
\begin{verbatim}
public int micopy_var_def(int incdfid, int invarid, int outcdfid);
\end{verbatim}

\item \code{micopy\_var\_values} : Copy a variable's values from one
file to another. \code{incdfid} and \code{outcdfid} must be in data
mode.
\begin{verbatim}
public int micopy_var_values(int incdfid, int invarid, 
                             int outcdfid, int outvarid);
\end{verbatim}

\item \code{micopy\_all\_var\_defs} : Copy all variable definitions from
one file to another, excluding a list of variables. The list of
\code{nexclude} variable id's is given in \code{excluded\_vars}.
\code{outcdfid} must be in define mode.
\begin{verbatim}
public int micopy_all_var_defs(int incdfid, int outcdfid, int nexclude,
                               int excluded_vars[]);
\end{verbatim}

\item \code{micopy\_all\_var\_values} : Copy all variable values from one
file to another, excluding a list of variables.  The list of
\code{nexclude} variable id's is given in \code{excluded\_vars}.
\code{outcdfid} must be in data mode.
\begin{verbatim}
public int micopy_all_var_values(int incdfid, int outcdfid, int nexclude,
                                 int excluded_vars[]);
\end{verbatim}

\end{itemize}

\subsection{MINC-specific convenience functions}

\begin{itemize}

\item \code{miget\_datatype} : Get the type and sign information for
an image variable. Signed data is indicated by setting
\code{is\_signed} to \code{TRUE}; unsigned by \code{FALSE}.
\begin{verbatim}
public int miget_datatype(int cdfid, int imgid,
                          nc_type *datatype, int *is_signed);
\end{verbatim}

\item \code{miget\_default\_range} : Returns the default range for a
specified type and sign.
\begin{verbatim}
public int miget_default_range(nc_type datatype, int is_signed,
                               double default_range[]);
\end{verbatim}

\item \code{miget\_valid\_range} : Gets the valid range information
for an image variable. This function handles potential type
differences between the \code{valid\_range} attribute and the image
data. These differences (particularly float images with double
\code{valid\_range}) could otherwise lead to problems in properly
identifying invalid data.
\begin{verbatim}
public int miget_valid_range(int cdfid, int imgid, double valid_range[]);
\end{verbatim}

\item \code{miset\_valid\_range} : Sets the valid range information
for an image variable. This function follows the NetCDF convention of
having both variable data and \code{valid\_range} attribute with the
same type.
\begin{verbatim}
public int miset_valid_range(int cdfid, int imgid, double valid_range[]);
\end{verbatim}

\item \code{miget\_image\_range} : Gets the maximum real range of the
image data based on the image-min and image-max variables.
\begin{verbatim}
public int miget_image_range(int cdfid, double image_range[]);
\end{verbatim}

\item \code{mivar\_exists} : Tests for the existence of a
variable. Returns true if the variable exists.
\begin{verbatim}
public int mivar_exists(int cdfid, char *varname);
\end{verbatim}

\item \code{miattput\_pointer} : Create an attribute \code{name} in the
variable \code{varid} that points to the variable \code{ptrvarid}.
\begin{verbatim}
public int miattput_pointer(int cdfid, int varid, char *name, int ptrvarid);
\end{verbatim}

\item \code{miattget\_pointer} : Returns the variable id pointed to by
attribute \code{name} of variable \code{varid}.
\begin{verbatim}
public int miattget_pointer(int cdfid, int varid, char *name);
\end{verbatim}

\item \code{miadd\_child} : Add the name of variable
\code{child\_varid} to the \code{MIchildren} attribute of variable
\code{parent\_varid} and set the \code{MIparent} attribute of variable
\code{child\_varid} to the name of variable \code{parent\_varid}. If
the attributes do not exist, they are created. The names in the
attribute \code{MIchildren} are separated by newlines.
\begin{verbatim}
public int miadd_child(int cdfid, int parent_varid, int child_varid);
\end{verbatim}

\item \code{micreate\_std\_variable} : Create any of the standard MINC
variables and set some attributes. Called in the manner of
\code{ncvardef}. The id of the newly created variable is returned.
For all variables, attributes \code{MIvarid},
\code{MIvartype} and \code{MIversion} are all set. For dimension
and dimension width variables, \code{MIspacing} is set to
\code{MI\_REGULAR} if the number of dimensions is zero and
\code{MI\_IRREGULAR} otherwise. For dimension variables,
\code{MIalignment} is set to \code{MI\_CENTRE} unless the variable is
\code{MItime}, then it is set to \code{MI\_START}. As well, 
MIcomments is set to a string describing the direction of the world
coordinates of spatial dimensions. For dimension
width variables, \code{MIfiltertype} is set to \code{MI\_SQUARE}. For
\code{MIimage} and for \code{MIimagemax} and \code{MIimagemin},
dimensions are checked to ensure that the last two do not vary over
image dimensions and attribute pointers from \code{MIimage} are
created to point to the other two.
\begin{verbatim}
public int micreate_std_variable(int cdfid, char *name, nc_type datatype, 
                                 int ndims, int dim[]);
\end{verbatim}

\item \code{micreate\_group\_variable} : Like
\code{micreate\_std\_variable}, but \code{ndims} is always set to zero
and the datatype is \code{NC\_INT}. The id of the newly created
variable is returned.
\begin{verbatim}
public int micreate_group_variable(int cdfid, char *name);
\end{verbatim}

\end{itemize}

\subsection{Image conversion variable functions}

\begin{itemize}

\item \code{miicv\_create} : Create an image conversion variable and
set the defaults --- an icv identifier is returned for later use (or
\code{MI\_ERROR} if an error occurs). The old limit of
\code{MI\_MAX\_NUM\_ICV} icv's that can exist at one time has been
removed, although the definition remains.
\begin{verbatim}
public int miicv_create();
\end{verbatim}

\item \code{miicv\_free} : Free an image conversion variable.
\begin{verbatim}
public int miicv_free(int icvid);
\end{verbatim}

\item \code{miicv\_setdbl} : Set a numeric icv property to a double value.
\begin{verbatim}
public int miicv_setdbl(int icvid, int icv_property, double value);
\end{verbatim}

\item \code{miicv\_setint} : Set a numeric icv property to an integer value.
\begin{verbatim}
public int miicv_setint(int icvid, int icv_property, int value);
\end{verbatim}

\item \code{miicv\_setlong} : Set a numeric icv property to a long
integer value.
\begin{verbatim}
public int miicv_setlong(int icvid, int icv_property, long value);
\end{verbatim}

\item \code{miicv\_setstr} : Set a string icv property.
\begin{verbatim}
public int miicv_set(int icvid, int icv_property, char *value);
\end{verbatim}

\item \code{miicv\_inqdbl} : Inquire about a numeric icv property.
\code{value} points to the double precision variable in which the
value should be returned. 
\begin{verbatim}
public int miicv_inqdbl(int icvid, int icv_property, double *value);
\end{verbatim}

\item \code{miicv\_inqint} : Inquire about a numeric icv property.
\code{value} points to the integer variable in which the
value should be returned. 
\begin{verbatim}
public int miicv_inqint(int icvid, int icv_property, int *value);
\end{verbatim}

\item \code{miicv\_inqlong} : Inquire about a numeric icv property.
\code{value} points to the long integer variable in which the
value should be returned. 
\begin{verbatim}
public int miicv_inqlong(int icvid, int icv_property, long *value);
\end{verbatim}

\item \code{miicv\_inqstr} : Inquire about a string icv property. \code{value}
points to the character array in which the value should be returned. The
calling routine must allocate enough space for the return string.
\begin{verbatim}
public int miicv_inqstr(int icvid, int icv_property, char *value);
\end{verbatim}

\item \code{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 \code{icvid} must be in
data mode.
\begin{verbatim}
public int miicv_attach(int icvid, int cdfid, int varid);
\end{verbatim}

\item \code{miicv\_ndattach} : Like \code{miicv\_attach} but no
dimension conversion facilities are available (much like setting
\code{MI\_ICV\_DO\_DIM\_CONV} to \code{FALSE}). This avoids linking in
all of the dimension conversion routines when they are not needed (for
machines where memory may be a concern).
\begin{verbatim}
public int miicv_ndattach(int icvid, int cdfid, int varid);
\end{verbatim}

\item \code{miicv\_detach} : Detach a variable from an icv.
\begin{verbatim}
public int miicv_detach(int icvid);
\end{verbatim}

\item \code{miicv\_get} : Get a hyperslab of values from a variable
through an icv.
\begin{verbatim}
public int miicv_get(int icvid, long start[], long count[], void *values);
\end{verbatim}

\item \code{miicv\_put} : Put a hyperslab of values to a variable
through an icv.
\begin{verbatim}
public int miicv_put(int icvid, long start[], long count[], void *values);
\end{verbatim}

\end{itemize}

\section{Image conversion variable properties}

\begin{itemize}

\item \code{MI\_ICV\_TYPE} (type \code{nc\_type}) : Specifies the type
of values that the user wants. Modifying this property automatically
causes \code{MI\_ICV\_VALID\_MAX} and \code{MI\_ICV\_VALID\_MIN} to
be set to their default values. Default = \code{NC\_SHORT}.

\item \code{MI\_ICV\_SIGN} (type \code{char *}) :  Specifies the sign of
values that the user wants (irrelevant for floating point types).
Modifying this property automatically causes
\code{MI\_ICV\_VALID\_MAX} and \code{MI\_ICV\_VALID\_MIN} to be set to
their default values. Default = \code{MI\_SIGNED}.

\item \code{MI\_ICV\_DO\_RANGE} (type \code{int}) : When \code{TRUE},
range conversions (for valid max and min and for value normalization)
are done. When \code{FALSE}, values are not modified. Default =
\code{TRUE}.

\item \code{MI\_ICV\_VALID\_MAX} (type \code{double}) : Valid maximum
value (ignored for floating point types). Default = maximum legal
value for type and sign (1.0 for floating point types).

\item \code{MI\_ICV\_VALID\_MIN} (type \code{double}) : Valid minimum
value (ignored for floating point types). Default = minimum legal
value for type and sign (1.0 for floating point types).

\item \code{MI\_ICV\_DO\_NORM} (type \code{int}) : If \code{TRUE},
then normalization of values is done (see user guide for details of
normalization). Default = \code{FALSE}.

\item \code{MI\_ICV\_USER\_NORM} (type \code{int}) : If \code{TRUE},
then the user specifies the normalization maximum and minimum. If
\code{FALSE}, values are taken as maximum and minimum for whole image
variable. Default = \code{FALSE}.

\item \code{MI\_ICV\_IMAGE\_MAX} (type \code{double}) : Image maximum
for user normalization. Default = 1.0.

\item \code{MI\_ICV\_IMAGE\_MIN} (type \code{double}) : Image minimum
for user normalization. Default = 0.0.

\item \code{MI\_ICV\_NORM\_MAX} (type \code{double}) : Read-only value
giving the user image maximum when doing normalization (either the
maximum in the variable or the user specified maximum).

\item \code{MI\_ICV\_NORM\_MIN} (type \code{double}) : Read-only value
giving the user image minimum when doing normalization (either the
minimum in the variable or the user specified minimum).

\item \code{MI\_ICV\_DO\_FILLVALUE} (type \code{int}) : If set to 
\code{TRUE}, then range checking is done on input and values that
are out of range (value in the file less than \code{MIvalid\_min} or
greater than \code{MIvalid\_max}) are set to the value of
\code{MI\_ICV\_FILLVALUE}.  Default = \code{FALSE}.

\item \code{MI\_ICV\_FILLVALUE} (type \code{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 = \code{-DBL\_MAX}.

\item \code{MI\_ICV\_DO\_DIM\_CONV} (type \code{int}) : If set to 
\code{TRUE}, then dimension conversions may be done. Default =
\code{FALSE}.

\item \code{MI\_ICV\_DO\_SCALAR} (type \code{int}) : If \code{TRUE},
then if \code{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 = \code{TRUE}.

\item \code{MI\_ICV\_XDIM\_DIR} (type \code{int}) : Indicates the
desired orientation of the x image dimensions (\code{MIxspace} and
\code{MIxfrequency}). Values can be one of \code{MI\_ICV\_POSITIVE},
\code{MI\_ICV\_NEGATIVE} or \code{MI\_ICV\_ANYDIR}. A positive
orientation means that the \code{MIstep} attribute of the dimension is
positive. \code{MI\_ICV\_ANYDIR} means that no flipping is done.
Default = \code{MI\_ICV\_POSITIVE}.

\item \code{MI\_ICV\_YDIM\_DIR} (type \code{int}) : Indicates the
desired orientation of the y image dimensions. Default =
\code{MI\_ICV\_POSITIVE}. 

\item \code{MI\_ICV\_ZDIM\_DIR} (type \code{int}) : Indicates the
desired orientation of the z image dimensions. Default =
\code{MI\_ICV\_POSITIVE}. 

\item \code{MI\_ICV\_ADIM\_SIZE} (type \code{long}) : Specifies the
desired size of the fastest varying image dimension. A value of
\code{MI\_ICV\_ANYSIZE} means that the actual size of the dimension
should be used. Default = \code{MI\_ICV\_ANYSIZE}.

\item \code{MI\_ICV\_BDIM\_SIZE} (type \code{long}) : Specifies the
desired size of the second image dimension. Default =
\code{MI\_ICV\_ANYSIZE}. 

\item \code{MI\_ICV\_KEEP\_ASPECT} (type \code{int}) : If \code{TRUE},
then image dimensions are resized by the same amount so that aspect
ratio is maintained. Default = \code{TRUE}.

\item \code{MI\_ICV\_ADIM\_STEP} (type \code{double}) : Read-only
property that gives the equivalent of attribute \code{MIstep} for the
first (fastest varying) image dimension after dimension conversion.

\item \code{MI\_ICV\_BDIM\_STEP} (type \code{double}) : Read-only
property that gives the equivalent of attribute \code{MIstep} for the
second image dimension after dimension conversion.

\item \code{MI\_ICV\_ADIM\_START} (type \code{double}) : Read-only
property that gives the equivalent of attribute \code{MIstart} for the
first (fastest varying) image dimension after dimension conversion.

\item \code{MI\_ICV\_BDIM\_START} (type \code{double}) : Read-only
property that gives the equivalent of attribute \code{MIstart} for the
second image dimension after dimension conversion.

\item \code{MI\_ICV\_NUM\_IMGDIMS} (type \code{int}) : Specifies the
number of image dimensions used in dimension conversions. Default = 2.

\item \code{MI\_ICV\_DIM\_SIZE} (type \code{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 = \code{MI\_ICV\_ANYSIZE}. 

\item \code{MI\_ICV\_DIM\_STEP} (type \code{double}) : Read-only
property that gives the equivalent of attribute \code{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). 

\item \code{MI\_ICV\_DIM\_START} (type \code{double}) : Read-only
property that gives the equivalent of attribute \code{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). 

\item \code{MI\_ICV\_NUM\_DIMS} (type \code{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.

\item \code{MI\_ICV\_CDFID} (type \code{int}) : Read-only property
that gives the id of the currently attached NetCDF file, or
\code{MI\_ERROR} if no file is attached.

\item \code{MI\_ICV\_VARID} (type \code{int}) : Read-only property
that gives the id of the currently attached NetCDF variable, or
\code{MI\_ERROR} if no variable is attached.

\item \code{MI\_ICV\_MAXVAR} (type \code{char *}) : String property
specifying the name of the variable that gives the image maximum. 
Default = \code{MIimagemax}. 

\item \code{MI\_ICV\_MINVAR} (type \code{char *}) : String property
specifying the name of the variable that gives the image minimum. 
Default = \code{MIimagemin}.

\end{itemize}

\section{Known bugs}

\begin{itemize}

\item For dimension conversion with image conversion variables, the
values of \code{MI\_ICV\_DIM\_START}, \code{MI\_ICV\_ADIM\_START} and
\code{MI\_ICV\_BDIM\_START} are computed assuming that
\code{MIalignment} is equal to \code{MI\_CENTRE}. 

\end{itemize}

\end{document}