Revision as of 05:03, 8 September 2011

TrakEM2 is an ImageJ plugin for morphological data mining, three-dimensional modeling and image stitching, registration, editing and annotation.

See TrakEM2 snapshots for an overview.

Features

• Segmentation: manually draw areas across stacks, and sketch structures with balls and pipes. Skeletonize entire neuronal arborizations and represent synapses with relational connector objects.
• Measurements: volumes, surfaces, lengths, and also measurements via ImageJ ROIs.
• Image Registration: register floating image tiles to each other using SIFT and global optimization algorithms.
• 3D Visualization: interacting with the 3D Viewer plugin, TrakEM2 displays image volumes and 3D meshes of all kinds.
• Image Annotation: floating text labels.
• Semantic segmentation: order segmentations in tree hierarchies, whose template is exportable for reuse in other, comparable projects.

TrakEM2 interacts with the 3D Viewer for visualization of image volumes and 3D meshes.

TrakEM2 in Fiji

• Create new projects from "File - New - TrakEM2 (blank)"
• Open an existing project by dragging its .xml file onto the toolbar, or via "File - Open".

Documentation

• How to
• Manual
• TrakEM2 tutorials with video tutorials.
• Examples of scripting in TrakEM2.

Running fiji for heavy-duty, memory-intensive, high-performance TrakEM2 tasks

The following configuration has been tested in a machine with 8 CPU cores and 16 Gb of RAM, running Ubuntu 8.04 "Hardy", with a 1.6.0_16 or newer JVM:

./fiji -Xms10g -Xmx10g -Xincgc -XX:MaxPermSize=256m -XX:PermSize=256m
-XX:NewRatio=5 -XX:CMSTriggerRatio=50 -XX:+UseCompressedOops --

Put all the above in one line.

What the JVM flags mean:

• -Xms10g : use an initial heap size of 10 Gb (i.e. start fiji with 10 Gb of RAM preallocated to it)
• -Xmx10g: use a maximum heap size of 10 Gb. Note it's the same amount as the intial heap size, so that the heap cannot be resized.
• -Xincgc : use the incremental garbage collector. Clean up unused memory in the concurrent mark-sweep generation (i.e. not the super-new generation of allocated objects) using parallel threads.
• -XX:MaxPermSize=256m : set the heap size allocated to objects that don't need to be garbage often to 256 Mb. The default is only 32 Mb, which proves insufficient.
• -XX:PermSize=256m : preallocate the heap for the permanent objects directly to the desired maximum, 256 Mb, so it doesn't ever have to be resized.
• -XX:NewRatio=5 : Set the ratio of ephemeral versus more long-lived objects to 5 (the default is 9 or more in 64-bit Sun JVMs).
• -XX:CMSTriggerRatio=50 : run the parallel garbage collector when the ratio of free versus non-free heap space is 50 % (the default is 92% in 64-bit JVM, which may incur in pauses and undesirable full sweeps).
• -XX:+UseCompressedOops : use 32-bit pointers when possible, in a 64-bit JVM. This can cut the memory footprint by half in many cases.
• The ending double hyphen "--" is to specify all of these are JVM arguments, not fiji/ImageJ arguments.

With the above settings, we have succesfully registered 33,000 image tiles corresponding to 459 serial sections, using the "Align multi-layer mosaic" TrakEM2 command.

Preparing TrakEM2 for best performance

For fastest browsing through layers

Right-click on the canvas and choose "Display - Properties...". Then make sure that:

• "snapshots mode" is set to "Disabled", or at most to "Outlines".
• "Prepaint" is not checked, so that it is disabled.

For importing large collections of images and editing them immediately afterwards

The goal is to avoid generating mipmaps multiple times, which may be very time consuming.

Right-click on the canvas and choose "Display - Properties...". Then make sure that:

• "enable mipmaps" is not checked, so that it is disabled.

Beware that you will not be able to browse quickly through layers while importing, given that mipmaps will not be generated.

Now to correct the contrast, first re-enable mipmaps by going again to "Display - Properties..." and checking the "enable mipmaps" checkbox. Then you have two general (non-exclusive) options:

A. Use the built-in commands from the right-click menu, such as:

• "Adjust images - Enhance contrast layer-wise"
• "Adjust images - Set min and max layer-wise"

B. Create a preprocessor script and set it to all images. For example, a beanshell script to run CLAHE on each image. In the script, the patch and imp variables exist automatically, and represent the Patch instance and the ImagePlus instance that the Patch wraps, respectively.

import ij.IJ;
IJ.run(imp, "Enhance Local Contrast (CLAHE)", "blocksize=127"
   + "histogram=256 maximum=3 mask=*None* fast_(less_accurate)");

To set the script to all images, save the above to a file named "whatever.bsh" (notice the filename extension ".bsh") and then right-click on the TrakEM2 canvas and choose "Script - Set preprocessor script layer-wise", and choose the whole range of layers. This will set the script to every image of every layer, and trigger mipmap regeneration for every image. When TrakEM2 loads the image, the script will run on the image before TrakEM2 ever sees its contents.

The preprocessor script gives you maximum power: do whatever you want with the image. For example, normalize the image relative to a known good mean and standard deviation for your data set.

For regenerating mipmaps the fastest possible

In TrakEM2 0.9a and later, the mipmaps machinery uses a multi-threaded Gaussian implementation now present in the latest ImageJ. This means that now there are two sets of threads:

1. The set of threads, where each thread regenerates the mipmap pyramid of a single image.
2. The set of threads that performs Gaussian blurring for downsampling, for each scaling iteration in the generation of the mipmap pyramid.

If your machine has 12 cores, the default settings will use 12 threads for mipmaps and 12 threads for gaussian blurring. This means that, if you are regenerating 12 or more images, there will be 12 + 12 * 12 = 156 concurrent threads. That's too many threads.

You must decide between two strategies:

• Strategy A: your data consists of large images (over 4000x4000). Right-click on the TrakEM2 display and choose "Project - Properties...", and set the mipmap threads to 1. Now, mipmaps will be regenerated for one single image at a time, using 12 threads (given 12 cores) for computing the Gaussians.
• Strategy B: your data consists of small images (smaller than 4000x4000). Go to the Fiji window and select "Edit - Options - Memory & Threads...", and set the number of threads to 1. Now, mipmaps will be regenerated for 12 images at a time (given 12 cores), using a single thread for each to compute the Gaussians.

How much RAM should I allocate to the JVM for Fiji to run TrakEM2?

Use a computer that follows this rule of thumb: take the largest single 2D image in your dataset, then multiply its size by 10, and make sure that every core of your CPU has at least that much RAM available to it.

For example, for a 4096x4096 16-bit image you will need at least 335 Mb per core, so at least 5.4 Gb of RAM for 16 cores. 8 Gb would likely work better. 32 Gb will be a pleasure to use.

As for a graphics card buy the largest you can afford, both in computing power and in internal memory.

Examples

TrakEM2: 359 montages of 13x13 tiles of 2048x2048 pixels each.

TrakEM2 Display showing 9 images in a layer, where 2 images and one floating text label (set to 30% transparency) are selected (pink and white frames; white is the active one – note the corresponding pink and blue coloration of the object panels on the left). The Navigator (bottom left) paints a red frame to indicate the area currently displayed in the canvas (right).

3D Viewer: hardware-accelerated 3D visualization of image stacks as volumes, orthoslices and meshes. Above, secondary lineages of Drosophila third instar larval brain segmented in TrakEM2.

The three TrakEM2 trees, as an interface for editing and visualizing the three internal TrakEM2 data structures.

Effect of the CLAHE live filter in TrakEM2. Data with high dynamic range is displayed with perceptually boosted local contrast. CLAHE parameters are relative to display pixels and, therefore, will not result in an effective bandpass when zooming out largely on statically pre-processed images.

Neuronal arbors reconstructed with TrakEM2 using the treeline segmentation type.

Neuronal arbors from serial section electron microscopy reconstructed with TrakEM2 using the manually segmentated data set.

TrakEM2 showing one section of a serial section transmission electron microscopy (ssTEM) data set, with numerous neuronal arbors reconstructed using treelines and connectors (for synapses).

Example TrakEM2 segmentations, including Ball, Pipe, Profile, AreaList and floating text labels.