nImage: automated neuron tracing in 3D volumes

Welcome to nImage. I wrote this function while working on my PhD in Gilles Laurent's lab at Caltech. It automates the process of isolating an object from background in a 3D volume. This process was designed for use with an image stack of an individual neuron filled with a (fluorescent) dye and imaged on a confocal or 2-photon microscope.

The gist of the process is: you load in your stack then pick a few starting points within the cell. The script uses those points and some other tunable parameters (see below) and traces out the cell from the background. The principal is that the cell is brighter than its local background at any point.

You can go on to pick more starting points after the initial run of the program until your cell has been traced out (in case there are gaps in brightness etc.) Though a bit of manual work is required, the process is fast and stress-free once you get the hang of it.

To see how I applied nImage to my work take a look at some links. You can also read about nImage in the methods section of my thesis.

Top

Note that (sadly) as of May 2005 nImage was not working on MAC OSX because MATLAB (v.7) for OSX has a java-related bug for which there is no workaround. Later versions of Matlab may have fixed these issues.

nImage has been optimized to work with the following configuration:

• Microscoft Windows XP running MATLAB 6.5 or 7.0 with available service packs

• • If using MATLAB 7.0, before running nImage you must enter the following command:

                    feature('javafigures', 0)

• • This disables JAVA features which contain bugs and interfere with nImage's proper performance

• 2GHz pentium IV processor (or faster)

• At least 1GB of RAM; 3GB or more will give much better performance

Top

nImage requires a particular type of image format saved with particular names. If your images are not already in this format, I suggest using a program such as ImageJ to convert your files.

Images from a stack must be saved individually as 8-bit grayscale tiffs in the same location. Save each with the same prefix, followed by a dash and a three-digit number corresponding to the stack position of the image, where the first image is 000. For example, the first image in a stack could be saved as image-000.tif (where the prefix 'image' can be any string). Then the second image in that stack would be saved as image-001.tif, and so on to the last image (image-xxx.tif). Note that in this current version, nImage doesn't handle more that 1000 images in a stack - up to number 999.

When you run the function, you have the option of searching a smaller chunk of your stack. So if you have a stack of 300 images, and you only want to trace out a cell in images 30 through 100, you can.

The images can be any size, as long as all the images in the stack are the same size. nImage reads in the size of the image automatically. I suggest an image size no larger than 512 x 512 pixels to save processing time.

Top

If using MATLAB 7.0, before running nImage you must enter the following command:

                    feature('javafigures', 0)

This disables JAVA features which contain bugs and interfere with nImage's proper performance

Once you've started Matlab, you can simply start the function by using the command:

            nimage18b(hotthresh,minframe, maxframe, changedefault)
where

• hotthresh is the threshold for a preliminary filtering pass through your stack. This is useful if there are a lot of saturated pixels throughout the stack. The range for hotthresh is a number between 0 and 255; use 255 in order to avoid any filtering; generally, it is not a good idea to use a hotthresh lower than 230

• minframe is the image number of the first image in stack. You can have your starting point as any image in the stack, as long as the ending point is an image with a higher number. nImage will search all images between minframe and maxframe (below). This should be a number between 0 and 999

• maxframe is the last image in the stack. This must be a higher number than minframe. nImage will search all images between minframe (above) and maxframe. This should be a number between 0 and 999

• changedefault tells the function if you want to be allowed to change the search parameters (see parameters below). If you set this to 1, then the function asks you to enter values for the parameters when it begins. If you don't want to change the default values (which is a good idea when you're first getting started) set changedefault to 0.

Once you've started nImage running, a dialogue will appear, asking you to select an image from the stack you want to examine. Choose any image in the stack - this helps nImage identify the path and file prefix for your images. (Note that all of your images should be saved in the same folder.)

If changedefault is set to 1, you be will asked to specify the variables you want to change and their new values at this point. If changedefault is set to 0, you simply get a printout of the current values of these parameters.

Next you will be asked if you'd like to load a previous array. For your first run, answer no. Previous arrays are discussed below.

Top

