EZ Writer Toolbox

The EZ-Writer toolbox provides an integrated suite of IDL programs for reading and writing a variety of medically-oriented image formats. It is used by the Spamalize software package to take care of all image input/output in a uniform and reliable manner.

The following formats are supported for reading:

The following formats can be written by EZ Writer:

There is a specialized program for reading and for writing every supported file format. Each read-program is responsible for:

  1. prompting for a filename if none was passed;
  2. determining if the desired file is in a supported format and can be read;
  3. opening the file(s) and reading the header information;
  4. setting up an array in memory and reading the data into it;
  5. applying all appropriate scaling or calibration factors;
  6. putting the header information and data into an EZ structure, and;
  7. returning the EZ structure to the caller.

There is an uber-program, "ez_read_img.pro" that can be used in a program if you are not sure (or don't care) what the format of the file is. This program is responsible for determining the type (format) of the indicated file, and passing the work of reading it off to the appropriate program. It is most convenient to use this program when writing a larger program, since then you can read in data from a variety of formats without having to modify your code whenever a new file format comes along.

The structure that the header information and data get placed into are the key to using "ez_read_img" as a hands-off interface to the actual read-programs. All of the information needed to display and work with the data is stored in the structure, which is defined in "ez_struct.pro". It contains information such as the number of dimensions, size of each dimension, pixel dimensions, original data bits/pixel, time-frame information (for 4D files), etc. In addition, the structure contains a pointer to the data.

Rather than actually containing the data itself, the structure contains a pointer to it. This has several benefits: the size of the data does not have to be known before defining the structure, and in fact can change after the structure has been created; and it is easy to pass the relatively small structure between programs since the data location remains unchanged. One repurcussion of this is that the pointer to the data must be explicitly destroyed. Merely destroying the structure will leave the data "hanging" or inaccessible in memory; the data as well as the pointer and structure containing the pointer must be destroyed by calling the program "ez_destroy" and passing the name of the EZ-structure as the only argument. This is easy to do, but it is also somewhat easy to forget to include in your program.

When a file is read, the EZ Writer program determines how many dimensions it has. It is up to the caller program to figure out what to do with it. Usually, the data can remain in the form of a pointer. When the data need to be accessed, the pointer is dereferenced to get at the data. Many Spamalize programs transfer the data from the EZ structure into their own local structure or pointer. Examples include BrainMaker, BrainSqueezer, and the PET quantitation programs.

Here is an example of how the EZZ read/write procedures are used in a larger program:

; Read the image: 
img_old = EZ_READ_IMG(fn, ERR_STATUS=err)

; Take the absolute value of the image data:
*img.img_old = ABS(temporary(*img.img_old) )

; Write the altered data to a new ANALYZE 16-bit integer file:
fn_out = fn_dir+fn_name+'_new.img'

; Destroy the structure containing the image data etc.:
EZ_DESTROY, img_old

You can either put the altered data into the original data structure (as in the above example) and pass the structure to EZ_WRITE_ANLZ, or you can pass an array and other information (pixel size, origin, etc.) explicitly.

4D images are usually treated as a time-series of 3D images. Special cases, such as DTI images which may have 5 or more dimensions, can also be handled by using appropriate labels in the EZ structure. Another special case is DTI data stored as 4D data where the 4th dimension is an RGB encoding for display of e.g. directional information. Yet another special case is VoxBo 4D data, whixh is ordered with time as the first dimension.

It is relatively straightforward to write your own EZ Read/Write program for a data format which is not currently supported. The EZ read-programs should apply all appropriate calibration or scaling factors. This is not so important for most types of MRI data which normally are in "machine units" ranging from 0-32767. However, this is relevant for PET data and for most types of processed data such as parametreic maps. Depending on the data format and content, there may be one or more calibration factors. All reconstructed PET data get converted to microCi/ml. Most other data, if converted, use a single scale-factor from the header.

If you are interested in using the EZ-Writer programs, email Terry Oakes (troakes@wisc.edu).