MINC/SoftwareDevelopment/MINC2.0 Application Programmers Interface
MINC 2.0 Application Programming Interface (API)
editAn Introduction to HDF5
edit(For a complete description, see the HDF5 User's Guide at http://hdf.ncsa.uiuc.edu/ ).
ATTRIBUTE/GROUP FUNCTIONS (11)
editmicreate_group
edit 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
edit 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 otherwisemidelete_group
edit 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 otherwisemiget_attr_length
edit
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 otherwisemiget_attr_type
edit 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
edit 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 otherwisemiset_attr_values
edit
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
edit 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 otherwisemilist_start
edit 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 otherwisemilist_attr_next
edit 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 otherwisemilist_grp_next
edit
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 otherwisemilist_finish
edit 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
edit 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)
editmiget_data_class
edit 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
edit 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
edit 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
edit 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_nameDIMENSION FUNCTIONS (39)
editmiget_volume_from_dimension
edit 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
edit 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 otherwisemicreate_dimension
edit 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
edit 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
edit 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_namemiset_apparent_dimension_order
edit 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_namemiset_apparent_dimension_order_by_name
edit 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 otherwisemiset_apparent_record_dimension_flag
edit 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
edit 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 otherwisemiset_dimension_apparent_voxel_order
edit 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 otherwisemiget_dimension_class/miset_dimension_class
edit 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
edit 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
edit 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
edit 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_namemiget_dimension_offsets/miset_dimension_offsets
edit 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
edit 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
edit 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_separationsmiget_dimension_separations/miset_dimension_separations
edit 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_separationmiget_dimension_size/miset_dimension_size
edit 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
edit 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_sizemiget_dimension_start/miset_dimension_start
edit 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
edit 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
edit 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_namemiget_dimension_width/miset_dimension_width
edit 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_widthsmiget_dimension_widths/miset_dimension_widths
edit 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_widthFREE FUNCTIONS (2)
editmifree_name/mifree_names
edit 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_nameHYPERSLAB FUNCTIONS (8)
editmiget_hyperslab_size
edit 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 otherwisemiget_hyperslab_normalized
edit 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
edit 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 otherwisemiset_hyperslab_with_icv
edit 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 otherwisemiget_real_value_hyperslab
edit 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 otherwisemiset_real_value_hyperslab
edit 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 otherwisemiget_voxel_value_hyperslab
edit 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 otherwisemiset_voxel_value_hyperslab
edit 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)
editmidefine_label
edit 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
edit 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
edit
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
edit
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
edit
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)
editmiget_record_name
edit 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
edit 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
edit 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
edit 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)
editmiget_slice_max
edit 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 otherwisemiset_slice_max
edit 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 otherwisemiget_slice_min
edit 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 otherwisemiset_slice_min
edit 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 otherwisemiget_slice_range
edit 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 otherwisemiset_slice_range
edit 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 otherwisemiget_slice_scaling_flag
edit 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 otherwisemiset_slice_scaling_flag
edit 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 otherwisemiget_volume_max
edit 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
edit 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
edit 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
edit 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
edit 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
edit 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)
editmiget_volume_valid_max
edit
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 otherwisemiset_volume_valid_max
edit 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 otherwisemiget_volume_valid_min
edit 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 otherwisemiset_volume_valid_min
edit 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 otherwisemiget_volume_valid_range
edit 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 otherwisemiset_volume_valid_range
edit 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)
editmicreate_volume_image
edit 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
edit 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 otherwisemiget_volume_dimension_count
edit 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
edit 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
edit 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
edit 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
edit 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)
editmiconvert_real_to_voxel, miconvert_voxel_to_real
edit 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
edit 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
edit 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
edit 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_frequencymiconvert_3D_spatial_frequency_to_voxel
edit 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_voxelmiconvert_voxel_to_world
edit 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_worldmiconvert_world_to_voxel
edit 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_voxelmiget_real_value
edit 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
edit 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
edit 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_NOERRORmiconvert_spatial_frequency_origin_to_start
edit 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_NOERRORmiset_world_origin
edit 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_NOERRORmiset_spatial_frequency_origin
edit 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_NOERRORmiget_voxel_value
edit 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
edit 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)
editminew_volume_props/mifree_volume_props
edit 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 VALUEmiget_volume_props
edit 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 failuremiset_props_multi_resolution/miget_props_multi_resolution
edit 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 failuremiselect_resolution
edit 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
edit 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
edit 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
edit 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
edit 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 failuremiset_props_record
edit 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
edit 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
editBert Vincent, Leila Baghdadi and John G Sled