Difference between revisions of "SNT: Manual"

(Advanced Text Filtering)
(Advanced Text Filtering)
Line 329: Line 329:
 
[[File:SNT-Path-Manager-Filtering-Menu.png|right|thumb|Advanced Filtering Menu]]
 
[[File:SNT-Path-Manager-Filtering-Menu.png|right|thumb|Advanced Filtering Menu]]
 
The Advanced Filtering Menu [[File:SNT-Text-Filter-Advanced-Button.png]] provides more sophisticated means of filtering paths, including support for wildcards (?*), color and morphology tag matching.
 
The Advanced Filtering Menu [[File:SNT-Text-Filter-Advanced-Button.png]] provides more sophisticated means of filtering paths, including support for wildcards (?*), color and morphology tag matching.
 +
[[File:SNT-Advanced-Text-Filtering-Text-Filtering-Menu.png|right|thumb|Text Filtering menu]]
 
* '''Text Filtering''' Contains options for advanced text filtering
 
* '''Text Filtering''' Contains options for advanced text filtering
 
** ''Case Sensitive Matching'' treats uppercase and lowercase characters as distinct.
 
** ''Case Sensitive Matching'' treats uppercase and lowercase characters as distinct.

Revision as of 14:38, 7 May 2019

Main Dialog

Main Tab

This home tab aggregated widgets for tracing and frequent operations.

Cursor Auto-snapping

Enable Snapping checkbox If active (the default) the cursor snaps to the brightest voxel in its vicinity (Toggling shortcut: S). To accomplish this, SNT takes the cuboid of the specified dimensions (in pixels) centered on the current cursor position and searches quickly for local maxima in that neighborhood, moving the cursor to that position. The Z-plane in which the maximum was found is automatically selected if the "Z" parameter is greater than 0. Noteworthy:

  • This feature assumes the signal is brighter than the background as typically found in fluorescent images.
  • If multiple maxima exist (e.g., when the signal is saturated), it snaps to their centroid.
    Cursor-snap.png
  • To streamline the computation: XYZ dimensions are constrained to even numbers and limited range.
  • Snapping occurs in 2D (i.e., in the active plane) if Z=0.
  • The XZ, ZY views are synchronized when 3D snapping is active (i.e., Z>0).

Auto-tracing

"Auto-tracing" widget

Enable A* Star By default, SNT uses the A* search algorithm to automatically trace paths between two manually selected points. To manually place nodes in a path, toggle this feature off. Note that it is also possible to enable other algorithms through the installation of further SNT addons. See SNT: Tubular Geodesics for more details.

Hessian-based analysis (Toggling shortcut: H) A quick way to improve the quality and efficiency of the pathfinding is to enable this feature, in which paths are computed after filtering the image for tube-like structures. Upon such filtering, SNT will use a measure of Tubeness at each point of the image to define the best path through it, based on eigenvalues and eigenvectors of the Hessian matrix. The later can be used to infer the likelihood that a point in the image belongs to a a tube-like structure. This concept is also known as vesselness or neuriteness.

Hessian options (Specified in the gear drop-down menu). Hessian analysis requires two parameters to be specified:

  • Sigma Controls the spatial scale of the filter. A lower Sigma will capture small scale structure but is more sensitive to noise. A larger Sigma will consider larger scale structures but is less sensitive to local shape characteristics. It is generally advised to pick a value which reflects the average radius of the structures to be traced. It corresponds to the standard deviation of the 3D Gaussian kernel used to smooth the image prior to Tubeness filtering
  • Maximum The maximum pixel intensity on the Tubeness image beyond which the cost function for A* search is minimized.

These parameters may be chosen "Manually" (if you already have a quantitative understanding of the image) or "Visually" (generally more intuitive). If you choose "Visually", the dialog will prompt you to click on a representative region of the image which has meaningful structure. Once you click there, a 9-square palette is generated showing increasing values of sigma (from top-left to bottom-right) applied to that chunk of the image. The palette is an image stack which can be scrolled through with the mouse wheel.

