Software - File Manipulation Utilities

8112 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 single-file nifti (.nii) format, 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

File formats and extensions

Header file utility

We have a single utility chg_hdr to address issues related to header files and formats..

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
if2q	interfile to quanta
 	---------------------
 		create quanta".demog" file from ".h01" file
q2if	quanta to interfile
 	---------------------
 		create interfile".h01" file from ".demog" file
q2ana	quanta to analyze
 	---------------------
 		create analyze ".hdr" file from ".demog" file
swapAna	swap bytes in analyze header
 	---------------------
 		swap analyze ".hdr" file 
swapNii	swap bytes in .nii file
 	---------------------
 		swap ".nii" file 
nii_2_ana  nifti-1 to analyze
	---------------------     
		convert from .nii to analyze format
editAna	edit analyze header
 	---------------------
 		edit analyze ".hdr" file 
createAna  create analyze header
 	---------------------
 		create analyze ".hdr" file from command-line input

		Must input desired name for file, e.g. "myfile.hdr"

Format conversion scripts

Scripts are provided to convert between analyze, interfile, in-house and nifti 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, Quanta2Ana and nii2Ana. The first two perform conversions between interfile and analyze. The third converts our in-house header format (with ".demog" suffix) to analyze. The fourth converts nifti single-file format to analyze.

Image Voxel Manipulations

We have a second utility, chg_data, for use with image manipulation. This means making changes to the image files (.img for analyze or in-house, .i01 for interfile, .nii for nifti) 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, or run the helper utility chgdata-help, e.g.

chgdata-help options
--> Outputs list of all options, piped through more
chgdata-help 
--> searches the options and returns corresponding instructions matching query.

Options 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)