From 95c0c3be99719ca0033759dc8f949b0ccbb67d3d Mon Sep 17 00:00:00 2001 From: Tiago Ferreira Date: Tue, 12 May 2026 10:15:55 -0400 Subject: [PATCH 1/2] snt: document label-based delineations and label detector --- _pages/plugins/snt/delineations.md | 37 +++++++++++++++-- _pages/plugins/snt/faq.md | 2 +- _pages/plugins/snt/manual.md | 11 ++--- _pages/plugins/snt/spines-varicosities.md | 49 ++++++++++++++++++----- _pages/plugins/snt/walkthroughs.md | 4 +- 5 files changed, 81 insertions(+), 22 deletions(-) diff --git a/_pages/plugins/snt/delineations.md b/_pages/plugins/snt/delineations.md index 5586da76c..aca978c71 100644 --- a/_pages/plugins/snt/delineations.md +++ b/_pages/plugins/snt/delineations.md @@ -9,12 +9,12 @@ icon: /media/icons/snt.png forum-tag: snt update-site: Neuroanatomy doi: 10.1038/s41592-021-01105-7 -tags: snt,tracing,neuroanatomy,contours +tags: snt,tracing,neuroanatomy,contours,labels,segmentation --- {% capture version%} -**This page was last revised for [version 5.0.6](https://github.com/morphonets/SNT/releases)**. +**This page was last revised for [version 5.0.10](https://github.com/morphonets/SNT/releases)**. {% endcapture %} {% include notice content=version %} @@ -63,6 +63,32 @@ ROIs generated programmatically or in bulk outside SNT can be applied in a singl Delineations can also be created from [neuropil annotations](/plugins/snt/analysis#atlas-based-analysis) using the _Import Assignments from Atlas Annotation_ option from the Options (gear) menu. In this case delineations are created from selected brain compartments associated with the cell(s) being analyzed. Note that this requires cells to be tagged by atlas annotations. Currently only cells downloaded directly from the MouseLight database fulfill this criterion. +## Creating Delineations from Label Images +Delineations can be imported from segmentation (label) images produced by tools such as [Labkit](/plugins/labkit), [Weka](/plugins/tws), [cellpose](https://cellpose.readthedocs.io/en/latest/), or similar. Each unique non-zero integer value in the label image becomes a delineation, with path nodes assigned to whichever label they overlap. To import: + +1. Open the label image in Fiji. The image should contain non-negative integer pixel values, with 0 as background. Its spatial dimensions must match those of the tracing image + +2. In the Delineations tab, choose _Import Assignments from Label Image_ from the Options (gear) menu + +3. If multiple candidate images are open, a dialog allows you to choose which one to import. Hyperstacks are excluded; only the first channel/frame of multi-dimensional images is considered + +Each label value is mapped to a new delineation entry. Path nodes whose coordinates fall within a labeled region are assigned to the corresponding delineation. Nodes outside all labels remain non-delineated. + +{% capture label-validation %} +SNT validates the selected image before importing: it must contain only non-negative integers with a bounded number of unique classes (≤ 500). If the image dimensions do not match the tracing image, a warning is displayed. Nodes whose coordinates fall outside the label image bounds are skipped. +{% endcapture %} +{% include notice icon="info" content=label-validation %} + + +## Exporting Delineations as Label Images +Delineation assignments can be exported back to a label image using _Export Assignments to Label Image_ from the Options (gear) menu. This generates a new image in which each voxel within a traced neurite is labeled by its delineation assignment. The export uses tube-based rasterization, filling each path's volume based on node radii. Each delineation is assigned a unique positive integer label; background voxels remain zero. This is useful for visualizing delineation assignments in 3D, or for downstream analysis in other tools. + +{% capture export-note %} +Export requires paths to have delineation assignments. If all assignments were made via ROIs or atlas annotations (rather than from a label image), the export still works: it rasterizes whatever assignments exist. The output is a 16-bit image; if there are more than 65,535 unique labels, values may overflow. +{% endcapture %} +{% include notice icon="info" content=export-note %} + + ## Editing Delineations To re-define a delineation it is sufficient to re-define or re-adjust an existing ROI and press the _Assign_ button. The Options (gear) menu lists commands for rebuilding, restoring, and deleting delineations. Most of the editing operations can be performed through the toolbar at the bottom of the delineations list, including: - Adds more entries to the delineations list @@ -77,7 +103,7 @@ To re-define a delineation it is sufficient to re-define or re-adjust an existin Measurements are retrieved using the _Plot_ and _Measure_ buttons: - _Plot_: Plots distributions of selected metrics. Plotting styles include: Box plots (one delineation per category), multi-series histograms (one delineation per series), or a montage of single-series histograms (one panel per delineation) -- _Measure_: Reports common metrics to a dedicated table (Total length, No. of nodes, No. of junctions, etc.) across delineations +- _Measure_: Reports common metrics to a dedicated table (Total length, No. of nodes, No. of junctions, etc.) across delineations. When delineations were imported from a label image, the table includes additional distance-to-boundary statistics computed via calibrated Euclidean Distance Transforms (EDT): _Mean dist. to boundary_, _Min dist. to boundary_, _Max dist. to boundary_, and _Fraction inside_ (the proportion of nodes with zero distance, i.e., fully contained within the label). These columns are only populated for label-image-based delineations In addition to defined delineations, plots and tables may include two other categories: @@ -86,3 +112,8 @@ In addition to defined delineations, plots and tables may include two other cate - _Unaffected paths_: This category corresponds to full paths that have no XY coordinates inside any delineation. _Unaffected paths_ retain their rendered colors {% include notice icon="info" content="Topological constraints may not allow certain metrics to be computed for a particular delineation. E.g., a metric that requires a [graph-theoretic tree](./analysis#graph-based-analysis) may not be computed for a delineation defined by a non-contiguous ROI." %} + +{% capture proximity-relation %} +Delineation analysis measures _aggregate_ properties of paths within labeled regions (lengths, node counts, distance statistics). To identify _specific contact points_ where paths approach or touch labeled structures, use the [Label Proximity Detector](/plugins/snt/spines-varicosities#label-proximity-detection), which emits navigable bookmarks or ROIs at individual contact locations. +{% endcapture %} +{% include notice icon="info" content=proximity-relation %} diff --git a/_pages/plugins/snt/faq.md b/_pages/plugins/snt/faq.md index e00106c1a..26ee3f295 100644 --- a/_pages/plugins/snt/faq.md +++ b/_pages/plugins/snt/faq.md @@ -129,7 +129,7 @@ See [Sholl Analysis › FAQ](./sholl#faq). ## Spine Analysis ### Does SNT support spine analysis? -See [Spine/Varicosity Analysis](./spines-varicosities). In-depth quantification of spine morphology can be done using [Spot Spine](/plugins/spot-spine), after tracing dendrites in SNT. +See [Spine/Varicosity/Label Analysis](./spines-varicosities). In-depth quantification of spine morphology can be done using [Spot Spine](/plugins/spot-spine), after tracing dendrites in SNT. ## Soma Analysis diff --git a/_pages/plugins/snt/manual.md b/_pages/plugins/snt/manual.md index 47b340d02..5624c7dae 100644 --- a/_pages/plugins/snt/manual.md +++ b/_pages/plugins/snt/manual.md @@ -538,7 +538,7 @@ Described in [Curation Assistant](./curation#curation-assistant). ## Bookmarks Tab -This tab hosts the Bookmark Manager, a utility that stores image locations to be (re)visited during tracing (e.g., a location of an ambiguous branching point or an ambiguous cross-over between two neurites). Bookmarked locations can also be used as [spine/varicosity markers](/plugins/snt/spines-varicosities). The basic usage is as follows: +This tab hosts the Bookmark Manager, a utility that stores image locations to be (re)visited during tracing (e.g., a location of an ambiguous branching point or an ambiguous cross-over between two neurites). Bookmarked locations can also be used as [spine/varicosity markers](/plugins/snt/spines-varicosities) or as output from the [Label Proximity Detector](/plugins/snt/spines-varicosities#label-proximity-detection). The basic usage is as follows: Delineations tab Bookmarks tab @@ -839,7 +839,7 @@ Assigns a constant radius to all the nodes of selected Path(s). This setting onl #### Specify No. Spine\Varicosity Markers... -Assigns the no. of markers (e.g., spines or varicosities) to be associated to selected path(s) (see [Spine/Varicosity Analysis](/plugins/snt/spines-varicosities)). +Assigns the no. of markers (e.g., spines or varicosities) to be associated to selected path(s) (see [Spine/Varicosity/Label Analysis](/plugins/snt/spines-varicosities)). #### Ramer-Douglas-Peuker Downsampling... @@ -1107,14 +1107,15 @@ NB: - *Integration metric* The statistics (Mean, Median, Sum, etc.) integrating pixel intensities within *shape*. -#### Spines/Varicosities › +#### Spine/Varicosities/Labels › -This menu contains tools for detecting and analyzing spines, varicosities, boutons, and other features along or around traced paths. It includes two automated detectors and tools for working with manual annotations: +This menu contains tools for detecting and analyzing spines, varicosities, boutons, and other features along or around traced paths, as well as proximity contacts with labeled structures from segmentation images. It includes three automated detectors and tools for working with manual annotations: - **Detect Maxima Around Paths...**: Detection of intensity peaks in perpendicular cross-sections outside the path centerline (off-skeleton) - **Detect Swellings Along Paths...**: Detection of radius swellings along the neurite centerline (on-skeleton) +- **Detect Label Proximity...**: Detection of contact points between paths and labeled surfaces from a segmentation image (e.g., from [Labkit](/plugins/labkit), [Weka](/plugins/tws), or cellpose). Computes calibrated distance transforms for each label and identifies path nodes within a configurable distance threshold. Supports both threshold mode (all nodes within distance) and closest-approach mode (one detection per path–label pair) - **Commands for handling manually placed markers** -These tools are detailed in [Spine/Varicosity Analysis](/plugins/snt/spines-varicosities). +These tools are detailed in [Spine/Varicosity/Label Analysis](/plugins/snt/spines-varicosities). #### Time-lapses › diff --git a/_pages/plugins/snt/spines-varicosities.md b/_pages/plugins/snt/spines-varicosities.md index e9c636ae6..162871f26 100644 --- a/_pages/plugins/snt/spines-varicosities.md +++ b/_pages/plugins/snt/spines-varicosities.md @@ -1,15 +1,15 @@ --- -title: SNT › Spine/Varicosity Analysis +title: SNT › Spine/Varicosity/Label Analysis nav-links: true -nav-title: Spines/Varicosities -name: Spine/Varicosity Analysis -categories: [Maxima,Analysis,Neuroanatomy] +nav-title: Spines/Varicosities/Labels +name: Spine/Varicosity/Label Analysis +categories: [Maxima,Analysis,Neuroanatomy,Labels] artifact: org.morphonets:SNT icon: /media/icons/snt.png forum-tag: snt update-site: Neuroanatomy doi: 10.1038/s41592-021-01105-7 -tags: snt,tracing,neuroanatomy,maxima +tags: snt,tracing,neuroanatomy,maxima,labels,segmentation --- @@ -18,7 +18,7 @@ tags: snt,tracing,neuroanatomy,maxima {% endcapture %} {% include notice content=version %} -# Spine/Varicosity Analysis +# Spine/Varicosity/Label Analysis {% capture spot-spine%} Currently, SNT supports detection, annotation, and density analysis of bright puncta around paths. Complete shape analysis of dendritic spines can be performed using [Spot Spine](/plugins/spot-spine). @@ -34,12 +34,12 @@ You can follow these instructions using {% include bc path='File|Load Demo Datas 1. Choose a neurite of interest. Adjust cursor size to the neurite thickness using {% include key keys='Ctrl|Mouse Wheel' %} 2. Trace a small path (finish it by {% include key keys='Double Click' %}) -3. Run {% include bc path='Analyze|Spines/Varicosities|Detect Maxima Around Paths...' %} +3. Run {% include bc path='Analyze|Spine/Varicosities/Labels|Detect Maxima Around Paths...' %} {% endcapture %} {% include notice icon="tip" content=maxima-demo %} -To run {% include bc path='Analyze|Spines/Varicosities|Detect Maxima Around Paths...' %}, select first the path(s) of interest (or none to include all). The command's dialog provides the following parameters: +To run {% include bc path='Analyze|Spine/Varicosities/Labels|Detect Maxima Around Paths...' %}, select first the path(s) of interest (or none to include all). The command's dialog provides the following parameters: - **Detection channel** The image channel to analyze (1-based; only for multi-channel images) @@ -80,7 +80,7 @@ SNT can also detect swellings (boutons, varicosities, blebs) **along** traced pa Unlike the Peripath Detector (which searches for bright *off-skeleton* [outside path centerline] maxima in perpendicular cross-sections), the Along-Path Detector identifies *on-skeleton* [along path centerline] swellings, i.e., regions where the neurite itself is wider than its surroundings. This is particularly suited for axonal varicosities and en-passant boutons. -To run {% include bc path='Analyze|Spines/Varicosities|Detect Swellings Along Paths...' %} Select the path(s) of interest. Note that **Paths must have radii**: Paths without radii are skipped. +To run {% include bc path='Analyze|Spine/Varicosities/Labels|Detect Swellings Along Paths...' %} Select the path(s) of interest. Note that **Paths must have radii**: Paths without radii are skipped. The command's dialog provides the following parameters: @@ -101,6 +101,33 @@ The command's dialog provides the following parameters: Detected counts are automatically assigned to each path's spine/varicosity tally, just as with the Peripath Detector. +## Label Proximity Detection + +SNT can detect **contact points** between traced paths and labeled surfaces from a segmentation image using the _Label Proximity Detector_. This is useful for identifying where neurites approach or contact structures segmented by tools such as [Labkit](/plugins/labkit), [Weka](/plugins/tws), cellpose, or similar. The detector computes a calibrated Euclidean Distance Transform (EDT) for each unique label in the image, then identifies path nodes that are within a configurable distance of a label boundary. + +To run {% include bc path='Analyze|Spine/Varicosities/Labels|Detect Label Proximity...' %}, select the path(s) of interest and ensure a label (segmentation) image is open in ImageJ. The label image should contain non-negative integer values, with 0 as background and each non-zero value identifying a distinct structure. + +The command's dialog provides the following parameters: + +- **Label image** A drop-down listing all open images that pass label-image validation (non-negative integers, bounded number of classes). Images whose spatial dimensions do not match the tracing image are excluded. Hyperstacks are also excluded (only the first channel/frame would be considered) + +- **Distance threshold** Maximum distance (in calibrated units) from a label boundary for a path node to be flagged as a contact point. Two modes are available: when set to a **positive value**, all nodes within that distance of any label boundary are detected (_threshold mode_); when set to **0**, only the single closest node per path–label pair is detected (_closest-approach mode_). Default: 0 + +- **Merging distance** Minimum separation between detections in physical units. Nearby detections are merged, keeping the one closest to the label boundary. Set to 0 to disable merging + +- **Output** Results can be exported as _Bookmarked locations_ (added to the [Bookmark Manager](/plugins/snt/manual#bookmarks-tab)) or as _ROIs_ (added to the ROI Manager, grouped per path with path name and color) + +{% capture label-note %} +The label image and the tracing image should share the same spatial dimensions and calibration. If dimensions differ, a warning is displayed but detection proceeds. The EDT is computed using the label image's pixel spacing, so results are in calibrated (physical) units. +{% endcapture %} +{% include notice icon="info" content=label-note %} + +{% capture label-relation %} +Label proximity detection is complementary to [Delineation Analysis](/plugins/snt/delineations): while delineations measure _how much_ of a path lies within a labeled region (length, node counts, distance-to-boundary statistics), the Label Proximity Detector identifies _specific points_ where paths approach or contact labeled structures, emitting navigable bookmarks or ROIs at those locations. +{% endcapture %} +{% include notice icon="info" content=label-relation %} + + ## Manual Annotation This approach uses manually placed multi-Point ROIs along paths as markers for neurite features. Currently only counts and densities are supported. A typical workflow proceeds as follows: @@ -110,10 +137,10 @@ You can follow these instructions using {% include bc path='File|Load Demo Datas {% endcapture %} {% include notice icon="tip" content=spines-demo %} -1. Run {% include bc path='Analyze|Spines/Varicosities|Spine/Varicosity Analysis Help...' %} in the Path Manager to have offline instructions available in a dedicated dialog +1. Run {% include bc path='Analyze|Spine/Varicosities/Labels|Spine/Varicosity Analysis Help...' %} in the Path Manager to have offline instructions available in a dedicated dialog 2. Pause SNT from the [contextual menu](/plugins/snt/manual#contextual-menu), and select the multipoint tool from ImageJ's toolbar 3. Click over the features to be counted. Point placement may not need to be accurate, but with 3D images points should be placed on the same plane (Z-plane) as the feature being counted. Skip this step if you are running a programmatic routine that automatically annotates locations -4. Once you have placed all the points, select the Path(s) associated with the features (or select none, if all Paths are to be considered) and run Path Manager's {% include bc path='Analyze|Spines/Varicosities|Compute Densities from Annotations...' %}. The dialog allows you to specify: +4. Once you have placed all the points, select the Path(s) associated with the features (or select none, if all Paths are to be considered) and run Path Manager's {% include bc path='Analyze|Spine/Varicosities/Labels|Compute Densities from Annotations...' %}. The dialog allows you to specify: - **Source of Multi-point ROI(s)** The location of the markers. Particularly useful if the ROIs are being generated programmatically and stored in the ROI Manager. It also allows [bookmarked locations](/plugins/snt/manual#bookmarks-tab) to be parsed as markers diff --git a/_pages/plugins/snt/walkthroughs.md b/_pages/plugins/snt/walkthroughs.md index bf4ac2836..df83b1e57 100644 --- a/_pages/plugins/snt/walkthroughs.md +++ b/_pages/plugins/snt/walkthroughs.md @@ -231,8 +231,8 @@ Use Path Orientation (hold {% include key keys='O' %}) to verify path orientatio Described in [Auto-tracing](/plugins/snt/auto-tracing). -# Spine/Varicosity Analysis -Described in [Spine/Varicosity Analysis](/plugins/snt/spines-varicosities). +# Spine/Varicosity/Label Analysis +Described in [Spine/Varicosity/Label Analysis](/plugins/snt/spines-varicosities). # Delineation Analysis From 240e45a2f15d91ba25146177d0571e4f6e3424e4 Mon Sep 17 00:00:00 2001 From: Tiago Ferreira Date: Tue, 12 May 2026 11:47:51 -0400 Subject: [PATCH 2/2] snt: Document hierarchical labels --- _pages/plugins/snt/delineations.md | 13 +++++++++++++ _pages/plugins/snt/manual.md | 5 +++++ 2 files changed, 18 insertions(+) diff --git a/_pages/plugins/snt/delineations.md b/_pages/plugins/snt/delineations.md index aca978c71..e45f023d1 100644 --- a/_pages/plugins/snt/delineations.md +++ b/_pages/plugins/snt/delineations.md @@ -98,6 +98,19 @@ To re-define a delineation it is sufficient to re-define or re-adjust an existin - _Outside color_ widget: Defines the color for non-delineated sections, i.e., those sections that remain _outside_ delineated areas +## Hierarchical Labels and Level-split Analysis + +Delineation names support hierarchical labeling using the `::` separator. For example, naming three delineations `Cortex::L1`, `Cortex::L2/3`, and `Cortex::L5` encodes both the parent region (Cortex) and the individual layers. This convention is particularly useful for atlas-imported delineations, where compartments are naturally hierarchical. + +When hierarchical labels are present, the _Measure_ and _Plot_ commands prompt for a **grouping level** before running the analysis. This allows measurements to be aggregated at different levels of granularity without redefining the delineations themselves. For example, with delineations named `Cortex::L1::proximal`, `Cortex::L1::distal`, and `Cortex::L2/3`: + +- **Level 1** groups everything under `Cortex` into a single entry +- **Level 2** groups by layer (`Cortex::L1` combines proximal and distal; `Cortex::L2/3` remains separate) +- **Level 3 (full)** reports each delineation individually + +The level-split prompt only appears when at least one delineation name contains the `::` separator. The _Non-delineated_ and _Unaffected paths_ categories always pass through unchanged regardless of the chosen level. + + ## Measuring Delineations Measurements are retrieved using the _Plot_ and _Measure_ buttons: diff --git a/_pages/plugins/snt/manual.md b/_pages/plugins/snt/manual.md index 5624c7dae..8a2e09111 100644 --- a/_pages/plugins/snt/manual.md +++ b/_pages/plugins/snt/manual.md @@ -202,6 +202,11 @@ See [Analysis › Strahler Analysis](/plugins/snt/analysis#strahler-analysis). #### Utilities +#### Ontology Browser... +Opens a standalone reference window for browsing brain-region ontologies (currently Allen CCF and Drosophila FBbt). The browser is intended for quickly looking up an acronym or ID while tracing or analyzing data. + +The browser is shared across ontology-aware features in SNT, including the [Reconstruction Viewer](/plugins/snt/reconstruction-viewer)'s atlas navigator and the [Delineations tab](#delineations-tab) when using atlas annotations. + #### Create Dendrogram Generates a Dendrogram plot of a connected component (i.e, one rooted tree structure in the Path Manager). See [Analysis › Graph-based Analysis](/plugins/snt/analysis#graph-based-analysis) for details.