BioImage Suite has a number of Command Line Utilities that are useful both for batch-mode computation and for the integration of BioImage Suite tools into other software. In particular these tools can be divided into:

• Inspecting analyze image headers and surface files.
• Image processing such as smoothing, thresholding, flipping etc.
• Segmentation (voxel classification), slice inhomogeneity correction & bias field correction tools.
• Image Reslicing and other utilities to manipulate transformations.
• Batch mode registration tools.
• Batch mode segmentation tools.

For all command line tools to function the path needs to appropriately set at the command line. On Microsoft Windows this is accomplished by first calling c:\yale\bioimagesuite\setpaths.bat, where as on Unix by the sourcing of one of the following shell scripts, either /usr/local/bioimagesuite/setpaths.csh or /usr/local/bioimagesuite/setpaths.sh depending on the shell used. See the Running BioImage Suite page for more details.

Typing any of the bioimagesuite command names with no arguments prints a short description of its usage. Arguments in square brackets are optional.

Note: Most of this functionality (with the exception of the batch-mode tools) is available via the graphical user interface see: the Image Processing, (ii) Segmentation and Registration pages respectively.

Inspecting Analyze Header Files and Surface Files (.vtk)

The pxmat_headerinfo.tcl command can be used to print basic information about analyze header files (.hdr). The syntax is:
This can be used to quickly scan the contents of a directory e.g. pxmat_headerinfo.tcl *.hdr A similar script for examining surface headers pxmat_surfaceinfo.tcl is also available.

Image Processing Tasks

Flipping Images

Sometimes images need to be flipped about one of the coordinate axes. This can be accomplished using the pxmat_flip.tcl sciprt. The syntax is

Reorienting

Reorienting is defined here as switching the orientation of an image from, for example, axial to coronal. This is accomplished by the pxmat_reorientimage.tcl command. The syntax is The input orientation is detected automatically.

Smoothing

This is accomplished by the pxmat_smoothimage.tcl command. The syntax is where the smoothing kernel_size in mm represents FWHM filter size. Multiple images may be specified on the command line.

Thresholding

Similarly this is performed by the pxmat_thresholdimage.tcl command. The syntax is: The output is a set of binary images with value = 1 where the original images had values above "threshold" and zero elsewhere. Multiple images may be specified on the command line.

Resampling Images

This is accomplished using the pxmat_resampleimage.tcl command. The syntax is: where blurmode = 0 or 1, setting this to one blurs the image with an appropriate Gaussian filter. The output dimensions of the voxels in mm are set using the voxelsize1, voxelsize2 and voxelsize3 parameters (if only one specified then an isotropic image is generated). (voxelsize1 = voxel size x, voxelsize2=voxel size y, voxelsize3=voxel size z).

Combining Multiple 3D Images into a single 4D Image

This is accomplished using the pxmat_create4dimage.tcl command. The syntax is:
This is particularly useful for generating appropriate input images for the Diffusion Tools.

Extracting 3D Image volumes from a single 4D Image

This is accomplished using the pxmat_split4dimage.tcl command. The syntax is:
The output images are saved in filenames image_001.hdr, image_002.hdr etc.

Segmentation and Bias Field Correction Tools

Segmentation Tools

A single script pxmat_segment.tcl captures some of the functionality from the < a tools (Histogram & Region Segmentation.) The reader refered to that page for more details. The syntax for pxmat_segment.tcl is: If smoothness is set to zero then the "histogram"-segmentation method is used, otherwise the region-segmentation method is applied. The maxsigmaratio parameter can be useful is one class has a relatively small number of voxels.

Slice Inhomogeneity correction & Bias Field Correction tools.

pxmat_biasfield.tcl is a multifunctional script for performing both these tasks. The syntax is:

Slice Inhomogeneity correction

This is performed simply using mode = 0 in pxmat_biasfield.tcl.

Bias Field correction

There are 2 methods here, which can be used in combination:

