MINC/SoftwareDevelopment/MINC1-programmers-reference
Dimension variable and attribute names
[edit | edit source]Of all of the variables, dimensions and attributes described here, only the variable
MIimage
and its dimensions are required to be present in a MINC file.
Additional variables, dimensions and attributes may be present in the file -- unrecognised
variables and attributes should be ignored.
A word on attribute conventions. All numeric values should be stored in one of the numeric
types (NC_BYTE
, NC_SHORT
,
NC_INT
, NC_FLOAT
or NC_DOUBLE
).
Some numeric attributes must be specified in a definite unit -- time attributes (such as
MIrepetition_time
and MIradionuclide_halflife
) are
given in seconds. Other attributes have an associated attribute that gives the unit -- e.g.
MIinjection_dose
and MIdose_units
.
NetCDF standard attributes
[edit | edit source]These attributes can be used with any variable. Fuller descriptions can be obtained from the NetCDF user's guide.
MIunits
Specifies the units of the variable values as a string -- units should be compatible with the udunits library.
MIlong_name
A string giving a textual description of the variable for human consumption.
MIvalid_range
A vector of two numbers specifying the minimum and maximum valid values in the variable.
For the MINC routines the order is not important. For the MIimage
variable, this attribute (or MIvalid_max
and
MIvalid_min
) should always be present unless the defaults of full
range for integer types and [0.0,1.0] for floating point types is correct.
MIvalid_max
A number giving the valid maximum for the variable.
MIvalid_min
A number giving the valid minimum for the variable.
MI_FillValue
Number to be used for filling in values in the variable that are not explicitly written.
MItitle
A global string that provides a description of what is in the file.
MIhistory
A global string that should store one line for each program that has modified the file. Each line should contain the program name and arguments.
MINC general attributes
[edit | edit source]These attributes apply to any variable in the file.
MIvartype
A string identifying the type of variable. Should be one of MI_GROUP
,
MI_DIMENSION
, MI_DIM_WIDTH
or
MI_VARATT
.
MIvarid
A string that identifies the origin of the variable. All standard MINC variables should
have this attribute with value MI_STDVAR
. Variables created by users
should have a distinctive name that will not be the same as the names used by other
applications.
MIsigntype
The NetCDF format does not need to know the sign of variables since it does not interpret
values -- it is left up to the invoking program to worry about the signs of integers.
Because the MINC interface translates variables, it must have this information.
MIsigntype
is a string with value MI_SIGNED
or
MI_UNSIGNED
. The default values are MI_UNSIGNED
for bytes and MI_SIGNED
for all other types.
MIparent
A string identifying by name the parent variable of this variable (either in the data hierarchy or as the parent of this variable attribute).
MIchildren
A newline-separated list of the children of this variable (in the data hierarchy).
MIcomments
Any text that should be included with this variable.
MIversion
A string identifying the file version. The current version is
MI_CURRENT_VERSION
. Each version can be identified by a constant of
the form MI_VERSION_1_0
.
The constants MI_TRUE
and MI_FALSE
are provided
for boolean attributes.
Dimensions and dimension variable
[edit | edit source]The following are the names of dimensions and their corresponding dimension variables. Only
MIvector_dimension
does not have a corresponding dimension variable.
MIxspace
Dimension and coordinate variable for x axis.
MIyspace
Dimension and coordinate variable for y axis.
MIzspace
Dimension and coordinate variable for z axis.
MItime
Dimension and coordinate for variable time axis.
MItfrequency
Dimension and coordinate variable for temporal frequency.
MIxfrequency
Dimension and coordinate variable for spatial frequency along the x axis.
MIyfrequency
Dimension and coordinate variable for spatial frequency along the y axis.
MIzfrequency
Dimension and coordinate variable for spatial frequency along the z axis.
MIvector_dimension
Dimension only for components of a vector field.
In addition to dimension variables, we can have dimension width variables that specify the FWHM width of the sample at each point.
MIxspace_width
Width of samples along x axis.
MIyspace_width
Width of samples along y axis.
MIzspace_width
Width of samples along z axis.
MItime_width
Width of samples along time axis.
MItfrequency_width
Width of samples along temporal frequency axis.
MIxfrequency_width
Width of samples along x spatial frequency axis.
MIyfrequency_width
Width of samples along y spatial frequency axis.
MIzfrequency_width
Width of samples along z spatial frequency axis.
The attributes associated with dimension and dimension width variables are given below:
MIspacing
A string with value MI_REGULAR
(for a regularly spaced grid) or
MI_IRREGULAR
(for irregular spacing of samples). If the value is
MI_REGULAR
, then the variable is permitted to be a scalar instead of a
vector varying with the dimension of the same name. Can be used for both dimension and
dimension width variables.
MIstep
A number indicating the step between samples for regular spacing. This value may be
negative to indicate orientation (to specify that MIxspace
runs from
patient right to left, for example). If the spacing is irregular, then the value can be an
average step size. Applies only to dimension variables.
MIstart
The coordinate of the index 0 of the dimension. Applies only to dimension variables.
MIspacetype
A string identifying the type of coordinate space. Currently one of
MI_NATIVE
(the coordinate system of the scanner),
MI_TALAIRACH
(a standardized coordinate system), or
MI_CALLOSAL
(another standardized coordinate system). Applies only to
dimension variables.
MIalignment
A string indicating the position of the coordinates relative to each sample (remembering
that each sample has a width). Can be one of MI_START
,
MI_CENTRE
or MI_END
. Applies only to dimension
variables.
MIdirection_cosines
A vector with MI_NUM_SPACE_DIMS
(=3) elements giving the direction
cosines of the axes. Although axes are labelled x, y and z, they may in fact have a
significantly different direction -- this attribute allows the direction relative to the
true axes to be specified exactly. Applies only to dimension variables. Note that the dot
product of the direction cosine with the corresponding axis <function>(1,0,0), (0,1,0) or
(0,0,1)</function> should be positive so that the sign of the attribute
MIstep
contains the orientation information.
MIwidth
For regularly dimension widths, this numeric attribute gives the FWHM width of all samples. It can be used for irregular widths to specify the average width. Applies only to dimension width variables.
MIfiltertype
A string specifying the shape of the convolving filter. Currently, can be one of
MI_SQUARE
, MI_GAUSSIAN
or
MI_TRIANGULAR
. Applies only to dimension width variables.
Root variable
[edit | edit source]The variable MIrootvariable
is used as the root of the data hierarchy,
with its MIchildren
attribute pointing to the first level of group
variables (including all of the MINC group variables), and with its
MIparent
attribute an empty string.
Image variable
[edit | edit source]The variable MIimage
is used to store the image data.
MIimagemax
A variable attribute (ie. an attribute pointing to a variable of the same name) that stores the real value maximum for the image. This variable should not vary over the image dimensions of MIimage. The units of this variable define the units of the image.
MIimagemin
Like MIimagemax
, but stores the real value minimum for the image.
MIimagemax
should not be present without
MIimagemin
and vice-versa.
MIcomplete
A boolean attribute (with values MI_TRUE
or
MI_FALSE
) that indicates whether the variable has been written in its
entirety. This can be used to detect program failure when writing out images as they are
processed : MIcomplete
is set to MI_FALSE
at the
beginning and
changed to MI_TRUE
at the end of processing.
Patient variable
[edit | edit source]The variable MIpatient
is a group variable with no dimensions and no
useful value. It serves only to group together information about the patient. Attributes
are modelled after ACR-NEMA conventions.
MIfull_name
A string specifying the full name of the patient.
MIother_names
A string giving other names for the patient.
MIidentification
A string specifying identification information for the patient.
MIother_ids
A string giving other id's.
MIbirthdate
A string specifying the patient's birthdate.
MIsex
A string specifying the patient's sex: MI_MALE
,
MI_FEMALE
or MI_OTHER
.
MIage
A number giving the patient's age.
MIweight
The patient's weight in kilograms.
MIsize
The patient's height or length in metres.
MIaddress
A string giving the patient's address.
MIinsurance_id
A string giving the patient's insurance plan id.
Study variable
[edit | edit source]Information about the study is grouped together in the MIstudy
variable which has no dimensions or values. Attributes are modelled after ACR-NEMA
conventions.
MIstart_time
String giving time (and date) of start of the study.
MIstart_year
Integer giving year of start.
MIstart_month
Integer giving month (1-12) of start.
MIstart_day
Integer giving day (1-31) of start.
MIstart_hour
Integer giving hour (0-23) of start.
MIstart_minute
Integer giving minute (0-59) of start.
MIstart_seconds
Floating-point value giving seconds of start.
MImodality
Imaging modality : one of MI_PET
, MI_SPECT
,
MI_GAMMA
, MI_MRI
, MI_MRS
,
MI_MRA
, MI_CT
, MI_DSA
,
MI_DR
.
MImanufacturer
String giving name of device manufacturer.
MIdevice_model
String identifying device model.
MIinstitution
String identifying institution.
MIdepartment
String identifying department.
MIstation_id
String identifying machine that generated the images.
MIreferring_physician
Name of patient's primary physician.
MIattending_physician
Physician administering the examination.
MIradiologist
Radiologist interpreting the examination.
MIoperator
Name of technologist operating scanner.
MIadmitting_diagnosis
String description of admitting diagnosis.
MIprocedure
String description of the procedure employed.
MIstudy_id
String identifying study.
Acquisition variable
[edit | edit source]Information about the acquisition itself is stored as attributes of the
MIacquisition
variable (again, no dimensions and no values).
MIprotocol
String description of the protocol for image acquisition.
MIscanning_sequence
String description of type of data taken (eg. for MR -- IR, SE, PS, etc.).
MIrepetition_time
Time in seconds between pulse sequences.
MIecho_time
Time in seconds between the middle of a 90 degree pulse and the middle of spin echo production.
MIinversion_time
Time in seconds after the middle of the inverting RF pulse to the middle of the 90 degree pulse to detect the amount of longitudinal magnetization.
MInum_averages
Number of times a given pulse sequence is repeated before any parameter is changed.
MIimaging_frequency
Precession frequency in Hz of the imaged nucleus.
MIimaged_nucleus
String specifying the nucleus that is resonant at the imaging frequency.
MIradionuclide
String specifying the isotope administered.
MIcontrast_agent
String identifying the contrast or bolus agent.
MIradionuclide_halflife
Half-life of radionuclide in seconds.
MItracer
String identifying tracer labelled with radionuclide that was injected.
MIinjection_time
String giving time (and date) of injection.
MIinjection_year
Integer giving year of injection.
MIinjection_month
Integer giving month (1-12) of injection.
MIinjection_day
Integer giving day (1-31) of injection.
MIinjection_hour
Integer giving hour (0-23) of injection.
MIinjection_minute
Integer giving minute (0-59) of injection.
MIinjection_seconds
Floating-point value giving seconds of injection.
MIinjection_length
Length of time of injection (in seconds).
MIinjection_dose
Total dose of radionuclide or contrast agent injected (in units specified by
MIdose_units
).
MIdose_units
String giving units of dose.
MIinjection_volume
Volume of injection in mL.
MIinjection_route
String identifying administration route of injection.
NetCDF routines
[edit | edit source]Because it is necessary to use NetCDF routines to access MINC files, a brief description of all NetCDF routines is provided here. For more information, see the NetCDF User's Guide. Note that the header file netcdf.h is automatically included by the header file minc.h.
Error handling
[edit | edit source]If an error occurs, the default behaviour is to print an error message and exit. It is possible to change this behaviour by modifying the value of the global variable ncopts. The default setting is
ncopts = NC_VERBOSE | NC_FATAL;
which means print error messages and exit when an error occurs. To get error messages without having fatal errors, set
ncopts = NC_VERBOSE;
For neither error messages nor fatal errors, set
ncopts = 0;
In these last two cases, the calling routine should check the function value returned by
each call to a NetCDF function. All routines return an integer value. If the value is
-1
(MI_ERROR
), then an error has occurred. The
value of the global variable ncerr
gives more information on the type
of error (see file netcdf.h
for error codes).
NetCDF file operations
[edit | edit source]nccreate
: Create the file specified by path
. The
argument cmode
must have a value of either
NC_CLOBBER
or NC_NOCLOBBER
. The return value is
an identifier for the NetCDF file and is used by subsequent NetCDF function calls.
int nccreate(char* path,int cmode);
ncopen
: Open the file specified by path
.
mode
must have value NC_NOWRITE
or
NC_WRITE
. The return value is a NetCDF file identifier.
int ncopen(char* path,int mode);
ncredef
: Put an open file into define mode.
int ncredef(int cdfid);
ncendef
: Put file into data mode.
int ncendef(int cdfid);
ncclose
: Close a NetCDF file.
int ncclose(int cdfid);
ncinquire
: Inquire about the number of dimensions in a file, the
number of variables, the number of global attributes or the id of the unlimited record
dimension. Passing a NULL value for any of the pointers means do not return the associated
value.
int ncinquire(int cdfid,int* ndims,int* nvars,int* natts,int* recdim);
ncsync
: Synchronize an open file to disk.
int ncsync(int cdfid);
ncabort
: Abort any changes to the file if it is in define mode.
int ncabort(int cdfid);
ncsetfill
: When ncendef
is called, all variables
are filled with a fill value by default. To turn this off, call this routine with
fillmode
set to NC_NOFILL
(to turn it back on,
use NC_FILL
).
int ncsetfill(int cdfid,int fillmode);
Dimension operations
[edit | edit source]ncdimdef
: Define a dimension with a name and a length. The return
value is a dimension id to be used in subsequent calls.
int ncdimdef(int cdfid,char* name,long length);
ncdimid
: Get a dimension id from a name.
int ncdimid(int cdfid,char* name);
ncdiminq
: Inquire about a dimension (name or length).
int ncdiminq(int cdfid,int dimid,char* name,long* length);
ncdimrename
: Rename a dimension.
int ncdimrename(int cdfid,int dimid,char* name);
Variable operations
[edit | edit source]ncvardef
: Define a variable by name, giving its datatype, number of
dimensions and the dimension id's that subscript the variable. Returns a variable id to be
used in subsequent calls.
int ncvardef(int cdfid,char* name,nc_type datatype,int ndims,int dim[]);
ncvarid
: Get a variable id from a name.
int ncvarid(int cdfid,char* name);
ncvarinq
: Inquire about a variable. Any NULL pointers mean do not
return the associated value. It is possible to get the variable name, type, number of
dimensions, dimension id's and number of attributes.
int ncvarinq(int cdfid,int varid,char* name,nc_type* datatype,int* ndims,
int dim[],int* natts);
ncvarput1
: Store a single value at the coordinate specified by
coords
. value
must be of the correct data type.
int ncvarput1(int cdfid,int varid,long coords[],void* value);
ncvarget1
: Get a single value from the coordinate specified by
coords.
int ncvarget1(int cdfid,int varid,long coords[],void* value);
ncvarput
: Put a hyperslab (multi-dimensional rectangle) of values
starting at start
with edge lengths given by
count
. For the C interface, the last dimension varies fastest. Values
must be of the correct type.
int ncvarput(int cdfid,int varid,long start[],long count[],void* value);
ncvarget
: Get a hyperslab (multi-dimensional rectangle) of values
starting at start
with edge lengths given by
count
. For the C interface, the last dimension varies fastest. Values
must be of the correct type.
int ncvarget(int cdfid,int varid,long start[],long count[],void* value);
ncvarrename
: Rename a variable.
int ncvarrename(int cdfid,int varid,char* name);
nctypelen
: Get the length (in bytes) of a data type.
int nctypelen(nc_type datatype);
Attribute operations
[edit | edit source]ncattput
: Store an attribute by name with variable
varid
. The type and length of the attribute must be specified.
int ncattput(int cdfid,int varid,char* name,nc_type datatype,int len,
void* value);
ncattinq
: Inquire about an attribute by name. Can get either type or
length.
int ncattinq(int cdfid,int varid,char* name,nc_type* datatype,int* len);
ncattget
: Get an attribute's value by name.
int ncattget(int cdfid,int varid,char* name,void* value);
ncattcopy
: Copy an attribute from one variable to another.
int ncattcopy(int incdf,int invar,char* name,int outcdf,int outvar);
ncattname
: Get the name of an attribute from its number. The number
is not an id, but can change as the number of attributes associated with a variable
changes. Attribute numbers run from 0 to natts-1.
int ncattname(int cdfid,int varid,int attnum,char* name);
ncattrename
: Rename an attribute.
int ncattrename(int cdfid,int varid,char* name,char* newname);
ncattdel
: Delete an attribute.
int ncattdel(int cdfid,int varid,char* name);
MINC routines
[edit | edit source]Error handling for MINC routines is the same as for NetCDF functions, with the exception that
routines returning pointers will return NULL
instead of
MI_ERROR
when an error occurs. Error codes (returned in
ncerr
) can be found in the header file minc.h.
General convenience functions
[edit | edit source]miexpand_file
: Routine to expand a minc file that has been compressed
with compress, pack, gzip or zip (using gunzip, zcat or pcat). The name of the temporary
minc file is returned -- this string must be freed by the caller. If the file specified by
path
is not compressed, then its name is returned.
*create_tempfile
is set to TRUE if a temporary file is created (and
the caller needs to delete the file), FALSE if the original file name is returned. If
tempfile is NULL, then the routine generates its own temporary file name, otherwise, the
user provided name is used. If header_only
is TRUE, then the routine
will expand only enough of the file to read the header.
public char *miexpand_file(char *path, char *tempfile, int header_only,
int *created_tempfile);
miopen
: Like ncopen
, but will temporarily
uncompress files (compress, pack, gzip, zip) opened with mode
NC_NOWRITE
.
public int miopen(char *path, int mode);
micreate
: Like nccreate
. May be enhanced in the
future.
public int micreate(char *path, int cmode);
miclose
: Like ncclose
, but finishes up for
miopen
and micreate
.
public int miclose(int cdfid);
miattget
: Like ncattget
, but the caller
specifies the desired numeric type and maximum number of values to get. Type is specified
with datatype
(the sign is the default for the type:
MI_UNSIGNED
for NC_BYTE
and
MI_SIGNED
otherwise). max_length
gives the
maximum number of values to get and att_length
returns the number of
values actually read. An error will occur if the attribute type is not numeric.
public int miattget(int cdfid, int varid, char *name, nc_type datatype,
int max_length, void *value, int *att_length);
miattget1
: Like miattget
, but only one value is
returned. If there is more than one value, an error occurs.
public int miattget1(int cdfid, int varid, char *name, nc_type datatype,
void *value);
miattgetstr
: Gets a string value from an attribute.
maxlen
gives the maximum number of characters to be returned
(including the terminating '\0'
). The string is written to the array
specified by value and a pointer to the string is returned.
public char *miattgetstr(int cdfid, int varid, char *name,
int maxlen, char *value);
miattputint
: Write an integer attribute.
public int miattputint(int cdfid, int varid, char *name, int value);
miattputdbl
: Write a double precision attribute.
public int miattputdbl(int cdfid, int varid, char *name, double value);
miattputstr
: Write a string attribute.
public int miattputstr(int cdfid, int varid, char *name, char *value);
mivarget
: Like ncvarget
, but the caller
specifies the desired numeric type and sign (either MI_SIGNED
or
MI_UNSIGNED
).
public int mivarget(int cdfid, int varid, long start[], long count[],
nc_type datatype, char *sign, void *values);
mivarget1
: Like ncvarget1
, but the caller
specifies the desired numeric type and sign.
public int mivarget1(int cdfid, int varid, long mindex[],
nc_type datatype, char *sign, void *value);
mivarput
: Like ncvarput
, but the caller
specifies the numeric type and sign of the values being passed.
public int mivarput(int cdfid, int varid, long start[], long count[],
nc_type datatype, char *sign, void *values);
mivarput1
: Like ncvarput1
, but the caller
specifies the numeric type and sign of the values being passed.
public int mivarput1(int cdfid, int varid, long mindex[],
nc_type datatype, char *sign, void *value);
miset_coords
: Set nvals
values of the coordinate
vector coords
to value
. A pointer to
coords
is returned.
public long *miset_coords(int nvals, long value, long coords[]);
mitranslate_coords
: Translates the coordinate vector
incoords
for subscripting variable invar
of file
cdfid
to vector outcoords
for subscripting
variable outvar
. This is useful when two variables have similar
dimensions, but not necessarily the same order of dimensions. If invar
has a dimension that is not in outvar
, then the corresponding
coordinate is ignored. If outvar
has a dimension that is not in
invar
, then the corresponding coordinate is not modified. A pointer to
outcoords
is returned.
public long *mitranslate_coords(int cdfid,
int invar, long incoords[],
int outvar, long outcoords[]);
micopy_all_atts
: Copy all of the attributes of one variable to
another (possibly across files).
public int micopy_all_atts(int incdfid, int invarid,
int outcdfid, int outvarid);
micopy_var_def
: Copy a variable definition (including attributes)
from one file to another. outcdfid
must be in define mode. The id of
the newly created variable is returned.
public int micopy_var_def(int incdfid, int invarid, int outcdfid);
micopy_var_values
: Copy a variable's values from one file to another.
incdfid
and outcdfid
must be in data mode.
public int micopy_var_values(int incdfid, int invarid,
int outcdfid, int outvarid);
micopy_all_var_defs
: Copy all variable definitions from one file to
another, excluding a list of variables. The list of nexclude
variable
id's is given in excluded_vars
. outcdfid
must be
in define mode.
public int micopy_all_var_defs(int incdfid, int outcdfid, int nexclude,
int excluded_vars[]);
micopy_all_var_values
: Copy all variable values from one file to
another, excluding a list of variables. The list of nexclude
variable
id's is given in excluded_vars
. outcdfid
must be
in data mode.
public int micopy_all_var_values(int incdfid, int outcdfid, int nexclude,
int excluded_vars[]);
MINC specific convenience functions
[edit | edit source]miget_datatype
: Get the type and sign information for an image
variable. Signed data is indicated by setting is_signed
to
TRUE
; unsigned by FALSE
.
public int miget_datatype(int cdfid, int imgid,
nc_type *datatype, int *is_signed);
miget_default_range
: Returns the default range for a specified type
and sign.
public int miget_default_range(nc_type datatype, int is_signed,
double default_range[]);
miget_valid_range
: Gets the valid range information for an image
variable. This function handles potential type differences between the
valid_range
attribute and the image data. These differences
(particularly float images with double valid_range
) could otherwise
lead to problems in properly identifying invalid data.
public int miget_valid_range(int cdfid, int imgid, double valid_range[]);
miset_valid_range
: Sets the valid range information for an image
variable. This function follows the NetCDF convention of having both variable data and
valid_range
attribute with the same type.
public int miset_valid_range(int cdfid, int imgid, double valid_range[]);
miget_image_range
: Gets the maximum real range of the image data
based on the image-min and image-max variables.
public int miget_image_range(int cdfid, double image_range[]);
mivar_exists
: Tests for the existence of a variable. Returns true if
the variable exists.
public int mivar_exists(int cdfid, char *varname);
miattput_pointer
: Create an attribute name
in
the variable varid
that points to the variable
ptrvarid
.
public int miattput_pointer(int cdfid, int varid, char *name, int ptrvarid);
miattget_pointer
: Returns the variable id pointed to by attribute
name
of variable varid
.
public int miattget_pointer(int cdfid, int varid, char *name);
miadd_child
: Add the name of variable
child_varid
to the MIchildren
attribute of
variable parent_varid
and set the MIparent
attribute of variable child_varid
to the name of variable
parent_varid
. If the attributes do not exist, they are created. The
names in the attribute MIchildren
are separated by newlines.
public int miadd_child(int cdfid, int parent_varid, int child_varid);
micreate_std_variable
: Create any of the standard MINC variables and
set some attributes. Called in the manner of ncvardef
. The id of the
newly created variable is returned. For all variables, attributes
MIvarid
, MIvartype
and
MIversion
are all set. For dimension and dimension width variables,
MIspacing
is set to MI_REGULAR
if the number of
dimensions is zero and MI_IRREGULAR
otherwise. For dimension
variables, MIalignment
is set to MI_CENTRE
unless
the variable is MItime
, then it is set to
MI_START
. As well, MIcomments is set to a string describing the
direction of the world coordinates of spatial dimensions. For dimension width variables,
MIfiltertype
is set to MI_SQUARE
. For
MIimage
and for MIimagemax
and
MIimagemin
, dimensions are checked to ensure that the last two do not
vary over image dimensions and attribute pointers from MIimage
are
created to point to the other two.
public int micreate_std_variable(int cdfid, char *name, nc_type datatype,
int ndims, int dim[]);
micreate_group_variable
: Like
micreate_std_variable
, but ndims
is always set to
zero and the datatype is NC_INT
. The id of the newly created variable
is returned.
public int micreate_group_variable(int cdfid, char *name);
Image conversion variable functions
[edit | edit source]miicv_create
: Create an image conversion variable and set the
defaults -- an icv identifier is returned for later use (or MI_ERROR
if an error occurs). The old limit of MI_MAX_NUM_ICV
icv's that can
exist at one time has been removed, although the definition remains.
public int miicv_create();
miicv_free
: Free an image conversion variable.
public int miicv_free(int icvid);
miicv_setdbl
: Set a numeric icv property to a double value.
public int miicv_setdbl(int icvid, int icv_property, double value);
miicv_setint
: Set a numeric icv property to an integer value.
public int miicv_setint(int icvid, int icv_property, int value);
miicv_setlong
: Set a numeric icv property to a long integer value.
public int miicv_setlong(int icvid, int icv_property, long value);
miicv_setstr
: Set a string icv property.
public int miicv_set(int icvid, int icv_property, char *value);
miicv_inqdbl
: Inquire about a numeric icv property.
value
points to the double precision variable in which the value
should be returned.
public int miicv_inqdbl(int icvid, int icv_property, double *value);
miicv_inqint
: Inquire about a numeric icv property.
value
points to the integer variable in which the value should be
returned.
public int miicv_inqint(int icvid, int icv_property, int *value);
miicv_inqlong
: Inquire about a numeric icv property.
value
points to the long integer variable in which the value should be
returned.
public int miicv_inqlong(int icvid, int icv_property, long *value);
miicv_inqstr
: Inquire about a string icv property.
value
points to the character array in which the value should be
returned. The calling routine must allocate enough space for the return string.
public int miicv_inqstr(int icvid, int icv_property, char *value);
miicv_attach
: Attach a MINC file and image variable to an icv. Note
that icv properties cannot be modified while a variable is attached to the icv. If a
variable is already attached to the icv, then it is automatically detached. The file
icvid
must be in data mode.
public int miicv_attach(int icvid, int cdfid, int varid);
miicv_ndattach
: Like miicv_attach
but no
dimension conversion facilities are available (much like setting
MI_ICV_DO_DIM_CONV
to FALSE
). This avoids linking
in all of the dimension conversion routines when they are not needed (for machines where
memory may be a concern).
public int miicv_ndattach(int icvid, int cdfid, int varid);
miicv_detach
: Detach a variable from an icv.
public int miicv_detach(int icvid);
miicv_get
: Get a hyperslab of values from a variable through an icv.
public int miicv_get(int icvid, long start[], long count[], void *values);
miicv_put
: Put a hyperslab of values to a variable through an icv.
public int miicv_put(int icvid, long start[], long count[], void *values);
Image conversion variable properties
[edit | edit source]MI_ICV_TYPE
(type nc_type
) : Specifies the type of
values that the user wants. Modifying this property automatically causes
MI_ICV_VALID_MAX
and MI_ICV_VALID_MIN
to be set to
their default values. Default = NC_SHORT
.
MI_ICV_SIGN
(type char *
) : Specifies the sign of
values that the user wants (irrelevant for floating point types). Modifying this property
automatically causes MI_ICV_VALID_MAX
and
MI_ICV_VALID_MIN
to be set to their default values. Default =
MI_SIGNED
.
MI_ICV_DO_RANGE
(type int
) : When
TRUE
, range conversions (for valid max and min and for value
normalization) are done. When FALSE
, values are not modified. Default =
TRUE
.
MI_ICV_VALID_MAX
(type double
) : Valid maximum value
(ignored for floating point types). Default = maximum legal value for type and sign (1.0 for
floating point types).
MI_ICV_VALID_MIN
(type double
) : Valid minimum value
(ignored for floating point types). Default = minimum legal value for type and sign (1.0 for
floating point types).
MI_ICV_DO_NORM
(type int
) : If
TRUE
, then normalization of values is done (see user guide for details of
normalization). Default = FALSE
.
MI_ICV_USER_NORM
(type int
) : If
TRUE
, then the user specifies the normalization maximum and minimum. If
FALSE
, values are taken as maximum and minimum for whole image variable.
Default = FALSE
.
MI_ICV_IMAGE_MAX
(type double
) : Image maximum for
user normalization. Default = 1.0.
MI_ICV_IMAGE_MIN
(type double
) : Image minimum for
user normalization. Default = 0.0.
MI_ICV_NORM_MAX
(type double
) : Read-only value
giving the user image maximum when doing normalization (either the maximum in the variable or
the user specified maximum).
MI_ICV_NORM_MIN
(type double
) : Read-only value
giving the user image minimum when doing normalization (either the minimum in the variable or
the user specified minimum).
MI_ICV_DO_FILLVALUE
(type int
) : If set to
TRUE
, then range checking is done on input and values that are out of
range (value in the file less than MIvalid_min
or greater than
MIvalid_max
) are set to the value of
MI_ICV_FILLVALUE
. Default = FALSE
.
MI_ICV_FILLVALUE
(type double
) : Value to use when
pixels are out of range (on input only). This value is written to user's buffer directly
without any scaling. Default = -DBL_MAX
.
MI_ICV_DO_DIM_CONV
(type int
) : If set to
TRUE
, then dimension conversions may be done. Default =
FALSE
.
MI_ICV_DO_SCALAR
(type int
) : If
TRUE
, then if MIvector_dimension
is the fastest
varying dimension of the variable, elements are averaged and the icv behaves as though this
dimension did not exist. Default = TRUE
.
MI_ICV_XDIM_DIR
(type int
) : Indicates the desired
orientation of the x image dimensions (MIxspace
and
MIxfrequency
). Values can be one of MI_ICV_POSITIVE
,
MI_ICV_NEGATIVE
or MI_ICV_ANYDIR
. A positive
orientation means that the MIstep
attribute of the dimension is positive.
MI_ICV_ANYDIR
means that no flipping is done. Default =
MI_ICV_POSITIVE
.
MI_ICV_YDIM_DIR
(type int
) : Indicates the desired
orientation of the y image dimensions. Default = MI_ICV_POSITIVE
.
MI_ICV_ZDIM_DIR
(type int
) : Indicates the desired
orientation of the z image dimensions. Default = MI_ICV_POSITIVE
.
MI_ICV_ADIM_SIZE
(type long
) : Specifies the desired
size of the fastest varying image dimension. A value of MI_ICV_ANYSIZE
means that the actual size of the dimension should be used. Default =
MI_ICV_ANYSIZE
.
MI_ICV_BDIM_SIZE
(type long
) : Specifies the desired
size of the second image dimension. Default = MI_ICV_ANYSIZE
.
MI_ICV_KEEP_ASPECT
(type int
) : If
TRUE
, then image dimensions are resized by the same amount so that aspect
ratio is maintained. Default = TRUE
.
MI_ICV_ADIM_STEP
(type double
) : Read-only property
that gives the equivalent of attribute MIstep
for the first (fastest
varying) image dimension after dimension conversion.
MI_ICV_BDIM_STEP
(type double
) : Read-only property
that gives the equivalent of attribute MIstep
for the second image
dimension after dimension conversion.
MI_ICV_ADIM_START
(type double
) : Read-only property
that gives the equivalent of attribute MIstart
for the first (fastest
varying) image dimension after dimension conversion.
MI_ICV_BDIM_START
(type double
) : Read-only property
that gives the equivalent of attribute MIstart
for the second image
dimension after dimension conversion.
MI_ICV_NUM_IMGDIMS
(type int
) : Specifies the number
of image dimensions used in dimension conversions. Default = 2.
MI_ICV_DIM_SIZE
(type long
) : Specifies the desired
size of an image dimension. The number of the dimension to be changed should be added to the
property (adding zero corresponds to the fastest varying dimension). Default =
MI_ICV_ANYSIZE
.
MI_ICV_DIM_STEP
(type double
) : Read-only property
that gives the equivalent of attribute MIstep
for the an image dimension
after dimension conversion. The number of the dimension to be queried should be added to the
property (adding zero corresponds to the fastest varying dimension).
MI_ICV_DIM_START
(type double
) : Read-only property
that gives the equivalent of attribute MIstart
for an image dimension
after dimension conversion. The number of the dimension to be queried should be added to the
property (adding zero corresponds to the fastest varying dimension).
MI_ICV_NUM_DIMS
(type int
) : Read-only property that
gives the number of dimensions of the image variable, taking into account the conversion of
vector images into scalar images.
MI_ICV_CDFID
(type int
) : Read-only property that
gives the id of the currently attached NetCDF file, or MI_ERROR
if no
file is attached.
MI_ICV_VARID
(type int
) : Read-only property that
gives the id of the currently attached NetCDF variable, or MI_ERROR
if
no variable is attached.
MI_ICV_MAXVAR
(type char *
) : String property
specifying the name of the variable that gives the image maximum. Default =
MIimagemax
.
MI_ICV_MINVAR
(type char *
) : String property
specifying the name of the variable that gives the image minimum. Default =
MIimagemin
.
Known bugs
[edit | edit source]For dimension conversion with image conversion variables, the values of
MI_ICV_DIM_START
, MI_ICV_ADIM_START
and
MI_ICV_BDIM_START
are computed assuming that
MIalignment
is equal to MI_CENTRE
.