Merge pull request #420 from imagej/curation

update snt documentation

Author: tferr

_pages/plugins/snt/curation.md

@@ -15,7 +15,7 @@ tags: snt,tracing,neuroanatomy,qc,ground-truth
 
 
 {% capture version%}
-**This page was last revised for [version 5.0.8](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 %}
 
@@ -106,6 +106,16 @@ A "run" is a consecutive sequence of nodes where each radius exceeds the previou
 When a run's length meets or exceeds this threshold, a warning is produced.
 **Range:** 3–100 (no. of nodes)
 
+### Min. signal contrast ratio
+Measures how well each path stands out from the background in the image. At every node (excluding the first and last), a perpendicular cross-section is sampled using a Bresenham line that extends 3× the path radius (minimum 5 px) on each side.
+The sampled intensities are split by percentile: the lower quartile (P25) estimates background, the upper quartile (P75) estimates signal. The contrast ratio is defined as:
+
+$$\frac{\mathrm{median}(\text{signal}) + 1}{\mathrm{median}(\text{background}) + 1}$$
+
+A path whose median contrast ratio falls below this threshold is flagged. The +1 offset prevents division by zero and stabilizes the ratio for dim images. When set to **-1** (Auto), the threshold is computed automatically from the image's intensity range as $$\frac{I_{\max} + 1}{I_{\min} + 1} \times \frac{1}{2}$$, representing half of the best achievable contrast ratio for the image. The computed value is displayed in the spinner after the scan completes; use the undo button to reset to auto mode. This check requires an image to be loaded and image statistics to be computed.
+
+**Range:** -1 (auto) or 1.0–100.0
+
 
 ## Toolbar Actions
 

_pages/plugins/snt/faq.md

@@ -57,7 +57,7 @@ When tracing 4D or 5D images, TRACES is preferable because the channel and/or ti
 | Presence                                     | Ubiquitous among reconstruction software. The *de facto* standard in data sharing                                                    | Exclusive to SNT. But [open and easily parsable](/plugins/snt/extending#traces-file-format) |
 
 ### Which file formats for neuronal reconstruction are supported by SNT?
-SNT can read TRACES, SWC, NDF (NeuronJ data format), and JSON files (as used by the [MouseLight](https://ml-neuronbrowser.janelia.org/) project). Other file formats can be converted to [SWC](#swc) using [xyz2swc](https://neuromorpho.org/xyz2swc/ui/).
+SNT can read TRACES, SWC, NDF (NeuronJ data format), JSON files (as used by the [MouseLight](https://ml-neuronbrowser.janelia.org/) project), and [Neurolucida XML](https://neuromorphological-file-specification.readthedocs.io/) (MBF Bioscience's Neuromorphological File Specification). Neurolucida XML files support both tree structures and markers. Other file formats can be converted to [SWC](#swc) using [xyz2swc](https://neuromorpho.org/xyz2swc/ui/).
 
 ### My neuronal reconstructions are saved under a format that is not supported. How can I open them?
 Unsupported and proprietary file formats can be converted to [SWC](#swc) using [xyz2swc](https://neuromorpho.org/xyz2swc/ui/).

_pages/plugins/snt/manual.md

@@ -9,7 +9,7 @@ tags: snt,reconstruction,tracing,arbor,neuron,morphometry,dendrite,axon,neuroana
 ---
 
 {% capture version%}
-**This page was last revised for [version 5.0.8](https://github.com/morphonets/SNT/releases)**.<br>
+**This page was last revised for [version 5.0.10](https://github.com/morphonets/SNT/releases)**.<br>
 Please help us to keep up-to-date documentation by [editing](https://github.com/imagej/imagej.github.io/edit/main/_pages/plugins/snt/manual.md) this page directly to fill in any documentation gap. Do [reach out](https://forum.image.sc/tag/snt) if you need assistance!
 {% endcapture %}
 {% include notice content=version %}
@@ -67,7 +67,7 @@ In either scenario. You should toggle the *validate spatial calibration* checkbo
 
 Imports of neuronal reconstructions from multiple sources, including:
 
-- **{% include bc path='Local Files' %}** [TRACES](/plugins/snt/faq#in-which-format-should-i-save-my-tracings-traces-or-swc), [SWC](/plugins/snt/faq#what-is-a-swc-file) (single files or bulk import of a directory of files), NDF ([NeuronJ](/plugins/neuronj) data format), or JSON.
+- **{% include bc path='Local Files' %}** [TRACES](/plugins/snt/faq#in-which-format-should-i-save-my-tracings-traces-or-swc), [SWC](/plugins/snt/faq#what-is-a-swc-file) (single files or bulk import of a directory of files), NDF ([NeuronJ](/plugins/neuronj) data format), JSON, or [Neurolucida XML](https://neuromorphological-file-specification.readthedocs.io/) (MBF Bioscience). Neurolucida files import both tree structures and markers (loaded as [bookmarks](#bookmarks-tab)).
 
 - **{% include bc path='Remote Databases' %}** Import of neuronal reconstructions from [FlyCircuit](http://www.flycircuit.tw/), [InsectBrain](https://insectbraindb.org/app/), [MouseLight](https://ml-neuronbrowser.janelia.org/), and [NeuroMorpho](http://neuromorpho.org/).
 
@@ -554,6 +554,12 @@ This tab hosts the Bookmark Manager, a utility that stores image locations to be
 
 - Use the {% include bc path='Export' %} button to save the current list to either: 1) a CSV file, 2) ImageJ's ROI Manager or 3) the overlay of the active image. Note that when images are saved as TIFF, ROIs are saved in the file's header, and automatically loaded by ImageJ when the image is open.
 
+The right-click contextual menu of the Bookmark Manager also provides commands for consolidating bookmarks:
+
+- **{% include bc path='Colocalize...' %}** Matches bookmarks across different channels within a specified distance threshold, replacing matched groups with their centroids. This is useful for identifying co-labeled structures in multichannel images. Only bookmarks from different channels are matched.
+
+- **{% include bc path='Merge...' %}** Merges nearby bookmarks within each channel independently, replacing clustered bookmarks with their centroids. This is useful for consolidating redundant or overlapping bookmarks that were placed on the same structure within a single channel.
+
 
 ## 3D Tab
 
@@ -839,6 +845,10 @@ Assigns the no. of markers (e.g., spines or varicosities) to be associated to se
 
 Simplifies paths by reducing their node density. Given an inputted maximum permitted distance between adjacent nodes, performs {% include wikipedia title="Ramer–Douglas–Peucker algorithm" %} downsampling on the selected Path(s) (undoable operation).
 
+#### Correct Z-Shrinkage...
+
+Corrects Z-axis shrinkage from tissue processing (e.g., histological sectioning and mounting). The command prompts for a correction factor, typically the ratio of *cut thickness / mounted thickness*. Values greater than 1 expand Z coordinates; values less than 1 compress them. If an image is loaded, a warning is displayed when corrected nodes would fall outside image bounds. This operation cannot be undone.
+
 #### Rebuild...
 
 Analyzes and rebuilds path relationships to fix structural issues. The command first scans all paths for problems, then offers to rebuild if issues are found. Detected issues include:
@@ -1099,7 +1109,12 @@ NB:
 
 #### Spines/Varicosities ›
 
-This menu contains commands tools for analyzing at manually placed markers along paths such as dendritic spines or axonal varicosities. The starting point for such analyses are multipoint ROIs placed along paths. These are detailed in [Spine/Varicosity Analysis](/plugins/snt/spines-varicosities).
+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:
+- **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)
+- **Commands for handling manually placed markers**
+
+These tools are detailed in [Spine/Varicosity Analysis](/plugins/snt/spines-varicosities).
 
 #### Time-lapses ›
 

_pages/plugins/snt/spines-varicosities.md

@@ -14,7 +14,7 @@ tags: snt,tracing,neuroanatomy,maxima
 
 
 {% capture version%}
-**This page was last revised for [version 5.0.7](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 %}
 
@@ -70,6 +70,37 @@ Note that the mask is a voxel-level approximation of the continuous search annul
 See {% include bc path='Scripts|Demos|Peripath Detection Demo' %} ({% include bc path='Templates|Neuroanatomy|Analysis|Peripath Detection Demo' %} in the Script Editor) for a working example that runs detection and generates the torus mask on one of the demo datasets.
 
 
+## Along-Path Detection (Radius Swellings)
+
+SNT can also detect swellings (boutons, varicosities, blebs) **along** traced paths using the _Along-Path Detector_, which analyzes longitudinal radius profiles. The algorithm works as follows:
+- At each node, the node radius is compared to the average radius of its neighbors within a sliding window
+- A node is flagged as a swelled candidate when its radius exceeds the neighbor average by a configurable factor
+- Optionally, a intensity (brighness) threshold can filter candidates further
+- Adjacent candidates are merged via non-maximum suppression
+
+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. 
+
+The command's dialog provides the following parameters:
+
+- **Swelling factor** A node is flagged when its radius exceeds the average of its neighbors by at least this factor. Default: 1.5 (i.e., 1.5× the local average). Lower values increase sensitivity; higher values restrict detection to more prominent swellings
+
+- **No. of neighbors** Total number of neighboring nodes used to compute the local average radius, split evenly on each side of the test node. Default: 10. Larger values smooth out local noise but may miss closely spaced features
+
+- **Min. intensity** Minimum on-skeleton (centerline) intensity for a detection to be accepted. Three modes: **0** disables intensity filtering (radius-only detection); **-1** auto-computes a threshold as the midpoint of the image's dynamic range; any **positive value** sets an explicit threshold in image intensity units
+
+- **Intensity channel** The image channel for intensity sampling (1-based; only shown for multi-channel images and when intensity filtering is enabled)
+
+- **Merging distance** Minimum separation between detections in physical units. Nearby detections are merged, keeping the one with the highest score. Set to 0 for automatic (defaults to 2× mean radius across all paths)
+
+- **Exclude junctions/tips** When enabled, nodes near branch points and path tips are excluded from detection. These regions may have naturally enlarged radii that produce false positives. The exclusion zone extends by the half-window size on each side of every junction and at each path endpoint. Default: enabled
+
+- **Output** Results can be exported as _ROIs_ (added to the ROI Manager, grouped per path) or as _Bookmarked locations_ (added to the [Bookmark Manager](/plugins/snt/manual#bookmarks-tab))
+
+Detected counts are automatically assigned to each path's spine/varicosity tally, just as with the Peripath Detector.
+
+
 ## 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: