MINC/Tutorials/Programming05

Working with hyperslabs
The previous tutorial stepped through every voxel of a volume, added 1 to it, and wrote the output back to the same volume. Here we will improve on that example: the output will be written to a new volume, and we will use hyperslabs for the data processing.

A hyperslab is a central concept in minc. It allows you to pull an arbitrary (but contiguous) chunk of data out of a volume, do something to it, and write it back to the volume. This is a lot faster than individually getting each voxel; it does, however, require more memory.

So on to the example: this code takes a volume, creates a copy of it the same in every way except for adding 1 to each voxel. The new volume will also always use global scaling, regardless of whether the input had slice scaling or not.

So far, so good - none of this code should be new to you. Do note the creation of two new variables for the new volume and new dimensions.

Here we allocate memory for the dimensions of the new volume, and copy the dimension definitions from the old volume.

The memory for the hyperslab is allocated and the hyperslab obtained - in this case the hyperslab is the entire volume. The key function is miget_real_value_hyperslab, which takes five arguments: the minc volume handle, the type you want the data to be in, an array of starts (all zeroes in this case), an array of counts( the volume sizes), and the address of where to write the data.

And now we loop over every voxel in the hyperslab (note how it is dealt with as a one-dimensional array), making sure to keep the modified image min and max.

We then create the actual volume using micreate_volume. It takes seven arguments: the filename, the number of dimensions, an array of the actual dimensions (created through the copy operation above), the data type (set to unsigned byte here), the data class, special volume properties (set to NULL here), and the address of the volume handle.

Now we make sure that the data is created inside the minc volume handle using micreate_volume_image.

We then set the valid range - from 0 to 255 since this is unsigned byte data - and the volume range, which was determined by keeping track of the min and max when looping over voxels. The hyperslab is the placed back into the volume using miset_real_value_hyperslab, which takes the exact same arguments as miget_real_value_hyperslab.

And finally we close the volumes, free the allocated memory, and exit.