changeset 1727:b51409a84f23

Include some explanation and examples about hyperslab I/O
author bert <bert>
date Tue, 20 Apr 2004 21:01:03 +0000
parents 9a0cc0b7e9ed
children b13c4d6050ed
files libsrc2/doc/minc2_uguide.tex
diffstat 1 files changed, 83 insertions(+), 2 deletions(-) [+]
line wrap: on
line diff
--- a/libsrc2/doc/minc2_uguide.tex
+++ b/libsrc2/doc/minc2_uguide.tex
@@ -1,7 +1,7 @@
 \documentclass{article}
 
 \usepackage{times}
-
+\renewcommand{\ttdefault}{cmtt}
 \title{MINC 2.0 User's Guide}
 \author{John G. Sled \\
 Robert D. Vincent \\
@@ -616,6 +616,88 @@
 chunks than in individual voxels, so if speed is important to your
 application it is best to avoid use of the single-voxel functions.
 
+\subsection{Specifying coordinates and lengths}
+All hyperslab operations require the programmer to specify the origin
+and size of the hyperslab.  These parameters as passed as arrays.  The
+{\tt start[]} (sometimes called {\tt voxel\_offsets[]} array
+specifies the origin of the hyperslab.  It can be thought of as the
+point closest to the true origin (0,0,0) in voxel dimensions.  The
+{\tt count[]} (sometimes called {\tt sizes[]} array specifies the length
+of the desired hyperslab along each dimension.
+
+Logically, none of the values of the {\tt count[]} array should ever be
+zero, since that would produce an overall hyperslab volume of zero.  In other
+words, you would read no data.
+
+Another constraint is that the {\tt start} value plus the {\tt count} value
+must always be less than or equal to the length of the dimension in voxels.
+
+Each of the voxel read/write functions assumes that the coordinates
+and lengths specified in the {\tt start[]} and {\tt count[]}
+arrays are in the ``apparent'' order.  By default the apparent order
+is the same as the file order.
+
+By way of an contrived example, suppose you have a four-dimensional
+file structured according to the dimensions {\tt xspace},{\tt
+time},{\tt zspace},{\tt yspace} with their respective lengths set to
+X, T, Z, and Y.
+
+We use {\tt miset\_apparent\_dimension\_order\_by\_name} to assign a 
+more conventional order to these dimensions:
+\begin{verbatim}
+static char *dimorder[] = { "time", "zspace","yspace","xspace" }
+
+miset_apparent_dimension_order_by_name(hvolume, 4, dimorder);
+
+\end{verbatim}
+
+Now suppose we want to read the entire file in one operation.  To do
+this, we might set up the following:
+\begin{verbatim}
+unsigned long start[4], count[4];
+short buffer[T][Z][Y][X];
+
+start[0] = start[1] = start[2] = start[3] = 0;
+count[0] = T;
+count[1] = Z;
+count[2] = Y;
+count[3] = X;
+
+miget_voxel_value_hyperslab(hvolume, MI_TYPE_SHORT, start, count, buffer);
+\end{verbatim}
+
+Alternatively, we might just want to read the data from one time location
+into a three-dimensional array:
+\begin{verbatim}
+unsigned long start[4], count[4];
+short buffer[Z][Y][X];
+
+start[0] = t;                   /* The desired time value */
+start[1] = start[2] = start[3] = 0;
+count[0] = 1;
+count[1] = Z;
+count[2] = Y;
+count[3] = X;
+
+miget_voxel_value_hyperslab(hvolume, MI_TYPE_SHORT, start, count, buffer);
+\end{verbatim}
+
+Another possibility would be to read the entire timecourse of a specific
+spatial location:
+\begin{verbatim}
+unsigned long start[4], count[4];
+short buffer[T];
+
+start[0] = 0;                   /* Start at time=0 */
+start[1] = z;                   /* z,y,x = spatial coordinate */
+start[2] = y;                   
+start[3] = x;
+count[0] = T;
+count[1] = count[2] = count[3] = 1;
+
+miget_voxel_value_hyperslab(hvolume, MI_TYPE_SHORT, start, count, buffer);
+\end{verbatim}
+
 \subsection{Details of voxel conversion}
 Conversion from real to voxel data, or from voxel to real data, can
 be expressed by the following relationships:
@@ -744,7 +826,6 @@
 real voxel values greater than or equal to {\tt max} will be mapped to the
 largest possible value of the data type.
 
-
 \section{Volume creation}
 After all the required dimension handles are defined/assigned with their appropriate 
 class and attribute, the MINC 2.0 file can be created by calling the following: