NeuronJ: Manual


NeuronJ


Conditions of usage

If you publish results that are based on NeuronJ, you are expected to acknowledge the work of Erik Meijering by putting a reference to the following paper:
* E. Meijering, M. Jacob, J.-C. F. Sarria, P. Steiner, H. Hirling, M. Unser, Design and Validation of a Tool for Neurite Tracing and Analysis in Fluorescence Microscopy Images, Cytometry, vol. 58A, no. 2, April 2004, pp. 167-176.

NeuronJ also features in the following paper on ImageJ:
* M. D. Abràmoff, P. J. Magalhães, S. J. Ram, Image Processing with ImageJ, Biophotonics International, vol. 11, no. 7, July 2004, pp. 36-42.

About the MRI NeuronJ version and this manual

This is the original NeuronJ manual by Erik Meijering with some additions for the NeuronJ version used at MRI. The NeuronJ version used at Montpellier RIO Imaging, has the following differences compared to the original version:

All chapters except "Conditions of usage", "About this manual" and "How to use NeuronJ from the MRI Cell Image Analyzer" are from the original manual by Erik Meijering.

How to use NeuronJ from the MRI Cell Image Analyzer

mri cell image analyzer
After you opened "MRI Cell Image Analyzer" press the NeuronJ  icon to open NeuronJ.

NeuronJ

Use the folder icon to open your first image. This will open the first image and bring up the "Slide Show Control" in the same time.

image    slide show control

If the actual number in the slide show control is not 1 you might want to press the |< button to jump to the first image in the folder before you begin working.
The slide show control works like the control of a cd player. The meaning of the buttons is:
Use the magnify button  on the NeuronJ window to adjust the zoom of your image. With the hand icon  you can scroll in the image if it is bigger than the window.

Now you can start to create some tracings. To create a new tracing press the add button . Place the mouse pointer near the outer end of a tracing. The little red cursor under the mouse pointer will jump automatically to the best pixel near your position. Press the left mouse button to mark the start of the tracing. Move along the structure you want to trace to the end point or a crossing. If the line that is drawn follows you up to the end point press space bar to end the tracing. If at a crossing the line doesn't follow your movement, press the left mouse button again to create an intermediate point.

After you finished a tracing with space bar, you can add another tracing by again clicking the add button.

If you made an error and want to delete a tracing press the delete button and point at the tracing you want to delete.

tracings

After you finished with the image you can use the "slide show control" to go to the next image. The tracings are saved automatically to a file with the same name as the image but the extension .ndf. They are automatically opened when you open the image again.

So its up to you if you want to measure your tracings after you created them or if you want to create the tracings for all images first.

Before you measure tracings you might want to set the pixel size. Press the set parameters button and change the pixel size and the unit.

To start measuring press the measure button . You can leave the dialog opened and add measurements by pressing the Run button each time. Uncheck the "clear previous measurements" option if you want to have all tracings in the same table.

tracings table    statistics table

Use the File menu to save your measurements to a text file. You can open the text file with your favorite spread sheet program afterwards. You can use copy &  paste as well, but this might not work as expected when the locale in your operating system has a decimal separator other then the decimal point (a comma for example).
If later you want to know which tracing was which in your image you can press the label tracings button . The tracing is highlighted in the image if you select its name in the dialog and the other way round the name is selected in the dialog when you point to the tracing in the image.

Description of Toolbar Components

* * Erase tracings. Opens a dialog asking whether you really want to erase all tracings. Upon pressing "Yes", all tracings are erased. The parameter settings, the names of tracing types and clusters, and the type colors are retained, however.
* * Load image/tracings. Opens a dialog for selecting and loading either an image (only 8-bit gray-scale and indexed color images are accepted) or previously saved tracings (including corresponding settings). NeuronJ can handle only images that have been loaded using this dialog, not images loaded with ImageJ or images already open when NeuronJ was started. Upon pressing "Open", the selected image is loaded and NeuronJ "attaches" itself to the image. Every time a new image is loaded, NeuronJ automatically closes the previous image.