Adusting max
Sigma-palette-location.png
Sigma-palette-max.png
Sigma-palette-mid.png
Sigma-palette-min.png
Oversaturated Default Undersaturated
Choosing sigma and max. parameters visually for hessian analysis from a representative region in the image (orange box). With saturated max, the cost function for A* search is equivalent across the signal. Also, note how lower sigma values cause the axon to be dimmer on the center and brighter on the edges, while higher sigma values eliminate detail from the structure.

Experiment with different Adjusted max. values to find a setting which captures the structures you are interested in while taking care to avoid over or under-saturation. In the former case, the search might consider pixels outside of the tubular structures, giving a less accurate result. In the latter case, the search might take significantly longer, since each pixel will carry greater cost than is reasonable. It is usually safe to choose a value somewhere near the default. Once you have chosen this value, click on the square in the palette with the sigma that best fits your application (its border will turn green) then press "Apply". The parameters will be transferred to the interface and a Gaussian convolution will be run over the image, which may take some time depending on its size. Once it's done, pathfinding will occur on the Hessian (aka Tubeness) image.

Other options are also available in the gear drop-down menu:

  • Cache All Hessian Computations By default SNT computes the Hessian matrix on a "compute-as-you-go" basis, which saves memory but increases the pathfinding time. If you have enough RAM, you can use this option to compute once the matrix and for the full image and cache the result, which in certain cases, can lead to almost-instantaneous searches. Note that this computation adopts the current values of sigma and max. reported in the widget, so you should adjust those before running this command.
  • Flush Cached Data Removes cached data from memory
  • Load Precomputed "Tubeness Image" This (advanced) option prompts you to load a file of a Tubeness image generated elsewhere. This is useful if e.g., you want to experiment algorithms from other software packages, or your own. Note that loaded image is assumed to have compatible dimensions with the image currently being traced.
  • Show Cached "Tubeness Image" Displays the Tubeness data currently cached. Useful for debugging purposes. Also mirrored in View  › Show Cached/Loaded Hessian (Tubeness) Image.
Original (left) and Hessian (right)

Tracing on Filtered Image

SNT's "Hessian-based analysis" option provides a convenient and easy way to preprocess your data. However, if your data require tailored preprocessing, you may also trace on a user-specified filtered image. For example, one might use the Frangi et al. 1998 method to enhance vessel-like structures in the image.

A Single Image

To process a single image with the Frangi Vesselness filter, load it ("test.tif", say) into Fiji and select Process  › Filters  › Frangi Vesselness. (There is more information about this plugin on its page.) By way of example, let's say you select two scales, twice the x voxel separation and five times that value. We apply a Gaussian convolution at each scale. Assuming your image has isotropic resolution with pixel width = pixel height = pixel depth = 1, the parameters would be:

Frangi parameters

Save the result by doing File  › Save As with the same extension as the original image ("test-filtered.tif", for example). Then, with SNT open, go to the main dialog tab and look for the "Tracing on Filtered Image" widget. Click "Browse" to load the filtered image, select "SNT" for the parser and press "Load". Finally, toggle the "Trace on filtered Image" checkbox. Now the pathfinding will occur on the filtered image.

  • Step 1
  • Step 2

To display the image in a separate window, from the SNT dialog go to View  › Show Filtered Image

Side-by-side original and filtered images

Preprocess Multiple Images

The easiest way to preprocess multiple images is to record a macro for processing a single image, then wrap it in a loop to iterate over all files in a directory. For example:

d = getDirectory("Select a directory");
files = getFileList(d);

extension = ".tif";

for( i = 0; i < files.length; ++i ) {
    filename = files[i];
    if( endsWith(filename,extension) ) {
        l = lengthOf(filename);
        el = lengthOf(extension);
        basename = substring(filename,0,l-el);
        expected_window_name = "vesselness of "+filename;
        output_filename = d + File.separator + basename + ".tubes.tif";
        open(filename);
        run("Frangi Vesselness (imglib, experimental)", "number=1 minimum=0.288387 maximum=0.288387");
        selectWindow(expected_window_name);
        saveAs("Tiff", output_filename);
    }
}

Filters for Visibility of Paths

By default, the entire path is projected onto the current Z-slice. This is useful to see how much has been completed, and gives a sense of the overall structure of the reconstruction. However, SNT provides 3 additional visibility options for paths:

"Filters for visibility of paths" widget
  1. Only selected paths (hide deselected) - Only show paths that have been manually selected in the Path Manger or with the G key ( Shift+G to select multiple paths).
  2. Only nodes within X nearby Z-slices - Only highlight nodes within X number of Z-slices on either side of the current slice. The projected skeletons of all paths remain visible.
  3. Only paths from active channel/frame - If tracing on a multichannel image or an image with a time axis, only show paths from the active channel or frame.

Any combination of these options may be toggled simultaneously.

Default Path Colors

Path coloring in SNT indicates status of the path. The default color indicators for finished paths are:
"Default Path Colors" widget
CMYK color selection UI
  • Green
    - Selected
  • Magenta
    - Deselected, meaning the path cannot be extended or edited until selected.

The default color for each path type can be changed to any color in the CMYK color model. To do so for selected and deselected paths, press the "Selected" or "Deselected" button in the "Default Path Colors" widget. For unconfirmed and temporary paths, see the "Colors" option in the UI Interaction widget.

The "Enforce default colors (ignore color tags)" option, if active, will force all paths to conform to the default colors specified by the "Selected" and "Deselected" color buttons. Any custom color tags will be ignored until the option is toggled OFF.

Selected paths can be assigned custom color tags in the Path Manager. To do so, go to Tag  › Color then choose the desired swatch. Each path can be assigned any color. To change color of all paths, deselect all paths first. Metric-based color mapping of paths can be done in the Path Manager through the Analyze › Color Coding menu option. See here.

Tip: Hover the mouse cursor over a color swatch to display a tooltip with its RGB value.



  • Color tagging
  • Arbitrary path coloring
  • Result


Options Tab

This tab aggregated widgets for advanced settings.

Data Source

"Data Source" widget

If tracing on a multi-dimensional image (i.e., one with multiple data channels and/or a time axis), a particular channel/frame can be loaded into the views by selecting each and pressing the "Reload" button.

Views

