Merge pull request #421 from imagej/labels

update snt docs: label image support (delineations and proximity detectors)

Author: tferr

_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:
 - <i class="fas fa-plus"></i> Adds more entries to the delineations list
@@ -72,12 +98,25 @@ 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 <i class="fas fa-chart-bar"></i> _Plot_ and <i class="fas fa-table"></i> _Measure_ buttons:
 
 - <i class="fas fa-chart-bar"></i> _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)
-- <i class="fas fa-table"></i> _Measure_: Reports common metrics to a dedicated table (Total length, No. of nodes, No. of junctions, etc.) across delineations
+- <i class="fas fa-table"></i> _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 +125,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 %}

_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

_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.
 
@@ -538,7 +543,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:
 
 <img align="right" width="300" src="/media/plugins/snt/snt-delineations-tab.png" alt="Delineations tab" title="Delineations tab" />
 <img align="right" width="300" src="/media/plugins/snt/snt-bookmarks-tab.png" alt="Bookmarks tab" title="Bookmarks tab" />
@@ -839,7 +844,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 +1112,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 ›