+
−%
+
−% 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 Guide}
+
−\author{Peter Neelin}
+
−\date{May 14, 1993}
+
−\textwidth 6.0in
+
−\oddsidemargin 0.125in
+
−\textheight 8.5in
+
−\topmargin -0.75in
+
−
+
−\begin{document}
+
−
+
−\maketitle
+
−
+
−\tableofcontents
+
−
+
−\clearpage
+
−
+
−\section{Introduction}
+
−
+
−The MINC file format (Medical Image NetCDF) is based on the NetCDF
+
−file format (Network Common Data Form) distributed by the Unidata
+
−Program Center. NetCDF provides a software interface for storing
+
−named, multi-dimensional variables in files in a machine-independent
+
−way. This interface removes applications from the concerns of
+
−portability and file structure and encourages a self-describing form
+
−of data.
+
−
+
−Each NetCDF multi-dimensional variable in a file is described by a
+
−name, by its dimensions and by attributes. For example, an image
+
−stored in a file might be stored as byte data in a variable called
+
−``\verb+image+'', with dimensions ``\verb+x+'' and ``\verb+y+'' (each
+
−of length 256) and with an attribute called ``\verb+long_name+'' which
+
−is a string describing the content of the image. Many variables can be
+
−stored in one file and each variable can have many attributes.
+
−Dimensions exist independently of variables and can subscript more
+
−than one variable.
+
−
+
−MINC provides three things on top of the NetCDF interface. It provides
+
−a standard for dimension, variable and attribute names suitable for
+
−medical imaging, it provides some convenience functions to complement
+
−the NetCDF interface (not specific to the MINC conventions) and it
+
−provides convenience functions for using MINC files.
+
−
+
−\section{An Introduction to NetCDF}
+
−
+
−(For a complete description, see the ``NetCDF User's Guide'').
+
−
+
−\subsection{The NetCDF file}
+
−
+
−It is useful to look at an example file while considering the NetCDF
+
−interface. Fortunately, the NetCDF package provides utilities (ncdump
+
−and ncgen) for converting the binary NetCDF files to an ascii format
+
−call CDL. A simple NetCDF file, converted to CDL notation by ncdump,
+
−is given below:
+
−
+
−\begin{verbatim}
+
−netcdf test {
+
−dimensions:
+
−	ycoord = 3 ;
+
−	xcoord = 4 ;
+
−
+
−variables:
+
−	double image(ycoord, xcoord) ;
+
−		image:long_name = "My favorite tiny image" ;
+
−	double xcoord(xcoord) ;
+
−
+
−data:
+
−
+
− image =
+
−  1, 2, 3, 4,
+
−  5, 6, 7, 8,
+
−  9, 10, 11, 12 ;
+
−
+
− xcoord = 100, 200, 300, 400 ;
+
−}
+
−\end{verbatim}
+
−
+
−The sample file stores a 3 by 4 image of double precision values. The
+
−first thing defined are the dimensions : \verb+xcoord+ and
+
−\verb+ycoord+. Dimensions can represent physical dimensions like x
+
−coordinate, y coordinate etc., or they can represent abstract things
+
−like lookup-table index.  Each dimension has a name and a length and
+
−when joined with other dimensions defines the shape of a variable ---
+
−the variable image is subscripted by \verb+ycoord+ and \verb+xcoord+.
+
−Dimensions can also be used across variables, relating them to each
+
−other. For example, if the file contained another image also
+
−subscripted by \verb+ycoord+ and \verb+xcoord+, we would have the
+
−important information that the two variables were sampled on the same
+
−grid.  Also, coordinate systems can be defined by creating variables
+
−by the same name as the dimension, like \verb+xcoord+ in the example
+
−above, giving the x coordinate of each point in the image.
+
−
+
−Variables are the next thing defined in the cdl file. Each variable
+
−has a name, data type and a shape specified by a list of dimensions
+
−(up to a maximum of \verb+MAX_VAR_DIMS+ = 32 dimensions per variable).
+
−The data types are \verb+NC_CHAR+, \verb+NC_BYTE+, \verb+NC_SHORT+,
+
−\verb+NC_INT+, \verb+NC_FLOAT+ and \verb+NC_DOUBLE+. Information
+
−about each variable is stored in attributes.  The attribute
+
−``\verb+long_name+'' gives a character string describing the variable
+
−``\verb+image+''. Attributes are either scalars or vectors of one of
+
−the six types listed above (a character string is a vector of type
+
−\verb+NC_CHAR+).
+
−
+
−\subsection{Programming with NetCDF}
+
−
+
−Programming with NetCDF can be quite simple. The file listed above was
+
−produced by the following program:
+
−
+
−\begin{verbatim}
+
−#include <netcdf.h>
+
−
+
−#define THE_NAME "My favorite tiny image"
+
−static double vals[][4]={
+
−   1.0, 2.0, 3.0, 4.0,
+
−   5.0, 6.0, 7.0, 8.0,
+
−   9.0,10.0,11.0,12.0
+
−};
+
−static int ysize=sizeof(vals)/sizeof(vals[0]);
+
−static int xsize=sizeof(vals[0])/sizeof(vals[0][0]);
+
−
+
−static double xcoord[]={100.,200.,300.,400.};
+
−
+
−main()
+
−{
+
−   int cdf, img, xvar;
+
−   int dim[MAX_VAR_DIMS];
+
−   long count[MAX_VAR_DIMS], start[MAX_VAR_DIMS];
+
−
+
−   /* Create the file */
+
−   cdf=nccreate("test.cdf",NC_CLOBBER);
+
−
+
−   /* Define the dimensions */
+
−   dim[0]=ncdimdef(cdf, "ycoord", ysize);
+
−   dim[1]=ncdimdef(cdf, "xcoord", xsize);
+
−
+
−   /* Define the variables */
+
−   img=ncvardef(cdf, "image", NC_DOUBLE, 2, dim);
+
−   xvar=ncvardef(cdf,"xcoord", NC_DOUBLE, 1, &dim[1]);
+
−
+
−   /* Add an attribute */
+
−   ncattput(cdf, img, "long_name", NC_CHAR, strlen(THE_NAME)+1, THE_NAME);
+
−
+
−   /* End definition mode */
+
−   ncendef(cdf);
+
−
+
−   /* Write the variable values */
+
−   start[0]=start[1]=0;
+
−   count[0]=ysize; count[1]=xsize;
+
−   ncvarput(cdf, img, start, count, vals);
+
−   ncvarput(cdf, xvar, &start[1], &count[1], xcoord);
+
−   ncclose(cdf);
+
−}
+
−\end{verbatim}
+
−
+
−The first executable line of the program creates a new NetCDF file. An
+
−open file is either in ``define'' mode or in ``data'' mode. In define
+
−mode, dimensions, variables and attributes can be defined, but data
+
−cannot be written to or read from variables. In data mode, variable
+
−values can be written or read, but no changes to dimensions or
+
−variables can be made and attributes can only be written if they exist
+
−already and will not get larger with the write. Newly created files
+
−are automatically in define mode.
+
−
+
−The lines following the call to nccreate define the dimensions and
+
−variables in the file. Notice that the NetCDF file, dimensions and
+
−variables are all identified by an integer returned when they are
+
−created. These id's are subsequently used to refer to each object. The
+
−attribute ``\verb+long_name+'' for the image variable is identified
+
−only by its name.
+
−
+
−Once everything is defined, ncendef puts the file into data mode and
+
−values are written. The values to write are defined by a vector of
+
−starting indices and a vector of the number of values to write in each
+
−dimension. This defines a multi-dimensional rectangle within the
+
−variable called a hyperslab. In the C interface, the first element of
+
−the vector refers to the slowest varying index of the variable, so in
+
−this example, the array vals has the \verb+xcoord+ varying fastest. In
+
−the FORTRAN interface, the convention has the first subscript varying
+
−fastest. These conventions follow the language conventions for
+
−multi-dimensional arrays.
+
−
+
−\section{The MINC format}
+
−
+
−It is possible to build MINC format files using only NetCDF function
+
−calls, however a C include file is provided to facilitate (and help
+
−ensure) adherence to the standard. This file defines useful constants,
+
−standard dimension, variable and attribute names and some attribute
+
−values. It also declares the functions defined in a library of minc
+
−convenience functions, designed to make an application programmer's
+
−life easier.
+
−
+
−\subsection{The MINC standard}
+
−
+
−Various requirements for file formats have been put forward. One such
+
−list is as follows: A protocol should be: 1) simple, 2) self
+
−describing, 3) maintainable, 4) extensible, 5) N dimensional, and 6)
+
−have a universal data structure. The NetCDF format meets all of these
+
−requirements, suggesting that it is a good place to start. I would,
+
−however, add some more requirements to the list. Implied in the above
+
−list is the requirement that there be a standard for accessing data
+
−(how do I get the patient name) --- this is not provided by NetCDF.
+
−Furthermore, a useful format should come with a software interface
+
−that makes it easy to use, particularly in a development environment.
+
−Finally, a format that stores many associated pieces of information
+
−should also provide some data organization.
+
−
+
−The MINC format attempts to add these things to the NetCDF format.
+
−
+
−\subsubsection{MINC variable types}
+
−
+
−Medical imaging tends to produce files with a large amount of
+
−ancillary data (patient information, image information, acquisition
+
−information, etc.). To organise this information in a useful fashion,
+
−MINC uses variables to group together related attributes. The variable
+
−itself may or may not contain useful data. For example, the variable
+
−\verb+MIimage+ contains the image data and has attributes relevant to this
+
−data. The variable \verb+MIpatient+ has no relevant variable data, but
+
−serves to group together all attributes describing the patient (name,
+
−birthdate, etc.). This sort of variable is called a group variable.
+
−
+
−Variables that correspond to dimensions are called dimension variables
+
−and describe the coordinate system corresponding to the dimension. An
+
−example is MIxspace --- both a dimension and a variable describing the
+
−x coordinate of other variables.
+
−
+
−The NetCDF conventions allow for these dimension variables to specify
+
−the coordinate at each point, but there is nothing to describe the
+
−width of the sample at that point. MINC provides the convention of
+
−dimension width variables, e.g. \verb+MIxspace_width+, to give this
+
−information.
+
−
+
−Finally, it is possible to have attributes that vary over some of the
+
−dimensions of the variable. For example, if we have a volume of image
+
−data, varying over \verb+MIxspace+, \verb+MIyspace+ and
+
−\verb+MIzspace+, we may want an attribute giving the maximum value of
+
−the each image, varying over \verb+MIzspace+. To achieve this we use a
+
−variable, called a variable attribute, pointed to by an attribute of
+
−the image variable.
+
−
+
−Thus MINC introduces a number of types of variables: group variables,
+
−dimension variables, dimension width variables and variable
+
−attributes.
+
−
+
−\subsubsection{Data organization}
+
−
+
−MINC attempts to provide some level of data organization through a
+
−hierarchy of group variables. As mentioned above, attributes are
+
−grouped according to type in group variables. Each group variable can
+
−have an \verb+MIparent+ and an \verb+MIchildren+ attribute --- the
+
−former specifying the name of another variable that is above this one
+
−in the hierarchy, the latter specifying a newline-separated list of
+
−variables that come below this one in the hierarchy. At the root of
+
−the hierarchy is the \verb+MIrootvariable+ variable, with no parent.
+
−Although it is not necessary to make use of this structure, it can
+
−provide a mechanism for ordering large amounts of information.
+
−
+
−\subsubsection{MINC dimension, variable and attribute names}
+
−
+
−The NetCDF format says nothing about variable and dimension naming
+
−conventions and little about attribute names. It does provide a few
+
−standards, such as the attribute ``\verb+long_name+'' for describing a
+
−variable, which have been adopted by the MINC standard. MINC defines a
+
−set of standard names for commonly used entities and the include file
+
−defines constants specifying these names. These are described at
+
−length in the MINC reference manual. The most interesting of these is
+
−\verb+MIimage+, the name of the variable used for storing the actual image
+
−data in the file.
+
−
+
−\subsubsection{Image dimensions}
+
−
+
−The MINC standard gives some special status to the concept of an
+
−image. There is nothing inherent in NetCDF that suggests any special
+
−status for particular dimensions, but it can be convenient to place
+
−limitations on what can vary over which dimensions in an imaging
+
−context. For example, the requirement that the variables that specify
+
−how to rescale images (see later section on pixel values) not vary
+
−with image dimensions means that we can treat the image as a simple
+
−unit. In the simplest case, the image dimensions are simply the two
+
−fastest varying dimensions of the \verb+MIimage+ variable.
+
−
+
−It can also be helpful to allow for vector fields --- images or image
+
−volumes that have a vector of values at each point. A simple example
+
−of a vector field is an RGB image. At each point in space, there are
+
−three values: red, green and blue. The dimension
+
−\verb+MIvector_dimension+ is used for the components of the vector and
+
−it should be the fastest varying dimension in the \verb+MIimage+ variable. If
+
−it is present, then the three fastest varying dimensions of \verb+MIimage+
+
−are the image dimensions.
+
−
+
−\subsubsection{MINC coordinate system}
+
−
+
−The MINC standard defines how spatial coordinates should be oriented
+
−relative to patients. Files are free to have data stored in the
+
−desired direction, but positive world coordinates are given a definite
+
−meaning in the medical imaging context. The standard is that the
+
−positive x axis points from the patient's left to right, the positive
+
−y axis points from posterior to anterior and the positive z axis
+
−points from inferior to superior.
+
−
+
−The conversion of element index to world coordinates is done using the
+
−dimension variable attributes \verb+MIdirection_cosines+,
+
−\verb+MIstep+ and \verb+MIstart+. If the direction cosines are 
+
−${\bf c}=(c_x, c_y, c_z)$, then the vector between adjacent elements
+
−along an axis is $step\times {\bf c}$. If $start(i)$ and 
+
−${\bf c}(i)$ are the \verb+MIstart+ and
+
−\verb+MIdirection_cosines+ attributes for dimension $i$ (one of
+
−\verb+MIxspace+, \verb+MIyspace+ and \verb+MIzspace+),
+
−then the first element of the image variable is at world coordinate
+
−$ \sum_i start(i) {\bf c}(i) $.
+
−
+
−If the direction cosines are not present, then they are
+
−assumed to be $(1,0,0)$ for \verb+MIxspace+, $(0,1,0)$ for
+
−\verb+MIyspace+ and $(0,0,1)$ for \verb+MIzspace+. Direction cosines are
+
−unit vectors and should be normalized. As well, the step attribute
+
−should carry the information about axis flipping (negative or
+
−positive) rather than the direction cosine.
+
−
+
−\subsubsection{Pixel values and real values}
+
−
+
−In medical imaging, pixel values are frequently stored as bytes or
+
−shorts, but there is a generally a real value associated with each
+
−pixel as well. This real value is obtained by a scale factor and
+
−offset associated with each image or image volume. The MINC standard
+
−indicates how pixel values should be interpreted. 
+
−
+
−Image data in the \verb+MIimage+ variable can be stored as bytes, shorts,
+
−ints (32-bit), floats or doubles. NetCDF conventions use the attributes
+
−\verb+MIvalid_range+ or \verb+MIvalid_max+ and \verb+MIvalid_min+ to
+
−indicate the range of values that can be found in the variable. For
+
−short values, for example, we might have a valid range of 0 to 32000.
+
−To convert these integers to real values, we could use a scale and
+
−offset. However, these values would have to change if the data where
+
−converted to bytes in the range 23 to 228. If we specify an image
+
−maximum and minimum to which \verb+MIvalid_max+ and \verb+MIvalid_min+
+
−should be mapped by an appropriate scale and offset, then we can
+
−convert type and valid range without having to change the real maximum
+
−and minimum.  To allow the maximum dynamic range in an image, we use
+
−the variables \verb+MIimagemax+ and \verb+MIimagemin+ to store the
+
−real maximum and minimum --- these can vary over any of the non-image
+
−dimensions of \verb+MIimage+.
+
−
+
−\subsection{General convenience functions}
+
−
+
−MINC provides a number of convenience functions that have nothing to
+
−do with medical imaging, but that make the use of NetCDF files a
+
−little easier. One of the drawbacks of the NetCDF format is that data
+
−can come in any form (byte, short, int, float, double) and the
+
−calling program must handle the general case. Rather than restrict
+
−this, MINC provides functions to convert types.
+
−
+
−The first set of convenience functions are for type conversion. A list
+
−follows : 
+
−\begin{itemize}
+
−   \item {\bf \verb+miattget+} - reads an attribute vector, specifying
+
−      the numeric type desired and the maximum number of values to read.
+
−   \item {\bf \verb+miattget1+} - reads one attribute value of the
+
−      specified type. 
+
−   \item {\bf \verb+miattgetstr+} - read a character attribute of a specified
+
−      maximum length.
+
−   \item {\bf \verb+miattputdbl+} - write a double precision attribute.
+
−   \item {\bf \verb+miattputstr+} - write a string attribute.
+
−   \item {\bf \verb+mivarget+} - get a hyperslab of values of the
+
−      specified type. 
+
−   \item {\bf \verb+mivarget1+} - get a single value of the specified type.
+
−   \item {\bf \verb+mivarput+} - put a hyperslab of values of the
+
−      specified type. 
+
−   \item {\bf \verb+mivarput1+} - put a single value of the specified type.
+
−\end{itemize}
+
−
+
−Next we have some functions for handling coordinate vectors :
+
−\begin{itemize}
+
−   \item {\bf \verb+miset_coords+} - set a vector of coordinates to a
+
−      single value. 
+
−   \item {\bf \verb+mitranslate_coords+} - translate the coordinates for one
+
−      variable to a vector for subscripting another variable.
+
−\end{itemize}
+
−
+
−Finally, there are functions for dealing with variables as groups of
+
−attributes, making it easier to modify a file while keeping ancillary
+
−information :
+
−\begin{itemize}
+
−   \item {\bf \verb+micopy_all_atts+} - copy all of the attributes of
+
−      one variable to another (possibly across files).
+
−   \item {\bf \verb+micopy_var_def+} - copy a variable definition (including
+
−      attributes) from one file to another.
+
−   \item {\bf \verb+micopy_var_vals+} - copy a variable's values from
+
−      one variable to another (possibly across files).
+
−   \item {\bf \verb+micopy_all_var_defs+} - copy all variable
+
−      definitions from one file to another, excluding a list of variables.
+
−   \item {\bf \verb+micopy_all_var_vals+} - copy all variable values
+
−      from one file to another, excluding a list of variables.
+
−\end{itemize}
+
−
+
−\subsection{MINC specific convenience functions}
+
−
+
−A few routines are provided to deal with some of the minc structures.
+
−\verb+miattput_pointer+ and \verb+miattget_pointer+ put/get a pointer to a
+
−variable attribute. \verb+miadd_child+ helps maintain the hierarchy of
+
−variables by handling the \verb+MIparent+ and \verb+MIchildren+
+
−attributes of two variables. Finally \verb+micreate_std_variable+ and
+
−\verb+micreate_group_variable+ create some of the standard variables
+
−and fill in a few of the default attributes.
+
−
+
−\subsection{Image conversion variables}
+
−
+
−One of the requirements for file formats mentioned earlier was
+
−a software interface to make the interface easy to use. The biggest
+
−difficulty in using a flexible format is that the application must
+
−handle many possibilities. Where images are concerned, this means
+
−various data types and scale factors, and images of differing sizes.
+
−The image conversion variable functions of MINC attempt to remove this
+
−complication for the programmer.
+
−
+
−An image conversion variable (icv) is essentially a specification of what
+
−the program wants images to look like, in type, scale and dimension.
+
−When an MINC image is read through an icv, it is converted for the
+
−calling program to a standard format regardless of how data is stored
+
−in the file.
+
−
+
−There are two categories of conversion: Type and range conversions
+
−change the datatype (and sign) of image values and optionally scale
+
−them for proper normalization. Dimension conversions allow programs to
+
−specify image dimension size and image axis orientation (should
+
−\verb+MIxspace+ coordinates be increasing or decreasing? should the
+
−patient's left side appear on the left or right of the image?).
+
−
+
−\subsubsection{ICV routines}
+
−
+
−Accessing a file through an icv is a straight-forward process.
+
−Create the icv with \verb+miicv_create+, set properties
+
−(like desired datatype) with the \verb+miicv_set+ routines, attach the
+
−icv to a NetCDF 
+
−variable with \verb+miicv_attach+ and access the data with
+
−\verb+miicv_get+ or \verb+miicv_put+. The icv can be detached from a
+
−NetCDF variable with \verb+miicv_detach+ and can be freed with
+
−\verb+miicv_free+.
+
−
+
−Icv properties are strings, integers, long integers or doubles. For
+
−example, \verb+MI_ICV_SIGN+ (the sign of variable values) is a string,
+
−while \verb+MI_ICV_IMAGE_MAX+ (image maximum) is a double precision
+
−value.  Four functions --- \verb+miicv_setint+, \verb+miicv_setlong+,
+
−\verb+miicv_setdbl+ and \verb+miicv_setstr+ ---
+
−are provided to simplify the setting of property values. Programs can
+
−inquire about property values with \verb+miicv_inqint+,
+
−\verb+miicv_inqlong+, \verb+miicv_inqdbl+ and \verb+miicv_inqstr+.
+
−
+
−\subsubsection{Type and range conversion}
+
−
+
−Pixel values are converted for type and sign by specifying values for
+
−the properties \verb+MI_ICV_TYPE+ and \verb+MI_ICV_SIGN+ (they default
+
−to \verb+NC_SHORT+ and \verb+MI_SIGNED+). Values can also be converted
+
−for valid range and for normalization. These conversions are enabled
+
−by setting \verb+MI_ICV_DO_RANGE+ to \verb+TRUE+ (the default).
+
−
+
−If \verb+MI_ICV_DO_NORM+ is \verb+FALSE+ (the default) then only
+
−conversions for valid range are made. This means that if the input
+
−file has shorts in the range 0 to 4095, then they can be converted to
+
−bytes in the range 64 to 248 (for example). The real image maximum and
+
−minimum (\verb+MIimagemax+ and \verb+MIimagemin+) are ignored. The
+
−valid range is specified by the properties \verb+MI_ICV_VALID_MAX+ and
+
−\verb+MI_ICV_VALID_MIN+, which default to the legal range for the type
+
−and sign.
+
−
+
−We may want to scale values so that they are normalized either to all
+
−values in the \verb+MIimage+ variable or to some user-defined range.
+
−To do normalization, set \verb+MI_ICV_DO_NORM+ to \verb+TRUE+. Setting
+
−\verb+MI_ICV_USER_NORM+ to \verb+FALSE+ (the default) causes normalization to
+
−the real maximum and minimum of the variable (the maximum of
+
−\verb+MIimagemax+ and the minimum of \verb+MIimagemin+). If
+
−\verb+MI_ICV_USER_NORM+ is true then the values of \verb+MI_ICV_IMAGE_MAX+
+
−and \verb+MI_ICV_IMAGE_MIN+ are used (defaulting to 1.0 and 0.0).
+
−
+
−When either \verb+MI_ICV_TYPE+ or the file type is floating-point,
+
−then the conversion to and from real values is always done using the
+
−real image maximum and minimum information. If the internal type is
+
−integer and \verb+MI_ICV_DO_NORM+ is \verb+FALSE+, then the rescaling
+
−is done so that the slice maximum maps to the valid range of the
+
−internal values.
+
−
+
−Note that when converting to integer types, values are rounded to the
+
−nearest integer and limited to be within the legal range for the data
+
−type.
+
−
+
−The above transformations are simple enough, but the use of
+
−floating-point values adds to the complexity, since in general we do
+
−not want to rescale these values to get the real values. The various
+
−possibilities are described in greater detail below.
+
−
+
−\subsubsection{The details of pixel value conversion}
+
−
+
−The easiest way to think about the rescaling is through four ranges
+
−(maximum-minimum pairs). In the file variable, values have a
+
−valid range \verb+var_vrange+ and these correspond to real values
+
−\verb+var_imgrange+. The user/application wants to convert real values
+
−\verb+usr_imgrange+ to a useful valid range \verb+usr_vrange+. From
+
−\verb+var_vrange+, \verb+var_imgrange+, \verb+usr_imgrange+ and
+
−\verb+usr_vrange+, we can determine a scale and offset for converting
+
−pixel values: Input values are scaled to real values by
+
−\verb+var_vrange+ to \verb+var_imgrange+ and then scaled again to user
+
−values by \verb+usr_imgrange+ to \verb+usr_vrange+.
+
−
+
−If either of the \verb+vrange+ variables are not specified, they default to
+
−maximum possible range for integer types. For floating
+
−point types, \verb+usr_vrange+ is set equal to \verb+usr_imgrange+
+
−so that no conversion of real values is done. 
+
−
+
−If normalization is not being done, then for integer types
+
−\verb+var_imgrange+ and \verb+usr_imgrange+ are set to [0,1] (scale
+
−down to [0,1] and scale up again).  When normalizibng,
+
−\verb+usr_imgrange+ is set to either the full range of the variable
+
−([0,1] if not found) or the user's requested range. If the variable
+
−values are floating point, then \verb+var_imgrange+ is set to
+
−\verb+var_vrange+ (no scaling to real values), otherwise
+
−\verb+var_imgrange+ is read for each image (again, [0,1] if not
+
−found).
+
−
+
−What this means for reading and writing images is discussed below.
+
−
+
−\subsubsection{Reading with pixel conversion}
+
−
+
−When reading into internal floating point values, normalization has no
+
−effect. When reading integers without normalization, each image is
+
−scaled to full range. With normalization they are scaled to the
+
−specified range and slices can be compared.
+
−
+
−When the input file is missing either
+
−\verb+MIimagemax+/\verb+MIimagemin+ (\verb+var_imgrange+ information)
+
−or \verb+MIvalid_range+, the routines try to provide sensible
+
−defaults, but funny things can still happen. The biggest problem is
+
−the absence of \verb+MIvalid_range+ if the defaults are not correct
+
−(full range for integer values and [0,1] for floating point). When
+
−converting floating point values to an integer type, there will be
+
−overflows if values are outside the range [0,1].
+
−
+
−\subsubsection{Writing with pixel conversion}
+
−
+
−The conversion routines can be used for writing values. This can be
+
−useful for data compression --- e.g. converting internal floats to
+
−byte values in the file, or converting internal shorts to bytes. When
+
−doing this with normalization (to rescale bytes to the slice maximum,
+
−for example) it is important to write the slice maximum and minimum in
+
−\verb+MIimagemax+ and \verb+MIimagemin+ before writing the slice.
+
−
+
−The other concern is that \verb+MIvalid_range+ or \verb+MIvalid_max+
+
−and \verb+MIvalid_min+ be written properly (especially if the defaults
+
−are not correct). When writing floating point values,
+
−\verb+MIvalid_range+ should be set to the full range of values in the
+
−variable. In this case, the attribute does not have to be set
+
−correctly before writing the variable, but if it exists, the values
+
−should be reasonable (maximum greater than minimum and values not
+
−likely to cause overflow). These will be set automatically if the
+
−routine \verb+micreate_std_variable+ is used with
+
−\verb+NC_FILL+ mode on (the default).
+
−
+
−\subsubsection{Example: Reading values}
+
−
+
−Read an image without normalization:
+
−\begin{verbatim}
+
−   /* Create the icv */
+
−   icv=miicv_create();
+
−   (void) miicv_setint(icv, MI_ICV_TYPE, NC_SHORT);
+
−   (void) miicv_setstr(icv, MI_ICV_SIGN, MI_UNSIGNED);
+
−   (void) miicv_setint(icv, MI_ICV_VALID_MAX, 32000);
+
−   (void) miicv_setint(icv, MI_ICV_VALID_MIN, 0);
+
−
+
−   /* Open the file, attach the image variable */
+
−   cdfid=ncopen(filename, NC_NOWRITE);
+
−
+
−   /* Attach image variable */
+
−   img=ncvarid(cdfid, MIimage);
+
−   (void) miicv_attach(icv, cdfid, img);
+
−
+
−   /* Get the data - we assume that coord and count are set properly */
+
−   (void) miicv_get(icv, coord, count, image);
+
−
+
−   /* Close the file and free the icv */
+
−   (void) ncclose(cdfid);
+
−   (void) miicv_free(icv);
+
−\end{verbatim}
+
−
+
−Read an integer image with normalization:
+
−\begin{verbatim}
+
−   /* Create the icv */
+
−   icv=miicv_create();
+
−   (void) miicv_setint(icv, MI_ICV_TYPE, NC_SHORT);
+
−   (void) miicv_setstr(icv, MI_ICV_SIGN, MI_UNSIGNED);
+
−   (void) miicv_setint(icv, MI_ICV_VALID_MAX, 32000);
+
−   (void) miicv_setint(icv, MI_ICV_VALID_MIN, 0);
+
−   (void) miicv_setint(icv, MI_ICV_DO_NORM, TRUE);
+
−   (void) miicv_setint(icv, MI_ICV_USER_NORM, TRUE);
+
−   (void) miicv_setdbl(icv, MI_ICV_IMAGE_MAX, 1.83);
+
−   (void) miicv_setdbl(icv, MI_ICV_IMAGE_MIN, -0.57);
+
−   ...
+
−\end{verbatim}
+
−
+
−Read a floating point image :
+
−\begin{verbatim}
+
−   /* Create the icv. We don't have to set MI_ICV_USER_NORM to TRUE,
+
−      but doing so ensures that the conversion is done properly
+
−      without looking at file values (the defaults for
+
−      MI_ICV_IMAGE_MAX and MI_ICV_IMAGE_MIN are 1 and 0) */
+
−   icv=miicv_create();
+
−   (void) miicv_setint(icv, MI_ICV_TYPE, NC_FLOAT);
+
−   (void) miicv_setint(icv, MI_ICV_DO_NORM, TRUE);
+
−   (void) miicv_setint(icv, MI_ICV_USER_NORM, TRUE);
+
−   ...
+
−\end{verbatim}
+
−
+
−\subsubsection{Example: Writing values}
+
−
+
−Writing from floating point to byte values :
+
−
+
−\begin{verbatim}
+
−   /* Create the icv */
+
−   icv=miicv_create();
+
−   (void) miicv_setint(icv, MI_ICV_TYPE, NC_FLOAT);
+
−   (void) miicv_setint(icv, MI_ICV_DO_NORM, TRUE);
+
−
+
−   /* Create the file */
+
−   cdf=nccreate(filename, NC_CLOBBER);
+
−
+
−   /* Define the dimensions */
+
−   dim[0]=ncdimdef(cdf, MIyspace, ysize);
+
−   dim[1]=ncdimdef(cdf, MIxspace, xsize);
+
−
+
−   /* Define the variables */
+
−   img=micreate_std_variable(cdf, MIimage, NC_BYTE, 2, dim);
+
−   (void) miattputstr(cdf, img, MIsigntype, MI_UNSIGNED);
+
−   vrange[0]=0; vrange[1]=200;
+
−   (void) ncattput(cdf, img, MIvalid_range, NC_DOUBLE, 2, vrange);
+
−   max=micreate_std_variable(cdf, MIimagemax, NC_DOUBLE, 0, NULL);
+
−   min=micreate_std_variable(cdf, MIimagemin, NC_DOUBLE, 0, NULL);
+
−
+
−   /* End definition mode */
+
−   ncendef(cdf);
+
−
+
−   /* Attach image variable */
+
−   (void) miicv_attach(icv, cdf, img);
+
−
+
−   /* Write the image max and min */
+
−   ncvarput1(cdf, max, NULL, &image_maximum);
+
−   ncvarput1(cdf, min, NULL, &image_minimum);
+
−
+
−   /* Write the image */
+
−   start[0]=start[1]=0;
+
−   count[0]=ysize; count[1]=xsize;
+
−   miicv_put(icv, start, count, vals);
+
−
+
−   /* Close the file and free the icv */
+
−   (void) ncclose(cdf);
+
−   (void) miicv_free(icv);
+
−\end{verbatim}
+
−
+
−If we were writing a floating point image, the only difference (apart
+
−from changing \verb+NC_BYTE+ to \verb+NC_FLOAT+) would be that we
+
−would rewrite \verb+MIvalid_range+ at the end of the file with the
+
−full range of floating point values.
+
−
+
−\subsubsection{Dimension conversion}
+
−
+
−One of the problems of arbitrary dimensioned images is that it becomes
+
−necessary for software to handle the general case. It is easier to write
+
−application software if it is known in advance that all images will
+
−have a specific size (e.g. $256\times 256$) and a specific orientation
+
−(e.g. the first pixel is at the patient's anterior, right side). 
+
−
+
−By setting the icv property \verb+MI_ICV_DO_DIM_CONV+ to \verb+TRUE+
+
−these conversions can be done automatically. The orientation of
+
−spatial axes is determined by the properties \verb+MI_ICV_XDIM_DIR+,
+
−\verb+MI_ICV_YDIM_DIR+ and \verb+MI_ICV_ZDIM_DIR+. These affect any
+
−image dimensions that are \verb+MI?space+ or \verb+MI?frequency+ where
+
−\verb+?+ corresponds to \verb+x+, \verb+y+ or \verb+z+. These
+
−properties can have values \verb+MI_ICV_POSITIVE+,
+
−\verb+MI_ICV_NEGATIVE+ or \verb+MI_ICV_ANYDIR+. The last of these will
+
−prevent flipping of the dimension. The first two will flip the
+
−dimension if necessary so that the attribute \verb+MIstep+ of the
+
−dimension variable will have the correct sign.
+
−
+
−The two image dimensions are referred to as dimensions A and B.
+
−Dimension A is the fastest varying dimension of the two. Setting
+
−properties \verb+MI_ICV_ADIM_SIZE+ and \verb+MI_ICV_BDIM_SIZE+ specify
+
−the desired size for the image dimension. Dimensions are resized so
+
−that the file image will fit entirely in the calling program's image,
+
−and is centred in the image. The size \verb+MI_ICV_ANYSIZE+ allows
+
−one of the dimensions to have a variable size. If property
+
−\verb+MI_ICV_KEEP_ASPECT+ is set to \verb+TRUE+, then the two
+
−dimensions are rescaled by the same amount. It is possible to inquire
+
−about the new step and start, corresponding to attributes
+
−\verb+MIstep+ and \verb+MIstart+ (where pixel position = ipixel*step +
+
−start, with ipixel counting from zero). The properties
+
−\verb+MI_ICV_?DIM_STEP+ and \verb+MI_ICV_?DIM_START+ (\verb+?+ =
+
−\verb+A+ or \verb+B+) are set automatically and can be inquired but
+
−not set.
+
−
+
−Although vector images are allowed, many applications would rather
+
−only deal with scalar images (one intensity value at each point).
+
−Setting \verb+MI_ICV_DO_SCALAR+ to \verb+TRUE+ (the default) will
+
−cause vector images to be converted to scalar images by averaging the
+
−components.  (Thus, RGB images are automatically converted to
+
−gray-scale images in this simple way).
+
−
+
−It can sometimes be useful for a program to perform dimension
+
−conversions on three (or perhaps more) dimensions, not just the two
+
−standard image dimensions. To perform dimension flipping and/or
+
−resizing on dimensions beyond the usual two, the property
+
−\verb+MI_ICV_NUM_IMGDIMS+ can be set to an integer value between
+
−one and \verb+MI_MAX_IMGDIMS+. To set the size of a dimension,
+
−set the property \verb+MI_ICV_DIM_SIZE+ (analogous to
+
−\verb+MI_ICV_ADIM_SIZE+). To specify the dimension to be set, add
+
−the dimension to the property (adding zero corresponds to the fastest
+
−varying dimension --- add zero for the ``A'' dimension, one for the
+
−``B'' dimension, etc.). Voxel separation and
+
−location can be inquired about through the properties
+
−\verb+MI_ICV_DIM_STEP+ and \verb+MI_ICV_DIM_START+ (analogous to
+
−\verb+MI_ICV_ADIM_STEP+ and \verb+MI_ICV_ADIM_START+), again
+
−adding the dimension number to the property.
+
−
+
−\subsubsection{Example: Reading with dimension conversion}
+
−
+
−Reading a $256 \times 256$ image with the first pixel at the patient's
+
−inferior, posterior, left side as short values between 0 and 32000:
+
−\begin{verbatim}
+
−   /* Create the icv */
+
−   icv=miicv_create();
+
−   (void) miicv_setint(icv, MI_ICV_TYPE, NC_SHORT);
+
−   (void) miicv_setstr(icv, MI_ICV_SIGN, MI_UNSIGNED);
+
−   (void) miicv_setint(icv, MI_ICV_VALID_MAX, 32000);
+
−   (void) miicv_setint(icv, MI_ICV_VALID_MIN, 0);
+
−   (void) miicv_setint(icv, MI_ICV_DO_DIM_CONV, TRUE);
+
−   (void) miicv_setint(icv, MI_ICV_ADIM_SIZE, 256);
+
−   (void) miicv_setint(icv, MI_ICV_BDIM_SIZE, 256);
+
−   (void) miicv_setint(icv, MI_ICV_KEEP_ASPECT, TRUE);
+
−   (void) miicv_setint(icv, MI_ICV_XDIM_DIR, MI_POSITIVE);
+
−   (void) miicv_setint(icv, MI_ICV_YDIM_DIR, MI_POSITIVE);
+
−   (void) miicv_setint(icv, MI_ICV_ZDIM_DIR, MI_POSITIVE);
+
−
+
−   /* Open the file, attach the image variable */
+
−   cdfid=ncopen(filename, NC_NOWRITE);
+
−
+
−   /* Attach image variable */
+
−   img=ncvarid(cdfid, MIimage);
+
−   (void) miicv_attach(icv, cdfid, img);
+
−
+
−   /* Get the data - we assume that coord and count are set properly */
+
−   (void) miicv_get(icv, coord, count, image);
+
−
+
−   /* Close the file and free the icv */
+
−   (void) ncclose(cdfid);
+
−   (void) miicv_free(icv);
+
−\end{verbatim}
+
−
+
−
+
−\end{document}
+
−