Software - File Manipulation Utilities

958 unique visits since June 1, 2006

File manipulation is a mundane but necessary activity. We have a suite of fairly comprehensive tools for use with analyze, interfile and our own in-house file format. In each of these file formats, a brain image is represented by a small header file, to store relevant image parameters, and a large image file, storing the voxel intensities. The file formats of these three examples differ only in the formatting of the header files.

Thus there are four principal categories of file manipulation tasks.

  1. Header file manipulation -- reading and adjusting parameter fields in header files
  2. Image voxel intensity operations
  3. Image lattice transformations
  4. Conversion between file formats

This page describes our approach to these tasks.

Header File Manipulation

Interfile headers are ascii files that can be directly edited. Analyze format headers, however, are binary files which need tools to access and change their fields. In addition, analyze header files suffer from problems of endian-ness, meaning that an analyze header file created on a SPARC workstation, for example, will be unreadable on a PC unless the bytes are swapped in a particular order depending on the field. Finally, we must be able to convert between header formats, reading the data stored in one format and writing out in another.

We have a single utility chg_hdr to address these problems. 

Usage: chg_hdr filename action
 
input filename:        name of input volume or header
where "filename" is most commonly the complete name (including extension .h01 or .hdr) of the image header file (the accompanying image file must be present in the current directory). 

reads header in one format and writes corresponding header in second format
 
action  action to take
======  ==============
 
if2ana  interfile to analyze
        ---------------------
                create analyze ".hdr" file from ".h01" file

ana2if  analyze to interfile
        ---------------------
                create interfile ".h01" file from ".hdr" file

swapAna swap bytes in analyze header
        ---------------------
                swap analyze ".hdr" file

editAna edit analyze header
        ---------------------
                edit analyze ".hdr" file

createAna  create analyze header
        ---------------------
                create analyze ".hdr" file from command-line input
Also, two scripts are provided to convert between analyze and interfile header formats. The input is a header file of a given format. The output is a header file of the other format and image files with the correct suffix. The scripts are called IF2Ana and Ana2IF.

Image Voxel Manipulations

We have a second utility, chg_data, for use with image manipulation. This means making changes to the image files (.img or .i01) storing the voxel intensities. In the two image formats used (analyze and interfile), the storage is exactly the same: row major order in a slice, ordered by slices. So the image file is a single dimension array with entries equal to the number of voxels in the image. The header file is used to parse it by providing, among other things, the row, column and slice dimensions.

The usage of chg_data is 

chg_data filename [option]
where "filename" is most commonly the complete name (including extension .h01 or .hdr) of the image header file (the accompanying image file must be present in the current directory).

chg_data handles images of any byte storage (unsigned char, short, float or double) with almost all of its options. There are lots of options for this utility, which can all be seen by invoking its name without any arguments. They will be summarized here by category.

  1. Resizing byte storage (bytes per pixel of the image)

    Examples include making byte images out of float or the reverse. In the case of downsizing the byte storage, scaling decisions need to be made.

  2. Cutting out parts of the volume or placing the image in a box

    • Make a box just large enough to hold the voxels above a threshold. Option to keep the image of original size but zero outside box, or reslice to new size fitting the box, discarding voxels outside.
    • Use a second image as a "cookie cutter" to cut out selected parts of the first image.

  3. Manipulating voxel intensities

    Options include:

    • making a mask image for all voxels above a threshold
    • rescaling the image to fill a specified range
    • stripping voxels above or below specified thresholds
    • voxel-by-voxel addition, multiplication, subtraction or division (in this case where meaningful) of two images.
    • More generally, many voxel-based binary arithmetic operations are implemented.


  4. Image transforms

    These include log, exponential, Z-transform, median filtering and square root transforms. It is possible to specify a mask over which these transforms may be applied.

  5. Smoothing

    Do Gaussian smoothing with an input 3D FWHM kernel. There is some imprecision for low FWHM values, since the transformation is done in the image space and the width is appoximated by integral numbers of voxels. In this respect, gsmooth from AIR is more accurate. But the advantage of our algorithm is that it handles images of any byte storage size.

  6. Boolean operations on masks

    Do Boolean AND, OR and NOT operations on mask images

  7. Manipulating image orientation

    • Flip an image top to bottom, right to left or by slice order.
    • Swap axes to change the image orientation, e.g. make a coronal from an axial image.
    • Change the image to match the parity of a second image (the parity is defined by the relationships between the subject coordinate axes and the image coordinate axes and must be specified using our parity tool).


  8. Dilating and eroding mask images

    Do specified number of iterations of dilation or erosion, also with the ability to specify the number of voxel neighbors (6, 18 or 26) involved for each voxel.

  9. Surgery on images

    Specify rows, columns or slices to cut or keep within an image. Discarded voxels are zeroed out while the overall image array remains the same size.

  10. Finding connected components

    Find the connected components above specified threshold cluster size in a mask image

There are a few other miscellaneous options functions as well.

Image Lattice Manipulation or Rigid Transformation

Often it is desirable to change the voxel spacing or the image orientation. These involve operations with the voxel lattice as well as image intensities. It may involve reslicing the image (i.e. changing the image voxel lattice dimensions) and it can also involve rigid transformations.

The utility transformL3 is used for these purposes. Some of its functions overlap with those of chg_data but it has the additional capabilities of reslicing images and performing any kind of linear transformation of the image. Like chg_data this utility can handle images with byte storage of 1, 2, 4 or 8 bytes. The usage is as follows: 

transformL3 object_volume [parameter files]  [-outname output_name]

parameter file options:
 -paramfile paramfile_name [-invert] 

              --- OR ---

transformL3 object_volume [transformation params] [reslice params] 
 
Transformation params:
 [-transX tX] [-transY tY] [-transZ tZ]
 [-rotX rX] [-rotY rY] [-rotZ rZ]
 [-scaleX scX] [-scaleY scY] [-scaleZ scZ]
 [-shearX shX] [-shearY shY] [-shearZ shZ]
 
Reslice params
 [-lattice xdim ydim zdim]
 [-voxmms xmm ymm zmm]
 
Explanation
===========
 
Perform 12-parameter image transformation
May transform an image in two ways:
        *supplying transformation parameters from the command line
        *using pre-existing paramfile (see below for recognized formats)
 
Command line parameters
-----------------------
Translations and scaling: use mm
 
Rotations: use degrees
"-transfile" option: specify output format of transformation file
(default is "paramfile" -- see below for parameter file description)
 
Reorient params:
Do an axis swap in one of the following ways:
-XY              (= rotate +90 deg around z axis)
-YX              (= rotate -90 deg around z axis)
-XZ              (= rotate +90 deg around y axis)
-ZX              (= rotate -90 deg around y axis)
-YZ              (= rotate +90 deg around x axis)
-ZY              (= rotate -90 deg around x axis)

This utility uses parameter files of a format produced by our in-house software. The format is ascii storage of the 12 parameters (X Y Z translations, rotations, scaling and shear) used to construct the affine transformation matrix, followed by information about the target voxel lattice, then file orientation and format, and finally world coordinates for the geographic centers of both images. These files are an output when transformL3 is called with command line parameters. And they are also created as one of the outputs of our linear alignment tool LinCoregL3.

Up (Software)