TraceROI ImageJ Plugin

Author: Tet Woo Lee
Contact: imagej at twlee dot nz
Version: 0.3.2
Date: December 2015
Copyright: Tet Woo Lee
License:GNU General Public License version 3
Download link:TraceROI_-0.3.2.jar


TraceROI is an ImageJ plugin that allows semi-automated tracing of neuronal processes (or other line-like structures) to generate polyline ROIs. The user clicks on the start and end points of the process and the plugin will trace along the process to find the best ‘route’. Tracing is performed with the NeuronJ algorithm but the interface was been completely re-implemented to improve integration with ImageJ. In particular, the polyline ROIs generated can be measured and straightened using the standard ImageJ tools.


Delete any previous versions of TraceROI-??.jar from your ImageJ or Fiji plugins directory. Copy TraceROI_-0.3.2.jar to the plugins directory. Install nz-twlee-common by copying the latest version of the nz-twlee-common-??.jar to your plugins directory. ImageJ users also need to copy imagescience.jar to their plugins directory (this is included by default in Fiji).

How to use


  1. To start using the plugin, open an image containing features to trace and execute the TraceROI command in the ImageJ Plugins menu. This will initialize the plugin for that image. A new tool (TraceROI with a cross shaped icon) will appear in the ImageJ toolbar. Note that the currently active image and slice will be used to initialize the plugin. It is possible to switch to a different slice and perform tracing, but pathfinding will be based on the slice selected when initializing.
  2. Activate the TraceROI tool in the toolbar. You can now begin tracing by clicking on a start-point in the image. After clicking, the plugin will automatically ‘snap’ to the the best start-point within a certain radius and begin tracing. (A Shift-click disables snapping so that the actual point under the cursor can be used as a start point if desired).
  3. While tracing, moving the mouse will cause plugin to automatically find a route to the end-point under the cursor (again, snapping to the best end point occurs). The pathfinding algorithm may take a short while to identify the route, particular at longer distances, but on modern computers the delay is minimal. A second click will finalize the endpoint and store the traced segment. You can continue tracing the same segment with additional clicks (sometimes intermediate points must be selected to correctly trace the process), or press Escape to stop tracing this segment and start tracing a new segment. Each individually traced section of the process is saved as its own polyline ROI. These are numbered as subsegments belonging to a segment, e.g. segment1-1 is the first subsegment of segment 1, segment1-2 is the second subsegment while segment2-1 is the first subsegment of segment 2.
  4. While tracing, the Ctrl key allows a user to manually trace a segment without using the pathfinding algorithm (snapping will still occur unless Shift is also pressed).
  5. It is possible to continue tracing an existing segment. To do so, move the cursor close to the terminus of a segment. The cursor will change to a hand icon. Click once to activate that subsegment as the selected ROI, showing the individual points that make up the ROI. Click again near a terminal point to continue the trace. Tracing can be continued from either end of the segment. (Holding down the Alt button prevents the plugin from selecting existing segments, and can be used to trace new segments adjacent to an existing segment).
  6. More advanced editing options are planned for a future release.

Joining subsegments and straightening

To preserve editing capabilities, TraceROI stores process segments as a series of subsegments, one for each additional click of the mouse. Each subsegment is an individual polyline ROI and is named segment<segment number>-<subsegment number>, e.g. segment2-1 is the first subsegment of segment 2. The TraceROI Join all subsegments command (under Plugins>TraceROI ) can be used to join all subsegments into segments, for example, to allow these to be measured. Note that this process is irreversible and the joined segments will no longer be editable with TraceROI.

The TraceROI Join & straighten all subsegments command (under Plugins>TraceROI ) is another convenience function that will join all subsegments and then run the ImageJ Straighten command (Edit>Selection>Straighten...) for all subsegments, producing a new straightened image for each segment. If the image is a stack, the entire stack will be straightened.

Saving and loading ROIs

TraceROI integrates with the ROI Manager in ImageJ. The ROIs can be saved and loaded using the options provided in the ROI Manager. Once the ROIs have been loaded, initialize (or re-initialize) the plugin by running the TraceROI command in the Plugins menu. This will convert any appropriate ROIs in the ROI Manager to traceable ROIs, allowing further editing of these, or joining and straightening.


