MINC/SoftwareDevelopment/MINC2.0 Application Programmers Interface

MINC 2.0 Application Programming Interface (API) An Introduction to HDF5 (For a complete description, see the HDF5 User's Guide at http://hdf.ncsa.uiuc.edu/ ). ATTRIBUTE/GROUP FUNCTIONS (11) micreate_group NAME micreate_group - create a new group SYNOPSIS #include <minc2.h> int micreate_group ( mihandle_t volume, const char *path, const char *name) DESCRIPTION This method creates a new empty group with the specified path and name. RETURN VALUE micreate_group returns MI_NOERROR if it successfully creates a group or MI_ERROR otherwise midelete_attr NAME midelete_attr - delete the attribute given its name SYNOPSIS #include <minc2.h> int midelete_attr ( mihandle_t volume, const char *path, const char *name) DESCRIPTION This methods deletes the attribute with the specified name. It also clears memory and releases handles. RETURN VALUE midelete_attr returns MI_NOERROR if it successfully deletes the attribute or MI_ERROR otherwise midelete_group NAME midelete_group - delete an existing group SYNOPSIS #include <minc2.h> int midelete_group ( mihandle_t volume, const char *path, const char *name) DESCRIPTION This method deletes the group with the given group name. RETURN VALUE midelete_group returns MI_NOERROR if it successfully deletes a group or MI_ERROR otherwise miget_attr_length NAME miget_attr_length - get the length of an attribute SYNOPSIS #include <minc2.h> int miget_attr_length ( mihandle_t volume, const char *path, const char *name, int *length ) DESCRIPTION This method gets the length of the given attribute name. RETURN VALUE miget_attr_length returns MI_NOERROR if it successfully gets the dimension of a given attribute name or MI_ERROR otherwise miget_attr_type NAME miget_attr_type - get the data type of the attribute SYNOPSIS #include <minc2.h> int miget_attr_type ( mihandle_t volume, const char *path, const char *name, mitype_t *attr_data_type) DESCRIPTION This method gets the data_type the given attribute name. For the definition of mitype_t see miget_data_type(). RETURN VALUE miget_attr_type returns MI_NOERROR if it successfully gets the data type of a given attribute name or MI_ERROR otherwise In the initial implementation, attributes are restricted to type of either MI_TYPE_DOUBLE or MI_TYPE_CHAR. miget_attr_values NAME miget_attr_values - get the value(s) of an attribute SYNOPSIS #include <minc2.h> int miget_attr_values ( mihandle_t volume, mitype_t attr_data_type, const char *path, const char *name, int length, void *values) DESCRIPTION This method returns the values of a given attribute name (of type double or string) in array "values". RETURN VALUE miget_attr_values returns MI_NOERROR if it successfully gets the attribute value(s) or MI_ERROR otherwise miset_attr_values NAME miset_attr_values - set the value(s) of the attribute SYNOPSIS #include <minc2.h> int miset_attr_values ( mihandle_t volume, mitype_t attr_data_type, const char *path, const char *name, int length, void *values) DESCRIPTION This method sets the value(s) of type double or string for the specified attribute name. If the attribute does not exist, it will be created. RETURN VALUE miset_attr_values returns MI_NOERROR if it successfully sets the attribute value(s) or MI_ERROR otherwise micopy_attr NAME micopy_attr - copy the list of attributes specified by their path to another minc file SYNOPSIS #include <minc2.h> int micopy_attr (mihandle_t volume, const char *path, mihandle_t new_volume) DESCRIPTION This function is meant to copy all the attributes from a specified (dataset) --> path to another volume hear information. It recursively finds all the attributes (non-standard) and copies them one by one. It comes in handy in cases where you create an image from an existing image and do not wish to lose any information supplied with the minc header. RETURN VALUE micopy_attr returns MI_NOERROR if it successfully gets the attribute(s) and copies them to the new volume or MI_ERROR otherwise milist_start NAME milist_start - get list of attributes or groups starting at given path SYNOPSIS #include <minc2.h> int milist_start ( mihandle_t volume, const char *path, int flags, milisthandle_t *handle) DESCRIPTION This function begins listing the attributes or groups in the given path. If the flags argument includes MILIST_RECURSE, then all of the paths subgroups will be searched and their attributes or groups will be listed as well. The path string should always end with a slash ("/") character. The returned handle is used to pass to milist_attr_next() for attributes or milist_grp_next() for groups and milist_finish() to actually perform the listing operation. RETURN VALUE milist_start returns MI_NOERROR if it successfully gets the attribute(s) or group(s) or MI_ERROR otherwise milist_attr_next NAME milist_attr_next - get the attributes at given path SYNOPSIS #include <minc2.h> int milist_attr_next ( milisthandle_t handle, char *path, int maxpath char *name, int maxname) DESCRIPTION This function returns each of the attributes associated with the listing initiated by a call to milist_attr_start(). Each successive call of the milist_attr_next() function returns the next attribute's path and name in the corresponding string buffers. When all possible attributes have been returned, the function returns an error. The maxpath and maxname parameters are used to set the maximum length of the two string buffers. If the listing operation is not recursive, the path parameter will always have length zero (the empty string). RETURN VALUE milist_attr_next returns MI_NOERROR if it successfully gets the attribute name or MI_ERROR otherwise milist_grp_next NAME milist_grp_next - get the group(s) at given path SYNOPSIS #include <minc2.h> int milist_grp_next ( milisthandle_t handle, char *path, int maxpath) DESCRIPTION This function returns each of the groups associated with the listing initiated by a call to milist_start(). Each successive call to milist_grp_next() returns the next group's path in the corresponding string buffer. When all possible groups have been returned, the function returns an error. RETURN VALUE milist_grp_next returns MI_NOERROR if it successfully gets the group(s) name or MI_ERROR otherwise milist_finish NAME milist_finish - finish listing attributes or groups SYNOPSIS #include <minc2.h> int milist_finish (milisthandle_t handle) DESCRIPTION Finishes the attribute or groups listing process, and frees any memory associated with the handle. RETURN VALUE milist_finish() returns MI_NOERROR if it completes successfully, or MI_ERROR otherwise. miadd_history_attr NAME miadd_history_attr - add the history string to minc2 attribute history SYNOPSIS #include <minc2.h> int miadd_history_attr (mihandle_t vol,int length, const void *values) DESCRIPTION Add history "string" to the minc2 attribute "history" located under group /minc-2.0 in the minc2 header RETURN VALUE miadd_history_attr() returns MI_NOERROR if it completes successfully, or MI_ERROR otherwise. DATA TYPE/SPACE FUNCTIONS (5) miget_data_class NAME miget_data_class - get the class type of data SYNOPSIS #include <minc2.h> int miget_data_class ( mihandle_t volume, miclass_t *volume_class) DESCRIPTION volume_class is the interpretation of the numerical values of the volume independent of the numerical type used to represent the data. The class type is defined as follows. tyepdef enum { MI_CLASS_REAL = 0, MI_CLASS_INT = 1, MI_CLASS_LABEL = 2, MI_CLASS_COMPLEX = 3, MI_CLASS_UNIFORM_RECORD = 4, MI_CLASS_NON_UNIFORM_RECORD = 5 } miclass_t; where MI_CLASS_LABEL is used for enumerated data in which a description is associated with each value and MI_CLASS_RECORD is used for aggregate datatypes consisting of multiple values. RETURN VALUE miget_data_class returns the data class of the volume or MI_ERROR if an error occurs. miget_data_type NAME miget_data_type - get the volume's data type SYNOPSIS #include <minc2.h> int miget_data_type( mihandle_t volume, mitype_t *volume_data_type) DESCRIPTION miget_data_type gets the date-type of the volume, which in this case refers to the actual format in which the data is stored on disk. Note that volume of type string is not supported. The mitype_t type is defined as follows: typedef enum { MI_TYPE_BYTE = 1, /* 8-bit signed integer */ MI_TYPE_SHORT = 3, /* 16-bit signed integer */ MI_TYPE_INT = 4, /* 32-bit signed integer */ MI_TYPE_FLOAT = 5, /* 32-bit floating point */ MI_TYPE_DOUBLE = 6, /* 64-bit floating point */ MI_TYPE_STRING = 7, /* ASCII string */ MI_TYPE_UBYTE = 100, /* 8-bit unsigned integer */ MI_TYPE_USHORT = 101, /* 16-bit unsigned integer */ MI_TYPE_UINT = 102, /* 32-bit unsigned integer */ MI_TYPE_SCOMPLEX = 1000, /* 16-bit signed integer complex */ MI_TYPE_ICOMPLEX = 1001, /* 32-bit signed integer complex */ MI_TYPE_FCOMPLEX = 1002, /* 32-bit floating point complex */ MI_TYPE_DCOMPLEX = 1003, /* 64-bit floating point complex */ MI_TYPE_UNKNOWN = -1 /* when the type is a non_uniform record */ } mitype_t; typedef struct { short real; short imag; } miscomplex_t; typedef struct { int real; int imag; } miicomplex_t; typedef struct { float real; float imag; } mifcomplex_t; typedef struct { double real; double imag; } midcomplex_t; RETURN VALUE miget_data_type returns the data-type of the volume or MI_ERROR if an error occurs. miget_data_type_size NAME miget_data_type_size - get the size of an individual voxel in a MINC volume SYNOPSIS #include <minc2.h> int miget_data_type_size( mihandle_t volume, misize_t *voxel_size); DESCRIPTION This function retrieves the size, in bytes, of the "native" voxel data type of the volume. RETURN VALUE Returns MI_ERROR on error (invalid volume handle, for example), or MI_NOERROR on success. miget_space_name/miset_space_name NAME miget_space_name, miset_space_name - get or set the space type name for a MINC volume SYNOPSIS #include <minc2.h> int miget_space_name( mihandle_t volume, char **name ); int miset_space_name( mihandle_t volume, const char *name ); DESCRIPTION miget_space_name retrieves the "space" name of the given volume, returning a pointer to a string. The memory allocated by this function should be released with a call to mifree_name(). miset_space_name will set the space name of the volume. The new name must be no greater than 128 characters in length, including the trailing zero byte. Space names are used to define the coordinate system of the volume. Three standard values are defined by MINC: MI_NATIVE "native____" MI_TALAIRACH "talairach_" MI_CALLOSAL "callosal__" "Native" space specifies the coordinate system of a particular scanner. Talairach and callosal are standard coordinate systems for brain images. If not explicitly set, the space will be type MI_NATIVE by default. RETURN VALUE miget_space_name returns the length of the name retrieved, including the terminating zero byte. miset_space_name will return MI_NOERROR on success. Both functions return MI_ERROR if an error occurs. SEE ALSO mifree_name DIMENSION FUNCTIONS (39) miget_volume_from_dimension NAME miget_volume_from_dimension - to figure out whether a dimensions is associated with a volume or not SYNOPSIS #include <minc2.h> int miget_volume_from_dimension ( midimhandle_t dimension, mihandle_t *volume) DESCRIPTION This method returns the volume handle associated with a given dimension. RETURN VALUE miget_volume_from_dimension returns MI_ERROR if the specified handle is not associated with the volume and MI_NOERROR otherwise. micopy_dimension NAME micopy_dimension - create copy of the given dimension SYNOPSIS #include <minc2.h> int micopy_dimension ( midimhandle_t dim_ptr, midimhandle_t *new_dim_ptr) DESCRIPTION Creates a copy of the specified dimension and returns the handle to the copy RETURN VALUE micopy_dimension returns MI_NOERROR if it successfully copies all the attributes of the provided dimension and MI_ERROR otherwise micreate_dimension NAME micreate_dimension - define a new dimension in a MINC volume SYNOPSIS #include <minc2.h> int micreate_dimension ( const char *name, midimclass_t class, midimattr_t attr, unsigned int size, midimhandle_t *new_dim_ptr); DESCRIPTION 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 type midimclass_t is defined as follows: typedef enum { MI_DIMCLASS_ANY = 0, /* Don't care (or unknown) */ MI_DIMCLASS_SPATIAL = 1, /* Space */ MI_DIMCLASS_TIME = 2, /* Time */ MI_DIMCLASS_SFREQUENCY = 3, /* Spatial frequency */ MI_DIMCLASS_TFREQUENCY = 4, /* Temporal frequency */ MI_DIMCLASS_USER = 5, /* Arbitrary user-defined axis */ MI_DIMCLASS_FLAT_RECORD = 6 /* Record as dimension */ } midimclass_t; The type midimattr_t is a bit field of dimension attributes, defined as follows: typedef unsigned int midimattr_t; #define MI_DIMATTR_ALL 0 #define MI_DIMATTR_REGULARLY_SAMPLED 0x1 #define MI_DIMATTR_NOT_REGULARLY_SAMPLED 0x2 The "size" argument 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. If successful, the function will return a handle to the newly-defined dimension in the location specified by "new_dim_ptr". RETURN VALUE micreate_dimension returns MI_NOERROR on success, MI_ERROR on failure. mifree_dimension_handle NAME mifree_dimension_handle - delete the dimension definition associated with the given handle SYNOPSIS #include <minc2.h> int mifree_dimension_handle ( midimhandle_t dim_ptr) DESCRIPTION Deletes the dimension definition (i.e., dimension handle and dimension itself) only if the dimension is NOT associated with a volume. RETURN VALUE mifree_dimension_handle returns MI_NOERROR if it successfully deletes a dimension or MI_ERROR otherwise. miget_volume_dimensions NAME miget_volume_dimensions - retrieve the list of dimensions defined in a MINC volume, according to their class and attribute. SYNOPSIS #include <minc2.h> int miget_volume_dimensions ( mihandle_t volume, midimclass_t class, midimattr_t attr, miorder_t order, int array_length, midimhandle_t dimensions[]); DESCRIPTION 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() or miset_apparent_dimension_order_by_name() before calling this function with MI_DIMORDER_APPARENT flag The following example will return up to 3 spatial dimensions: int result; midimhandle_t dimensions[3]; mihandle_t volume; result = miget_vol_dimensions (volume, MI_DIMCLASS_SPATIAL, MI_DIMATTR_ALL, MI_DIMORDER_FILE, 3, dimensions); RETURN VALUE miget_volume_dimensions returns the number of dimension handles copied to the array, or MI_ERROR on failure. SEE ALSO miset_apparent_dimension_order, miset_apparent_dimension_order_by_name miset_apparent_dimension_order NAME miset_apparent_dimension_order - set apparent dimension order SYNOPSIS #include <minc2.h> int miset_apparent_dimension_order ( mihandle_t volume, int array_length, midimhandle_t dimensions[]) DESCRIPTION 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. For example, given (z,y,x) for the file dimension order of (x,y,z,t) will result in (t,z,y,x) and so on. RETURN VALUE miset_apparent_dimension_order returns MI_NOERROR if it successfully sets the apparent dimension order or MI_ERROR otherwise SEE ALSO miset_apparent_dimension_order_by_name miset_apparent_dimension_order_by_name NAME miset_apparent_dimension_order_by_name - set apparent dimension order by name SYNOPSIS #include <minc2.h> int miset_apparent_dimension_order_by_name ( mihandle_t volume, int array_length, char **names) DESCRIPTION This method sets an apparent dimension order by dimension name. Note that all dimension names must be different or an error occurs. RETURN VALUE miset_apparent_dimension_order_by_name returns MI_NOERROR if it successfully sets the apparent dimension order by name or MI_ERROR otherwise miset_apparent_record_dimension_flag NAME miset_apparent_record_dimension_flag - set the record flag SYNOPSIS #include <minc2.h> int miset_apparent_record_dimension_flag ( mihandle_t volume, int flatten_flag) DESCRIPTION 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 have one more dimension (n+1)). RETURN VALUE miset_apparent_record_dimension_flag sets a flat uniform_record dimension to a volume and returns MI_NOERROR or MI_ERROR otherwise. miget_dimension_apparent_voxel_order NAME miget_dimension_apparent_voxel_order - gets the apparent order of voxels SYNOPSIS #include <minc2.h> int miget_dimension_apparent_voxel_order ( midimhandle_t dimension, miflipping_t *file_order, miflipping_t *sign) DESCRIPTION This method gets the apparent order of voxels for the specified dimension and the sign of the step values. RETURN VALUE miget_dimension_apparent_voxel_order returns MI_NOERROR if it successfully gets the apparent voxel order of the specified dimension or MI_ERROR otherwise miset_dimension_apparent_voxel_order NAME miset_dimension_apparent_voxel_order - sets the apparent order of voxels SYNOPSIS #include <minc2.h> int miset_dimension_apparent_voxel_order ( midimhandle_t dimension, miflipping_t flipping_order) DESCRIPTION This method sets the apparent order of voxels for the specified dimension. The miflipping_t is an enumerated type as follows: tyepdef enum { MI_FILE_ORDER = 0, /* no flip */ MI_COUNTER_FILE_ORDER = 1, /* flip */ MI_POSITIVE = 2, /* check step if positive -> no flip negative -> flip */ MI_NEGATIVE = 3 /* check step if positive -> flip negative -> no flip */ } miflipping_t; RETURN VALUE miset_dimension_apparent_voxel_order returns MI_NOERROR if it successfully sets the apparent voxel order of the specified dimension or MI_ERROR otherwise miget_dimension_class/miset_dimension_class NAME miget_dimension_class, miset_dimension_class - get or set the class of a MINC dimension. SYNOPSIS #include <minc2.h> int miget_dimension_class ( midimhandle_t dimension, midimclass_t *class ); int miset_dimension_class ( midimhandle_t dimension, midimclass_t class); DESCRIPTION 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. The definition of midimclass_t is as follows: typedef enum { MI_DIMCLASS_ANY = 0, /* Don't care (or unknown) */ MI_DIMCLASS_SPATIAL = 1, /* Space */ MI_DIMCLASS_TIME = 2, /* Time */ MI_DIMCLASS_SFREQUENCY = 3, /* Spatial frequency */ MI_DIMCLASS_TFREQUENCY = 4, /* Temporal frequency */ MI_DIMCLASS_USER = 5, /* Arbitrary user-defined axis */ MI_DIMCLASS_FLAT_RECORD = 6 /* Record as dimension */ } midimclass_t; While the MINC library does not enforce any particular semantics based upon dimension class, individual MINC programs may define default behaviors for certain classes of dimensions. RETURN VALUE Returns MI_NOERROR on success, or MI_ERROR on failure. miget_dimension_cosines/miset_dimension_cosines NAME miget_dimension_cosines, miset_dimension_cosines - Get or set the dimension's cosine vector. SYNOPSIS #include <minc2.h> int miget_dimension_cosines ( midimhandle_t dimension, double cosines[3]); int miset_dimension_cosines ( midimhandle_t dimension, const double cosines[3]); DESCRIPTION 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. The direction cosine vector always consists of exactly three values which correspond to the x, y, and z directions, respectively. This is true regardless of the ordering of dimensions in a specific volume or data object. Because of the direction cosines, it is possible for MINC volumes to define non-orthogonal dimensions. These functions fail if the dimension is not of the spatial class. RETURN VALUE Returns MI_NOERROR on success, or MI_ERROR on failure. miget_dimension_description/miset_dimension_description NAME miget_dimension_description, miset_dimension_description - Get or set the dimension's description. SYNOPSIS #include <minc2.h> int miget_dimension_description ( midimhandle_t dimension, char **comments_ptr); int miset_dimension_description ( midimhandle_t dimension, const char *comments); DESCRIPTION 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. RETURN VALUE Returns MI_NOERROR on success, or MI_ERROR on failure. miget_dimension_name/miset_dimension_name NAME miget_dimension_name, miset_dimension_name - get or set the identifier of a MINC dimension SYNOPSIS #include <minc2.h> int miget_dimension_name ( midimhandle_t dimension, char **name_ptr ); int miset_dimension_name ( midimhandle_t dimension, const char *name ); DESCRIPTION miget_dimension_name retrieves the name of the given dimension, allocating the space needed. The memory allocated by this function should be released with a call to mifree_name(). miset_dimension_name will rename an existing dimension. The new name must be no greater than 128 characters in length, including the trailing zero byte. RETURN VALUE miget_dimension_name returns the length of the name retrieved, including the terminating zero byte. miset_dimension_name will return MI_NOERROR on success. Both functions return MI_ERROR if an error occurs. SEE ALSO mifree_name miget_dimension_offsets/miset_dimension_offsets NAME miget_dimension_offsets, miset_dimension_offsets - get or set the absolute world coordinates of points along a MINC dimension SYNOPSIS #include <minc2.h> int miget_dimension_offsets ( midimhandle_t dimension, unsigned long array_length, unsigned long start_position, double offsets[]); int miset_dimension_offsets ( midimhandle_t dimension, unsigned long array_length, unsigned long start_position, const double offsets[]); DESCRIPTION These functions 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. It is explicitly legal to call this function for a regularly sampled dimension. The result will be a list of values calculated from the "start" and "separation" values of the dimension. However, it is not possible to set offsets on a regularly sampled dimension. RETURN VALUE Returns the number of offset values read or written , or MI_ERROR if an error is detected. miget_dimension_sampling_flag/miset_dimension_sampling_flag NAME miget_dimension_sampling_flag, miset_dimension_sampling_flag - get or set the sampling flag for a MINC dimension SYNOPSIS #include <minc2.h> int miget_dimension_sampling_flag ( midimhandle_t dimension, miboolean_t *sampling_flag); int miset_dimension_sampling_flag ( midimhandle_t dimension, miboolean_t sampling_flag); DESCRIPTION The miget_dimension_sampling flag function retrieves the value of the "sampling" flag for a given MINC dimension. This flag is false (zero) if the dimension is sampled at regular intervals, and true (non-zero) if the dimension is sampled irregularly. If a dimension has regular sampling, the miget_dimension_step function may be used to retrieve the sampling interval, and the miget_dimension_start function may be used to retrieve the origin value along the axis. If a dimension has irregular sampling, the miget_dimension_offsets function may be used to retrieve the positions of each sample along that axis. RETURN VALUE These functions returns MI_NOERROR on success, or MI_ERROR if an error is detected (for example, if a parameter is invalid). miget_dimension_separation/miset_dimension_separation NAME miget_dimension_separation, miset_dimension_separation - set/get the sampling interval for a single dimension SYNOPSIS #include <minc2.h> int miget_dimension_separation ( midimhandle_t dimension, mivoxel_order_t voxel_order, double *separation_ptr ); int miset_dimension_separation ( midimhandle_t dimension, double separation ); DESCRIPTION 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. The mivoxel_order_t is an enumerated type which is defined as follows typedef enum { MI_ORDER_FILE = 0, MI_ORDER_APPARENT = 1 } mivoxel_order_t; This flag specifies whether the voxel order is original from file or is an apparent one which can be the default (i.e., the same as the original file) or the order that is specified by the user. If not explicitly set, the separation will have a default value of one. RETURN VALUE Returns MI_NOERROR on success, or MI_ERROR on failure. SEE ALSO miget_dimension_separations, miset_dimension_separations miget_dimension_separations/miset_dimension_separations NAME miget_dimension_separations, miset_dimension_separations - get/set the sampling intervals for a list of dimensions. SYNOPSIS #include <minc2.h> int miget_dimension_separations ( const midimhandle_t dimensions[], mivoxel_order_t voxel_order, int array_length, double separations[] ); int miset_dimension_separations ( const midimhandle_t dimensions[], int array_length, const double separations[] ); DESCRIPTION These functions 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. RETURN VALUE Returns the number of separations copied to (or from) the array, or MI_ERROR if an error occurs. SEE ALSO miget_dimension_separation, miset_dimension_separation miget_dimension_size/miset_dimension_size NAME miget_dimension_size, miset_dimension_size - get or set the length of a MINC dimension SYNOPSIS #include <minc2.h> int miget_dimension_size ( midimhandle_t dimension, unsigned int *size_ptr ); int miset_dimension_size ( midimhandle_t dimension, unsigned int size ); DESCRIPTION These functions 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. One can, however, make a copy of an existing dimension and set the size of the copy. RETURN VALUE Returns MI_NOERROR on success, MI_ERROR on failure. miget_dimension_sizes NAME miget_dimension_sizes - retrieve the sizes of an array of dimension handles SYNOPSIS #include <minc2.h> int miget_dimension_sizes ( const midimhandle_t dimensions[], int array_length, unsigned int sizes[] ); DESCRIPTION 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. RETURN VALUE Returns MI_NOERROR on success, or MI_ERROR on failure. SEE ALSO miget_dimension_size, miset_dimension_size miget_dimension_start/miset_dimension_start NAME miget_dimension_start, miset_dimension_start - get or set the origin of a MINC dimension SYNOPSIS #include <minc2.h> int miget_dimension_start ( midimhandle_t dimension, mivoxel_order_t voxel_order, double *start_ptr); int miset_dimension_start ( midimhandle_t dimension, double start); DESCRIPTION These functions 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. RETURN VALUE Returns MI_NOERROR on success, or MI_ERROR on failure. miget_dimension_starts/miset_dimension_starts NAME miget_dimension_starts, miset_dimension_starts - get or set the start values SYNOPSIS #include <minc2.h> int miget_dimension_starts ( const midimhandle_t dimensions[], mivoxel_order_t voxel_order, int array_length, double starts[]); int miset_dimension_starts ( const midimhandle_t dimensions[], int array_length, const double starts[]); DESCRIPTION These functions 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. If not explicitly set, the start value defaults to zero. RETURN VALUE These functions return the number of start values copied to or from the starts[] array, or MI_ERROR on failure. miget_dimension_units/miset_dimension_units NAME miget_dimension_units, miset_dimension_units - get or set the unit string for a MINC dimension SYNOPSIS #include <minc2.h> int miget_dimension_units ( midimhandle_t dimension, char **units_ptr ); int miset_dimension_units ( midimhandle_t dimension, const char *units ); DESCRIPTION miget_dimension_units retrieves the units of the given dimension, allocating the space needed for the string. The memory allocated by this function should be released with a call to mifree_name(). miset_dimension_name will set the units for an existing dimension. The new string must be no greater than 128 characters in length, including the trailing zero byte. Typical values for units include "mm" or "cm" for spatial dimensions and "seconds" or "msec" for time dimensions. RETURN VALUE miget_dimension_units returns the length of the string retrieved, including the terminating zero byte. miset_dimension_units will return MI_NOERROR on success. Both functions return MI_ERROR if an error occurs. SEE ALSO mifree_name miget_dimension_width/miset_dimension_width NAME miget_dimension_width, miset_dimension_width - get or set the full-width half-maximum value for points along a MINC dimension SYNOPSIS #include <minc2.h> int miget_dimension_width ( midimhandle_t dimension, mivoxel_order_t voxel_order, double *width_ptr ); int miset_dimension_width ( midimhandle_t dimension, mivoxel_order_t voxel_order, double width ); DESCRIPTION These functions 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. If not explicitly set, the width will be assumed to be equal to the dimension's step size. RETURN VALUE Returns MI_NOERROR on success, or MI_ERROR on failure. Will fail if called for an irregularly-sampled dimension. SEE ALSO miget_dimension_widths, miset_dimension_widths miget_dimension_widths/miset_dimension_widths NAME miget_dimension_widths, miset_dimension_widths - get or set the full-width half-maximum values for points along a MINC dimension SYNOPSIS #include <minc2.h> int miget_dimension_widths ( midimhandle_t dimension, mivoxel_order_t voxel_order, unsigned long array_length, unsigned long start_position, double widths[]); int miset_dimension_widths ( midimhandle_t dimension, unsigned long array_length, unsigned long start_position, const double widths[]); DESCRIPTION These functions 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. It is explicitly legal to call this function for a regularly sampled dimension. The result will be a list of constant width values. However, it is not possible to set widths on a regularly sampled dimension. RETURN VALUE Returns the number of offset values read or written , or MI_ERROR if an error is detected. SEE ALSO miget_dimension_width, miset_dimension_width FREE FUNCTIONS (2) mifree_name/mifree_names NAME mifree_name, mifree_names - free the storage allocated for strings by MINC functions SYNOPSIS #include <minc2.h> int mifree_name ( char *name ); int mifree_names ( char **names ); DESCRIPTION Frees the space allocated for string storage by MINC function such as miget_dimension_name and miget_space_name. RETURN VALUE Returns MI_NOERROR on success, or MI_ERROR on failure. SEE ALSO miget_dimension_name, miget_space_name HYPERSLAB FUNCTIONS (8) miget_hyperslab_size NAME miget_hyperslab_size - calculate the size of the hyperslab SYNOPSIS #include <minc2.h> int miget_hyperslab_size ( mitype_t volume_data_type, int number_of_dimensions, int sizes_of_dimensions[], misize_t *size) DESCRIPTION calculate the size of the hyperslab. i.e., the amount of memory in BYTES which is needed to store the hyperslab RETURN VALUE miget_hyperslab_size returns MI_NOERROR if it successfully calculates the size of the hyperslab with specified dimensions and MI_ERROR otherwise miget_hyperslab_normalized NAME miget_hyperslab_normalized - get a normalized hyperslab SYNOPSIS #include <minc2.h> int miget_hyperslab_normalized ( mihandle_t volume, mitype_t buffer_data_type, long voxel_offsets[], long sizes[], double min, double max, void *buffer) DESCRIPTION The real values in the volume from the interval min through max is mapped to the maximum representable range for the requested data type. This function is also intended to be used for visualization tools in which the data is scaled to map onto an integer range for passing through color maps or displaying by video cards. Float type is NOT an allowed data type. RETURN VALUE miget_hyperslab_normalized returns MI_NOERROR if it successfully returns a normalized hyperslab with specified size and type and MI_ERROR otherwise miget_hyperslab_with_icv NAME miget_hyperslab_with_icv - get hyperslab with the specified icv SYNOPSIS #include <minc2.h> int miget_hyperslab_with_icv ( int icv, mitype_t buffer_data_type, long voxel_offsets[], long sizes[], void *buffer) DESCRIPTION This method gets the hyperslab with the specified icv. RETURN VALUE miget_hyperslab_with_icv returns MI_NOERROR if it successfully gets the hyperslab with specified icv and MI_ERROR otherwise miset_hyperslab_with_icv NAME miset_hyperslab_with_icv - set hyperslab with the specified icv SYNOPSIS #include <minc2.h> int miset_hyperslab_with_icv ( int icv, mitype_t buffer_data_type, long voxel_offsets[], long sizes[], void *buffer) DESCRIPTION This method sets the hyperslab with the specified icv. It is important to mention that if the apparent dimension order of the volume has been set (miset_apparent_dimension_order or miset_apparent_dimension_order_by_name) and is different from the dimension order of the file, then the buffer will be re-ordered in-place before the hyperslab is written. Hence, the ordering of the data in the buffer is *NOT* preserved by this function call. RETURN VALUE miset_hyperslab_with_icv returns MI_NOERROR if it successfully sets the hyperslab with specified icv and MI_ERROR otherwise miget_real_value_hyperslab NAME miget_real_value_hyperslab - get a real value hyperslab SYNOPSIS #include <minc2.h> int miget_real_value_hyperslab( mihandle_t volume, mitype_t buffer_data_type, long voxel_offsets[], long sizes[], void *buffer) DESCRIPTION This method converts the data from the type that is in the file in a value preserving way irrespective of the underlying datatype.If real value exceeds range of the requested data type, the result is UNDEFINED. The void pointer is pointing to memory which has to be allocated by the programmer in advance. RETURN VALUE miget_real_value_hyperslab returns MI_NOERROR if it successfully returns the real value hyperslab and MI_ERROR otherwise miset_real_value_hyperslab NAME miset_real_value_hyperslab - set a real value hyperslab SYNOPSIS #include <minc2.h> int miset_real_value_hyperslab( mihandle_t volume, mitype_t buffer_data_type, long voxel_offsets[], long sizes[], void *buffer) DESCRIPTION This method sets a real value hyperslab with the specified type and size. The void pointer would get casted to the appropriate type once it is used. The data_type argument will be used to ensure type compatibility with the hyperslab data type. It is important to mention that if the apparent dimension order of the volume has been set (miset_apparent_dimension_order or miset_apparent_dimension_order_by_name) and is different from the dimension order of the file, then the buffer will be re-ordered in-place before the hyperslab is written. Hence, the ordering of the data in the buffer is *NOT* preserved by this function call. RETURN VALUE miset_real_value_hyperslab returns MI_NOERROR if it successfully sets the hyperslab with specified size and type and MI_ERROR otherwise miget_voxel_value_hyperslab NAME miget_voxel_value_hyperslab - get a voxel value hyperslab SYNOPSIS #include <minc2.h> int miget_voxel_value_hyperslab( mihandle_t volume, mitype_t buffer_data_type, long voxel_offsets[], long sizes[], void *buffer) DESCRIPTION This method returns a voxel value hyperslab. RETURN VALUE miget_voxel_value_hyperslab returns MI_NOERROR if it successfully gets the hyperslab with specified size and type and MI_ERROR otherwise miset_voxel_value_hyperslab NAME miset_voxel_value_hyperslab - set a voxel value hyperslab SYNOPSIS #include <minc2.h> int miset_voxel_value_hyperslab( mihandle_t volume, mitype_t buffer_data_type, long voxel_offsets[], long sizes[], void *buffer) DESCRIPTION This method sets a voxel value hyperslab with the specified type and size. If the type does not match a simple C cast will be applied. It is important to mention that if the apparent dimension order of the volume has been set (miset_apparent_dimension_order or miset_apparent_dimension_order_by_name) and is different from the dimension order of the file, then the buffer will be re-ordered in-place before the hyperslab is written. Hence, the ordering of the data in the buffer is *NOT* preserved by this function call. RETURN VALUE miset_voxel_value_hyperslab returns MI_NOERROR if it successfully sets the voxel value hyperslab with specified size and type and MI_ERROR otherwise %=IMAGE CONVERSION VARIABLE FUNCTIONS (4)= %==miicv_volume_attach== % %NAME %miicv_volume_attach - attach a MINC ICV object to a MINC 2.0 volume. %SYNOPSIS %#include <minc2.h> %int miicv_volume_attach ( int icv, % mihandle_t volume); %DESCRIPTION %This function attaches a MINC image conversion variable (ICV) object %to a MINC 2.0 volume. %Given the flexibility of the MINC format, there are many different %possible choices available for details such as dimension order, data %type, and data range. Accounting for all of the possible combinations %of these items could make MINC programming too complex or unwieldy in %many situations. %MINC ICV objects are a solution to this problem. They are essentially %a specification of the properties that the programmer would like the %data to have. The ICV is responsible for making any necessary %conversions, hiding the details of the actual data format from the %programmer. %A program may allocate any number of ICV objects and may configure and %attach them independently, allowing the program to have several %different views of the volume's data at the same time. %Note that ICV properties cannot be modified while a variable is %attached to the ICV. If a file and variable are already attached to %the ICV, they will be automatically detached before the new variable %is attached. %NOTE %This interface is being extended to allow use with the new MINC 2.0 %interface, however, the existing ICV interface will be retained as %well. %RETURN VALUE %MI_NOERROR on success, or MI_ERROR on failure. % %==miicv_volume_detach== % %NAME %miicv_volume_detach - detach an image conversion variable from a volume. %SYNOPSIS %#include <minc2.h> %int miicv_volume_detach ( int icv); %DESCRIPTION %Deletes the association between an image conversion variable (ICV) %and a MINC2.0 volume object. %RETURN VALUE %MI_NOERROR on success, or MI_ERROR on failure. %SEE ALSO %miicv_volume_attach % %==miicv_volume_get/miicv_volume_put== % %NAME %miicv_volume_get, miicv_volume_put %SYNOPSIS %#include <minc2.h> %int miicv_volume_get(int icv, % mihandle_t volume, % const unsigned long start[], % const unsigned long count[], % void *value_ptr); %int miicv_volume_put(int icv, % mihandle_t volume, % const unsigned long start[], % const unsigned long count[], % void *value_ptr); %DESCRIPTION %These functions actually read or write data through the ICV to the attached %variable and volume. %All value/range conversions and dimension conversions are applied before the %data is read or written. %RETURN VALUES %MI_NOERROR on success, MI_ERROR on failure. % LABEL FUNCTIONS (5) midefine_label NAME midefine_label - define a label value for a labelled volume. SYNOPSIS #include <minc2.h> int midefine_label ( mihandle_t volume, int value, const char *name ); DESCRIPTION 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. RETURN VALUE MI_NOERROR on success, or MI_ERROR on failure. miget_label_name NAME miget_label_name - convert a label type to a text string SYNOPSIS #include <minc2.h> int miget_label_name ( mihandle_t volume, int value, char **name ); DESCRIPTION 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(). RETURN VALUE MI_NOERROR on success, MI_ERROR on failure. miget_label_value NAME miget_label_value - translate a label name into the corresponding integer value. SYNOPSIS #include <minc2.h> int miget_label_value ( mihandle_t volume, const char *name, int *value_ptr ); DESCRIPTION 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. RETURN VALUE MI_NOERROR on success, MI_ERROR on failure. miget_number_of_defined_labels NAME miget_number_of_defined_labels - Retrieve the number of defined labels SYNOPSIS #include <minc2.h> int miget_number_of_defined_labels ( mihandle_t volume, int *number_of_labels ); DESCRIPTION This function returns the number of defined labels, if any, or zero otherwise. RETURN VALUE MI_NOERROR on success, MI_ERROR on failure. miget_label_value_by_index NAME miget_label_value_by_index - Retrieve the label value from its index SYNOPSIS #include <minc2.h> int miget_label_value_by_index ( mihandle_t volume, int idx, int *value); DESCRIPTION This function returns the label value from its indexs, if any, or zero otherwise. RETURN VALUE MI_NOERROR on success, MI_ERROR on failure. RECORD FUNCTIONS (4) miget_record_name NAME miget_record_name - get the name of the record SYNOPSIS #include <minc2.h> int miget_record_name ( mihandle_t volume, char **name) DESCRIPTION This method gets the name of the record dimension. RETURN VALUE MI_NOERROR on success, MI_ERROR on failure. miget_record_length NAME miget_record_length - get the length of the record SYNOPSIS #include <minc2.h> int miget_record_length ( mihandle_t volume, int *length) DESCRIPTION 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. RETURN VALUE MI_NOERROR on success, MI_ERROR on failure. miget_record_field_name NAME miget_record_field_name - get the record's field name SYNOPSIS #include <minc2.h> int miget_record_field_name ( mihandle_t volume, int index, char **name) DESCRIPTION This method sets a field name for the given record. RETURN VALUE MI_NOERROR on success, MI_ERROR on failure. miset_record_field_name NAME miset_record_field_name - set the record's field name SYNOPSIS #include <minc2.h> int miset_record_field_name ( mihandle_t volume, int index, char *name) DESCRIPTION This method sets a field name for the given record. e.g. field is "red" RETURN VALUE MI_NOERROR on success, MI_ERROR on failure. SLICE/VOLUME SCALE FUNCTIONS (14) miget_slice_max NAME miget_slice_max - get maximum real value of all the slice SYNOPSIS #include <minc2.h> int miget_slice_max ( mihandle_t volume, unsigned long start_positions[], unsigned long array_length, double *slice_max) NOTE All of the slice scale (i.e., one scale per slice) functions take an array of long integer coordinates to specify the slice in particular and the order of the coordinates is always set to FILE ORDER of the dimensions (i.e. not the apparent order). The number of coordinates to specify is the first (n-2) dimensions except in the case of a uniform record which is also flattened (i.e., flatten_flag=1) that is the first (n-3) dimensions. DESCRIPTION This method returns the slice_max with the minimum real value of the corresponding slice. Note that this function is not defined for floating point data type nor it works if the volume is globally scaled. RETURN VALUE miget_slice_max returns MI_NOERROR if it successfully returns the slice_max or MI_ERROR otherwise miset_slice_max NAME miset_slice_max - set maximum real value for the slice SYNOPSIS #include <minc2.h> int miset_slice_max ( mihandle_t volume, unsigned long start_positions[], unsigned long array_length, const double slice_max) DESCRIPTION This method sets the slice_max with the minimum real value for the corresponding slice. Note that this function is not defined for floating point data type nor it works if the volume is globally scaled. RETURN VALUE miset_slice_max returns MI_NOERROR if it successfully sets the slice_max or MI_ERROR otherwise miget_slice_min NAME miget_slice_min - get the minimum real value of the slice SYNOPSIS #include <minc2.h> int miget_slice_min ( mihandle_t volume, unsigned long start_positions[], unsigned long array_length, double *slice_min) DESCRIPTION This method returns the slice_min with the minimum real value of the corresponding slice. Note that this function is not defined for floating point data type nor it works if the volume is globally scaled. RETURN VALUE miget_slice_min returns MI_NOERROR if it successfully returns the slice_min or MI_ERROR otherwise miset_slice_min NAME miset_slice_min - set the minimum real value for all the slice SYNOPSIS #include <minc2.h> int miset_slice_min ( mihandle_t volume, unsigned long start_positions[], unsigned long array_length, const double slice_min) DESCRIPTION This method sets the slice_min with the minimum real value for the corresponding slice. Note that this function is not defined for floating point data type nor it works if the volume is globally scaled. RETURN VALUE miset_slice_min returns MI_NOERROR if it successfully sets the slice_min or MI_ERROR otherwise miget_slice_range NAME miget_slice_range - get the min and max real values of the slice range SYNOPSIS #include <minc2.h> int miget_slice_range ( mihandle_t volume, unsigned long start_positions[], unsigned long array_length, double *slice_max, double *slice_min) DESCRIPTION This method returns the slice range according to their minimum and maximum real values . Note that this function is not defined for floating point data type nor it works if the volume is globally scaled. RETURN VALUE miget_slice_range returns MI_NOERROR if it successfully returns min and max or MI_ERROR otherwise miset_slice_range NAME miset_slice_range - set the min and max real values of the slice range SYNOPSIS #include <minc2.h> int miset_slice_range ( mihandle_t volume, unsigned long start_positions[], unsigned long array_length, const double slice_max, const double slice_min) DESCRIPTION This method sets the slice range according to the minimum and maximum real values . Note that this function is not defined forfloating point data type nor it works if the volume is globally scaled. RETURN VALUE miset_slice_range returns MI_NOERROR if it successfully sets the slice_max and the slice_min or MI_ERROR otherwise miget_slice_scaling_flag NAME miget_slice_scaling_flag - get the scaling flag for slices SYNOPSIS #include <minc2.h> int miget_slice_scaling_flag ( mihandle_t volume, miboolean_t *scaling_flag) DESCRIPTION This method gets the scaling flag for slices which determines whether the volume slices have different scale factors. RETURN VALUE miget_slice_scaling_flag returns MI_NOERROR if it successfully gets the scaling flag or MI_ERROR otherwise miset_slice_scaling_flag NAME miset_slice_scaling_flag - set the scaling flag for slices SYNOPSIS #include <minc2.h> int miset_slice_scaling_flag ( mihandle_t volume, miboolean_t scaling_flag) DESCRIPTION This method sets the scaling flag for slices which determines whether the volume slices have different scale factors. NOTE: when creating a volume with slice scaling , this fuction MUST be called before micreate_volume_image(). RETURN VALUE miset_slice_scaling_flag returns MI_NOERROR if it successfully sets the scaling flag or MI_ERROR otherwise miget_volume_max NAME miget_volume_max - get the global max scale for volume SYNOPSIS #include <minc2.h> int miget_volume_max ( mihandle_t volume, double *volume_max) DESCRIPTION This method gets the max scale value for the volume. Note that this method only works if volume is not slice scaled. RETURN VALUE miget_volume_max returns MI_NOERROR if it successfully gets the global max scale for the volume or MI_ERROR otherwise. miset_volume_max NAME miset_volume_max - set the global max scale for volume SYNOPSIS #include <minc2.h> int miset_volume_max ( mihandle_t volume, double volume_max) DESCRIPTION This method sets the max scale value for the volume. Note that this method only works if volume is not slice scaled. RETURN VALUE miset_volume_max returns MI_NOERROR if it successfully sets the global max scale for the volume or MI_ERROR otherwise. miget_volume_min NAME miget_volume_min - get the global min scale for volume SYNOPSIS #include <minc2.h> int miget_volume_min ( mihandle_t volume, double *volume_min) DESCRIPTION This method gets the min scale value for the volume. Note that this method only works if volume is not slice scaled. RETURN VALUE miget_volume_min returns MI_NOERROR if it successfully gets the global min scale for the volume or MI_ERROR otherwise. miset_volume_min NAME miset_volume_min - set the global min scale for volume SYNOPSIS #include <minc2.h> int miset_volume_min ( mihandle_t volume, double volume_min) DESCRIPTION This method sets the min scale value for the volume. Note that this method only works if volume is not slice scaled. RETURN VALUE miset_volume_min returns MI_NOERROR if it successfully sets the global min scale for the volume or MI_ERROR otherwise. miget_volume_range NAME miget_volume_range - get the global range scale for volume SYNOPSIS #include <minc2.h> int miget_volume_range ( mihandle_t volume, double *volume_max, double *volume_min) DESCRIPTION This method gets the range (min and max) scale value for the volume. Note that this method only works if volume is not slice scaled. RETURN VALUE miget_volume_range returns MI_NOERROR if it successfully gets the global range scale for the volume or MI_ERROR otherwise. miset_volume_range NAME miset_volume_range - set the global range scale for volume SYNOPSIS #include <minc2.h> int miset_volume_range ( mihandle_t volume, double volume_max, double volume_min) DESCRIPTION This method sets the range (min and max) scale value for the volume. Note that this method only works if volume is not slice scaled. RETURN VALUE miset_volume_range returns MI_NOERROR if it successfully sets the global range scale for the volume or MI_ERROR otherwise. VALID MIN/MAX AND RANGE FUNCTIONS (6) miget_volume_valid_max NAME miget_volume_valid_max - get the valid maximum value SYNOPSIS #include <minc2.h> int miget_volume_valid_max ( mihandle_t volume, double *valid_max) DESCRIPTION This method gets the valid maximum value specific to the data type. RETURN VALUE miget_volume_valid_max returns MI_NOERROR if it successfully gets the valid maximum or MI_ERROR otherwise miset_volume_valid_max NAME miset_volume_valid_max - set the valid maximum value SYNOPSIS #include <minc2.h> int miset_volume_valid_max ( mihandle_t volume, double valid_max) DESCRIPTION This method sets the valid maximum value specific to the data type. RETURN VALUE miset_volume_valid_max returns MI_NOERROR if it successfully sets the valid maximum or MI_ERROR otherwise miget_volume_valid_min NAME miget_volume_valid_min - get the valid minimum value SYNOPSIS #include <minc2.h> int miget_volume_valid_min ( mihandle_t volume, double *valid_min) DESCRIPTION This method gets the valid minimum value specific to the data type. RETURN VALUE miget_volume_valid_min returns MI_NOERROR if it successfully gets the valid minimum or MI_ERROR otherwise miset_volume_valid_min NAME miset_volume_valid_min - set the valid minimum value SYNOPSIS #include <minc2.h> int miset_volume_valid_min ( mihandle_t volume, double valid_min) DESCRIPTION This method sets the valid minimum value specific to the data type. RETURN VALUE miset_volume_valid_min returns MI_NOERROR if it successfully sets the valid minimum or MI_ERROR otherwise miget_volume_valid_range NAME miget_volume_valid_range - get the valid range values SYNOPSIS #include <minc2.h> int miget_volume_valid_range ( mihandle_t volume, double *valid_max, double *valid_min) DESCRIPTION This method gets the valid range values specific to the data type. RETURN VALUE miget_volume_valid_range returns MI_NOERROR if it successfully gets the valid range values or MI_ERROR otherwise miset_volume_valid_range NAME miset_volume_valid_range - set the valid range values SYNOPSIS #include <minc2.h> int miset_volume_valid_range ( mihandle_t volume, double valid_max, double valid_min) DESCRIPTION This method sets the valid range values specific to the data type. RETURN VALUE miset_volume_valid_range returns MI_NOERROR if it successfully sets the valid range values or MI_ERROR otherwise % THE FOLLOWING IS NO LONGER IN THE CODE (leila) %==miset_valid_range_to_default== % %NAME %miset_valid_range_to_default - set the range to the default value %SYNOPSIS %#include <minc2.h> %int miset_valid_range_to_default ( mihandle_t volume) %DESCRIPTION %This method sets the valid range to the dafault value specific to the %data type. %RETURN VALUE %miset_valid_range_to_default returns MI_NOERROR if it successfully sets %the valid range to default values or MI_ERROR otherwise % VOLUME FUNCTIONS (6) micreate_volume_image NAME micreate_volume_image - create the actual image data for volume. SYNOPSIS #include <minc2.h> int micreate_volume_image ( mihandle_t volume); DESCRIPTION Create the actual image for the volume. RETURN VALUE Returns MI_NOERROR on success or MI_ERROR on failure. micreate_volume NAME micreate_volume - create a volume with the specified properties SYNOPSIS #include <minc2.h> 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) DESCRIPTION Create a volume with the specified filename, data type, dimension handles, type, class and compression type. RETURN VALUE micreate_volume returns MI_NOERROR if it successfully creates a volume with all the specified properties and MI_ERROR otherwise miget_volume_dimension_count NAME miget_volume_dimension_count - get the number of dimensions defined in a MINC volume, according to their class and attribute. SYNOPSIS #include <minc2.h> int miget_volume_dimension_count ( mihandle_t volume, midimclass_t class, midimattr_t attr, int *dimension_count ); DESCRIPTION This function may be used to determine the number of dimensions with the given class and attributes. RETURN VALUE MI_NOERROR if the call succeeds, or MI_ERROR if an error is detected. miget_volume_voxel_count NAME miget_volume_voxel_count - get the number of voxels in the volume. SYNOPSIS #include <minc2.h> int miget_volume_voxel_count ( mihandle_t volume, int *number_of_voxels ); DESCRIPTION This function returns the number of voxels in the volume. RETURN VALUE MI_NOERROR if the call succeeds, or MI_ERROR if an error is detected. miopen_volume NAME miopen_volume - open a volume for reading SYNOPSIS #include <minc2.h> int miopen_volume(const char *filename, int mode, mihandle_t *volume); DESCRIPTION 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. RETURN VALUE Returns MI_NOERROR on success or MI_ERROR on failure. miflush_volume NAME miflush_volume SYNOPSIS #include <minc2.h> int miflush_volume ( mihandle_t volume); DESCRIPTION Writes any changes associated with the volume to disk. RETURN VALUE Returns MI_NOERROR on success or MI_ERROR on failure. miclose_volume NAME miclose_volume - close an open volume, freeing the volume handle SYNOPSIS #include <minc2.h> int miclose_volume ( mihandle_t volume); DESCRIPTION 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. RETURN VALUE Returns MI_NOERROR on success or MI_ERROR on failure. VOXEL/REAL FUNCTIONS (16) miconvert_real_to_voxel, miconvert_voxel_to_real NAME miconvert_real_to_voxel, miconvert_voxel_to_real - conversion between voxel and real values SYNOPSIS #include <minc2.h> int miconvert_real_to_voxel( mihandle_t volume, const unsigned long location[], int array_length, double value, double *voxel_ptr ); int miconvert_voxel_to_real ( mihandle_t volume, const unsigned long location[], int array_length, double voxel, double *value_ptr ); DESCRIPTION These 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. RETURN VALUE Returns MI_NOERROR on success, MI_ERROR on failure. miconvert_3D_voxel_to_world NAME miconvert_3D_voxel_to_world - convert voxel to world coordinates SYNOPSIS #include <minc2.h> int miconvert_3D_voxel_to_world ( mihandle_t volume, const double voxel[3], double world[3]) DESCRIPTION ** Not implemented yet!! This method makes conversion from voxel to world coordinate system. The voxels can come in any order but the result in world coordinate system would be in (x,y,z) order. Use "miconvert_voxel_to_world" if any number of spatial dimensions other than three (3) is present. RETURN VALUE miconvert_3D_voxel_to_world returns MI_ERROR if there are not exactly three (3) spatial dimensions present or MI_NOERROR otherwise. miconvert_3D_world_to_voxel NAME miconvert_3D_world_to_voxel - convert world to voxel coordinates SYNOPSIS #include <minc2.h> int miconvert_3D_world_to_voxel ( mihandle_t volume, double voxel[3], const double world[3]) DESCRIPTION ** Not implemented yet!! This method makes conversion from world to voxel coordinate system. The dimensions in world coordinate system come in (x,y,z) order but the result in voxel coordinates will be in the order of spatial dimensions. Use "miconvert_world_to_voxel" if any number of spatial dimensions other than three (3) is present. RETURN VALUE miconvert_3D_world_to_voxel returns MI_ERROR if there are not exactly three (3) spatial dimensions present or MI_NOERROR otherwise. miconvert_3D_voxel_to_spatial_frequency NAME miconvert_3D_voxel_to_spatial_frequency SYNOPSIS #include <minc2.h> int miconvert_3D_voxel_to_spatial_frequency ( mihandle_t volume, const double voxel[3], double world[3]) DESCRIPTION ** Not implemented yet!! RETURN VALUE miconvert_3D_voxel_to_spatial_frequency miconvert_3D_spatial_frequency_to_voxel NAME miconvert_3D_spatial_frequency_to_voxel SYNOPSIS #include <minc2.h> int miconvert_3D_spatial_frequency_to_voxel ( mihandle_t volume, double voxel[3], const double world[3]) DESCRIPTION ** Not implemented yet!! RETURN VALUE miconvert_3D_spatial_frequency_to_voxel miconvert_voxel_to_world NAME miconvert_voxel_to_world SYNOPSIS #include <minc2.h> int miconvert_voxel_to_world ( midimhandle_t dimensions[], int n_dimensions, const double voxels[], double worlds[]) DESCRIPTION ** Not implemented yet!! RETURN VALUE miconvert_voxel_to_world miconvert_world_to_voxel NAME miconvert_world_to_voxel SYNOPSIS #include <minc2.h> int miconvert_world_to_voxel ( midimhandle_t dimensions[], int n_dimensions, double voxels[], const double worlds[]) DESCRIPTION ** Not implemented yet!! RETURN VALUE miconvert_world_to_voxel miget_real_value NAME miget_real_value - return a specific scaled value from a volume SYNOPSIS #include <minc2.h> int miget_real_value ( mihandle_t volume, const unsigned long location[], int array_length, double *value_ptr ); DESCRIPTION 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. RETURN VALUE Returns MI_NOERROR on success, MI_ERROR on failure. miset_real_value NAME miset_real_value - set the scaled value of a particular position in the MINC volume. SYNOPSIS #include <minc2.h> int miset_real_value( mihandle_t volume, const unsigned long location[], int array_length, double value ); DESCRIPTION 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. RETURN VALUE Returns MI_NOERROR on success, MI_ERROR on failure. miconvert_spatial_origin_to_start NAME miconvert_spatial_origin_to_start SYNOPSIS #include <minc2.h> int miconvert_spatial_origin_to_start( mihandle_t volume, double world[3], double starts[3]) DESCRIPTION ** Not implemented yet!! This function calculates the start values for the volume dimensions, assuming that the spatial origin is relocated to the given world coordinate. RETURN VALUE Returns MI_ERROR or MI_NOERROR miconvert_spatial_frequency_origin_to_start NAME miconvert_spatial_frequency_origin_to_start SYNOPSIS #include <minc2.h> int miconvert_spatial_frequency_origin_to_start( mihandle_t volume, const double world[3], double starts[3]) DESCRIPTION This function calculates the start values for the volume dimensions, assuming that the spatial origin is relocated to the given world coordinate. RETURN VALUE Returns MI_ERROR or MI_NOERROR miset_world_origin NAME miset_world_origin SYNOPSIS #include <minc2.h> int miset_world_origin( mihandle_t volume, double world[3]) DESCRIPTION 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. RETURN VALUE Returns MI_ERROR or MI_NOERROR miset_spatial_frequency_origin NAME miset_spatial_frequency_origin SYNOPSIS #include <minc2.h> int miset_spatial_frequency_origin( mihandle_t volume, double world[3]) DESCRIPTION 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. RETURN VALUE Returns MI_ERROR or MI_NOERROR miget_voxel_value NAME miget_voxel_value - return a specific unscaled value from a given volume SYNOPSIS #include <minc2.h> int miget_voxel_value ( mihandle_t volume, const unsigned long location[], int array_length, double *voxel_ptr ); DESCRIPTION This function retrieves the real 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. RETURN VALUE Returns MI_NOERROR on success, MI_ERROR on failure. miset_voxel_value NAME miset_voxel_value - set the unscaled value of a particular position in the MINC volume. SYNOPSIS #include <minc2.h> int miset_voxel_value( mihandle_t volume, const unsigned long location[], int array_length, double voxel ); DESCRIPTION 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. RETURN VALUE Returns MI_NOERROR on success, MI_ERROR on failure. VOLUME PROPERTIES FUNCTIONS (15) minew_volume_props/mifree_volume_props NAME minew_volume_props, mifree_volume_props - create or destroy a volume property list. SYNOPSIS #include <minc2.h> int minew_volume_props(mivolumeprops_t *props); int mifree_volume_props(mivolumeprops_t props); DESCRIPTION MINC volume properties objects are used to set or query the state of a number of the internal parameters of the volume. RETURN VALUE miget_volume_props NAME miget_volume_props - Get a copy of the property list of a volume. SYNOPSIS #include <minc2.h> int miget_volume_props(mihandle_t volume, mivolumeprops_t *props); DESCRIPTION Returns a copy of the properties associated with the volume. Any changes made to the properties will not take effect on the original volume, but the resulting properties structure may be used in the creation of a new volume. The handle must be freed by calling mifree_volume_props(). RETURN VALUE MI_NOERROR on success, MI_ERROR on failure miset_props_multi_resolution/miget_props_multi_resolution NAME miset_props_multi_resolution, miget_props_multi_resolution - get or set the multi-resolution properties for a property list. SYNOPSIS #include <minc2.h> int miset_props_multi_resolution(mivolumeprops_t props, miboolean_t enable_flag, int depth); int miget_props_multi_resolution(mivolumeprops_t props, miboolean_t *enable_flag, int *depth); DESCRIPTION Returns the multi-resolution properties for a property list. RETURN VALUE Returns MI_NOERROR on success, MI_ERROR on failure miselect_resolution NAME miselect_resolution - compute a different resolution SYNOPSIS #include <minc2.h> int miselect_resolution ( mihandle_t volume, int depth) DESCRIPTION This method computes a new resolution on according to the depth (resolution level) provided by the user. RETURN VALUE miselect_resolution returns MI_NOERROR if it successfully computes a new resolution from the data or MI_ERROR otherwise. miflush_from_resolution NAME miflush_from_resolution - compute all resolutions SYNOPSIS #include <minc2.h> int miflush_from_resolution ( mihandle_t volume, int depth) DESCRIPTION This method sets the resolution level (depth) to the parameter provided and computes all the other resolutions. RETURN VALUE miflush_from_resolution returns MI_NOERROR if it successfully computes all the resolutions from the data or MI_ERROR otherwise. miset_props_compression_type/miget_props_compression_type NAME miset_props_compression_type, miget_props_compression_type - get or set the compression type for a volume property list. SYNOPSIS #include <minc2.h> int miset_props_compression_type(mivolumeprops_t props, micompression_t compression_type); int miget_props_compression_type(mivolumeprops_t props, micompression_t *compression_type); DESCRIPTION Set or retrieve the compression type, if any, for the volume properties. Currently only two compression types are defined: Enabling compression will automatically enable blocking with default parameters (see miset_props_blocking). typedef enum { MI_COMPRESS_NONE = 0, MI_COMPRESS_ZLIB = 1 } micompression_t ; RETURN VALUE MI_NOERROR on success, or MI_ERROR on failure. miset_props_zlib_compression/miget_props_zlib_compression NAME miset_props_zlib_compression, miget_props_zlib_compression - get or set the zlib compression properties for a volume property list. SYNOPSIS #include <minc2.h> int miset_props_zlib_compression(mivolumeprops_t props, int zlib_level); int miget_props_zlib_compression(mivolumeprops_t props, int *zlib_level); DESCRIPTION Get or set the Zlib compression level for the volume properties. The compression level is an integer from 1 to 9. RETURN VALUE MI_NOERROR on success, or MI_ERROR on failure. miset_props_blocking/miget_props_blocking NAME miset_props_blocking, miget_props_blocking - get or set the blocking structure properties for a volume property list. SYNOPSIS #include <minc2.h> int miset_props_blocking(mivolumeprops_t props, int edge_count, const int *edge_lengths); int miget_props_blocking(mivolumeprops_t props, int *edge_count, int *edge_lengths, int max_lengths); DESCRIPTION Gets or sets the block-structuring properties of a volume property list. If this option is set on a MINC volume, image data will be stored in a series of 2D or 3D chunks rather than as a simple linear array. This option is enabled implicitly whenever compression is enabled - all compressed volumes must be block-structured. RETURN VALUE Returns MI_NOERROR on success, MI_ERROR on failure miset_props_record NAME miset_props_record - set properties of a uniform/nonuniform record dimension SYNOPSIS #include <minc2.h> int miset_props_record ( mivolumeprops_t props, long length, char *name) DESCRIPTION This method sets the properties of arecord given its name and size (i.e., number of fields included in the record). RETURN VALUE miset_props_record returns MI_NOERROR if it successfully sets the properties of a record or MI_ERROR otherwise. miset_props_template NAME miset_props_template - set the template volume flag SYNOPSIS #include <minc2.h> int miset_props_template ( mivolumeprops_t props, int template_flag) DESCRIPTION This method sets the template volume flag to (1) to create a template volume (i.e, which is exaclty like an image except the image itself) or (0) for no template volume. The default flag is set to zero. RETURN VALUE miset_props_template returns MI_NOERROR if it successfully sets the template flag or MI_ERROR otherwise. Authors Bert Vincent, Leila Baghdadi and John G Sled