diff --git a/_pages/plugins/snt/auto-tracing.md b/_pages/plugins/snt/auto-tracing.md index 098ad97af..b199bde3b 100644 --- a/_pages/plugins/snt/auto-tracing.md +++ b/_pages/plugins/snt/auto-tracing.md @@ -10,7 +10,7 @@ tags: snt,tracing,neuroanatomy,big-data --- {% capture version%} -**This page was last revised for [version 5.0.0](https://github.com/morphonets/SNT/releases)**. +**This page was last revised for [version 5.1.0](https://github.com/morphonets/SNT/releases)**. {% endcapture %} {% include notice content=version %} @@ -18,12 +18,31 @@ Fully automated tracing routines can be accessed through the _Auto-trace_ menu i # Grayscale Images -Grayscale images are processed using the {% include bc path='Auto-trace|Grayscale Image...' %} command for images already loaded or {% include bc path='Auto-trace|Grayscale Image File...' %} to load from disk ([Big data support](#about-the-algorithm)). +Grayscale images are processed using the {% include bc path='Auto-trace|Grayscale Image...' %} command for single-cell tracing of images already loaded, or {% include bc path='Auto-trace|Grayscale Image (Multiple Cells)...' %} when the image contains multiple cells (see [Multiple Cells](#multiple-cells)). File-based and batch variants are available under {% include bc path='Auto-trace|Batch Processing' %} ([Batch Processing](#batch-processing)). + +This command reconstructs neuronal structures directly from grayscale (intensity) images without requiring binarization. The method is particularly effective for fluorescence microscopy images with bright foreground structures on dark backgrounds. It builds on two foundational algorithms: [APP2](https://pubmed.ncbi.nlm.nih.gov/23603332/) (Gray-Weighted Distance Transform with Fast Marching and hierarchical pruning) and [neuTube](https://pubmed.ncbi.nlm.nih.gov/26464967/) (several of the [post-processing](#post-processing) refinements described below). SNT extends these with its own capabilities: + +1. **Images parsed at full-resolution** and native bit-depth without downsampling + +2. **[Big data](./big-data) support**: Ability to process TB datasets that exceed available RAM + +3. **Learning from manual annotations**: Ability to [derive tracing parameters](#learning-parameters-from-selected-paths) automatically from ground-truth paths, reducing trial-and-error when tuning the algorithm for a new dataset + +4. **Score maps for pruning guidance**: Ability to use either Vesselness-based (e.g., [Tubeness](/plugins/tubeness)/[Frangi](/plugins/frangi)) or external segmentation p-maps to better guide the detection of neurites + +5. **Tip extension across dim gaps**: Ability to 'hop' over blebbed or non-contiguous signal + +6. **Post-hoc fitting for node position and radius [refinement](./manual#refinefit-)**: Ability to obtain more natural curvatures by snapping traces to the neurite's signal + +7. **Automated detection of somata**: Ability to simultaneously seed the tracing algorithm on somata in a multi-cell labeled neuropil + +8. **Territory-controlled multi-soma tracing**: Ability to predict whether a neurite belongs to which cell in a _sparsely labeled_ multi-cell neuropil + +For technical implementation details and references, see the [SNT technical notes](https://github.com/morphonets/SNT/blob/main/NOTES.md). -This command reconstructs neuronal structures directly from grayscale (intensity) images without requiring binarization. It uses the Gray-Weighted Distance Transform (GWDT) algorithm combined with Fast Marching and hierarchical pruning, following an [APP2-like strategy](https://pubmed.ncbi.nlm.nih.gov/23603332/). The method is particularly effective for fluorescence microscopy images with bright foreground structures on dark backgrounds. {% capture op1-demo%} -You can follow these instructions using {% include bc path='File|Load Demo Dataset...' %} and choosing the _Drosophila OP neuron_, a Drosophila olfactory projection neuron and respective ground truth reconstruction. +You can follow these instructions using {% include bc path='File|Load Demo Dataset...' %} and choosing either 1) the _Drosophila OP neuron_, a Drosophila olfactory projection neuron and respective ground truth reconstruction (single cell); or the _Microglia cells_ dataset, a 2D image with multiple ramified microglia in the mouse retina. {% endcapture %} {% include notice icon="info" content=op1-demo %} @@ -35,7 +54,7 @@ You can follow these instructions using {% include bc path='File|Load Demo Datas The algorithm requires a starting point (seed) to begin tracing. Several strategies are available: -- **None. Use auto-detection** Automatically detects the soma/root at the thickest and brightest region using a combined Euclidean Distance Transform (EDT) and intensity scoring approach. This strategy finds the most prominent structure in the image, which typically corresponds to the cell body (see [Soma Detection](#soma-detection)). No ROI is required +- **None. Use auto-detection** Automatically detects the soma/root at the thickest and brightest region as per [Soma Detection](#soma-detection). No ROI is required - **Area ROI around soma: One tree per primary neurite** An area ROI delineates the soma boundary. Creates separate trees for each neurite exiting the soma, rooting them at the soma perimeter. Best for complex morphologies where multiple primary branches emerge from the cell body and individual neurites need to be analyzed separately @@ -57,43 +76,103 @@ When working with 3D images, the _Active plane only_ option restricts the ROI to - Adjust manually if auto-detection includes too much noise or misses dim structures - Valid range: -1 (auto) to the image maximum intensity -## Branch Filtering +## Branch Filtering and Scoring These parameters control which branches are retained in the final reconstruction: -**Min. segment length** The minimum intensity-weighted length threshold for branches to be included. This metric accumulates normalized pixel intensities along each branch path (rather than measuring spatial distance), so brighter branches accumulate length faster than dim ones. Branches below this threshold are pruned as noise. Increase to remove small spurious branches; decrease to retain finer details. Default: 5.0 +**Score map filter** Selects a vesselness filter used to compute a confidence map for each traced segment. The score map assigns a "how tube-like is this location" score to every node, enabling adaptive pruning that adapts to each segment's minimum radius: The pruning is more lenient for thin structures and stricter for thick ones. Options include: -**Connectivity** Defines the neighborhood connectivity used during tracing: -- _Low_ (6-connected): Only axis-aligned neighbors -- _Medium_ (18-connected): Axis-aligned plus face-diagonal neighbors (default) -- _High_ (26-connected): All 26 voxel neighbors including edge and corner diagonals +- _None_: Disables score-based pruning +- _Tubeness_ (default): Hessian-based [tubeness](/plugins/tubeness) filter, computed at scales derived from the radius distribution (25th/50th/75th percentile) of the initial reconstruction +- _Frangi_: [Frangi](/plugins/frangi) vesselness filter, an alternative Hessian-based approach +- _Secondary image layer_: Uses the currently loaded [secondary layer](./manual#tracing-on-secondary-image-layer) as a pre-computed score map (e.g., a deep-learning probability map obtained outside SNT) + +**Min. branch score** The minimum intensity-weighted score threshold for branches to be included. This metric accumulates normalized pixel intensities along each branch path (rather than measuring spatial distance), so brighter branches accumulate score faster than dim ones. Branches below this threshold are pruned as noise. Increase to remove small spurious branches; decrease to retain finer details. Default: 5.0 + +**Branch sensitivity** Controls how aggressively dim branches are pruned relative to the overall signal. Higher values impose stricter requirements; lower values are more permissive. Default: 0.3 + +**Overlap tolerance** Controls overlap detection between traced branches and existing structures. Higher values allow more overlap before a branch is pruned. Default: 0.1 + +**Strict tip filtering** When enabled, removes terminal branches that substantially overlap with their parent branch. Useful for eliminating false-positive branches that shadow thick parent neurites. Default: off -Higher connectivity produces smoother paths through the image but may trace through gaps more liberally. ## Post-processing -**Terminal leaf pruning** Removes short terminal branches that represent noise or incomplete tracing. Terminal branches are pruned if they substantially overlap with their parent branch (>90% coverage). +After the initial tree extraction and branch filtering, several post-processing steps refine the geometry and topology of the reconstruction: -**Smoothing** Applies a moving average filter to reduce zigzag artifacts in traced paths. The window size determines how many adjacent nodes are averaged together. Larger windows create smoother paths but may lose fine details. +**Max. branching angle** Controls branch-point parent reassignment (branch tuning). At each branch point, the algorithm tests whether re-attaching a continuation node to its grandparent or a sibling produces a straighter path. If the alternative attachment avoids a turn exceeding the specified angle, the topology is rewired. Set to -1 to disable. Default: 90° -**Resampling** Redistributes nodes along paths at regular intervals to standardize node density. The step size (in voxels) determines spacing between resampled nodes. Useful for ensuring consistent spatial sampling across the reconstruction. +**Tip extension distance (voxels)** Maximum distance (in voxels) for A*-based tip extension (experimental feature). After pruning, each leaf tip is scanned along its tangent direction for bright signal beyond the Fast Marching frontier. If a foreground target is found within this distance, an A* path is traced through the gap and grafted onto the tree. Each candidate bridge is validated against geometric and intensity criteria (contraction ratio, direction compatibility, mean intensity). Disconnected components that cannot be bridged are discarded. Set to 0 to disable. Default: 0 (disabled) +**Remove zigzags** When enabled (default), iteratively detects and collapses zigzag artifacts: consecutive nodes that both form sharp turns (angles of 90°—270°). The inner node is merged into its parent. The process repeats until no more zigzags are found, producing smoother paths at junctions -### About the Algorithm +**Remove overshoots** When enabled (default), detects and removes overshoot nodes in a single pass. A node is an overshoot if it forms a sharp turn and exactly one of its neighbors (parent or child) is a branch point. Such nodes likely represent tracing artifacts where a path extends slightly past a junction before turning back -SNT's grayscale autotracing has been implemented with substantial re-engineering/improvements: +**Smoothing** Applies a moving average filter to reduce residual irregularities in traced paths. The window size determines how many adjacent nodes are averaged together. Larger windows create smoother paths but may lose fine details. Default: 5 (set to 1 to disable) -- **Full-resolution tracing** Works directly on original image data without mandatory downsampling, preserving fine details +**Resampling** Redistributes nodes along paths at regular intervals to standardize node density. The step size (in voxels) determines spacing between resampled nodes. Useful for ensuring consistent spatial sampling across the reconstruction. Default: 2.0 (set to 0 to disable) -- **Native bit-depth support** Handles 8-bit, 16-bit, and 32-bit images without conversion, maintaining full dynamic range -- **Big data support with scalable architecture** Automatically adapts to image size using optimized storage strategies: fast in-memory processing for typical images, memory-efficient sparse storage for larger images with sparse signal, or disk-backed processing for TB datasets that exceed available RAM +## Learning Parameters from Selected Paths -- **Automatic soma detection** Locates the soma automatically using combined EDT × intensity scoring, eliminating the need for manual seed point placement (see [Soma Detection](#soma-detection)) +The _Learn Parameters From Selected Path(s)..._ button (located in the autotracing prompt) derives tracing parameters from paths already traced in the current session. This is useful when starting with a new dataset: instead of manually tuning thresholds and scales, you trace a representative neurite (or a few branches), then let SNT extract sensible defaults from those examples. -- **Optimized parameters** Default settings have been tuned and validated across SNT's demo datasets, and are expected to work well out-of-the-box +Learning from Selected Paths (v5.1.0) + +### Workflow + +1. **Trace one or more representative paths** manually (or load existing reconstructions). Select them in Path Manager + +2. **Click** _Learn Parameters From Selected Path(s)..._ in the {% include bc path='Auto-trace|Grayscale Image...' %} prompt. SNT analyzes the selected paths and opens a review dialog + +3. **Review the results**. The dialog has two sections: _Source Statistics_ (read-only summary of what was measured: path count, node count, mean radius, mean intensity, etc.) and _Derived Parameters_ (a table with checkboxes). Each derived parameter has a checkbox controlling whether it will be applied + +4. **Apply**. Click _Apply & Close_ to transfer the checked parameters into the autotracing prompt. Only checked rows are applied; unchecked values are left at their current settings + +### Derived Parameters + +SNT samples radius, intensity, and branch geometry from the selected paths to derive the following: + +**Background threshold** Set to 25% of the mean signal intensity sampled along the traced paths. Because the paths run through bright foreground, a quarter of that mean provides a conservative floor that excludes background while preserving dim neurites. + +**Score map scales** Computed from the 25th/50th/75th percentile of node radii across all selected paths. These percentiles become the sigma values for the Hessian-based tubeness filter, ensuring the score map is tuned to the actual thickness range of the structures being traced. Near-duplicate scales (within 10%) are merged. + +**Min. branch score** Derived from the 10th percentile of node radii, with a floor of 3.0 pixels. Branches shorter than the thinnest observed radius are likely noise. + +**Max. branching angle** Set to the 90th percentile of fork angles measured at branch points where child paths diverge from their parents. This captures the typical range of branching geometry, so the post-processing branch-tuning step can rewire only unusually sharp turns. + +**Reconnect parameters** _(unchecked by default)_ Three values for the tip-extension feature: minimum contraction (80% of the lowest observed path contraction, floored at 0.3), maximum bridge angle (120% of the branch-tune angle, capped at 90°), and maximum bridge distance (4× the largest observed radius in voxel units, floored at 10). These are conservative starting points and are unchecked by default because tip extension is an experimental feature. + +### Radius Fitting + +If the selected paths lack radii (i.e., they were traced without fitting), SNT automatically performs a non-destructive fit before analysis. The fit estimates radii from the image signal without modifying the original paths. + +{% capture learn-tip %} +For best results, select paths that are representative of the structures you want to auto-trace: include both thin and thick branches if present, and ensure the paths span the typical intensity range of the image. A handful of well-placed paths (3–5 branches from different parts of the arbor) is usually sufficient. +{% endcapture %} +{% include notice icon="info" content=learn-tip %} + + +## Options + +**Connectivity** Defines the neighborhood of voxel connectivity used during tracing: + +- _Low_ (6-connected): Only axis-aligned neighbors +- _Medium_ (18-connected): Axis-aligned plus face-diagonal neighbors (default) +- _High_ (26-connected): All 26 voxel neighbors including edge and corner diagonals + +**Debug mode** Enables verbose logging to the Console, useful for troubleshooting. + +**After tracing** Determines what happens after the traced trees are added to the Path Manager. Options include: + +- _Do nothing_: Simply adds the traced trees with distinct inter-tree colors +- _Replace existing paths_: Clears all current paths before adding new traces +- _Prepare for proofreading_: Assigns distinct 'dim' colors to each tree and activates the [Curation Assistant](./curation#curation-assistant) for systematic review of the reconstruction +- _Replace existing paths & prepare for proofreading_: Combines both of the above + + +Batch processing of entire directories is also supported. See [Batch Processing](#batch-processing) for details. -For technical implementation details and references, see the [SNT technical notes](https://github.com/morphonets/SNT/blob/main/NOTES.md). # Soma Detection @@ -116,17 +195,28 @@ This dual approach is more robust than using intensity alone because it effectiv **Brightest/largest soma only** Detects the single most prominent soma in the image—the structure with the highest EDT × intensity score. Use this for images containing a single neuron or when you want to identify the primary cell body. -**All somata in image** Detects multiple somas by finding local maxima in the EDT map. Each local maximum represents a thick structure that likely corresponds to a cell body. The _Min. radius_ parameter filters out small detections (debris, hot pixels) by discarding structures below the specified radius. +**All somata in image** Detects multiple somas by finding local maxima in the EDT map. Each local maximum represents a thick structure that likely corresponds to a cell body. When this scope is selected, several additional filtering parameters become available (see below). ## Threshold -The intensity threshold determines which pixels are considered foreground during detection. Use `-1` (default) to automatically compute the threshold using Otsu's method. Manual adjustment may be needed for images with uneven illumination or weak signal. +The intensity threshold determines which pixels are considered foreground during detection. Use `-1` (default) to automatically compute the threshold using image statistics. Manual adjustment may be needed for images with uneven illumination or weak signal. + +## Multi-soma Filtering Parameters + +The following parameters are only active when the detection scope is set to _All somata in image_: + +**Min. radius** The minimum soma radius in spatially calibrated units. Detections with an EDT-derived radius below this value are discarded as noise (debris, hot pixels, etc.). Default: 0 (no filtering). + +**Min. inter-soma distance** The minimum distance between detected soma centers in spatially calibrated units. When greater than zero, non-maximum suppression is applied: among detections that are closer than this distance, only the one with the highest EDT × intensity score is kept. This is the most reliable way to separate closely spaced detections. Default: 0 (disabled). + +**Expected no. of somata** _[Experimental]_ When greater than zero, keeps only the top-N detections ranked by EDT thickness. This uses an additional binarization step (Minimum auto-threshold) to recompute the EDT and rank candidates, which may not work well for images with large connected bright regions. In most cases, _Min. inter-soma distance_ (above) is a more reliable filtering strategy. Default: 0 (disabled). + ## Output Types -Results can be exported in several formats: +Results can be exported in several formats. When detecting all somata, the output is added to the image overlay (for ROI types) or to the Path Manager (for path output): -- **Single-node path** Creates a path in SNT's Path Manager consisting of a single node at the soma center. The node radius is estimated from the distance transform. Useful for marking soma locations in reconstructions +- **Single-node path** Creates a path in SNT's Path Manager consisting of a single node at the soma center. The node radius is estimated from the distance transform. Useful for marking soma locations in reconstructions and for seeding [multi-soma autotracing](#multi-soma-autotracing) - **Point ROI** Places a point marker at the detected soma center. Simplest output for marking locations @@ -134,11 +224,114 @@ Results can be exported in several formats: - **Circular ROI** Draws a circle centered on the soma with radius estimated from the distance transform. Approximates soma size when the cell body is roughly spherical +## Multiple Cells + +The {% include bc path='Auto-trace|Grayscale Image (Multiple Cells)...' %} command traces all cells in a grayscale image in a single run. It automatically detects all soma locations, then traces each cell independently using the GWDT + Fast Marching pipeline with exclusion masks that prevent territory overlap between cells. + +
+ Autotracing of multiple cells +
+ +The command shares the same tracing parameters as the single-cell variant (thresholding, branch filtering, scoring, post-processing, smoothing, and resampling) but replaces the Soma/Root Detection section with parameters specific to multi-cell reconstruction. + +{% capture soma-accuracy %} +**Accurate soma detection is essential** for multiple-cell autotracing. The multi-soma pipeline traces each cell independently from its detected soma, so any missed or spurious detection will propagate through the entire reconstruction. Strategies for ensuring the correct cell count can be further tuned using [scripting](#scripting). +{% endcapture %} +{% include notice icon="info" content=soma-accuracy %} + +{% capture territory-limitation %} +**This approach assumes spatially separable cells.** Because each traced voxel is exclusively assigned to the nearest soma via the exclusion mask, arbors that intertwine in the same territory will be truncated at the boundary claimed by the first-traced cell. For dense neuropil with overlapping arbors, instance segmentation (e.g., deep-learning-based voxel classification) or spectral separation (e.g., multicolor labeling) would be needed to disambiguate cells prior to tracing. +{% endcapture %} +{% include notice content=territory-limitation %} + +### Soma Detection + +These are the filtering parameters for soma detection [described earlier](#multi-soma-filtering-parameters). + +### Territory Control + +**Territory reach** Controls how far each cell's tracing can extend toward its nearest neighbor, expressed as a fraction of the inter-soma distance. At 0.5 (default), each cell traces up to the midpoint between somas, so territories just touch. Values above 0.5 allow territories to overlap—the exclusion mask still prevents actual re-tracing. Set to -1 to disable territory limits (unlimited spread) + +### Multi-Cell Options + +**Exclusion buffer (voxels)** After tracing from one soma, the traced voxels are dilated by this buffer before being masked out in subsequent Fast Marching runs. Larger values create wider exclusion zones, preventing re-tracing of neurites already claimed by another cell. Default: 5 (set to 0 to disable) + +**Min. paths per cell** Minimum number of paths a traced cell must have to be retained. Cells producing fewer paths (e.g., soma-only traces with no neurites) are discarded. Default: 2 + +A batch variant is available under {% include bc path='Auto-trace|Batch Processing' %} for processing directories of images. Each image is processed independently with automatic soma detection, and results are exported as SWC files (one per detected cell). + +### Scripting + +Fully automated tracing of multiple cells in a single image is also supported via scripting. + +{% capture soma-accuracy-scripting %} +**Accurate soma detection is essential** for multiple-cell autotracing. Strategies for ensuring the correct cell count, from least to most accurate: + +1. **Fully automatic detection with defaults**: `SomaUtils.detectAllSomas()` with default parameters. Convenient but sensitive to image quality and cell density +2. **Tuned filtering parameters**: Adjusting _Min. radius_ and _Min. inter-soma distance_ to match the expected cell morphology (see [Multi-soma Filtering Parameters](#multi-soma-filtering-parameters)) +3. **Expected number of somata**: Setting the expected count to keep only the top-N candidates ranked by EDT thickness. Experimental; may not work well for images with large connected bright regions +4. **User-provided coordinates or ROIs**: Supplying exact soma locations via `SomaUtils.detectSomasAt()`. The most reliable approach: bypasses all heuristic detection, giving you full control over which cells are traced. When using curated seeds, call `setAutoFilter(false)` on the tracer to prevent heuristic filtering from discarding valid somas +{% endcapture %} +{% include notice icon="info" content=soma-accuracy-scripting %} + + +The general workflow is: + +1. **Detect soma locations**: Either automatically using `SomaUtils.detectAllSomas()`, or from user-provided seed coordinates / ROIs using `SomaUtils.detectSomasAt()` +2. **Configure the tracer**: Set up a GWDT tracer with appropriate parameters. When using user-provided seeds (from ROIs or manual coordinates), call `setAutoFilter(false)` on the tracer to prevent heuristic filtering from discarding valid somas +3. **Trace**: Pass the detected somas to `traceMultiSoma()`, which runs the full GWDT + Fast Marching pipeline independently for each soma, with exclusion masks preventing traced territories from being retraced + +Here is a minimal Groovy example using ROI-based seeds: + +```groovy +#@ SNTService sntService +import sc.fiji.snt.tracing.auto.GWDTTracer +import sc.fiji.snt.tracing.auto.SomaUtils + +// Assumes SNT is running with an image loaded and ROIs marking soma locations +def snt = sntService.getInstance() +def imp = snt.getImagePlus() +def rois = imp.getOverlay().toArray() as List + +// Detect somas at ROI centroids: +// imp - the ImagePlus with the image data +// rois - collection of ROIs whose centroids mark soma locations. +// Z is derived per ROI from Roi.getZPosition(); ROIs not +// associated with a slice have Z resolved via MIP-based lookup +def somas = SomaUtils.detectSomasAt(imp, rois) + +// Initialize the GWDT tracer: +// 1st arg - the image as an ImgPlus (false = do not duplicate) +// 2nd arg - background threshold (-1 = auto-estimate via Otsu) +def tracer = new GWDTTracer(snt.getLoadedDataAsImg(false), -1) +tracer.setAutoFilter(false) // disable heuristic filtering: seeds are user-curated + +// Trace all cells and add results to the Path Manager +def trees = tracer.traceMultiSoma(somas) +println("Traced ${trees.size()} cell(s)") +sntService.addTrees(trees) +``` + +For automatic seed detection (no ROIs required), replace the seed detection step with: + +```groovy +def img = snt.getLoadedDataAsImg(false) // get loaded data as ImgPlus +// detectAllSomas parameters: +// img - the image as an ImgPlus +// threshold - intensity threshold (-1 = auto via Otsu) +// zSlice - Z-slice (0-indexed; -1 = auto: per-soma auto detection using MIP-based intensity lookup) +// minRadius - minimum soma radius in pixels (filters out small detections) +// minDist - minimum inter-soma distance in pixels (0 = no NMS filtering) +def somas = SomaUtils.detectAllSomas(img, -1, -1, 10, 0) +``` +Look for the _AutoTracing_Demo_(Microglia_Cells)_ [demo script](./scripting#bundled-templates) for other details. + # Segmented Images Segmented (binary or thresholded) images are processed using skeleton-based tracing, which converts the image topology into neuronal tree structures. This approach is suitable for images with clear foreground/background separation where structures have already been segmented through thresholding or other preprocessing methods. -The algorithm works by first skeletonizing the segmented image to extract its topological structure, then converting the resulting skeleton graph into neuronal trees. Segmented images are processed using the {% include bc path='Auto-trace|Segmented Image...' %} command when the image to be processed is already open or {% include bc path='Auto-trace|Segmented Image File...' %}, if the image is yet to be loaded from disk. +The algorithm works by first skeletonizing the segmented image to extract its topological structure, then converting the resulting skeleton graph into neuronal trees. Segmented images are processed using the {% include bc path='Auto-trace|Segmented Image...' %} command when the image to be processed is already open or {% include bc path='Auto-trace|Segmented Image File...' %}, if the image is yet to be loaded from disk. For technical implementation details including the skeletonization algorithm and graph conversion methods, see the [SNT technical notes](https://github.com/morphonets/SNT/blob/main/NOTES.md). + {% capture ddac-demo%} You can follow these instructions using {% include bc path='File|Load Demo Dataset...' %} and choosing the _Drosophila ddaC neuron (Autotrace demo)_. It will load a binary (thresholded) image of a Drosophila space-filling neuron (ddaC) displaying autotracing options for automated reconstruction. @@ -208,9 +401,26 @@ Use Path Orientation (hold {% include key keys='O' %}) to verify path orientatio Additional processing options are available in the dialog: -- **Replace existing paths** Whether any existing paths in the Path Manager should be discarded before adding newly traced structures -- **Apply distinct colors** Whether each traced tree should be assigned a unique color to facilitate visual distinction -- **Activate 'Edit Mode'** Whether SNT's Edit Mode should be automatically activated after tracing completes, allowing immediate refinement of results -- **Prune single-node paths** Whether single-point paths without children should be filtered out from the final reconstruction +**Prune single-node paths** Whether single-point paths without children should be filtered out from the final reconstruction. + +**After tracing** As described [earlier](#options), this option determines what happens after the traced trees are added to the Path Manager. + + +# Batch Processing + +All autotracing commands (grayscale single-cell, grayscale multi-cell, and segmented image) can process entire directories of images in batch mode. Batch commands are available from the {% include bc path='Auto-trace' %} menu under the _Batch Processing_ separator, or through the {% include bc path='File|Load Tracings|' %} import menu. + +In batch mode, all tracing parameters are configured once and applied uniformly to every image in the input directory. Each image is loaded, traced, and the resulting reconstruction is exported as an [SWC](/plugins/snt/faq#what-is-a-swc-file) file to the specified export directory. For multi-cell batch processing, each detected cell produces a separate SWC file (named `_cell1.swc`, `_cell2.swc`, etc.). Processing errors on individual images are logged but do not halt the batch, so the remaining images continue to be processed. + +## Batch Parameters + +**Path to image(s)** The directory containing images to be traced _or_ a path to a single file (e.g., an OME-ZARR, or .IMS file) that may be too large to fit into memory. + +**NB:** +- The _Browse_ button may not allow you to select a folder directly: In that case simplify select a file within that folder, and manually remove it from the resulting path. E.g., if the goal is to parse `/path/to/folder/`, browse to `/path/to/folder/random.file`, and delete "random.file" from the file path + +- For grayscale tracing, images should contain bright neuronal structures on a dark background. For segmented image tracing, images should be binary masks or thresholded images where non-zero pixels represent foreground structures. + +**Export directory** The output directory where SWC files will be saved. One SWC file is generated per input image. -For technical implementation details including the skeletonization algorithm and graph conversion methods, see the [SNT technical notes](https://github.com/morphonets/SNT/blob/main/NOTES.md). +All other tracing parameters (thresholds, filtering, post-processing, etc.) are shared with the corresponding interactive command and apply to every image in the batch. Soma/root detection defaults to automatic in batch mode (no ROI interaction). diff --git a/_pages/plugins/snt/index.md b/_pages/plugins/snt/index.md index 4441b472f..6a973d495 100644 --- a/_pages/plugins/snt/index.md +++ b/_pages/plugins/snt/index.md @@ -29,30 +29,33 @@ The [source repository](https://github.com/morphonets/SNT) contains more details {% include gallery align="fill" content= " /media/plugins/snt/snt-auto-tracing-overview.png | [Fully automated tracing](/plugins/snt/auto-tracing) from both [grayscale images](./auto-tracing#grayscale-images) (no thresholding required) and [segmented images](./auto-tracing#segmented-images) -/media/plugins/snt/snt-bvv.png | [Big-data (out-of-core) support](/plugins/snt/big-data): Automatic switch to disk-backed processing for TB-scale datasets that don’t fit in RAM (experimental) +/media/plugins/snt/snt-autotracing-multiple-somata.webp | [Fully automated tracing](/plugins/snt/auto-tracing) of [multiple cells in the same image](./auto-tracing#multiple-cells) +/media/plugins/snt/snt-autotracing-groundtruth-learning.png | [Auto-tuned tracing](./auto-tracing#learning-parameters-from-selected-paths): Learned tracing parameters from manually traced paths +/media/plugins/snt/snt-soma-detection.png | Automated [soma detection](/plugins/snt/auto-tracing#soma-detection) /media/plugins/snt/snt-4D-examples.png | [Semi-automated tracing](/plugins/snt/walkthroughs#semi-automated-tracing): Support for multi-channel and [timelapse](/plugins/snt/walkthroughs#time-lapse-analysis) images -/media/plugins/snt/snt-soma-detection.png | Automated [soma detection](/plugins/snt/auto-tracing#soma-detection) (no thresholding required) -/media/plugins/snt/snt-v3-overview.png | [Scripted routines](/plugins/snt/scripting#snt-scripts) co-exist with graphical user interface operations /media/plugins/snt/snt-spectral-unmixing.png | Support for [Brainbow-like images](./walkthroughs#tracing-in-multichannel-brainbow-images) -/media/plugins/snt/snt-script-example.png | [Scripting](/plugins/snt/scripting) in any of Fiji's supported languages facilitated by SNT's [Script Recorder](/plugins/snt/scripting#script-recorder) -/media/plugins/snt/snt-notebook.png | Scripting in native Python using [PySNT](https://pysnt.readthedocs.io/en/latest/) -/media/plugins/snt/snt-delaunay-triangulation.png | Delaunay tessellation: Tracings can be used in [image processing routines](/plugins/snt/manual#process-) -/media/plugins/snt/snt-density-map.png | Density maps for group(s) of cells obtained from [built-in scripts](/plugins/snt/scripting#bundled-templates) -/media/plugins/snt/snt-recviewer-convexhull-and-surface.png | [Convex hulls](/plugins/snt/analysis#convex-hull-analysis) and [surface annotations](/plugins/snt/reconstruction-viewer#geometric-annotations) -/media/plugins/snt/snt-montage-light.png | Quantitative and publication quality visualizations -/media/plugins/snt/snt-montage-dark.png | Data-rich 3D visualizations -/media/plugins/snt/snt-rec-viewer-demo2-dark.gif | [Interactive 3D scenes](/plugins/snt/reconstruction-viewer) +/media/plugins/snt/snt-bvv.png | [Big data support](/plugins/snt/big-data): TB-scale datasets that exceed available RAM (experimental) +/media/plugins/snt/snt-curation-assistant.png | [Calibrated, real-time quality-control](./curation#curation-assistant) of traced morphologies +/media/plugins/snt/snt-labkit-training.png | [Semantic segmentation](/plugins/snt/machine-learning) /media/plugins/snt/sholl-analysis-outputs.png | [Sholl](/plugins/snt/sholl) and [Strahler](/plugins/snt/analysis#strahler) directly from images (bypassing tracing) /media/plugins/snt/snt-angular-sholl.png | Advanced [Sholl-based quantifications](/plugins/snt/sholl#angular-sholl) /media/plugins/snt/snt-root-angle-analysis.png | [Root Angle Analysis](/plugins/snt/analysis#root-angle-analysis) /media/plugins/snt/snt-local-angle-surface-analysis.png | Analysis of [surface angles/arbor orientation](/plugins/snt/metrics#extension-angle) -/media/plugins/snt/snt-delineation-analysis2.png | [Delineation analyses](/plugins/snt/walkthroughs#delineation-analysis) /media/plugins/snt/snt-growth-analysis.png | [Growth Analysis](/plugins/snt/analysis#growth-analysis) +/media/plugins/snt/snt-delineation-analysis2.png | [Delineation analyses](/plugins/snt/walkthroughs#delineation-analysis) /media/plugins/snt/snt-ferris-wheel.png | Routines to summarize [innervation patterns](/plugins/snt/analysis#graph-based-analysis) /media/plugins/snt/graph-viewer-ferris-wheel.png | Routines to summarize data from [projectomes and connectomics](/plugins/snt/analysis#graph-based-analysis) /media/plugins/snt/snt-2d-histogram.png | Specialized [statistics](/plugins/snt/analysis#statistics) -/media/plugins/snt/snt-labkit-training.png | [Semantic segmentation](/plugins/snt/machine-learning) -/media/plugins/snt/snt-astrocyte-example.png | Glia analysis: Bulk characterization (width and length) of astrocytic processes ([use case](https://forum.image.sc/t/determining-astrocyte-width-from-2d-images-using-fiji-snt/56426/2)) +/media/plugins/snt/snt-delaunay-triangulation.png | Delaunay tessellation: Tracings can be used in [image processing routines](/plugins/snt/manual#process-) +/media/plugins/snt/snt-density-map.png | Density maps for group(s) of cells obtained from [built-in scripts](/plugins/snt/scripting#bundled-templates) +/media/plugins/snt/snt-recviewer-convexhull-and-surface.png | [Convex hulls](/plugins/snt/analysis#convex-hull-analysis) and [surface annotations](/plugins/snt/reconstruction-viewer#geometric-annotations) +/media/plugins/snt/snt-montage-light.png | Quantitative and publication-quality visualizations +/media/plugins/snt/snt-montage-dark.png | Rich 3D visualizations with dark theme +/media/plugins/snt/snt-rec-viewer-demo2-dark.gif | [Interactive 3D scenes](/plugins/snt/reconstruction-viewer) +/media/plugins/snt/snt-v3-overview.png | [Scripted routines](/plugins/snt/scripting#snt-scripts) co-exist with graphical user interface operations +/media/plugins/snt/snt-script-example.png | [Scripting](/plugins/snt/scripting) in any of Fiji's supported languages facilitated by SNT's [Script Recorder](/plugins/snt/scripting#script-recorder) +/media/plugins/snt/snt-notebook.png | Scripting in native Python using [PySNT](https://pysnt.readthedocs.io/en/latest/) +/media/plugins/snt/snt-astrocyte-example.png | Glia analysis: Quantification of [astrocyte and microglia morphologies](./auto-tracing#multiple-cells) /media/plugins/snt/snt-non-neuronal-example.png | Not only neurons: SNT can be used to analyze many types of filamentous structures " %} diff --git a/_pages/plugins/snt/key-shortcuts.md b/_pages/plugins/snt/key-shortcuts.md index 111d4dada..c81692cb0 100644 --- a/_pages/plugins/snt/key-shortcuts.md +++ b/_pages/plugins/snt/key-shortcuts.md @@ -54,7 +54,7 @@ The [Command Palette](manual#command-palette) ({% include key keys='ctlcmd|Shift | {% include key key='1' %} | Toggles the first visibility filter: Whether all traced paths should be displayed or just selected ones | | {% include key key='2' %} | Toggles the second visibility filter: Whether all nodes should be displayed across the Z-stack or just those in nearby Z-slices | | {% include key key='3' %} | Toggles the third visibility filter: Whether paths from all channels/frames should be displayed or just those in the active channel/frame | -| {% include key key='G' %} | Selects the nearest path to the mouse cursor. Holding {% include key keys='Shift|G' %} adds the path nearest to the mouse cursor to the current list of selected paths. *Mnemonic: Grab paths around cursor.* Note that Paths can only be edited one at a time, and thus {% include key keys='Shift|G' %} is disabled in *Edit Mode* | +| {% include key key='G' %} | Grabs the nearest path to the mouse cursor. Holding {% include key keys='Shift|G' %} adds the nearest path to the current selection. Note that Paths can only be edited one at a time, and thus {% include key keys='Shift|G' %} is disabled in *Edit Mode* | | {% include key key='H' %} | Temporarily Hides all paths/annotations while pressed | | {% include key key='O' %} | Temporarily shows path Orientations (start→end direction) while pressed | @@ -87,9 +87,12 @@ These shortcuts become available in *Edit Mode*, activated through the contextua | {% include key key='I' %} | Inserts a new node at cursor position | | {% include key key='L' %} | Locks active node to prevent accidental editing | | {% include key key='M' %} | Moves active node to cursor position | +| {% include key key='P' %} | Toggle Paint Mode for brush editing | | {% include key key='R' %} | Changes the Radius of active node | | {% include key key='X' %} | Splits tree at active node, re-rooting the selected structure at the active node | | {% include key key='Z' %} | Undo last operation | +| {% include key keys='Ctrl|Mouse Wheel' %} | Adjust node radius / brush size (Paint Mode) | +| {% include key keys='Alt|Drag' %} | Move node / blend radii (Paint Mode) | ### Reconstruction Viewer diff --git a/_pages/plugins/snt/manual.md b/_pages/plugins/snt/manual.md index 8a2e09111..a9df72c3f 100644 --- a/_pages/plugins/snt/manual.md +++ b/_pages/plugins/snt/manual.md @@ -152,23 +152,34 @@ Exits the program. ### Auto-trace › -#### Grayscale Image (GWDT)... -Runs fully automated tracing directly from a **grayscale (intensity) image** already open in SNT (no binarization required). The approach uses **Gray-Weighted Distance Transform (GWDT)** with Fast Marching and expects bright-on-dark imagery. See [Autotracing › Grayscale Images](/plugins/snt/auto-tracing#grayscale-images) for details. +#### Grayscale Image... +Runs fully automated tracing of a single cell directly from a **grayscale (intensity) image** already open in SNT (no binarization required). See [Autotracing › Grayscale Images](/plugins/snt/auto-tracing#grayscale-images) for details. -#### Grayscale Image (GWDT) File... +#### Grayscale Image (Multiple Cells)... +Runs automated tracing of **multiple cells** in a single grayscale image. Automatically detects all soma locations, then traces each cell independently using exclusion masks to prevent territory overlap. See [Auto-tracing › Multiple Cells](/plugins/snt/auto-tracing#multiple-cells) for details. -Same as {% include bc path='Grayscale Image (GWDT)...' %}, but loads the grayscale image from a **file path** (including [big-data/out-of-core](/plugins/snt/big-data) datasets). See [Auto-tracing › Grayscale Images](/plugins/snt/auto-tracing#grayscale-images) for details. +#### Detect Soma(s)... +Standalone tool for automatic soma/root detection in neuronal images, and can export results as a path node or ROI (point, contour, circle) for annotation or seeding autotracing. Options include: -#### Detect Soma... -Standalone tool for automatic soma/root detection in neuronal images. Detects the thickest and brightest structures using an EDT×intensity score, and can export results as a path node or ROI (point, countour, circle) for annotation or seeding autotracing. See [Auto-tracing › Soma Detection](/plugins/snt/auto-tracing#soma-detection) for details. +- **Scope** Whether to detect only the single brightest/largest soma or all somata in the image. When detecting all somata, additional filtering parameters become available + +- **Output type** How results are exported: as a _Single-node path_ (for seeding autotracing), _Point ROI_, _Area ROI_ (contour from thresholding), or _Circular ROI_ (circle with EDT-derived radius) + +Remaining options are described in [Auto-tracing › Soma Detection](/plugins/snt/auto-tracing#soma-detection). #### Autotrace Segmented Image... Runs fully automated tracing on a segmented image that is already open. A segmented image can be a binary mask or a thresholded image, where background pixels have been set to zero. See [Auto-tracing › Segmented Images](/plugins/snt/auto-tracing#segmented-images) for details. +#### Grayscale Image File(s)... +Batch-capable variant that loads grayscale images from a **file** or **directory**, traces a single cell per image using GWDT autotracing, and exports reconstructions as SWC files. See [Auto-tracing › Grayscale Images](/plugins/snt/auto-tracing#grayscale-images) and [Batch Processing](/plugins/snt/auto-tracing#batch-processing) for details. + +#### Grayscale Image File(s) (Multiple Cells)... +Batch-capable variant that loads grayscale images from a **file too large to be loaded into memory** (e.g., an OME-ZARR, or .IMS file) or **directory**, detects all soma locations, and traces each cell independently using GWDT autotracing with exclusion masks. Results are exported as SWC files (one per detected cell). See [Auto-tracing › Multiple Cells](/plugins/snt/auto-tracing#multiple-cells) and [Batch Processing](/plugins/snt/auto-tracing#batch-processing) for details. + #### Autotrace Segmented Image File... -Same as {% include bc path='Autotrace Segmented Image...' %}, but loads the segmented image from a file path instead of using an image already open. See [Fully automated tracing](/plugins/snt/auto-tracing#segmented-images) for details. +Batch-capable variant that loads segmented images from a **directory**, traces each image, and exports the resulting reconstructions as SWC files. See [Auto-tracing › Segmented Images](/plugins/snt/auto-tracing#segmented-images) and [Batch Processing](/plugins/snt/auto-tracing#batch-processing) for details. ### Analysis › @@ -617,7 +628,7 @@ The status bar at the bottom of the Main Dialog displays brief messages about on Right-clicking on any of the tracing views will bring up a menu with various editing tools. The corresponding [keyboard shortcuts](/plugins/snt/key-shortcuts) are shown to the right of each option. The list includes: -### Select Nearest Path {% include key key='G' %} +### Grab Nearest Path {% include key key='G' %} Selects ("Groups") the path closest to the mouse cursor. ### Add Nearest Path to Selection {% include key key='Shift|G' %} @@ -661,7 +672,7 @@ Removes the last segment from the temporary path. Finishes the temporary path. Note that a path can always be finished by {% include key key='double click' %} ## Edit Mode {% include key keys='Shift|E' %} -Pressing *Edit Mode*, selects the nearest path for editing, unlocking the edit options. When *Edit Mode* is active, moving the mouse cursor along the path will highlight the nearest node with a crosshair icon and synchronize the current Z-slice to the location of that node. Note that the ability to create new paths is temporarily disabled when in *Edit Mode*. +Pressing *Edit Mode*, selects the nearest path for editing, unlocking the edit options. When *Edit Mode* is active, moving the mouse cursor along the path will highlight the nearest node with a crosshair icon and synchronize the current Z-slice to the location of that node. Note that the ability to create new paths is temporarily disabled when in *Edit Mode*. For brush-based editing of multiple nodes at once, see [Paint Mode](#paint-mode-p) below. ### Bring Active Node to Current Z-plane {% include key key='B' %} Moves the active node to the active Z-plane. Note that the translation is only done in Z. XY positions are unchanged. @@ -714,6 +725,22 @@ Reorganizes the existing tree so that the active node becomes its root. ### Split Tree at Active Node {% include key key='X' %} Splits the current tree into two subtrees by disconnecting the active node from its parent structure +### Paint Mode {% include key key='P' %} +Toggles Paint Mode, a brush-based sub-mode of Edit Mode for adjusting paths. In Paint Mode, operations fade smoothly from full effect at the cursor to no effect at the brush edge, like a soft brush in image editors. The brush radius (number of flanking nodes affected) is displayed in the status label. + +**{% include key keys='Drag' %}** Moves nodes within the brush radius toward the cursor, weighted by proximity to the center node (Gaussian-like displacement) + +**{% include key keys='Alt|Drag' %}** Blends radii from the center node outward. Each flanking node's radius is pulled toward the center node's radius with fading falloff. Dashed arcs show the brush extent during the operation. + +**{% include key keys='Ctrl|Mouse Wheel' %}** Adjusts the brush radius (number of flanking nodes). Transient dashed arcs preview the brush extent. + +Press {% include key key='P' %} again or exit Edit Mode to leave Paint Mode. Undo ({% include key key='Z' %}) reverts the last paint stroke. + +{% capture tip-paint%} +Use {% include key key='R' %} to set the center node's radius first, then {% include key keys='Alt|Drag' %} to propagate it smoothly along the path. +{% endcapture %} +{% include notice icon="tip" content=tip-paint %} + ## Pause Tracing {% include key keys='Shift|P' %} Disables tracing functions until this option is deselected. Tracing views are annotated with the *Tracing Paused* [label](#misc) to indicate this state. diff --git a/media/plugins/snt/snt-autotracing-groundtruth-learning.png b/media/plugins/snt/snt-autotracing-groundtruth-learning.png new file mode 100644 index 000000000..41a7258df Binary files /dev/null and b/media/plugins/snt/snt-autotracing-groundtruth-learning.png differ diff --git a/media/plugins/snt/snt-autotracing-multiple-somata.webp b/media/plugins/snt/snt-autotracing-multiple-somata.webp new file mode 100644 index 000000000..ce82fb146 Binary files /dev/null and b/media/plugins/snt/snt-autotracing-multiple-somata.webp differ