The TraceROI Setup command (under Plugins>TraceROI ) allows the user to set several parameters for the algorithm and plugin:

This parameter sets the scale parameter of the Gaussian smoothing kernel used when calculating image derivatives, see Meijering2004. This parameter should be set based on the width of the features that are being detected in the image, a larger value can be used to smooth over wider neurites, and vice versa. Default: 2.0
This parameters sets that gamma value for the tracing algorithm, see Meijering2004. This parameter should be set to be between 0.0 and 1.0. A value closer to zero emphasizes the ‘direction’ component of the tracing algorithm (ridge following) when finding the best route, while a value closer to one emphasizes the ‘neuriteness’ component. Default: 0.7
This parameter sets the radius (in pixels) for snapping to the ‘best’ points for a neurite. The best point is defined as the point with the highest ‘neuriteness’ value within the search area, see Meijering2004. Default: 4
This parameter sets the width (in pixels) of the straightened image. Default: 20
If checked, this parameter will suppress various warning dialogs that occur when the plugin is used. Default: false

TraceROI submenu

The TraceROI plugin installs a submenu in the Plugins menu (Plugins>TraceROI ). The submenu has the following commands:

TraceROI Setup
Opens a dialog to set the parameters of the plugin. See Parameters.
TraceROI Uninstall
Uninstalls the plugin from the current image. The TraceROI icon will still be present in the toolbar, but will not do anything.
TraceROI Uninstall & reset toolbar
Uninstalls the plugin from the current image and resets the ImageJ toolbar to remove the TraceROI tool. Note: This command will uninstall any other custom tools or macros that have been installed since starting ImageJ.
TraceROI Sort tracing rois
See Joining subsegments and straightening.
TraceROI Join all subsegments
See Joining subsegments and straightening.
TraceROI Join & straighten all subsegments
See Joining subsegments and straightening.

Convenience macros

The following convenience macros are available to speed up use of this plugin (download and install with Plugins>Macros>Install...):

This macro provides shortcut keys for initializing TraceROI and straightening/saving segments. Details in comments at the top of TraceROI_straighten_macro_v1.txt.

Known issues

  • This plugin is causing intermittent AWT exceptions (e.g. Exception in thread "AWT-EventQueue-0" java.lang.ArrayIndexOutOfBoundsException: 3 >= 3). These do not appear to affect the normal functioning of the plugin.
  • Select a terminal handle to continue the segment” message: This occurs if you click on a internal point of a segment rather than a terminal point using the TraceROI tool to continue a segment. If you get this message when apparently clicking a terminal point, it is usually because there is an internal point close to a terminal node. Zoom in to the image so that you can clear select the terminal point and continue tracing.
  • Difficulties selecting an existing segment with TraceROI tool: On occasions, the plugin will fail to detect an existing segment (hand cursor does not appear). To overcome this issue, select the subsegment manually in the ROI manager.

Nitty gritty

This plugin uses the NeuronJ algorithm described in detail in Meijering et al. 2004 [Meijering2004] with one notable exception, namely the final smoothing of the paths (using a uniform postfilter in Meijering2004) is substituted for a digital straight segment (DSS) recognition algorithm [Debled-Rennesson1995]. The DSS algorithm converts the 8-connected digital line obtained by pathfinding into a series of straight line segments. Redundant points in the digital line are eliminated and only the ‘jointing points’ at which the line direction changes are retained, effectively removing the digital ‘noise’ that occurs in lines defined on a discrete digital grid.

Source code

Included in TraceROI_-0.3.2.jar.


0.3.2 4 December 2015
Initial working release with full functionality but limited editing functionality.


This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <>.


[Meijering2004]Meijering E1, Jacob M, Sarria JC, Steiner P, Hirling H, Unser M (2004). Design and validation of a tool for neurite tracing and analysis in fluorescence microscopy images. Cytometry A, 58(2):167-176.
[Debled-Rennesson1995]Debled-Rennesson I & Reveillès, J-P (1995). A linear algorithm for segmentation of digital curves. International Journal of Pattern Recognition and Artificial Intelligence, 9:635-662.