MINC/Tutorials/Programming01

The MINC version of hello world.

Any introduction to a programming language worth its salt will start with a hello world example. MINC, of course, is not its own programming language; it is a C library. So this tutorial will assume some basic knowledge of C, and will guide the reader through opening and reading MINC volumes and then move on to more advanced topics, discussing some of the peculiarities of the MINC file format along the way.

All code examples will work with the MINC library version 2.x (tested on 2.0.13). There are two other libraries for accessing data in MINC files: the MINC version 1.x library, and volume_io. The vast majority of currently existing code uses either of those two; MINC2 is a new library recently introduced. One important difference is that MINC2 can only read version 2.x files; older files have to be converted using the mincconvert command.

The code will be split up and commented upon in pieces for all these tutorials. The unadulterated source code can be found at the end of each tutorial.

The code compiles in the following way (assuming that the minc-toolkit-v2 is installed in /opt/minc/1.9.15):

gcc -g -o minc2_tutorial1  -I /opt/minc/1.9.15/include -L /opt/minc/1.9.15/lib -lminc2 -lhdf5 -lniftiio -lznz -lz -lm -ldl -lrt -lnetcdf minc2_tutorial1.c

Hello World

So on to the hello world example. Here we open a MINC2 volume and get the value of the first voxel.

#include <minc2.h>
#include <stdio.h>

The include files - only minc2.h is needed for getting all the minc2 functionality.

int main(int argc, char **argv) {
  mihandle_t    minc_volume;
  double        voxel;
  int           result;
  unsigned long location[3];

The data types: the only non-standard one here is mihandle_t, a struct which will be needed by almost all minc2 functions that need to do something or other on a minc2 volume.

  /* open the volume - first and only command line argument */
  result = miopen_volume(argv[1], MI2_OPEN_READ, &minc_volume);
  /* check for error on opening */
  if (result != MI_NOERROR) {
    fprintf(stderr, "Error opening input file: %d.\n", result);
  }

And here is the first minc2 command: miopen_volume, which you guessed it, opens a minc2 volume specified by a C string, an indicator of whether the file should be open for reading or writing (reading in this case), and the address of the mihandle_t struct which, if the operation succeeded, will then hold important information about the volume.

  /* get the first voxel in the image */
  location[0] = location[1] = location[2] = 0;
  miget_real_value(minc_volume, location, 3, &voxel);
  printf("Hello MINC2 - first voxel was: %f\n", voxel);

  return(0);
}

Now we get the first voxel, specified by volume coordinates 0,0,0. We are just looking at three-dimensional volumes here, so we created an unsigned long array of three elements, and assigned them all to be 0. We then call the miget_real_value function, specifying the volume handle to get the voxel from, the location (the unsigned long array), the number of dimensions in the file, and the address of the double to which to assign the voxel value. And then we print it to the terminal.

And that was it - the first and quite simple MINC2 program, really just needing two library calls: opening the volume and getting the voxel.

code

#include <minc2.h>
#include <stdio.h>

int main(int argc, char **argv) {
  mihandle_t    minc_volume;
  double        voxel;
  int           result;
  misize_t      location[3];
  
  /* open the volume - first and only command line argument */
  result = miopen_volume(argv[1], MI2_OPEN_READ, &minc_volume);
  /* check for error on opening */
  if (result != MI_NOERROR) {
    fprintf(stderr, "Error opening input file: %d.\n", result);
  }

  /* get the first voxel in the image */
  location[0] = location[1] = location[2] = 0;
  miget_real_value(minc_volume, location, 3, &voxel);
  printf("Hello MINC2 - first voxel was: %f\n", voxel);

  return(0);
}