/**
 * \file minc2_api.h
 * MINC2 API FUNCTION DECLARATIONS
 **/

#ifndef MINC2_API_H
#define MINC2_API_H

#ifdef __cplusplus
extern "C" {               /* Hey, Mr. Compiler - this is "C" code! */
#endif /* __cplusplus defined */


/** \defgroup mi2Group ATTRIBUTE/GROUP FUNCTIONS */

/** Start listing the objects in a group.
 * \ingroup mi2Group
 */
int milist_start(mihandle_t vol, const char *path, int flags,
                        milisthandle_t *handle);

/** Iterate through attributes
 * \ingroup mi2Group
 */
int milist_attr_next(mihandle_t vol, milisthandle_t handle, 
                            char *path, int maxpath,
                            char *name, int maxname);

/** Finish listing attributes or groups
 * \ingroup mi2Group
 */
int milist_finish(milisthandle_t handle);

/** Get the group at given path
 * \ingroup mi2Group
 */
int milist_grp_next(milisthandle_t handle, char *path, int maxpath);

/** Create a group at "path" using "name".
 * \ingroup mi2Group
 */
int micreate_group(mihandle_t vol, const char *path, const char *name);

/** Delete the named attribute.
 * \ingroup mi2Group
 */
int midelete_attr(mihandle_t vol, const char *path, const char *name);

/** Delete the subgroup \a name from the group \a path
 * \ingroup mi2Group
 */
int midelete_group(mihandle_t vol, const char *path, const char *name);

/**
 * Returns the length in bytes of the attribute \a name in the
 * group or dataset at \a path. For strings, this length will reflect
 * the number of characters actually stored, which may not include the
 * terminating null character.
 * \ingroup mi2Group
 */
int miget_attr_length(mihandle_t vol, const char *path, 
                             const char *name, size_t *length);

/** Get the type of an attribute.
 * \ingroup mi2Group
 */
int miget_attr_type(mihandle_t vol, const char *path, const char *name,
                           mitype_t *data_type);

/** Copy all attribute given a path
 * \ingroup mi2Group
 */
int micopy_attr(mihandle_t vol, const char *path, mihandle_t new_vol);

/** Get the values of an attribute.
 * Note: for MI_TYPE_STRING data_type, the length and values buffer
 * should include space for the null termination.
 * \ingroup mi2Group
 */
int miget_attr_values(mihandle_t vol, mitype_t data_type,
                             const char *path, const char *name, 
                             size_t length, void *values);

/** Set the values of an attribute.
 * \ingroup mi2Group
 */
int miset_attr_values(mihandle_t vol, mitype_t data_type,
                             const char *path, const char *name, size_t length,
                             const void *values);

/** Add global history attribute
 * \ingroup mi2Group
 */
int miadd_history_attr(mihandle_t vol, size_t length, const void *values);

/** \defgroup mi2Memory FREE FUNCTIONS */

/**
 * Free space allocated for string storage by a MINC function.
 * \param name_ptr A pointer to the space to be freed.
 * \ingroup mi2Memory
 */
int mifree_name(char *name_ptr);

/**
 * Free list of names
 * not certain we really need this...
 * \ingroup mi2Memory
*/
int mifree_names(char **name_pptr);

/** \defgroup mi2DataType DATA TYPE/SPACE FUNCTIONS */

/** Return the data class of a volume (See miclass_t).
 * \ingroup mi2DataType
 */
int miget_data_class(mihandle_t vol, miclass_t *volume_class);

/** Return the data type of a volume (See mitype_t).
 * \ingroup mi2DataType
 */
int miget_data_type(mihandle_t vol, mitype_t *volume_data_type);

/** Return the byte size of the voxel datatype
 * \ingroup mi2DataType
 */
int miget_data_type_size(mihandle_t vol, misize_t *voxel_size);

/** Return the minc space type, name should be freed after use
 * \ingroup mi2DataType
 */
int miget_space_name(mihandle_t vol, char **name);

/**
 * Set minc space type
 * \ingroup mi2DataType
 */
int miset_space_name(mihandle_t vol, const char *name);

/** \ingroup mi2Dim DIMENSION FUNCTIONS */

/**
  * Figure out whether a dimension is associated with a volume.
  * \param dimension The dimension handle.
  * \param volume    A pointer to the volume handle.
  *
  * This method returns the volume handle associated with a given dimension
  * or an error if the specified handle is not associated with the volume.
  * \ingroup mi2Dim
  */
int miget_volume_from_dimension(midimhandle_t dimension, mihandle_t *volume);

/**
  * Create a copy of a given dimension.
  * \param dim_ptr The dimension handle of the dimension to copy.
  * \param new_dim_ptr A pointer to the dimension handle of the copied dimension.
  *
  * This method creates a copy of the specified dimension and returns the handle
  * to the copied dimension or error on failure.
  * \ingroup mi2Dim
 */
int micopy_dimension(midimhandle_t dim_ptr, midimhandle_t *new_dim_ptr);

/**
  * Define a new dimension in a MINC volume.
  * \param name A pointer to the string specifying the dimension name.
  * \param dimclass The class of the dimension.
  * \param attr  The attribute of the dimension.
  * \param length The size of the dimension.
  * \param new_dim_ptr A pointer to the dimension handle.
  *
  * This function defines a dimension that can be used in the definition
  * of a new MINC volume (see the create_volume function).  The name may
  * be an arbitrary string of up to 128 alphanumeric characters. Any of
  * the "standard" names retained from MINC 1.0 retain their default
  * behaviors: MIxspace, MIyspace, and MIzspace default to spatial
  * dimensions, and MItime default to be a time dimension.  MItfrequency
  * is a temporal frequency axis, and MIxfrequency, MIyfrequency, and
  * MIzfrequency are spatial frequency axes.  Any other name may be used.
  *
  * When initially defined, a regularly-sampled dimension will have a
  * "start" value of zero, and a "separation" or "step" value of 1.0.  An
  * irregular dimension will be initialized with all offsets equal to
  * zero.
  *
  * The size of the dimension may range from 0 to 2^32, which should provide
  * enough range to represent detail on the order of 10 Angstroms in
  * typical medical imaging applications.
  *
  * For the detailed definition of \a class and \a type refer to the MINC 2.0 API
  * definition.
  * \ingroup mi2Dim
  */
int micreate_dimension(const char *name, midimclass_t dimclass, midimattr_t attr, 
                              misize_t length, midimhandle_t *new_dim_ptr);

/**
  * Delete the dimension definition.
  * \param dim_ptr The dimension handle.
  *
  * Note: The original document stated that a dimension has to be
  * associated with a given volume before it can be deleted. This
  * feature was erased from the document and not considered here.
  * \ingroup mi2Dim
  */
int mifree_dimension_handle(midimhandle_t dim_ptr);

/** Retrieve the list of dimensions defined in a MINC volume,
 * with the same class \a class and attribute \a attr.
 * \param volume The volume handle.
 * \param dimclass  The class of the dimensions.
 * \param attr   The attribute of the dimensions.
 * \param order  The order of the dimension (file or apparent).
 * \param array_length The number of dimension to be retrieved.
 * \param dimensions An array of dimension handles to be retrieved.
 *
 * This function is used to retrieve an array of dimension handles for a
 * MINC volume.  It will place the handles of the first "array_length"
 * dimensions into the "dimensions[]" array, returning only those dimension
 * whose characteristics match the "class" and "attr" parameters.
 * The miorder_t is an enumerated type flag which determines whether the
 * dimension order is determined by the file or by the apparent order set by
 * the user. This function will fail if the user has not set the apparent
 * dimension order by calling either of
 * (miset_apparent_dimension_order(_by_name))
 * before calling this function with MI_DIMORDER_APPARENT flag.
 * \ingroup mi2Dim
 */
int miget_volume_dimensions(mihandle_t volume, midimclass_t dimclass, midimattr_t attr,
                                   miorder_t order, int array_length, 
                                   midimhandle_t dimensions[]);


/**
 * Set apparent dimension order, based on an array of dimensions.  You
 * may also set the dimension order by the name of the dimension, see
 * miset_apparent_dimension_order_by_name().
 * \param volume The volume handle.
 * \param array_length The number of dimensions to be sorted.
 * \param dimensions An "ordered" array of dimension handles.
 *
 * This method sets an apparent dimension order. The user can sort the
 * dimensions in any desired order. If the user specifies fewer dimensions
 * than the existing ones, then they are assumed to be added to the last.
 * \ingroup mi2Dim
 */
int miset_apparent_dimension_order(mihandle_t volume, int array_length, midimhandle_t dimensions[]);


/**
  * Set apparent dimension order by name.
  * \param volume The volume handle.
  * \param array_length The number of dimensions to be sorted.
  * \param names An "ordered" array of dimension names.
  *
  * This method sets an apparent dimension order by dimension name. Note that
  * all dimension names must be different or an error occurs.
  * \ingroup mi2Dim
  */
int miset_apparent_dimension_order_by_name(mihandle_t volume, int array_length, char **names);


/**
  *Set the record flag and add a record dimension to the volume
  * dimensions so the volume would appear to have an extra dimension.
  * \param volume The volume handle.
  * \param record_flag The flag to determine whether there exist a record dimension
  * in the volume.
  *
  * This method causes a volume to appear to have a record dimension. The record
  * dimension will be set to uniform and flat (i.e., the volume will appear to have
  * an extra dimension)
 * \ingroup mi2Dim
 */
int miset_apparent_record_dimension_flag(mihandle_t volume, int record_flag);


/**
  * Get the apparent order of voxels (i.e., the order that voxel indices increase/decrease)
  * \param dimension The dimension handle
  * \param file_order The order of voxels.
  * \param sign The sign of the step value.
  *
  * This method gets the apparent order of voxels for the specified dimension
  * and the sign of the step values.
  * \ingroup mi2Dim
  */
int miget_dimension_apparent_voxel_order(midimhandle_t dimension, miflipping_t *file_order,
                                                miflipping_t *sign);

/**
 * Set the apparent order of voxels.
 * \param dimension The dimension handle.
 * \param flipping_order The order of voxels.
 *
 * This method sets the apparent order of voxels for the specified dimension.
 * For the detailed description of voxel order refer to the MINC 2.0 API definition.
 * \ingroup mi2Dim
 */
int miset_dimension_apparent_voxel_order(midimhandle_t dimension, miflipping_t flipping_order);


/**
 * Get the class of a MINC dimension.
 * \param dimension The dimension handle.
 * \param dimclass A pointer to the dimension class.
 *
 * The "class" of a MINC dimension defines the general type of a dimension,
 * whether it is a spatial dimension, a time dimension, or a frequency dimension
 * as transformed from either space or time.  User-defined dimension are also
 * permitted, with no default handling assumed. Finally, a record can be specified
 * as a dimension.
 * \ingroup mi2Dim
 */
int miget_dimension_class(midimhandle_t dimension, midimclass_t *dimclass);


/**
  * Set the class of a MINC dimension.
  * \param dimension The dimension handle.
  * \param dimclass The dimension class.
  *
  * Refer to miget_dimension_class().
  * \ingroup mi2Dim
  */
int miset_dimension_class(midimhandle_t dimension, midimclass_t dimclass);


/**
  * Get the direction cosine vector of a given SPATIAL dimension.
  * \param dimension The dimension handle.
  * \param direction_cosines An array of direction_cosines(i.e., vector determining the direction cosine).
  *
  * Spatial dimension in MINC volumes may be associated with a vector of direction
  * cosines which define the precise orientation of the axis relative to "true"
  * x, y, or z coordinates.
  * \ingroup mi2Dim
  */
int miget_dimension_cosines(midimhandle_t dimension, 
                                   double direction_cosines[3]);

/**
  * Set the direction cosine vector for a given SPATIAL dimension.
  * \param dimension The dimension handle.
  * \param direction_cosines An array of direction_cosines(i.e., vector determining the direction cosine).
  *
  * Refer to miget_dimension_cosines().
  * \ingroup mi2Dim
  */
int miset_dimension_cosines(midimhandle_t dimension, 
                                   const double direction_cosines[3]);

/**
  * Set the comments attribute for a given dimension.
  * \param dimension The dimension handle.
  * \param comments A pointer for the comments.
  *
  * Refer to miget_dimension_description().
  * \ingroup mi2Dim
  */
int miset_dimension_description(midimhandle_t dimension, const char *comments);


/**
 * Get the comments attribute for a given dimension.
 * \param dimension The dimension handle.
 * \param comments_ptr A string pointer for the comments.
 *
 * Get and Set the dimension description. Note that the spatial dimensions
 * (xspace, yspace, zspace) are initialized according to minc1 description.
 * All other dimensions will have an empty description unless set by the user.
 * The string pointer returned in \a *comments_ptr must be freed by the caller.
 * \ingroup mi2Dim
 */
int miget_dimension_description(midimhandle_t dimension, char **comments_ptr);


/**
  * Get the identifier (name) of a MINC dimension.
  * \param dimension The dimension handle.
  * \param name_ptr A string pointer for returning the dimension name.
  *
  * Retrieves the name of the given dimension.
  * \ingroup mi2Dim
  */
int miget_dimension_name(midimhandle_t dimension, char **name_ptr);


/**
 * Set the identifier (name) of a given MINC dimension.
 * \param dimension The dimension handle.
 * \param name A pointer for the dimension name.
 *
 * Rename the given dimension.
 * \ingroup mi2Dim
 */
int miset_dimension_name(midimhandle_t dimension, const char *name);

/**
  * Get the untransformed world coordinates of points along a MINC dimension.
  * \param dimension The dimension handle.
  * \param array_length The number of dimensions.
  * \param start_position The position in which to retrieve the offsets.
  * \param offsets The array of offsets to be returned.
  *
  * Get or Set the dimension offsets, that is, the
  * absolute world coordinates of each sampled point along the dimension.
  *
  * The caller may retrieve up to "array_length" values, starting at the
  * integer index "start_position".  Thus an arbitrary contiguous subset
  * of the dimension's offsets may be retrieved or stored.  An error is
  * returned if the "start_position" exceeds the total size of the
  * dimension.  If the value of "start_position" is legal, but the sum of
  * "start_position" and "array_length" exceeds the size of the dimension,
  * the function will get or set offsets up to the size of the dimension.
  * Any extra positions in the offsets[] array will be ignored.
  * \ingroup mi2Dim
  */
int miget_dimension_offsets(midimhandle_t dimension, misize_t array_length, 
                                   misize_t start_position, double offsets[]);

/**
  * Set the absolute world coordinates of points along a MINC dimension.
  * \param dimension The dimension handle.
  * \param array_length The number of dimensions.
  * \param start_position The position in which to retrieve the offsets.
  * \param offsets The array of offsets to be set.
  *
  * Refer to miget_dimension_offsets().
  * \ingroup mi2Dim
  */
int miset_dimension_offsets(midimhandle_t dimension, misize_t array_length, 
                                   misize_t start_position, const double offsets[]);

/**
  * Get the sampling flag for a MINC dimension.
  * \param dimension The dimension handle.
  * \param sampling_flag The flag to determine regular/irregular sampling dimensions.
  *
  * This flag is true (non-zero) if the dimension is sampled at regular
  * intervals, and false if the dimension is sampled irregularly.
  * If a dimension has regular sampling, the miget_dimension_separation()
  * may be used to retrieve the sampling interval, and the
  * miget_dimension_start() may be used to retrieve the origin
  * value along the axis.
  *
  * If a dimension has irregular sampling, the miget_dimension_offsets()
  * may be used to retrieve the positions of each sample along that axis.
  * \ingroup mi2Dim
  */
int miget_dimension_sampling_flag(midimhandle_t dimension, miboolean_t *sampling_flag);


/**
  * Set the sampling flag for a MINC dimension.
  * \param dimension The dimension handle.
  * \param sampling_flag The flag to determine regular/irregular sampling dimensions.
  *
  * Refer to miget_dimension_sampling_flag().
  * \ingroup mi2Dim
  */
int miset_dimension_sampling_flag(midimhandle_t dimension, miboolean_t sampling_flag);


/**
 * Get the constant sampling interval (step) for a single dimension.
 * \param dimension The dimension handle.
 * \param voxel_order The order in which the voxel indices increase/decrease.
 * \param separation_ptr The Pointer to the dimension sampling interval (step).
 *
 * Gets or sets the constant sampling interval defined on a regularly-sampled
 * dimension. While it is legal to call these functions for an irregularly-
 * sampled dimension, the values will be ignored.
 * \ingroup mi2Dim
 */
int miget_dimension_separation(midimhandle_t dimension, 
                                      mivoxel_order_t voxel_order, 
                                      double *separation_ptr);


/**
  * Set the sampling interval (step) for a single dimension.
  * \param dimension The dimension handle.
  * \param separation The dimension sampling interval (step).
  *
  * Refer to miget_dimension_separation().
  * \ingroup mi2Dim
  */
int miset_dimension_separation(midimhandle_t dimension, 
                                      double separation);

/**
  * Get the sampling interval (STEP) for a list of dimensions.
  * \param dimensions An array of dimension handles.
  * \param voxel_order The order in which the voxel indices increase/decrease.
  * \param array_length The number of dimensions in the dimensions array.
  * \param separations An array of dimensions sampling intervals (step) values.
  *
  * Get or Set the scalar separation (sampling interval)
  * associated with each of the dimensions in the input "dimensions[]"
  * array.  The "array_length" parameter specifies the size of both the
  * input and output arrays. While it is legal to call these functions for
  * an irregularly-sampled dimension, the values will be ignored.
  * \ingroup mi2Dim
  */
int miget_dimension_separations(const midimhandle_t dimensions[], 
                                       mivoxel_order_t voxel_order, 
                                       misize_t array_length, 
                                       double separations[]);


/**
  * Set the sampling interval (STEP) for a list of dimensions.
  * \param dimensions An array of dimension handles.
  * \param array_length The number of dimensions in the dimensions array.
  * \param separations An array of dimensions sampling intervals (step) values.
  *
  * Refer to miget_dimension_separations().
  * \ingroup mi2Dim
  */
int miset_dimension_separations(const midimhandle_t dimensions[], misize_t array_length,
                                       const double separations[]);

/**
  * Get the length of a MINC dimension.
  * \param dimension The dimension handle.
  * \param size_ptr A pointer to the dimension size.
  *
  * Get or Set the size (or length) of a MINC 2 dimension
  * object used in creating a new volume.  The size of a dimension
  * associated with an existing volume cannot be changed.
  * \ingroup mi2Dim
  */
int miget_dimension_size(midimhandle_t dimension, misize_t *size_ptr);

/**
  * Set the length of a MINC dimension if not associated with a volume.
  * \param dimension The dimension handle.
  * \param size  The size of the dimension.
  *
  * Refer to miget_dimension_size().
  * \ingroup mi2Dim
  */
int miset_dimension_size(midimhandle_t dimension, misize_t size);


/**
  * Retrieve the length of all dimensions in dimensions array.
  * \param dimensions An array of dimension handles.
  * \param array_length The number of dimensions in the dimensions array
  * \param sizes An array of dimension sizes.
  *
  * This function will copy the lengths of each of the dimensions listed in the
  * "dimensions[]" array into the "sizes[]" array.  The parameter "array_length"
  * specifies the length of both of the arrays.
  * \ingroup mi2Dim
  */
int miget_dimension_sizes(const midimhandle_t dimensions[], misize_t array_length,
                                misize_t sizes[]);

/**
  * Get the start value of a MINC dimension.
  * \param dimension The dimension handle.
  * \param voxel_order The order in which the voxel indices increase/decrease.
  * \param start_ptr A pointer to the start value.
  *
  * Get or set the origin of the dimension in world
  * coordinates. While a "start" value may be legally associated with any
  * dimension, it is considered meaningless when associated with an
  * irregularly sampled dimension.
  * \ingroup mi2Dim
  */
int miget_dimension_start(midimhandle_t dimension, 
                          mivoxel_order_t voxel_order,
                          double *start_ptr);

/** 
  * Set the start of a MINC dimension.
  * \param dimension The dimension handle.
  * \param start_ptr The start of the dimension.
  *
  * Refer to miget_dimension_start().
  * \ingroup mi2Dim
  */
int miset_dimension_start(midimhandle_t dimension, double start_ptr);

/**
  * Get the start values for MINC dimensions in dimensions array.
  * \param dimensions The array of dimension handles.
  * \param voxel_order The order in which the voxel indices increase/decrease.
  * \param array_length The number of dimensions in the dimensions array.
  * \param starts The array of dimension starts.
  *
  * Get or Set the start value for an array of
  * regularly-sampled dimensions.  The start value defines the origin of
  * that dimension.  While it is legal to call these functions for an
  * irregularly-sampled dimension, the values will be ignored.
  * \ingroup mi2Dim
  */
int miget_dimension_starts(const midimhandle_t dimensions[], mivoxel_order_t voxel_order,
                                  misize_t array_length, double starts[]);

/**
  * Set the start values for MINC dimensions in dimensions array.
  * \param dimensions The array of dimension handles.
  * \param array_length The number of dimensions in the dimensions array.
  * \param starts The array of dimension starts.
  *
  * Refer to miget_dimension_starts().
  * \ingroup mi2Dim
  */
int miset_dimension_starts(const midimhandle_t dimensions[], misize_t array_length, 
                                  const double starts[]);

/**
  * Get the unit string for a MINC dimension.
  * \param dimension The dimension handle.
  * \param units_ptr A string pointer to the dimension units.
  *
  * Retrieves the units of the given dimension,
  * The caller must free the string returned by this function.
  * \ingroup mi2Dim
  */
int miget_dimension_units(midimhandle_t dimension, char **units_ptr);

/**
 * Set the unit string for a MINC dimension.
 * \param dimension The dimension handle.
 * \param units A pointer to the dimension units.
 *
 * Set the units for an existing dimension.
 * The new string must be no greater than 128 characters in length,
 * including the trailing zero byte.
 * \ingroup mi2Dim
 */
int miset_dimension_units(midimhandle_t dimension, const char *units);

/**
  * Get A single full-width half-maximum value from a
  * regularly sampled dimension.
  * \param dimension The dimension handle.
  * \param width_ptr A pointer to the FWHM value.
  *
  * Get or Set the dimension width, that is, the
  * full-width half-maximum values of each sampled point along the dimension.
  * These functions are used to set a constant width for regularly-sampled
  * dimensions.
  * \ingroup mi2Dim
  */
int miget_dimension_width(midimhandle_t dimension, double *width_ptr);

/**
  * Set the A single full-width half-maximum value for a
  * regularly sampled dimension.
  * \param dimension The dimension handle.
  * \param width_ptr The FWHM value.
  *
  * Refer to miget_dimension_width().
  * \ingroup mi2Dim
  */
int miset_dimension_width(midimhandle_t dimension, double width_ptr);

/**
  * Get the full-width half-maximum value for points along an
  * irregularly sampled dimension.
  * \param dimension The dimension handle.
  * \param voxel_order The order in which the voxel indices increase/decrease.
  * \param array_length The number of width in the widths array.
  * \param start_position Index for starting position.
  * \param widths An array of width values to be retrieved.
  *
  * Get or Set the dimension widths, that is, the
  * full-width half-maximum values of each sampled point along the
  * dimension.
  * The caller may retrieve up to "array_length" values, starting at the
  * integer index "start_position".  Thus an arbitrary contiguous subset
  * of the dimension's widths may be retrieved or stored.  An error is
  * returned if the "start_position" exceeds the total size of the
  * dimension.  If the value of "start_position" is legal, but the sum of
  * "start_position" and "array_length" exceeds the size of the dimension,
  * the function will get or set widths up to the size of the dimension.
  * Any extra positions in the widths[] array will be ignored.
  * \ingroup mi2Dim
  */
int miget_dimension_widths(midimhandle_t dimension, mivoxel_order_t voxel_order,
                                  misize_t array_length, misize_t start_position,
                                  double widths[]);


/**
  * Set the full-width half-maximum value for points along an
  * irregularly sampled dimension.
  * \param dimension The dimension handle.
  * \param array_length The number of width in the widths array.
  * \param start_position Index for starting position.
  * \param widths An array of width values to be set.
  *
  * Refer to miget_dimension_widths().
  * \ingroup mi2Dim
  */
int miset_dimension_widths(midimhandle_t dimension, misize_t array_length,
                                  misize_t start_position, const double widths[]);


/* VOLUME FUNCTIONS */
/** Create a volume with the specified name, dimensions,
    type, class, volume properties and retrieve the volume handle.
    \ingroup mi2Vol
*/
int micreate_volume(const char *filename, 
                           int number_of_dimensions,
                           midimhandle_t dimensions[],
                           mitype_t volume_type,
                           miclass_t volume_class,
                           mivolumeprops_t create_props,
                           mihandle_t *volume);

/** Create the actual image for the volume.
  * Note that the image dataset muct be created in the hierarchy
  * before the image data can be added.
  * \ingroup mi2Vol
*/
int micreate_volume_image(mihandle_t volume);


/** Return the number of dimensions associated with this volume.
  * \ingroup mi2Vol
*/
int miget_volume_dimension_count(mihandle_t volume, midimclass_t dimclass,
                                        midimattr_t attr, int *number_of_dimensions);

/** Return the number of slice dimensions associated with this volume.
 *  it's only useful for slice normalization
 *  will return the total number of volume dimensions if slice normalization is not used
 * \ingroup mi2Vol
*/
int miget_slice_dimension_count(mihandle_t volume, midimclass_t dimclass,
                                        midimattr_t attr, int *number_of_dimensions);

/** Returns the number of voxels in the volume.
  * \ingroup mi2Vol
*/
int miget_volume_voxel_count(mihandle_t volume, misize_t *number_of_voxels);

/** Opens an existing MINC volume for read-only access if mode argument is
  * MI2_OPEN_READ, or read-write access if mode argument is MI2_OPEN_RDWR.
  * \ingroup mi2Vol
*/
int miopen_volume(const char *filename, int mode, mihandle_t *volume);


/** Close an existing MINC volume. If the volume was newly created,
  *  all changes will be written to disk. In all cases this function closes
  *  the open volume and frees memory associated with the volume handle.
  *  \ingroup mi2Vol
*/
int miclose_volume(mihandle_t volume);

/** Function to get the volume's slice-scaling flag.
 */
int miget_slice_scaling_flag(mihandle_t volume, 
                                    miboolean_t *slice_scaling_flag);

/** Function to set the volume's slice-scaling flag.
 */
int miset_slice_scaling_flag(mihandle_t volume, 
                                    miboolean_t slice_scaling_flag);

/** \defgroup mi2VPrp VOLUME PROPERTIES FUNCTIONS */

/** Create a volume property list.  The new list will be returned in the
 * \a props parameter.    When the program is finished 
 * using the property list it should call  mifree_volume_props() to free the
 * memory associated with the list.
 * \param props A pointer to the returned volume properties handle.
 * \ingroup mi2VPrp
 */
int minew_volume_props(mivolumeprops_t *props);

/** Destroy a volume property list.
 * \param props The volume property list to delete.
 * \ingroup mi2VPrp
 */
int mifree_volume_props(mivolumeprops_t props);

/** Get a copy of the volume property list.  When the program is finished 
 * using the property list it should call  mifree_volume_props() to free the
 * memory associated with the list.
 * \param vol A volume handle
 * \param props A pointer to the returned volume properties handle.
 * \ingroup mi2VPrp
 */
int miget_volume_props(mihandle_t vol, mivolumeprops_t *props);


/** Set multi-resolution properties.  The \a enable_flag determines
 * whether or not thumbnail images will be calculated at all.  The \a
 * depth parameter determines the lowest-resolution image that will be
 * available.  The full resolution image is considered to be image #0,
 * the half resolution image is image #1, the quarter-resolution image
 * is #2, etc. Therefore a \a depth value of 2 implies both the half
 * and quarter resolution thumbnails will be calculated and stored in
 * the file.
 * \param props A volume property list handle 
 * \param enable_flag TRUE if multiresolution support should be enabled in
 * this file.  
 * \param depth The maximum depth of multiresolution data
 * to support.
 * \ingroup mi2VPrp
 */
int miset_props_multi_resolution(mivolumeprops_t props, miboolean_t enable_flag, 
                                        int depth);

/** Get multi-resolution properties.  Returns the value of the \a enable_flag
 * and \a depth parameters.
 * \param props A volume property list handle
 * \param enable_flag Pointer to a boolean which will be set to TRUE if 
 * multiresolution has been enabled.
 * \param depth Pointer to a integer which will contain the maximum resolution
 * depth enabled if multiresolution is enabled.
 * \ingroup mi2VPrp
 */
int miget_props_multi_resolution(mivolumeprops_t props, miboolean_t *enable_flag,
                                        int *depth);


/** Select a different resolution from a multi-resolution image.
 * \ingroup mi2VPrp
 */
int miselect_resolution(mihandle_t volume, int depth);


/** Compute or recompute all resolution groups.
 * 
 * \ingroup mi2VPrp
 */
int miflush_from_resolution(mihandle_t volume, int depth);


/** Set compression type for a volume property list
 * Note that enabling compression will automatically 
 * enable blocking with default parameters. 
 * \param props A volume properties list
 * \param compression_type The type of compression to use (MI_COMPRESS_NONE
 * or MI_COMPRESS_ZLIB)
 * \ingroup mi2VPrp
 */
int miset_props_compression_type(mivolumeprops_t props, micompression_t compression_type);


/** Get compression type for a volume property list
 * \param props A volume property list handle
 * \param compression_type A pointer to a variable to which the current
 * compression type will be assigned.
 * \ingroup mi2VPrp
 */
int miget_props_compression_type(mivolumeprops_t props, micompression_t *compression_type);


/** Set zlib compression properties for a volume list.  The \a zlib_level
 * parameter may range from 1 to 9, where higher numbers request that the
 * library attempt to use more memory (and possibly processing power) to
 * achieve the highest possible compression ratio.
 *
 * \param props A volume property list handle
 * \param zlib_level An integer specifying the desired compression level.
 * \ingroup mi2VPrp
 */
int miset_props_zlib_compression(mivolumeprops_t props, int zlib_level);


/** Get zlib compression properties from a volume property list.
 * \param props A volume property list handle
 * \param zlib_level Pointer to an integer variable that will receive the
 * current compression level.
 * \ingroup mi2VPrp
 */
int miget_props_zlib_compression(mivolumeprops_t props, int *zlib_level);


/** Set blocking structure properties for the volume
 * \param props A volume property list handle
 * \param edge_count The number of edges (dimensions) in a block
 * \param edge_lengths The lengths of the edges
 * \ingroup mi2VPrp
 */
int miset_props_blocking(mivolumeprops_t props, int edge_count, const int *edge_lengths);


/** Get blocking structure properties for the volume
 * \param props The properties structure from which to get the information
 * \param edge_count Returns the number of edges (dimensions) in a block
 * \param edge_lengths The lengths of the edges
 * \param max_lengths The number of elements of the edge_lengths array
 * \ingroup mi2VPrp
 */
int miget_props_blocking(mivolumeprops_t props, int *edge_count, int *edge_lengths,
                                int max_lengths);




/** Set checksumming for volume
 * \param on A volume property list handle
 * \ingroup mi2VPrp
 */
int miset_props_checksum(mivolumeprops_t props, int on);


/** Get checksumming for volume
 * \ingroup mi2VPrp
 */
int miget_props_checksum(mivolumeprops_t props, int *on);



/** Set properties for uniform/nonuniform record dimension
 * \ingroup mi2VPrp
 */
int miset_props_record(mivolumeprops_t props, misize_t record_length, char *record_name); 


/** Set the template volume flag
 * \ingroup mi2VPrp
 */ 
int miset_props_template(mivolumeprops_t props, int template_flag);

/** \defgroup mi2Slice SLICE/VOLUME SCALE FUNCTIONS */
/**
 * This function sets \a slice_max to the maximum real value of
 * voxels in the slice containing the coordinates \a start_positions.
 * The \a array_length may be less than or equal to the number of dimensions
 * in the volume, extra coordinates will be ignored.  Specifying too few
 * coordinates will trigger an error.
 * Coordinates must always be specified in raw file order.
 * \ingroup mi2Slice
 */
int miget_slice_max(mihandle_t volume, 
                           const misize_t start_positions[],
                           size_t array_length, double *slice_max);

/**
 * This function sets minimum real value of
 * values in the slice containing the coordinates \a start_positions.
 * The \a array_length may be less than or equal to the number of dimensions
 * in the volume, extra coordinates will be ignored.  Specifying too few
 * coordinates will trigger an error.
 * Coordinates must always be specified in raw file order.
 * \ingroup mi2Slice
 */
int miset_slice_max(mihandle_t volume, 
                           const misize_t start_positions[],
                           size_t array_length, double slice_max);


/**
 * This function sets \a slice_min to the minimum real value of
 * voxels in the slice containing the coordinates \a start_positions.
 * The \a array_length may be less than or equal to the number of dimensions
 * in the volume, extra coordinates will be ignored.  Specifying too few
 * coordinates will trigger an error.
 * Coordinates must always be specified in raw file order.
 * \ingroup mi2Slice
 */
int miget_slice_min(mihandle_t volume, 
                           const misize_t start_positions[],
                           size_t array_length, double *slice_min);


/**
 * This function sets minimum real value of
 * values in the slice containing the coordinates \a start_positions.
 * The \a array_length may be less than or equal to the number of dimensions
 * in the volume, extra coordinates will be ignored.  Specifying too few
 * coordinates will trigger an error.
 * Coordinates must always be specified in raw file order.
 * \ingroup mi2Slice
 */
int miset_slice_min(mihandle_t volume, 
                           const misize_t start_positions[],
                           size_t array_length, double slice_min);


/**
 * This function gets both the minimum and
 * maximum real value of voxels in the slice containing the coordinates
 * \a start_positions.  The \a array_length may be less than or equal to
 * the number of dimensions in the volume, extra coordinates will be
 * ignored.  Specifying too few coordinates will trigger an error.
 * Coordinates must always be specified in raw file order.
 * \ingroup mi2Slice
 */
int miget_slice_range(mihandle_t volume,
                             const misize_t start_positions[],
                             size_t array_length, double *slice_max,
                             double *slice_min);


/**
 * This function the minimum and maximum real value of voxels in the
 * slice containing the coordinates \a start_positions.  The \a
 * array_length may be less than or equal to the number of dimensions in
 * the volume, extra coordinates will be ignored.  Specifying too few
 * coordinates will trigger an error.  Coordinates must always be
 * specified in raw file order.
 * \ingroup mi2Slice
 */
int miset_slice_range(mihandle_t volume, 
                             const misize_t start_positions[],
                             size_t array_length, double slice_max,
                             double slice_min);

/**
 * This function returns the maximum real value of
 * voxels in the entire \a volume.  If per-slice scaling is enabled, this
 * function will return an error.
 * \ingroup mi2Slice
 */
int miget_volume_max(mihandle_t volume, double *slice_max);


/**
 * This function sets the maximum real value of
 * voxels in the entire \a volume.  If per-slice scaling is enabled, this
 * function will return an error.
 * \ingroup mi2Slice
 */
int miset_volume_max(mihandle_t volume, double slice_max);


/**
 * This function returns the minimum real value of
 * voxels in the entire \a volume.  If per-slice scaling is enabled, this
 * function will return an error.
 * \ingroup mi2Slice
 */
int miget_volume_min(mihandle_t volume, double *slice_min);


/**
 * This function sets the minimum real value of
 * voxels in the entire \a volume.  If per-slice scaling is enabled, this
 * function will return an error.
 * \ingroup mi2Slice
 */
int miset_volume_min(mihandle_t volume, double slice_min);


/**
 * This function retrieves the maximum and minimum real values of
 * voxels in the entire \a volume.  If per-slice scaling is enabled, this
 * function will return an error.
 * \ingroup mi2Slice
 */
int miget_volume_range(mihandle_t volume, double *volume_max, 
                              double *volume_min);

/**
 * This function sets the maximum and minimum real values of
 * voxels in the entire \a volume.  If per-slice scaling is enabled, this
 * function will return an error.
 * \ingroup mi2Slice
 */
int miset_volume_range(mihandle_t volume, double volume_max, 
                              double volume_min);


/** \defgroup mi2Hyper HYPERSLAB FUNCTIONS */

/** Calculates and returns the number of bytes required to store the
 * hyperslab specified by the \a n_dimensions and the
 * \a count parameters.
 * \ingroup mi2Hyper
 */
int miget_hyperslab_size(mitype_t volume_data_type, int n_dimensions, 
                                const hsize_t count[], 
                                misize_t *size_ptr);


/** Calculates and returns the number of bytes required to store the
 * hyperslab specified by the \a n_dimensions and the
 * \a count parameters, using hdf type id
 * \ingroup mi2Hyper
 */
void miget_hyperslab_size_hdf(hid_t hdf_type_id, int n_dimensions, 
                                const hsize_t count[], 
                                misize_t *size_ptr);


/** Reads the real values in the volume from the interval min through
 *  max, mapped to the maximum representable range for the requested
 *  data type. Float types is mapped to 0.0 1.0
 * \ingroup mi2Hyper
 */
int miget_hyperslab_normalized(mihandle_t volume, 
                                      mitype_t buffer_data_type,
                                      const misize_t start[], 
                                      const misize_t count[],
                                      double min, 
                                      double max, 
                                      void *buffer);

/** Writes the real values in the volume from the interval min through
 *  max, mapped to the maximum representable range for the requested
 *  data type. Float types is mapped to 0.0 1.0
 * \ingroup mi2Hyper
 */
int miset_hyperslab_normalized(mihandle_t volume, 
                                      mitype_t buffer_data_type,
                                      const misize_t start[], 
                                      const misize_t count[],
                                      double min, 
                                      double max, 
                                      void *buffer);

/** Get a hyperslab from the file, 
 * converting voxel values into real values
 * \ingroup mi2Hyper
 */
int miget_hyperslab_with_icv(mihandle_t volume, 
                                    mitype_t buffer_data_type, 
                                    const misize_t start[], 
                                    const misize_t count[], 
                                    void *buffer);

/** Write a hyperslab to the file, converting real values into voxel values
 * \ingroup mi2Hyper
 */
int miset_hyperslab_with_icv(mihandle_t volume,
                                    mitype_t buffer_data_type, 
                                    const misize_t start[],
                                    const misize_t count[],
                                    void *buffer);

/** Read a hyperslab from the file into the preallocated buffer,
 *  converting from the stored "voxel" data range to the desired
 * "real" (float or double) data range, same as miget_hyperslab_with_icv
 * \ingroup mi2Hyper
 */
int miget_real_value_hyperslab(mihandle_t volume,
                                      mitype_t buffer_data_type,
                                      const misize_t start[],
                                      const misize_t count[],
                                      void *buffer);

/** Write a hyperslab to the file from the preallocated buffer,
 *  converting from the stored "voxel" data range to the desired
 * "real" (float or double) data range, same as miset_hyperslab_with_icv
 * \ingroup mi2Hyper
 */
int miset_real_value_hyperslab(mihandle_t volume,
                                      mitype_t buffer_data_type,
                                      const misize_t start[],
                                      const misize_t count[],
                                      void *buffer);

/** Read a hyperslab from the file into the preallocated buffer,
 * with no range conversions or normalization.  Type conversions will
 * be performed if necessary.
 * \ingroup mi2Hyper
 */
int miget_voxel_value_hyperslab(mihandle_t volume,
                                       mitype_t buffer_data_type,
                                       const misize_t start[],
                                       const misize_t count[],
                                       void *buffer);

/** Write a hyperslab to the file from the preallocated buffer,
 * with no range conversions or normalization.  Type conversions will
 * be performed if necessary.
 * \ingroup mi2Hyper
 */
int miset_voxel_value_hyperslab(mihandle_t volume,
                                       mitype_t buffer_data_type,
                                       const misize_t start[],
                                       const misize_t count[],
                                       void *buffer);


/** \defgroup mi2Cvt CONVERT FUNCTIONS */

/** Convert values between real (scaled) values and voxel (unscaled)
 * values.  The voxel value is the unscaled value, and corresponds to the
 * value actually stored in the file, whereas the "real" value is the
 * value at the given location after scaling has been applied.
 * 
 * The \a coords parameter specifies the location at which the
 * conversion is performed.  This is needed because MINC supports
 * per-slice scaling, therefore a conversion performed at one location
 * may differ from that performed at another location.
 *
 * \param volume A volume handle
 * \param coords The position for which to perform the conversion.
 * \param ncoords The length of the \a coords array.
 * \param real_value The original real value, to be converted to voxel.
 * \param voxel_value_ptr A pointer to the converted voxel value.
 * \ingroup mi2Cvt
 */
int miconvert_real_to_voxel(mihandle_t volume,
                                   const misize_t coords[],
                                   size_t ncoords,
                                   double real_value,
                                   double *voxel_value_ptr);

/** Convert values between real (scaled) values and voxel (unscaled)
 * values.  The voxel value is the unscaled value, and corresponds to the
 * value actually stored in the file, whereas the "real" value is the
 * value at the given location after scaling has been applied.
 *
 * The \a coords parameter specifies the location at which the
 * conversion is performed.  This is needed because MINC supports
 * per-slice scaling, therefore a conversion performed at one location
 * may differ from that performed at another location. 
 *
 * \param volume A volume handle
 * \param coords The position for which to perform the conversion.
 * \param ncoords The length of the \a coords array.
 * \param voxel_value The original voxel value, to be converted to real.
 * \param real_value_ptr A pointer to the converted real value.
 * \ingroup mi2Cvt
 */
int miconvert_voxel_to_real(mihandle_t volume,
                                   const misize_t coords[],
                                   int ncoords,
                                   double voxel_value,
                                   double *real_value_ptr);

/** Converts an N-dimensional spatial position in voxel coordinates into a 
 * 3-dimensional spatial position in world coordinates.
 *
 * The returned world coordinate vector is in a standardized order, with
 * the X position first (at index 0), followed by the Y and Z coordinates.
 * The voxel coordinate vector is in the native order appropriate to the
 * file.
 *
 * \ingroup mi2Cvt
 */
int miconvert_voxel_to_world(mihandle_t volume,
                                    const double voxel[],
                                    double world[MI2_3D]);

/** Converts a 3-dimensional spatial position in world coordinates into a 
 * N-dimensional spatial position in voxel coordinates.
 *
 * The input world coordinate vector is in a standardized order, with
 * the X position first (at index 0), followed by the Y and Z coordinates.
 * The voxel coordinate vector is in the native order appropriate to the
 * file.
 *
 * \ingroup mi2Cvt
 */
int miconvert_world_to_voxel(mihandle_t volume,
                                    const double world[MI2_3D],
                                    double voxel[]);

/**
 * This function calculates the start values for the volume dimensions,
 * assuming that the spatial origin is relocated to the given world
 * coordinate.
 *
 * \ingroup mi2Cvt
 */
int
miconvert_world_origin_to_start( mihandle_t volume,
                                 double world[3],
                                 double starts[3]);

/**
 * This function calculates the start values for the volume dimensions,
 * assuming that the spatial origin is relocated to the given world
 * coordinate.
 *
 * \ingroup mi2Cvt
 */
int
miconvert_spatial_frequency_origin_to_start( mihandle_t volume,
                                             double world[3],
                                             double starts[3]);

/**
 * This function sets the world coordinates of the point (0,0,0) in voxel
 * coordinates.  This changes the constant offset of the two coordinate
 * systems.
 *
 * \ingroup mi2Cvt
 */
int
miset_spatial_frequency_origin(mihandle_t volume,
                               double world[3]);

/** This function retrieves the real values of a position in the
 *  MINC volume.  The "real" value is the value at the given location 
 *  after scaling has been applied.
 *
 * \param volume A volume handle
 * \param coords The voxel position to retrieve
 * \param ndims The number of values in the \a coords array
 * \param value_ptr Pointer to a double variable to hold the returned value.
 *
 * \ingroup mi2Cvt
 */
int miget_real_value(mihandle_t volume,
                            const misize_t coords[],
                            int ndims,
                            double *value_ptr);

/** This function sets the  real value of a position in the MINC
 *  volume. The "real" value is the value at the given location 
 *  after scaling has been applied.
 *
 * \param volume A volume handle
 * \param coords The voxel position to retrieve
 * \param ndims The number of values in the \a coords array
 * \param value The value to save at this location.
 *
 * \ingroup mi2Cvt
 */
int miset_real_value(mihandle_t volume,
                            const misize_t coords[],
                            int ndims,
                            double value);


/** This function retrieves the voxel values of a position in the
 * MINC volume. The voxel value is the unscaled value, and corresponds
 * to the value actually stored in the file.
 *
 * \ingroup mi2Cvt
 */
int miget_voxel_value(mihandle_t volume,
                             const misize_t coords[],
                             int ndims,
                             double *voxel_ptr);


/** This function sets the voxel value of a position in the MINC
 * volume.  The voxel value is the unscaled value, and corresponds to the
 * value actually stored in the file.
 *
 * \ingroup mi2Cvt
 */
int miset_voxel_value(mihandle_t volume,
                             const misize_t coords[],
                             int ndims,
                             double voxel);

/** Get the absolute minimum and maximum values of a volume.
 *
 * \ingroup mi2Cvt
 */
int miget_volume_real_range(mihandle_t volume, double real_range[2]);

/**
 * This function sets the world coordinates of the point (0,0,0) in voxel
 * coordinates.  This changes the constant offset of the two coordinate
 * systems.
 *
 * \ingroup mi2Cvt
 */
int miset_world_origin(mihandle_t volume, double origin[MI2_3D]);

/* VALID functions */
/** This function gets the maximum valid value specific to the data
 *  type of the \a volume parameter.
 * \retval MI_ERROR on failure
 * \retval MI_NOERROR on success
 */
int miget_volume_valid_max(mihandle_t volume, double *valid_max);

/** This function sets the maximum valid value specific to the data
 *  type of the \a volume parameter.
 * \retval MI_ERROR on failure
 * \retval MI_NOERROR on success
 */
int miset_volume_valid_max(mihandle_t volume, double valid_max);

/** This function gets the minimum valid value specific to the data
 *  type of the \a volume parameter.
 * \retval MI_ERROR on failure
 * \retval MI_NOERROR on success
 */
int miget_volume_valid_min(mihandle_t volume, double *valid_min);

/** This function sets the minimum valid value specific to the data
 *  type of the \a volume parameter.
 * \retval MI_ERROR on failure
 * \retval MI_NOERROR on success
 */
int miset_volume_valid_min(mihandle_t volume, double valid_min);

/** This function gets the minimum and maximum valid value specific to the 
 * data type of the \a volume parameter.
 * \retval MI_ERROR on failure
 * \retval MI_NOERROR on success
 */
int miget_volume_valid_range(mihandle_t volume, double *valid_max, double *valid_min);

/** This function sets the minimum and maximum valid value specific to the 
 * data type of the \a volume parameter.
 * \retval MI_ERROR on failure
 * \retval MI_NOERROR on success
 */
int miset_volume_valid_range(mihandle_t volume, double valid_max, double valid_min);

/** \defgroup mi2Rec RECORD functions */
/** This method gets the name of the record dimension
 * TODO: set record name??
 * \ingroup mi2Rec
 */
int miget_record_name(mihandle_t volume, char **name);

/** This method gets the length (i.e., number of fields in the case of
 * uniform records and number of bytes for non_uniform ones) of the
 * record.
 * \ingroup mi2Rec
 */
int miget_record_length(mihandle_t volume, int *length);

/** This method returns the field name for the given field index.  Memory
 * for returned string is allocated on the heap and should be released using
 * mifree_name().
 * \ingroup mi2Rec
 */
int miget_record_field_name(mihandle_t volume, int index, char **name);

/** This method sets a field name for the volume record. The volume
 * must be of class "MI_CLASS_UNIFORM_RECORD".  The size of record
 * type will be increased if necessary to accommodate the new field.
 * \ingroup mi2Rec
 */
int miset_record_field_name(mihandle_t volume, int index, 
                                   const char *name);

/** \ingroup mi2Label LABEL functions */

/**
 * This function associates a label name with an integer value for the given
 * volume. Functions which read and write voxel values will read/write 
 * in integer values, and must call miget_label_name() to discover the 
 * descriptive text string which corresponds to the integer value.
 * \ingroup mi2Label
 */
int midefine_label(mihandle_t volume, int value, const char *name);

/**
 * For a labelled volume, this function retrieves the text name
 * associated with a given integer value.
 * 
 * The name pointer returned must be freed by calling mifree_name().
 * \ingroup mi2Label
*/
int miget_label_name(mihandle_t volume, int value, char **name);

/**
 * This function is the inverse of miget_label_name(). It is called to determine
 * what integer value, if any, corresponds to the given text string.
 * \ingroup mi2Label
*/
int miget_label_value(mihandle_t volume, const char *name, int *value);


/**
 * This function returns the number of defined labels, if any, or zero.
 * \ingroup mi2Label
*/
int miget_number_of_defined_labels(mihandle_t volume, int *number_of_labels);

/**
 * This function returns the label value associated with an index (0,1,...)
 * \ingroup mi2Label
*/
int miget_label_value_by_index(mihandle_t volume, int idx, int *value);

#ifdef __cplusplus
}
#endif /* __cplusplus defined */


#endif /*MINC2_API_H*/
// kate: indent-mode cstyle; indent-width 2; replace-tabs on;