IO basics

On this page you will find the basics about loading and saving medical images with MedPy. All examples use IPython, which I really recommend over the standard Python console. Please see [here](./Installing-MedPy-from-source-(Ubuntu)#wiki-installing-the-requirements) on how to install it.

Getting a medical image

First, you'll need a medical image. If you've followed the installation instructions, your MedPy installation will be able to handle NIfTI, Analyze and DICOM file format. See the supported image formats list. If you don't have any image in these formats ready, take a look at the NIH pages and get e.g. the avg152T1_RL_nifti.nii.gz volume (an average MRI T1 brain). Place it somewhere you can find it and give it a nicer name (e.g. image.nii.gz).

Loading an image

We start the Python console with ipython (resp. python). First, we import the load-function:

 from medpy.io import load

load is a simple file loader function, that returns two parameters: (1) a numpy ndarray and (2) a image header object. All MedPy methods come with a documentation string, that you can display using

 load?

We now load our image by calling

 image, header = load('image.nii.gz')

of course you'll have to adapt the path to the image.

But what did we got now?

 type(image)
 > numpy.ndarray

shows us that the image is a numpy ndarray object, which is essentially a matrix or data container. MedPy takes the view that an image is not different from any matrix and such the great numerical powers of NumPy and SciPy become available for medical image processing.

What about our second object, the header? This object is used to carry the meta-information about the image (e.g. the voxel spacing and offset). It's type depends on the 3rd party library used to load the image.

 type(header)
 > nibabel.nifti1.Nifti1Image # but can be another type

Modify the image

Now let us modify the image with a simple operation. Let us say, we want to set all values above the images mean intensity to the highest intensity value. With the amazing power of Python/NumPy, we simply call

 image[image > image.mean()] = image.max()

Don't worry if you do not understand this yet. You will get to know more about manipulating matrices in the tutorials on this page and there is a lot of help about NumPy on the web.

Save the image

Finally, we want to save our modified image back into a file. First load the save-function and take a look at its description

 from medpy.io import save
 save?

The profile tells us that the function expects an image (in the form of a numpy ndarray), a file name where to save it (by which ending the target image type is identified), a header object with the meta-information. Thus, we can save our image using

 save(image, "modified_image.nii", header)

in the current directory as an uncompressed NIfTI image.

Taking a look at the image

If you are not familiar with medical images, I would recommend you ITKSnap as a viewer, which is fast, easy to handle and can open virtually all image formats. On Ubuntu systems, simply call apt-get install itksnap to get it.

Now open the original and the modified images in ITKSnap or the image viewer of your choice. You see the changes? An isn't it easy to do medical image processing with Python? If you are not yet convinced, take a look at the examples of basic image manipulation.