Files containing tracings and settings saved by NeuronJ have the extension ".ndf", which stands for "NeuronJ data file". If you load an image, NeuronJ checks if there exists a data file for that image (must be a file in the same directory and with the same base name as the image file, but with extension ".ndf"). If so, it will load it automatically and display the tracings. Parameter settings, type and cluster names, and type colors contained in the file are also loaded and replace the current settings. It is also possible to load a data file manually, replacing the current tracings and settings.

The first time you load an image using the NeuronJ toolbar, the program also checks if there are other images in the same directory (only files with extension ".tif", ".tiff", ".gif", or ".jpg" are considered). If so, you can load the next or the previous image in the directory by pressing, respectively, the "right-arrow" or "left-arrow" key on the keyboard (provided that the current image is active, which you can achieve by clicking its title bar). This facilitates tracing multiple images.
* * Save tracings. Opens a dialog for choosing a file name and directory and saving the current tracings and all settings. The file name extension for NeuronJ data files is ".ndf", which is attached to the base file name by default.
* * Add tracings. Mode for adding tracings. The first time this button is pressed, the program carries out some image processing operations to compute features that are required for the tracing algorithm. This preprocessing may take a few seconds (depending on the size of the image and the speed of your computer).

The actual tracing of neurites is initiated by moving the mouse to the beginning of a neurite of interest and clicking the (left) mouse button. The tracing algorithm subsequently computes and shows the "optimal" path from the current mouse position in the image to the clicked point. Move the mouse roughly along the neurite until the path suggested by the program starts to deviate too much from what you consider the correct tracing. Clicking the mouse button again causes the program to fix the displayed path and to start the computation of optimal paths from the newly clicked point. This procedure can be repeated until the end of the neurite is reached, which you can indicate by double-clicking the mouse button or by pressing the "Tab" key or the "Spacebar" on your keyboard (provided that the image window is active). Note that in regions with very low contrast the program may fail to find a correct path. In such cases you may want to temporarily switch to manual ("straight-line") tracing mode, which is accomplished by pressing the "Shift" key on the keyboard (while the image window is active). Releasing the "Shift" key causes the program to return to automatic tracing mode.

To facilitate accurate positioning of starting points, so that they are really on a neurite rather than close to one, the program carries out a local snapping operation. This means that when moving the mouse within the image, the program quickly searches in a small window around the current mouse position for the pixel that is most likely to be on a neurite. This position is indicated by the red cross-hair cursor which is behind the real, white cross-hair cursor. The size of the search window, and thus the snapping range, can be set in the Parameters dialog (see below). Choosing a window size of 1 x 1 pixel effectively means switching off local snapping. Temporarily disabling local snapping is accomplished by pressing the "Ctrl" key on the keyboard (while the image window is active). Releasing the "Ctrl" key causes the program to enable local snapping again.
* * Delete tracings. Mode for deleting individual tracings. Move the mouse to the tracing that you would like to remove and the program will highlight it when it comes in its vicinity. If the Attributes dialog (see below) is open, it will show the tracing's attributes. Upon clicking the (left) mouse button the program opens a dialog asking whether you really want to remove the highlighted tracing. The tracing is removed upon pressing "Yes".
* * Measure tracings. Opens the dialog below for measuring tracing lengths.

NeuronJ: Measurements

There are two types of measurements: individual or statistical. With the former the program subsequently lists the image base name, cluster, type, label, and length of each individual tracing. In the case of statistical measurements the program computes and displays a summary of the tracing lengths, including the count (number of tracings incorporated), the sum (total length), the mean, the (N-1) standard deviation, and the minimum and maximum tracing length. With both types, the length measurements can be restricted to a certain cluster or type. The individual and statistical measurement results are displayed in separate text windows. The units in which lengths are expressed can be set in the Parameters dialog (see below).
* * Label tracings. Mode for setting the attributes of selected tracings. Pressing this button causes the dialog below to be opened, if it is not already open. The dialog remains opened until it is closed explicitly by pressing the dialog's "Close" button.

NeuronJ: Attributes

There are two ways of selecting tracings for labeling. The first is to use the upper choice-box, "Tracing ID". Selecting a tracing from this box causes the tracing to be highlighted in the image and the corresponding attributes to be displayed in the remaining items of the dialog. Now you can change the type, cluster, and label, which are stored upon pressing the "OK" button of the dialog.

