1 /** \file minc2.h 2 * \brief MINC 2.0 public constants, types, and definitions. 3 */ 4 5 #ifndef _MINC2_H_ /* Avoid multiple inclusions */ 6 #define _MINC2_H_ 1 7 8 #ifdef __cplusplus 9 extern "C" { /* Hey, Mr. Compiler - this is "C" code! */ 10 #endif /* __cplusplus defined */ 11 12 /************************************************************************ 13 * CONSTANTS 14 ************************************************************************/ 15 16 #ifndef MI_NOERROR 17 /** Generic return code for successful operations. */ 18 #define MI_NOERROR 0 19 #endif /* MI_NOERROR not defined */ 20 21 #ifndef MI_ERROR 22 /** Generic return code for operations which fail for any reason. */ 23 #define MI_ERROR (-1) 24 #endif /* MI_ERROR not defined */ 25 26 #define MI_NATIVE "native____" 27 #define MI_TALAIRACH "talairach_" 28 #define MI_CALLOSAL "callosal__" 29 30 #ifndef TRUE 31 #define TRUE 1 32 #endif /* TRUE */ 33 34 #ifndef FALSE 35 #define FALSE 0 36 #endif /* FALSE */ 37 38 /** World spatial coordinates should always have this structure. 39 */ 40 #define MI2_3D 3 41 #define MI2_X 0 42 #define MI2_Y 1 43 #define MI2_Z 2 44 45 /** Dimension attribute values. 46 */ 47 #define MI_DIMATTR_ALL 0 48 #define MI_DIMATTR_REGULARLY_SAMPLED 0x1 49 #define MI_DIMATTR_NOT_REGULARLY_SAMPLED 0x2 50 51 /** Maximum length of a standard string. 52 */ 53 #define MI2_CHAR_LENGTH 128 54 55 /** Maximum number of dimensions a variable can have. 56 */ 57 #define MI2_MAX_VAR_DIMS 100 58 59 #define MI2_CHUNK_SIZE 32 /* Length of chunk, per dimension */ 60 #define MI2_DEFAULT_ZLIB_LEVEL 4 61 #define MI2_MAX_ZLIB_LEVEL 9 62 63 #define MI2_MAX_PATH 128 64 #define MI2_MAX_RESOLUTION_GROUP 16 65 66 #define MI2_OPEN_READ 0x0001 67 #define MI2_OPEN_RDWR 0x0002 68 69 #define MI_VERSION_2_0 "MINC Version 2.0" 70 /************************************************************************ 71 * ENUMS, STRUCTS, and TYPEDEFS 72 ************************************************************************/ 73 /* These structure declarations exist to allow the following typedefs to 74 * work. Since the details of these structures are not meant to be public, 75 * the actual structure definitions are in minc2_private.h 76 */ 77 struct mivolprops; 78 struct midimension; 79 struct mivolume; 80 /** \typedef mivolumeprops_t 81 * Opaque pointer to volume properties. 82 */ 83 typedef struct mivolprops *mivolumeprops_t; 84 85 86 /** \typedef midimhandle_t 87 * Opaque pointer to a MINC dimension object. 88 */ 89 typedef struct midimension *midimhandle_t; 90 91 92 /** \typedef mihandle_t 93 * The mihandle_t is an opaque type that represents a MINC file object. 94 */ 95 typedef struct mivolume *mihandle_t; 96 97 98 typedef void *milisthandle_t; 99 100 /** 101 * This typedef used to represent the type of an individual voxel <b>as 102 * stored</b> by MINC 2.0. If a volume is 103 */ 104 typedef enum { 105 MI_TYPE_BYTE = 1, /**< 8-bit signed integer */ 106 MI_TYPE_SHORT = 3, /**< 16-bit signed integer */ 107 MI_TYPE_INT = 4, /**< 32-bit signed integer */ 108 MI_TYPE_FLOAT = 5, /**< 32-bit floating point */ 109 MI_TYPE_DOUBLE = 6, /**< 64-bit floating point */ 110 MI_TYPE_STRING = 7, /**< ASCII string */ 111 MI_TYPE_UBYTE = 100, /**< 8-bit unsigned integer */ 112 MI_TYPE_USHORT = 101, /**< 16-bit unsigned integer */ 113 MI_TYPE_UINT = 102, /**< 32-bit unsigned integer */ 114 MI_TYPE_SCOMPLEX = 1000, /**< 16-bit signed integer complex */ 115 MI_TYPE_ICOMPLEX = 1001, /**< 32-bit signed integer complex */ 116 MI_TYPE_FCOMPLEX = 1002, /**< 32-bit floating point complex */ 117 MI_TYPE_DCOMPLEX = 1003, /**< 64-bit floating point complex */ 118 MI_TYPE_UNKNOWN = -1 /**< when the type is a record */ 119 } mitype_t; 120 121 /** 122 * This typedef is used to represent the class of the MINC file. 123 * 124 * The class specifies the data's interpretation rather than its 125 * storage format. For example, a floating point class implies 126 * that the data may be stored as integers but must nonetheless be 127 * scaled into a "real" range before any mathematical operations 128 * are performed. A label class implies that the values of a voxel 129 * should be considered to represent a symbol, and therefore many 130 * operations on the voxels would be considered meaningless. 131 */ 132 typedef enum { 133 MI_CLASS_REAL = 0, /**< Floating point (default) */ 134 MI_CLASS_INT = 1, /**< Integer */ 135 MI_CLASS_LABEL = 2, /**< Enumerated (named data values) */ 136 MI_CLASS_COMPLEX = 3, /**< Complex (real/imaginary) values */ 137 MI_CLASS_UNIFORM_RECORD = 4, /**< Aggregate datatypes consisting of multiple values of the same underlying type. */ 138 MI_CLASS_NON_UNIFORM_RECORD = 5 /**< Aggregate datatypes consisting of multiple values of potentially differing types (not yet implemented). */ 139 } miclass_t; 140 141 /** Dimensions be members of one of several classes. The "MI_DIMCLASS_ANY" 142 * value is never actually assigned to a dimension. It is used in the 143 * programming interface to specify that an operation should apply to 144 * all dimensions regardless of class. 145 */ 146 typedef enum { 147 MI_DIMCLASS_ANY = 0, /**< Don't care (or unknown) */ 148 MI_DIMCLASS_SPATIAL = 1, /**< Spatial dimensions (x, y, z) */ 149 MI_DIMCLASS_TIME = 2, /**< Time dimension */ 150 MI_DIMCLASS_SFREQUENCY = 3, /**< Spatial frequency dimensions */ 151 MI_DIMCLASS_TFREQUENCY = 4, /**< Temporal frequency dimensions */ 152 MI_DIMCLASS_USER = 5, /**< Arbitrary user-defined dimension */ 153 MI_DIMCLASS_RECORD = 6 /**< Record as dimension */ 154 } midimclass_t; 155 156 /** Dimension order refers to the idea that data can be structured in 157 * a variety of ways with respect to the dimensions. For example, a typical 158 * 3D scan could be structured as a transverse (ZYX) or sagittal (XZY) image. 159 * Since it may be convenient to write code which expects a particular 160 * dimension order, a user can specify an alternative ordering by using 161 * miset_apparent_dimension_order(). This will cause most functions 162 * to return data as if the file was in the apparent, rather than the 163 * file (native) order. 164 */ 165 typedef enum { 166 MI_DIMORDER_FILE = 0, 167 MI_DIMORDER_APPARENT = 1 168 } miorder_t; 169 170 /** Voxel order can be either file (native), or apparent, as set by 171 * the function miset_dimension_apparent_voxel_order(). 172 */ 173 typedef enum { 174 MI_ORDER_FILE = 0, /**< File order */ 175 MI_ORDER_APPARENT = 1 /**< Apparent (user) order */ 176 } mivoxel_order_t; 177 178 /** 179 * Voxel flipping can be specified to either follow the file's native 180 * order, the opposite of the file's order, or it can be tied to the 181 * value of the dimension's step attribute. A value of MI_NEGATIVE 182 * implies that the voxel order should be rearranged such that the step 183 * attribute is negative, a value of MI_POSITIVE implies the opposite. 184 */ 185 typedef enum { 186 MI_FILE_ORDER = 0, /**< no flip */ 187 MI_COUNTER_FILE_ORDER = 1, /**< flip */ 188 MI_POSITIVE = 2, /**< force step value to be positive */ 189 MI_NEGATIVE = 3 /**< force step value to be negative */ 190 } miflipping_t; 191 192 /** Compression type 193 */ 194 typedef enum { 195 MI_COMPRESS_NONE = 0, /**< No compression */ 196 MI_COMPRESS_ZLIB = 1 /**< GZIP compression */ 197 } micompression_t; 198 199 typedef int miboolean_t; 200 201 typedef unsigned int midimattr_t; 202 203 typedef unsigned long misize_t; 204 205 /** 16-bit integer complex voxel. 206 */ 207 typedef struct { 208 short real; /**< Real part */ 209 short imag; /**< Imaginary part */ 210 } miscomplex_t; 211 212 /** 32-bit integer complex voxel. 213 */ 214 typedef struct { 215 int real; /**< Real part */ 216 int imag; /**< Imaginary part */ 217 } miicomplex_t; 218 219 /** 32-bit floating point complex voxel. 220 */ 221 typedef struct { 222 float real; /**< Real part */ 223 float imag; /**< Imaginary part */ 224 } mifcomplex_t; 225 226 /** 64-bit floating point complex voxel. 227 */ 228 typedef struct { 229 double real; /**< Real part */ 230 double imag; /**< Imaginary part */ 231 } midcomplex_t; 232 233 /************************************************************************ 234 * FUNCTION DECLARATIONS 235 ************************************************************************/ 236 237 /* ATTRIBUTE/GROUP FUNCTIONS */ 238 extern int milist_start(mihandle_t vol, const char *path, int flags, 239 milisthandle_t *handle); 240 extern int milist_attr_next(mihandle_t vol, milisthandle_t handle, 241 char *path, int maxpath, 242 char *name, int maxname); 243 extern int milist_finish(milisthandle_t handle); 244 extern int milist_grp_next(milisthandle_t handle, char *path, int maxpath); 245 extern int micreate_group(mihandle_t vol, const char *path, const char *name); 246 extern int midelete_attr(mihandle_t vol, const char *path, const char *name); 247 extern int midelete_group(mihandle_t vol, const char *path, const char *name); 248 extern int miget_attr_length(mihandle_t vol, const char *path, 249 const char *name, int *length); 250 extern int miget_attr_type(mihandle_t vol, const char *path, const char *name, 251 mitype_t *data_type); 252 extern int micopy_attr(mihandle_t vol, const char *path, mihandle_t new_vol); 253 extern int miget_attr_values(mihandle_t vol, mitype_t data_type, 254 const char *path, const char *name, 255 int length, void *values); 256 extern int miset_attr_values(mihandle_t vol, mitype_t data_type, 257 const char *path, const char *name, int length, 258 const void *values); 259 extern int miadd_history_attr(mihandle_t vol, int length, const void *values); 260 /* FREE FUNCTIONS */ 261 extern int mifree_name(char *name_ptr); 262 extern int mifree_names(char **name_pptr); 263 264 /* DATA TYPE/SPACE FUNCTIONS */ 265 extern int miget_data_class(mihandle_t vol, miclass_t *volume_class); 266 extern int miget_data_type(mihandle_t vol, mitype_t *volume_data_type); 267 extern int miget_data_type_size(mihandle_t vol, misize_t *voxel_size); 268 extern int miget_space_name(mihandle_t vol, char **name); 269 extern int miset_space_name(mihandle_t vol, const char *name); 270 271 /* DIMENSION FUNCTIONS */ 272 extern int miget_volume_from_dimension(midimhandle_t dimension, mihandle_t *volume); 273 extern int micopy_dimension(midimhandle_t dim_ptr, midimhandle_t *new_dim_ptr); 274 extern int micreate_dimension(const char *name, midimclass_t dimclass, midimattr_t attr, 275 unsigned int length, midimhandle_t *new_dim_ptr); 276 extern int mifree_dimension_handle(midimhandle_t dim_ptr); 277 extern int miget_volume_dimensions(mihandle_t volume, midimclass_t dimclass, midimattr_t attr, 278 miorder_t order, int array_length, 279 midimhandle_t dimensions[]); 280 extern int miset_apparent_dimension_order(mihandle_t volume, int array_length, midimhandle_t dimensions[]); 281 extern int miset_apparent_dimension_order_by_name(mihandle_t volume, int array_length, char **names); 282 extern int miset_apparent_record_dimension_flag(mihandle_t volume, int record_flag); 283 extern int miget_dimension_apparent_voxel_order(midimhandle_t dimension, miflipping_t *file_order, 284 miflipping_t *sign); 285 extern int miset_dimension_apparent_voxel_order(midimhandle_t dimension, miflipping_t flipping_order); 286 extern int miget_dimension_class(midimhandle_t dimension, midimclass_t *dimclass); 287 extern int miset_dimension_class(midimhandle_t dimension, midimclass_t dimclass); 288 extern int miget_dimension_cosines(midimhandle_t dimension, 289 double direction_cosines[3]); 290 extern int miset_dimension_cosines(midimhandle_t dimension, 291 const double direction_cosines[3]); 292 extern int miset_dimension_description(midimhandle_t dimension, const char *comments); 293 extern int miget_dimension_description(midimhandle_t dimension, char **comments_ptr); 294 extern int miget_dimension_name(midimhandle_t dimension, char **name_ptr); 295 extern int miset_dimension_name(midimhandle_t dimension, const char *name); 296 extern int miget_dimension_offsets(midimhandle_t dimension, unsigned long array_length, 297 unsigned long start_position, double offsets[]); 298 extern int miset_dimension_offsets(midimhandle_t dimension, unsigned long array_length, 299 unsigned long start_position, const double offsets[]); 300 extern int miget_dimension_sampling_flag(midimhandle_t dimension, miboolean_t *sampling_flag); 301 extern int miset_dimension_sampling_flag(midimhandle_t dimension, miboolean_t sampling_flag); 302 extern int miget_dimension_separation(midimhandle_t dimension, 303 mivoxel_order_t voxel_order, 304 double *separation_ptr); 305 extern int miset_dimension_separation(midimhandle_t dimension, 306 double separation); 307 extern int miget_dimension_separations(const midimhandle_t dimensions[], 308 mivoxel_order_t voxel_order, 309 int array_length, 310 double separations[]); 311 extern int miset_dimension_separations(const midimhandle_t dimensions[], int array_length, 312 const double separations[]); 313 extern int miget_dimension_size(midimhandle_t dimension, unsigned int *size_ptr); 314 extern int miset_dimension_size(midimhandle_t dimension, unsigned int size); 315 extern int miget_dimension_sizes(const midimhandle_t dimensions[], int array_length, 316 unsigned int sizes[]); 317 extern int miget_dimension_start(midimhandle_t dimension, 318 mivoxel_order_t voxel_order, 319 double *start_ptr); 320 extern int miset_dimension_start(midimhandle_t dimension, double start_ptr); 321 extern int miget_dimension_starts(const midimhandle_t dimensions[], mivoxel_order_t voxel_order, 322 int array_length, double starts[]); 323 extern int miset_dimension_starts(const midimhandle_t dimensions[], int array_length, 324 const double starts[]); 325 extern int miget_dimension_units(midimhandle_t dimension, char **units_ptr); 326 extern int miset_dimension_units(midimhandle_t dimension, const char *units); 327 extern int miget_dimension_width(midimhandle_t dimension, double *width_ptr); 328 extern int miset_dimension_width(midimhandle_t dimension, double width_ptr); 329 extern int miget_dimension_widths(midimhandle_t dimension, mivoxel_order_t voxel_order, 330 unsigned long array_length, unsigned long start_position, 331 double widths[]); 332 extern int miset_dimension_widths(midimhandle_t dimension, unsigned long array_length, 333 unsigned long start_position, const double widths[]); 334 335 336 /* VOLUME FUNCTIONS */ 337 extern int micreate_volume(const char *filename, int number_of_dimensions, 338 midimhandle_t dimensions[], 339 mitype_t volume_type, 340 miclass_t volume_class, 341 mivolumeprops_t create_props, 342 mihandle_t *volume); 343 extern int micreate_volume_image(mihandle_t volume); 344 extern int miget_volume_dimension_count(mihandle_t volume, midimclass_t dimclass, 345 midimattr_t attr, int *number_of_dimensions); 346 extern int miget_volume_voxel_count(mihandle_t volume, int *number_of_voxels); 347 extern int miopen_volume(const char *filename, int mode, mihandle_t *volume); 348 extern int miclose_volume(mihandle_t volume); 349 350 extern int miget_slice_scaling_flag(mihandle_t volume, 351 miboolean_t *slice_scaling_flag); 352 extern int miset_slice_scaling_flag(mihandle_t volume, 353 miboolean_t slice_scaling_flag); 354 355 /* VOLUME PROPERTIES FUNCTIONS */ 356 extern int minew_volume_props(mivolumeprops_t *props); 357 extern int mifree_volume_props(mivolumeprops_t props); 358 extern int miget_volume_props(mihandle_t vol, mivolumeprops_t *props); 359 extern int miset_props_multi_resolution(mivolumeprops_t props, miboolean_t enable_flag, 360 int depth); 361 extern int miget_props_multi_resolution(mivolumeprops_t props, miboolean_t *enable_flag, 362 int *depth); 363 extern int miselect_resolution(mihandle_t volume, int depth); 364 extern int miflush_from_resolution(mihandle_t volume, int depth); 365 extern int miset_props_compression_type(mivolumeprops_t props, micompression_t compression_type); 366 extern int miget_props_compression_type(mivolumeprops_t props, micompression_t *compression_type); 367 extern int miset_props_zlib_compression(mivolumeprops_t props, int zlib_level); 368 extern int miget_props_zlib_compression(mivolumeprops_t props, int *zlib_level); 369 extern int miset_props_blocking(mivolumeprops_t props, int edge_count, const int *edge_lengths); 370 extern int miget_props_blocking(mivolumeprops_t props, int *edge_count, int *edge_lengths, 371 int max_lengths); 372 extern int miset_props_record(mivolumeprops_t props, long record_length, char *record_name); 373 extern int miset_props_template(mivolumeprops_t props, int template_flag); 374 375 /* SLICE/VOLUME SCALE FUNCTIONS */ 376 extern int miget_slice_max(mihandle_t volume, 377 const unsigned long start_positions[], 378 int array_length, double *slice_max); 379 extern int miset_slice_max(mihandle_t volume, 380 const unsigned long start_positions[], 381 int array_length, double slice_max); 382 extern int miget_slice_min(mihandle_t volume, 383 const unsigned long start_positions[], 384 int array_length, double *slice_min); 385 extern int miset_slice_min(mihandle_t volume, 386 const unsigned long start_positions[], 387 int array_length, double slice_min); 388 extern int miget_slice_range(mihandle_t volume, 389 const unsigned long start_positions[], 390 int array_length, double *slice_max, 391 double *slice_min); 392 extern int miset_slice_range(mihandle_t volume, 393 const unsigned long start_positions[], 394 int array_length, double slice_max, 395 double slice_min); 396 extern int miget_volume_max(mihandle_t volume, double *slice_max); 397 extern int miset_volume_max(mihandle_t volume, double slice_max); 398 extern int miget_volume_min(mihandle_t volume, double *slice_min); 399 extern int miset_volume_min(mihandle_t volume, double slice_min); 400 extern int miget_volume_range(mihandle_t volume, double *slice_max, 401 double *slice_min); 402 extern int miset_volume_range(mihandle_t volume, double slice_max, 403 double slice_min); 404 /* HYPERSLAB FUNCTIONS */ 405 extern int miget_hyperslab_size(mitype_t volume_data_type, int n_dimensions, 406 const unsigned long count[], 407 misize_t *size_ptr); 408 409 extern int miget_hyperslab_normalized(mihandle_t volume, 410 mitype_t buffer_data_type, 411 const unsigned long start[], 412 const unsigned long count[], 413 double min, 414 double max, 415 void *buffer); 416 417 extern int miget_hyperslab_with_icv(mihandle_t volume, 418 int icv, 419 mitype_t buffer_data_type, 420 const unsigned long start[], 421 const unsigned long count[], 422 void *buffer); 423 424 extern int miset_hyperslab_with_icv(mihandle_t volume, 425 int icv, 426 mitype_t buffer_data_type, 427 const unsigned long start[], 428 const unsigned long count[], 429 void *buffer); 430 431 extern int miget_real_value_hyperslab(mihandle_t volume, 432 mitype_t buffer_data_type, 433 const unsigned long start[], 434 const unsigned long count[], 435 void *buffer); 436 437 extern int miset_real_value_hyperslab(mihandle_t volume, 438 mitype_t buffer_data_type, 439 const unsigned long start[], 440 const unsigned long count[], 441 void *buffer); 442 443 extern int miget_voxel_value_hyperslab(mihandle_t volume, 444 mitype_t buffer_data_type, 445 const unsigned long start[], 446 const unsigned long count[], 447 void *buffer); 448 449 extern int miset_voxel_value_hyperslab(mihandle_t volume, 450 mitype_t buffer_data_type, 451 const unsigned long start[], 452 const unsigned long count[], 453 void *buffer); 454 455 456 457 /* CONVERT FUNCTIONS */ 458 extern int miconvert_real_to_voxel(mihandle_t volume, 459 const unsigned long coords[], 460 int ncoords, 461 double real_value, 462 double *voxel_value_ptr); 463 464 extern int miconvert_voxel_to_real(mihandle_t volume, 465 const unsigned long coords[], 466 int ncoords, 467 double voxel_value, 468 double *real_value_ptr); 469 470 extern int miconvert_voxel_to_world(mihandle_t volume, 471 const double voxel[], 472 double world[]); 473 474 extern int miconvert_world_to_voxel(mihandle_t volume, 475 const double world[], 476 double voxel[]); 477 478 extern int miget_real_value(mihandle_t volume, 479 const unsigned long coords[], 480 int ndims, 481 double *value_ptr); 482 483 extern int miset_real_value(mihandle_t volume, 484 const unsigned long coords[], 485 int ndims, 486 double value); 487 extern int miget_voxel_value(mihandle_t volume, 488 const unsigned long coords[], 489 int ndims, 490 double *voxel_ptr); 491 492 extern int miset_voxel_value(mihandle_t volume, 493 const unsigned long coords[], 494 int ndims, 495 double voxel); 496 497 extern int miget_volume_real_range(mihandle_t volume, double real_range[2]); 498 499 extern int miset_world_origin(mihandle_t volume, double origin[MI2_3D]); 500 501 /* VALID functions */ 502 extern int miget_volume_valid_max(mihandle_t volume, double *valid_max); 503 extern int miset_volume_valid_max(mihandle_t volume, double valid_max); 504 extern int miget_volume_valid_min(mihandle_t volume, double *valid_min); 505 extern int miset_volume_valid_min(mihandle_t volume, double valid_min); 506 extern int miget_volume_valid_range(mihandle_t volume, 507 double *valid_max, double *valid_min); 508 extern int miset_volume_valid_range(mihandle_t volume, 509 double valid_max, double valid_min); 510 511 /* RECORD functions */ 512 extern int miget_record_name(mihandle_t volume, char **name); 513 extern int miget_record_length(mihandle_t volume, int *length); 514 extern int miget_record_field_name(mihandle_t volume, int index, char **name); 515 extern int miset_record_field_name(mihandle_t volume, int index, 516 const char *name); 517 518 /* LABEL functions */ 519 extern int midefine_label(mihandle_t volume, int value, const char *name); 520 extern int miget_label_name(mihandle_t volume, int value, char **name); 521 extern int miget_label_value(mihandle_t volume, const char *name, int *value); 522 extern int miget_number_of_defined_labels(mihandle_t volume, int *number_of_labels); 523 extern int miget_label_value_by_index(mihandle_t volume, int idx, int *value); 524 525 #ifdef __cplusplus 526 } 527 #endif /* __cplusplus defined */ 528 529 #endif /* _MINC2_H_ */ 530