1. Multiple (triple slice) orientation slice inhomogeneity correction – set mode = 1 in pxmat_biasfield.tcl.
2. Polynomial bias field correction using the method of Styner et al (TMI 2000) – set mode = 2 (quadratic ) or 3 (cubic) in pxmat_biasfield.tcl. This second method requires a crude histogram segmentation hence the other parameters – this invokes the histogram segmentation (i.e. smoothness=0) method from the previous section.

The two bias field correction methods may be combined by setting the mode to 4 or 5 respectively. In general, the triple-slice method can be used to get a good initial starting point for the polynomial method in cases where the bias field change is large.

In addition to the segmentation parameters, the parameters threshold, res, minb1 and maxb1 or only used by the polynomial method.

Reslicing Images and other command line tool using transformations

The BioImage Suite registration tools (both command line and using the graphical user interface), produce transformation files as outputs, typically with a ".matr" or a ".grd" extensions. (See the File Formats page for more details.) The command line tools described here can be used to apply these transformations to images (reslicing) or to manipulate the transformations in different ways.

Image Reslicing

Given a reference image, a target image and an appropriate transformation (or set of transformations) the target image can be resliced in the space of the reference image using the command

Note: The direction of the transformations is a common source of confusion. When computing registrations, the estimated transformations is FROM the reference TO the target. This transformation can be used in pmat_reslice.tcl to move the target image to the reference image. A good rule of thumb is to remember that images move in the opposite direction as transformations.

If multiple transformations are specified (upto 3) then the the concatenation of these transformations will be used. For example, consider the case where we have:

• A transformation from a 3D reference brain to a 3D individual anatomical. xf1.grd
• A transformation from a 3D individual anatomical to a scout image. xf2.matr
• A transformation from the scout image to a functional acquisition. xf3.matr

The following command will reslice the functional image to the space of the 3D reference brain:

Inverting Transformations

Often the inverse transformation is required. This can be accomplished using the pxmat_inverttransform.tcl script. The syntax is: If multiple transformations are specified (upto 3) then the inverse will be the inverse of the concatenation of these transformations.

Computing Displacement Fields

Sometimes it is desired to get the displacement field for each voxel. This can be accomplished using the pxmat_displacementfield.tcl command. The syntax is: The output_field will be a 4D analyze image file with three frames, storing the x, y and z displacement of each voxel in mm (or nominal units). If more than one transformation is specified the final displacement field will be a result of the concatenation of the transformations specified.

Batch Mode Registration

A quick overview of GNU Make.

All Batch Job Generators in BioImage Suite result in a makefile which needs to be processed with the Unix Make Utility (most commonly GNU Make). While "makefiles" are primarily used to compile large programs they are a great mechanism for general batch mode processing because they enable:

1. the definition of job dependencies -- i.e. job A must be completed before job B
2. the use of multiple processors at the same time -- i.e. run two or more jobs at once.
3. the ability to automatically recover from a system crash and to restart at the point that the job failed -- i.e. no repeat computations.

The standard name for a makefile is unsurprisingly "makefile", although in this context I recommend the use of more descriptive names e.g. "makefile.controls" etc. Given a makefile, the batch job is executed using On Linux systems make=gmake i.e. typing gmake is equivalent to typing make -- this may appear in some examples. Additional useful flags include

1. "-n" - do a dry run i.e. simply print a list of commands to be executed without doing anything

   make -n -f makefile.controls

2. "-j" - specify how many jobs to run at once -- typically equal to the number of processors available e.g. to use 2 processors type

   make -j2 -f makefile.controls
   

   In addition makefiles contain a number of "jobs" which may be explicitly specified. Typically the first job defined in BioImage Suite batch jobs is the equivalent of "do everything" so you need not worry about this - in some cases other specifications will need to be given given. Note: If after starting a batch job -- it is for some reason terminated (either by a system crash or a reboot or ....) it may be restarted by typing exactly the same command as the one used to originally start the batch job. The job dependency mechanism in make will ensure that no processing that was previously completed is re-run.

Microsft Windows Info

Whereas make is a standard feature on most unix system, to run batch jobs in MS-Windows you will to download and install GNU Make. A binary (from the UnixUtils distribution ) is available for download at this location (source code here. Place make.exe in a directory in your path such as C:\yale\vtk44_yale\bin.

Single Reference Image Registrations

To compute batch-mode registrations to a single reference (typically inter-subject nonlinear brain mappings for the purpose of computing fMRI composite maps etc.) BioImage Suite provides the pxmultiregister_int.tcl tool. This is a batch-mode generator which will generate a makefile - the batch job itself is executed using the standard make program - see detailed description above. pxmultiregister_int.tcl has a large number of options -- with more to be added in the next release. Simply typing pxmultiregister_int.tcl sample lists all options, which might be intimidating for the average user. A basic setup file has the form: (Lines beginning with # are treated as comments and may be added liberally to document the processing. Once the setup file is completed, the next step is to decide where the results (and a host of log files) will be stored. Typically this is in a subdirectory (e.g. results). If the setupfile is called controls_setup and we want the results to go to controls_results type: This will check for the existence of all files in the setup file, if a file (image) is missing an error will be given. Once this completes OK, the next step is to generate the makefile using At this point the batch-job is ready and can be started using the make utility described above.

Pairwise Image Registrations

The case of interest here is where one set of images (e.g. thick-slice "2D" conventional images) are to be mapped to another set of images (e.g. high resolution 3D anatomical images). To accomplish this use the pxpairwiseregister.tcl script. This is a batch-mode generator which will generate a makefile -- the batch job itself is executed using the standard make program -- see above for instructions as to how to use GNU make. pxpairwiseregister.tcl has a large number of options. Simply typing pxpairwiseregiste.tcl sample lists all options, which might be intimidating for the average user. A basic setup file has the form: (Lines beginning with # are treated as comments and may be added liberally to document the processing. See the previous section for more description of the parameters. Executing pxpairwiseregister.tcl is also identical to pxmultiregister_int.tcl, i.e. first then and then use the make utility to start the makefile.

Batch Mode Registration Utilities

The following helper scripts are used to assist/compute the batch mode registrations. They are not meant to be invoked directly, so only a cursory description is given. Invoking each script with no arguments gives a brief description of its syntax.

1. pxmat_register.tcl – computes intensity based registrations.
2. pxmat_distortioncorrection.tcl – computes intensity based distortion correction for Echoplanar images.
3. pxmat_pointregister.tcl – computes point based registrations.
4. pxmat_integratedregistration.tcl – computes integrated intensity + point based registrations.
5. pxmat_computeoverlap.tcl – computes the overlap of pre-segmented structures after registration &ndash this is a measure of registration quality.
6. pxmat_computesimilarity.tcl – computes the similarity of two images after registration.
7. pxmat_computedistance.tcl – computes the distance of two surfaces after registration.

Batch Mode Segmentation

To compute batch-mode segmentation, BioImage Suite provides the pxmultisegment.tcl tool. This is a batch-mode generator which will generate a makefile - the batch job itself is executed using the standard make program - see detailed description above. Simply typing pxmultisegment.tcl sample lists all options. A basic setup file has the form: (Lines beginning with # are treated as comments and may be added liberally to document the processing. If usefsl=1 then the batch mode segmentation will leverage the FSL/FAST Gray/White Segmentation tools, otherwise the native BioImage Suite tools are employed. Once the setup file is completed, the next step is to decide where the results (and a host of log files) will be stored. Typically this is in a subdirectory (e.g. results). If the setupfile is called controls_setup and we want the results to go to controls_results type: This will check for the existence of all files in the setup file, if a file (image) is missing an error will be given. Once this completes OK, the next step is to generate the makefile using At this point the batch-job is ready and can be started using the make utility described above.

---

About this manual.