"Views" widget
  • Image without MIP overlay
  • Image with MIP overlay at 30%
  • Draw diameters in XY view - Display the stored diameter (if any) in the XY view for all existing nodes. Each diameter is drawn as a line segment with length = diameter, which is bisected by the orthogonal tangent vector to the path at that node.
  • Draw diameters in XY view - disabled
  • Draw diameters in XY view - enabled
  • Apply zoom changes to all views - If a zoom change is applied to any one of the XY, ZY or XZ views, apply the same change to the two other views if they are open. May resize windows.
  • Resize Canvas - If using a display canvas to view reconstructions, reset its dimensions to the default. (Currently, this command is only available for display canvases, to resize an image go to IJ's command Image  › Adjust  › Canvas Size...
  • Display ZY/XZ views - If currently using the XY only view, display the ZY and XZ views as well.

Temporary Paths

"Temporary Paths" widget
  • Confirm temporary segments - If active, prompts for either confirmation or denial of whether or not to keep an unconfirmed path segment. If inactive, automatically confirms the path segment created on each left-click after starting a path (first click). Applies to both auto-traced and manually traced path segments. The following two settings are only toggle-able when this setting is active.
    • Pressing 'Y' twice finishes path - Finish a temporary path on two successive Y key presses.
    • Pressing 'N' twice cancels path - Discard a temporary or unconfirmed path, including the start node, on two successive N key presses.

UI Interaction

"UI Interaction" widget
  • Colors - The default color for the following items (can be changed to any color in the CMYK color model):
    • Red
      - Canvas annotations: these indicate the various possible states of the UI, and are shown in the top-left corner of the views ("Tracing Paused", "Choosing Sigma", etc...)
    • Dark Green
      - Fills: the pixels that have been reached by the Fill search.
    • Cyan
      - Unconfirmed paths
    • Red
      - Temporary paths
  • Path nodes rendering scale - (default is 2 pixels at default zoom level) Adjusts the radius of the circles representing path nodes. A path node is rendered as a circle centered at the XYZ coordinate of the point annotation.
  • Activate canvas on mouse hovering - If active, moving the mouse cursor over the any of the views automatically brings the view window into focus, allowing it to receive input.

Misc

"Misc" widget
  • Remember window locations - If active, preserves the position of dialogs across restarts.
  • Use compression when saving traces - If active, uses Gzip compression (lossless) to reduce the storage footprint of the ".traces" file.
  • Skip confirmation dialogs - If active, forgoes the "Are you sure?" prompt preceding major actions.
  • Debug mode - If active, logs detailed information about actions in the console.

The "Reset Preferences..." button, when pressed, will reset all options to their defaults. A restart of SNT may be required for changes to take effect.

3D Tab

"3D" menu tab

This tab aggregates widgets related to 3D interaction.

Reconstruction Viewer

The Reconstruction Viewer is an advanced OpenGL visualization tool. For performance reasons, some Path Manager changes may need to be synchronized manually from RV controls. To open Reconstruction Viewer with the currently loaded tracings, press Open Reconstruction Viewer. For more information, see the Reconstruction Viewer wiki page.

Legacy 3D Viewer

The Legacy 3D Viewer is a functional tracing canvas but it depends on outdated services that are now deprecated. It may not function reliably on recent operating systems. For usage instructions, see Legacy 3D Viewer

SciView

SciView is IJ2's modern replacement for the Legacy 3D Viewer providing 3D visualization and virtual reality capabilities for both images and meshes. It is not yet available in SNT.


Path Manager

Path Manager

The Path Manager dialog displays all existing paths in a hierarchical structure (tree), where one path is "primary" (path 0) and all other paths (paths 1...N) are children of the primary path. The dialog also contains several menus with various editing, tagging, refinement/fitting, filling and analysis options. Paths can be searched by name and/or tags in the text filter.

Edit

  • Delete Remove selected path(s) from the Path Manager. This will also delete them from the tracing and update the canvas accordingly.
  • Rename Rename the selected path.
  • Make Primary Make the selected path the primary path, moving it to the top of the tree. Note that this alters the path ordering.
  • Disconnect Disconnect the selected path from all of its connections.
  • Merge Merge the selected paths (at least two) into one path. Note the starting node of path i is merged to the endpoint of path i+1
  • Specify Radius Specify a constant radius to be applied to all the nodes of selected path(s). This setting only applies to unfitted paths and overrides any existing values.
"Edit" menu
  • Ramer-Douglas-Peuker Downsampling Given an inputted maximum permitted distance between adjacent nodes, perform Ramer-Douglas-Peucker downsampling on the selected path(s). N.B.:
    • This operation cannot be undone.
    • Paths can only be downsampled: Smaller inter-node distances will not be interpolated.
    • It is advised to choose a value at least twice the smallest voxel separation.


Tag

"Tag" menu
  • Type Type of neurite compartment. SNT provides four basic types associated with neuronal structures, as well as the ability to define custom tags:
    • Basal Dendrite
    • Apical Dendrite
    • Axon
    • Custom
    • Soma
    • Undefined
  • Color Assigns the color shown in the swatch to selected paths. Custom colors can be manually chosen using the CMYK palette or mapped using the Color Mapper.
  • Image Metadata Tag path with any of three types of metadata:
    • Traced Channel
    • Traced Frame
    • Slice Labels
  • Morphology Three morphometric properties:
    • Branch Order Centrifugal branch order of the path.
    • Length - Path length.
    • Mean Radius - Path mean radius.
  • Custom Specify a custom tag string.
  • Remove All Tags Remove all tags from selected paths. SWC-type tags are preserved.

Refine/Fit

"Refine/Fit" menu

See Fitting in the Step-By-Step Instructions wiki page.


Fill

"Fill" menu
  • Fill Out Begins the filling process for selected paths. For detailed instructions see Filling in the Step-By-Step Instructions page.


Analyze

This menu contains several options which provide quick ways to analyze and visualize numerical properties of paths.

"Analyze" menu
  • Color Coding Assigns color codes to paths based on the chosen metric.
    • Color by Drop-down menu containing the metrics which inform the color mapping.
    • LUT Drop-down menu containing the LUTs (Look Up Tables) that define the color palettes. The LUTs are those that come packaged with ImageJ. The selected LUT is displayed in the color bar directly underneath.
    • Rec. Viewer Color Map If active, opens an instance of the Reconstruction Viewer with the selected paths color coded with the selected LUT.
    • Rec. Plotter Color Map If active, open an instance of the Reconstruction Plotter with the selected paths color coded with the selected LUT.
    • Remove Existing Color Coding Removes existing color coding from the selected paths.
After choosing metric: Branch Order, LUT: Ice, showing the Reconstruction Viewer with the color-mapped OP_1 tracing.
Color Mapper prompt
OP_1 color-mapped


  • Distribution Analysis Plots a histogram of the selected metric.
    • Measurement - Drop-down menu with the available metrics.
Choosing Branch Order for the measurement.
Distribution Analysis prompt
Branch Order histogram


  • Measure Shows a table of summary statistics for selected paths. If measuring multiple tracings, the table can be sorted by column.
Measurements table for OP_1


  • Convert to ROIs Allows conversion of paths to ROIs (Regions of Interest). Creates an instance of the ROI Manager
    • Convert Drop-down menu specifying the compartment to convert.
    • View Drop-down menu specifying which view to overlay the ROIs.
    • Impose SWC colors
    • Adopt path diameter as line thickness
    • Discard existing ROIs in ROI Manager
Converting paths to ROIs with the default parameters.
Convert to ROIs prompt
ROI Manager


  • Plot Profile Uses the pixel intensity values under point annotations to generate a pixel intensity vs. distance plot for selected paths.
Intensity profile for Path 0 of OP_1.
SNT-Path-Profile-Graph.png


  • Skeletonize Outputs a binary image that is a topographic skeleton, ie, it generates an empty (zero-filled) image of the same dimensions of the one being traced, then paints a pixel at each node coordinates following the topographic rules of bitmap skeletons in which fork points, tips and slab voxels are determined by voxel connectivity.
    • Roi filtering
      • None
      • Convert only segments contained by ROI
    • Run "Analyze Skeleton" after conversion Runs the AnalyzeSkeleton plugin on the skeletonized output image.
Converting paths to a topographic skeleton with default parameters.
Skeletonize prompt
Skeleton of OP_1, Z-projected


  • Save as SWC Exports selected paths as an SWC file. Note the paths to be exported must include a primary path (i.e., one a the top level in the Path Manager tree).


Text Filter

Text Filter

The text filter allows paths to be searched by any characters in the path name string and by color. The name string includes all tags.

  • Up Arrow Button SNT-Text-Filter-Up-Arrow-Button.png Finds next occurrence of the entered phrase.
  • Down Arrow Button SNT-Text-Filter-Down-Arrow-Button.png Finds previous occurrence of the entered phrase.
  • Balloon Button SNT-Text-Filter-Balloon-Button.png Highlights all occurrences of the entered phrase.


Advanced Text Filtering

Advanced Filtering Menu

The Advanced Filtering Menu SNT-Text-Filter-Advanced-Button.png provides more sophisticated means of filtering paths, including support for wildcards (?*), color and morphology tag matching.

Text Filtering menu
  • Text Filtering Contains options for advanced text filtering
    • Case Sensitive Matching treats uppercase and lowercase characters as distinct.
    • Enable Wildcards Allows the use of the question mark (?) and asterisk (*) wildcards.
      • "?" Matches exactly one character. For example, the pattern 123? will match 123 and 1234, but not 12345.
      • "*" Matches zero or more characters. For example, doc* matches doc and document but not dodo.
    • Loop After First/Last Hit Cycles back to the first/last matched phrase upon pressing the Up/Down Arrow Button at the end of the list of matches.
    • Display No. of Matches Displays the number of phrase matches in the bottom left corner of the Path Manager dialog.
    • Replace Replaces all occurrences of the matched phrase in the path name string for currently selected paths.
    • Clear History Erases the previously searched phrases in the text filter drop-down menu.
    • Tips & Shortcuts
      • Case-insensitive by default. Wildcards ? (any character), and * (any string) can also be used.
      • Press the Highlight All button or Ctrl+A to select all the paths filtered by the search string.
      • Press and hold Ctrl while pressing the up/down keys to select multiple filtered paths.
      • Press the up/down keys to find the next/previous occurrence of the filtering string.
      • Uncheck Display No. of Matches to improve search performance.

Fill Manager

Provides controls for all filling operations. It is described in more detail in the Filling Walkthrough