-
Notifications
You must be signed in to change notification settings - Fork 13
Vaa3DNeuron1.wiki
Content
There are several ways in the Vaa3D-Neuron module to trace, visualize, and measure the morphology of the 3D structure of a neuron. There are also some built-in functions for comparing various neurons or geometrically transform them. Note, in addition to the information shown below, recently the BigNeuron project (http://bigneuron.org) has used Vaa3D as the platform to develop a whole range of neuron tracing and utility functions. Please check BigNeuron project's GitHub page for more information (https://github.com/BigNeuron).
If you are using Vaa3D-Neuron 1.0, you can following an instruction here in the next section and also use this example dataset. You can watch a demo movie of Vaa3D-Neuron 1.0 tracing and editing. (Note: if you’d like to repeat this experiment, on some machines that may have different numerical precision of floating numbers, you may need to turn on the “full image” checkbox in the “Curve tracing parameters” dialog to ensure the entire image, but not only the “foreground” voxels - defined as whose intensity are above the mean intensity of the image, will be searched.)
Vaa3D-Neuron2 contains many interesting features of fully automated tracing, as well as interactive tracing. More details will be added in the near future.
If you are using the alpha-testing version of Vaa3D-Neuron 2.0, one additional feature is that you can use your computer mouse (or a tablet pen) to move over where you want to define the a curved structure in the neuron; Vaa3D can automatically use that information to produce a 3D reconstructed path (with all 3D XYZ information!). This function is called “paint-and-trace” (see this demo movie of Vaa3D-Neuron 2.0), and is a semi-automatic method which is designed to trace the place in an image where only a human user is able to tell what is the signal and what is not. Combined with the automatic path finding and editing functions in Vaa3D-Neuron 1.0 (see this demo movie of Vaa3D-Neuron 1.0), Vaa3D-Neuron 2.0 is able to trace very complicated neuron structure in a fairly easy way.
Similar to the 3D pinpointing, when using the 1-stroke paint-and-trace function, if the image signal is not in the first (i.e. red) channel, but in the 2nd (green) or 3rd (blue) channel, you can press the number key ‘2’, ‘3’ to specify the channel to use.
The software can be downloaded from http://penglab.janelia.org/proj/vaa3d . You need to ensure you download the correct version for you machine. If for any reason the standard QT library is not included in the Vaa3D installer, you may download it separately from Nokia's website (http://qt.nokia.com/).
See the PDF user-manual and tutorial movies on how to use Vaa3D can be downloaded from the Vaa3D website.
Drag and drop the test image "neuron01.tif" into the Vaa3D main window. You should see a tri-view window open and a 3D viewer (which is the global 3D viewer) automatically opens as well. You can change the behavior of the auto-launching of the 3D viewer from the main menu "File -> Adjust Preference -> 3D viewer -> Automatic launch 3D viewer ...".
You can define 3D markers either in the tri-view window or in a 3D viewer. In the tri-view window, just right-click the mouse to re-focus at any 3D localization, and press the 'm' key. More interestingly, you can directly define 3D markers in a 3D viewer using one- or two- mouse clicks. To do so, you go to the 3D viewer, when there is a 3D rendered volume image, you can right-click your mouse button (i.e. the secondary mouse button. If you have a different habit from most users and reset the order of mouse buttons, you need to figure out what is your own "right-click" on your mouse.), and then follow the pop-up menu to choose 1- or 2- clicks for marker definition.
-
For 1-click, you just move your mouse to anywhere you like to pinpoint, and right click it, then you should see a 3D marker gets defined and show up; you can repeatedly right-click the mouse and define as many markers as you like; you can exit this marker-defining mode by pressing the "Esc" key. If your image has multiple channels, you can press '1', '2', '3', ... , while you right-clicking, to specify which color channel you are working on to define the markers.
-
For 2-click, you right-click the mouse once at the location you want to pinpoint, and rotate the image to a different angle, and right-click at the same location again, then you will see a marker.
-
There is also a 3-click menu which uses 3 rays instead of 2 (as in the 2-clicks) and sometimes will give extra precision. But the 1- or 2-clicks should be very robust.
The pinpointed locations (markers) can be displayed in different colors, sizes, with their labels on/off. You can find the options easily on the 3D viewer's main control panel, or from the "Object Manager" button at top-right side of the 3D viewer control panel. You can also directly "jump to" a 3D marker using the "Landmarker Manager" from the Vaa3D main menu or on tri-view window control panel.
You can use these 3D markers for a number of different purposes. For example:
-
3D Annotation. You can right-click a marker in the 3D viewer, select the first menu item of the pop-up menu, and write down your annotations. You can export (i.e. save) the marker information as a .marker file, which is essentially a .CSV file and can be read by any other text editing program (e.g. Excel).
-
3D quantitative measuring.
-
You can right-click a marker and select the first item in the pop-up menu which shows regions statistics. You can adjust the radius, shape, and channel to check the statistics for a different setting.
-
You can also right-click a marker and select it as the starting location for measurement, and then right-click a different marker as the ending location for 3D measurement. In this way you can draw a line in 3D along any direction, and produce the intensity profile of all color channels for this line segment. This function can be used to measure gene expression or other image content directly.
Now you can pinpoint many markers that correspond to the terminal points of a neuron (e.g. the image "neuron01.tif"). You can also drag-and-drop the pre-generated marker file "neuron01.marker" into a 3D viewer. This will update the marker using what have been stored in the marker file. Again, the marker file is actually a .CSV file. Thus you can use any text editor to change it. But ensure you follow the format of the existing rows in the marker file example if you change it.
You can right-click any marker in a 3D viewer now and choose the menu item "Trace from one start pos to all others" to produce a 3D neuron reconstruction. If you would rather just trace the path between one pair of markers instead of doing it for all markers, you can right click the first marker and choose "Label as starting pos for tracing/measuring", and then right-click an ending marker and choose "trace from the start pos ..." menu items. You can specify which color channel to trace, as well as other parameters in the pop-up dialog.
The traced neuron structure is displayed right away. You can always undo/redo by pressing "Ctrl-/.wiki-z" and "Ctrl-/.wiki-x". The neuron is displayed as colored segments, bounded by branching points and neuron termini. You can right-click on any segment and follow the pop-up menu there to change the type (e.g. 0 – soma, etc.), delete it, break it into smaller pieces, and many other operations. To best use the V3D-Neuron tool, you can also display a neuron in different modes, e.g. line mode ("Ctrl-/.wiki-L" key), or other general surface display modes ("Ctrl-/.wiki-P"). Therefore, you can easily proofread the reconstructed structure. If you are unhappy with any portion, you can correct it conveniently.
You can right-click on a neuron in the 3D viewer and save it to a .SWC file, just choose "save the selected structure to file". You can also save the structure by selecting the main menu "Process -> 3D tracing ... -> Save the traced neuron to a file". You can do all other customary post-processing by using the Vaa3D Matlab IO toolbox to load a SWC file in Matlab and then use your own program. The toolbox can be downloaded from the Vaa3D website (http://penglab.janelia.org/proj/vaa3d).
You can select which channel contains the neuronal information to reconstruct, as well as many other parameters from the neuron tracing dialog when you select "Trace from one start pos to all others" or "trace from the start pos ..." menus. In Vaa3D the red channel normally corresponds to channel 1, and green to channel 2, blue to 3. V3D-Neuron 1.0 uses a method that combines a shortest path algorithm and a deformable curve algorithm. You can tune the parameters of both steps, and optionally also disable one of these steps.
You can also consider some special uses of the V3D tracing to make it much faster (if the default setting is not as fast as you like).
-
For example, if you use the "Volume Cut" X, Y, Z scroll bars in a 3D viewer to define a sub-volume of an image stack, then the neuron tracing will only run within that sub-volume and all marker outside of the sub-volume will not be used in tracing. Many times this makes the tracing much faster because only a much smaller number of voxels are considered in tracing.
-
Another example is that you can right-click any marker and select "open the local zoom-in 3D viewer", and then you can see a local 3D viewer, where you can do tracing as well. The tracing results will be automatically merged into that obtained for the entire image, with the correct coordinates. Such a local 3D viewer can also be launched from the Vaa3D main window as well (either 'Visualization' menu or 'See in 3D' button). Of course, you need to define a region of interest if you launch the local 3D viewer from the main window. You can press the '.wiki/Ctrl' key while you left-click your mouse in a tri-view window to define a region of interest. You can press 'Ctrl/.wiki-D' to remove previously defined vertexes of the polygonal region of interest. When you define different regions of interests in all the XY, YZ, and ZX planes of the tri-view window, the 3D region of interest is defined as their intersection. If you don't define a region of interest, then by default the entire image is treated as the region of interest.
-
Another special usage is that many times in confocal images the z-resolution can be much worse than that of xy plane. In this case, the separation of neuronal structure along z is hard to perceive. With V3D, you can adjust "Z-Thickness" (input either an integer or floating number) in a 3D viewer. Interestingly, we associate such a user-defined z-thickness factor to neuron tracing, and use it in computing the reconstruction. That means once a >1 z-thickness is given, that factor is multiplied to the z coordinates of voxels so that they may be better separated to produce a more reasonably reconstruction.
You can drag and drop many neurons into V3D and display them in different ways.
-
If you drag and drop into the V3D main window (but not an existing 3D viewer window), then V3D opens the neuron in a separate window (if this file is not currently being opened as the first neuron in an existing 3D viewer).
-
If you drag and drop a neuron into an existing 3D viewer, V3D will display two or more neurons together.
-
You can change the colors of neurons by either right-clicking a neuron and change color, or do it from the "Object Manager" from the V3D 3D viewer window. You can also define different color groups there. You can also search neurons based on their names in V3D Object Manager.
A special editing function of a neuron is to adjust its coordinate, size, width of a neurite tract, etc. You can right click a neuron and select "lock scene and adjust this object" and follow the instructions in the pop-up dialog.
When there are multiple neurons displayed in the same 3D viewer window, you can right click one of them and select "distance of two neurons". This will return a dialog contains all distances from the currently selected neuron to all remaining neurons in this window. The distance function is defined in the Vaa3D's Nature Biotechnology 2010 paper. In short, it is the average of the shortest Euclidean distance of all neuron reconstruction nodes to another structure. This metric provides a structure-free score of how similar any two neurons are. We also developed more sophisticated neuron similarity scores based on their structures, and developed some related V3D plug-in programs. If you need more information of these functions, please contact Hanchuan Peng.
Neuron Tracing
Converting Big-Image-Data
Build Vaa3D Qt6 version on Windows
Build Vaa3D Qt6 version on Ubuntu 20.04