Software - File Manipulation Utilities
Warning: date() [function.date]: It is not safe to rely on the system's timezone settings. You are *required* to use the date.timezone setting or the date_default_timezone_set() function. In case you used any of those methods and you are still getting this warning, you most likely misspelled the timezone identifier. We selected 'UTC' for 'UTC/0.0/no DST' instead in /var/www/html/software/utilities_counter.php on line 88
Warning: date() [function.date]: It is not safe to rely on the system's timezone settings. You are *required* to use the date.timezone setting or the date_default_timezone_set() function. In case you used any of those methods and you are still getting this warning, you most likely misspelled the timezone identifier. We selected 'UTC' for 'UTC/0.0/no DST' instead in /var/www/html/software/utilities_counter.php on line 63
Warning: fopen(./counter/utilities_ip.txt) [function.fopen]: failed to open stream: Permission denied in /var/www/html/software/utilities_counter.php on line 17
Warning: fwrite() expects parameter 1 to be resource, boolean given in /var/www/html/software/utilities_counter.php on line 19
Warning: fclose() expects parameter 1 to be resource, boolean given in /var/www/html/software/utilities_counter.php on line 20
Warning: fopen(./counter/utilities_ip.txt) [function.fopen]: failed to open stream: Permission denied in /var/www/html/software/utilities_counter.php on line 24
Warning: fwrite() expects parameter 1 to be resource, boolean given in /var/www/html/software/utilities_counter.php on line 26
Warning: fclose() expects parameter 1 to be resource, boolean given in /var/www/html/software/utilities_counter.php on line 27
Warning: fopen(./counter/utilities_count.txt) [function.fopen]: failed to open stream: Permission denied in /var/www/html/software/utilities_counter.php on line 17
Warning: fwrite() expects parameter 1 to be resource, boolean given in /var/www/html/software/utilities_counter.php on line 19
Warning: fclose() expects parameter 1 to be resource, boolean given in /var/www/html/software/utilities_counter.php on line 20
Warning: date() [function.date]: It is not safe to rely on the system's timezone settings. You are *required* to use the date.timezone setting or the date_default_timezone_set() function. In case you used any of those methods and you are still getting this warning, you most likely misspelled the timezone identifier. We selected 'UTC' for 'UTC/0.0/no DST' instead in /var/www/html/software/utilities_counter.php on line 76
Warning: fopen(./counter/utilities_visit_log.txt) [function.fopen]: failed to open stream: Permission denied in /var/www/html/software/utilities_counter.php on line 24
Warning: fwrite() expects parameter 1 to be resource, boolean given in /var/www/html/software/utilities_counter.php on line 26
Warning: fclose() expects parameter 1 to be resource, boolean given in /var/www/html/software/utilities_counter.php on line 27
11034 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.
- Header file manipulation -- reading and adjusting parameter fields in header files
- Image voxel intensity operations
- Image lattice transformations
- Conversion between file formats
This page describes our approach to these tasks.
Header File Manipulation
File formats and extensions
- Interfile headers (".h01") are ascii files that can be directly edited.
- Analyze format headers (".hdr") 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.
- Our in-house header format (".demog") is a text file containing additional "demographic" information about a subject, such as age, gender and scan date, not provided for by analyze header fields.
- Nifti files come without separate headers (".nii" extension) or in two-file format similar to analyze.
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 headerwhere "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.
- 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.
- 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.
- 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.
- 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.
- 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.
- Boolean operations on masks
Do Boolean AND, OR and NOT operations on mask images
- 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).
- 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.
- 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.
- Finding connected components
Find the connected components above specified threshold cluster size in a mask image
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.