The alternative way of selecting tracings, to be employed when you want to label multiple tracings in one go, is to move the mouse in the image to each tracing whose attributes you would like to set. The program will highlight the tracing when the pointer comes in its vicinity. Upon clicking the (left) mouse button the program marks the highlighted tracing for labeling (it remains highlighted). Once you have selected all tracings that should get the same attributes, you can return to the dialog, change the type, cluster, and label, and press the "OK" button of the dialog to apply them to all of the marked tracings. The possibility to specify a cluster allows you to group tracings, which may come in handy when doing measurements.

In addition to the default type and cluster, there are 10 tracing types and 10 tracing clusters, the names of which can be changed in the dialog that is opened when pressing the "Rename" button. In the left choice-box of that dialog (shown below), select the type or cluster you would like to rename, specify the new name in the text field on the right, and press "OK".

NeuronJ: Rename

Furthermore, each tracing type is assigned a certain color with which the corresponding tracings are drawn in the image. The color assignments can be changed in the dialog that is opened when pressing the "Recolor" button. In the left choice-box of that dialog (shown below), select the type of which you would like to change the color, select the new color in the right choice-box, and press "OK".

NeuronJ: Recolor
* * Set parameters. Opens the dialog below for setting the program's parameters. The values for the algorithm parameters shown (the default values) are equal to those given in the paper describing the program.

NeuronJ: Parameters

As described in the paper, the tracing algorithm computes optimal paths based on cost values computed from the eigenvalues and eigenvectors of the Hessian matrix at each point in the image. The first parameter is the smoothing scale at which these features are computed (parameter "sigma" in the paper). The second parameter determines the weight that is given to the eigenvalue costs versus the eigenvector costs (parameter "gamma" in the paper). Note that upon changing any of these two parameters, the program recomputes the cost values used by the tracing algorithm, which may take a few seconds again.

The third parameter is the size (in pixels) of the window used for local snapping. The fourth parameter determines the size (also in pixels) of the window to which path searching is restricted. This allows you to limit the computation time required by the program to recompute optimal paths after each mouse click. The optimal value of this parameter depends on the computational power of your computer as well as on your patience.

The next two parameters affect the visual smoothness of the tracings. The tracing smoothing range is the half-length (in pixels, not counting the center pixel) of the uniform filter that is applied to the pixel positions in the raw tracings as computed by the path searching algorithm. The larger this parameter, the smoother the tracings, but also the more difficult it will be to accurately trace sharply bending neurites. A value of 0 effectively means that no smoothing is applied. The tracing subsampling factor determines the frequency at which points along the smoothed tracings are sampled. A subsampling factor of 5, for example, means that only 1 out of every 5 pixels along tracings is kept.

The next three parameters allow you to set the pixel size and units in both x- and y-dimension. These are used by the program when measuring tracing lengths.

By default, when an image is closed (either explicitly by the user, or automatically by NeuronJ when loading a new image) and you made some changes in the tracings or the settings, the program will ask you if you want to save these changes. Marking the first check-box makes NeuronJ save any changes automatically when closing an image. Finally, with the last check-box, you can choose whether or not to let NeuronJ show debug messages.

Upon pressing the "Save" button, the settings in the dialog are saved to a file (called NJOptions.dat) on disk (in the root directory of ImageJ). Each time NeuronJ is launched, the program checks whether this file exists, and if so, loads it and sets the parameters accordingly.
* * Zoom in/out. Mode for enlarging or reducing the size of the displayed image and tracings. This functionality is based on ImageJ's zooming routines, which implies, among other things, that zooming is limited to 3200%.
* * Scroll canvas. Mode for scrolling the image canvas containing the image and tracings. This functionality allows you to shift the field of view for zooming levels of 200% and higher.
* * Quit NeuronJ. Opens a dialog asking whether you really want to quit NeuronJ. Upon pressing "Yes", the program provides the possibility to save the last changes pertaining to the current image (if any), whereupon the current image is closed, the original toolbar is restored, and NeuronJ is shut down.



Last update on September 05, 2005.