Once your entire stack has been loaded, you are asked to identify a starting pixel or pixels. Use the up and down arrows on your keyboard to move though the stack. Using your mouse, point to a pixel that you can identify as definitely within the neuron of interest and press the space bar. The pixel should now appear red. (A good starting point is a bright pixel in the neuron's soma.) For keyboard commands related to moving through the stack see Keyboard Shortcuts.

You may continue in this manner and identify as many starting points as you desire. I recommend you begin with just one or two pixels. More starting points usually adds unncessary processing time, but will not necessarily do a better search.

Once you have identified your starting pixels, press q on your keyboard. This starts the search loop that identifies all the connected pixels to your starting pixel(s).

When the search is completed (this can take several hours depending on the size of your image stack, background noise, etc.) your stack is loaded again, this time with all the identified pixels from the search (as well as your starting pixels) highlighted in red. At this point, you may choose more starting pixels and continue with the search. If you're happy with this first run through, press the s key on your keyboard to save the work. Then, press the t key to terminate nImage.

Top

• thresh: the number of standard deviations above the mean brightness of its immdediate neighbors that a pixel should be in order to be identified as part of the cell image. Generally, this number should be between 2 and 4. The dafault value of thresh is 2

• S: Search square radius. For each pixel P which is searched and identified as a part of the cell, S is the number of pixels around P in each direction which will be searched next. The default value of S is 4

• N: Outer square radius. Defines the outer limit, in the x-y plane, of the shell of pixels around P that is used to generate the mean and standard deviation (SD) to which P is compared. N must be greater than M (below). The default value for N is 8

• M: Inner square radius. Defined the inner limit, in the x-y plane, of the shell of pixels around P that is used to generate the mean and SD to which P is compared. M must be less than N (above). The default value for M is 7

• R1: Outer depth radius. Defines the outer limit, in the Z (depth) plane, of the shell of pixels around P that is used to generate the mean and SD to which P is compared. R1 must be greater than R2. The default value for R1 is 3

• R2: Inner depth radius. Defines the outer limit, in the Z (depth) plane, of the shell of pixels around P that is used to generate the mean and SD to which P is compared. R2 must be less than R1. The default value for R2 is 2

Top

nImage allows you to load in stacks or arrays saved from previous searches so that you may continue a previous search. When you first start an nImage run, you will be asked if you'd like to load in a previous array (see the section on Getting Started above). When you enter "y", you will be prompted to select an image from a previously saved array. If this saved array was generated using a previous run of nImage, it should be in the proper format already and will give nImage all the information it needs to find and load the saved array, and also to find the previously identified hot pixels. nImage can then use the original stack and the saved array to display previously identified hot pixels in red. You may continue the process of choosing seed pixels as discussed above.

Top

A number of keyboard shortcuts help you navigate around your stack, choose seed pixels, start the search, and terminate nImage. Keyboard shortcuts are:

• f: moves to the first image in the stack (where the smallest image number is first)

• l: moves to the last image in the stack (where the largest image number is last)

• up arrow: moves to the next image

• down arrow: moves to the previous image

• left arrow: moves 10 images before the current image

• right arrow: moves 10 images after the current image

• space bar: marks the pixel that the pointer is currently pointing to as a seed pixel. This pixel should now appear in red

• q: terminates the choose-seed-pixels process and begins the search

• s: saves the current array (saves all pixels that currently appear red)

• t: terminates nImage

Top

Once your stack is loaded and displayed you may use the s-key to save the stack at any time, as long as the function is not conducting an active search. nImage will automatically create a folder within the directory where the original stack is saved called 'nout' appended by a number corresponding to the number of saves, and will save the images for the current save there. For example, the first time you press the s-key, nImage will create a folder called nout-1, the second time you save, it will create another folder called nout-2 etc.

The stack is saved as a series of 8-bit grey-scale tiff images (with pixel value range between 0 and 255), where all the hot pixels found by nImage have the value 254 - 254 is now the top value in these images. This is done so that nImage can identify the hot pixels if you load a stack in as a previous array.

When you are completely done tracing your cell, you can simply 'extract' your cell from the most recent saved array or nout-final (or any saved array of your choosing) by filtering out all pixels with values under 254. It can be helpful to have the original pixel values of these hot pixels for reconstruction purposes; to do this, use your filtered nout-final array as a mask on the original stack to extract your original pixel values.

Top