Document Spectral unmixing

_pages/plugins/snt/faq.md

@@ -105,6 +105,9 @@ Yes. Use {% include key key='ctlcmd|Shift|O' %} / {% include key key='ctlcmd|Alt
 ### How can I import an image sequence into SNT?
 Loading of images that require input options is handled by ImageJ directly. To load a directory of images (e.g., one file per Z-slice), run {% include bc path='File| Import|Image Sequence' color='white'%} and select the first file in the sequence, adjusting any needed parameters in the subsequent dialog prompt. Once the sequence is imported adjust voxel dimensions using {% include bc path='Image|Properties...' color='white'%}. To save yourself from having to go through these steps again, you should save the imported stack as a single TIFF file using {% include bc path='File|Save As|Tiff...' color='white'%}
 
+### Does SNT support brainbow-like images?
+Yes. See [Tracing in Multichannel (Brainbow) Images](./walkthroughs#tracing-in-multichannel-brainbow-images).
+
 ## Proofreading
 ### What is proofreading and curation?
 SNT provides two complementary approaches to reconstruction quality control:

_pages/plugins/snt/index.md

@@ -33,6 +33,7 @@ The [source repository](https://github.com/morphonets/SNT) contains more details
 /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-)

_pages/plugins/snt/key-shortcuts.md

@@ -96,7 +96,8 @@ These shortcuts become available in *Edit Mode*, activated through the contextua
 | {% include key key='left' %} {% include key key='right' %} {% include key key='up' %} {% include key key='down' %} | Rotate (with mouse: {% include key keys='Left Drag' %}) |
 | {% include key keys='shift|left' %} {% include key key='right' %} {% include key key='up' %} {% include key key='down' %} | Pan (with mouse: {% include key keys='Right Drag' %}) |
 | {% include key key='+' %} / {% include key key='-' %} | Zoom (with mouse: {% include key keys='Mouse Wheel' %}) |
-| {% include key keys='Double Click' %} | Toggle animation |
+| {% include key keys='Double Click' %} | Toggle animation (auto-detect rotation axis) |
+| {% include key keys='Shift|Double Click' %} | Toggle animation (force Z-axis rotation) |
 | {% include key keys='CTRL|Left Click' %} | Snap to top/side view |
 | {% include key key='A' %}        | Toggle <u>A</u>xes |
 | {% include key key='C' %}        | Toggle <u>C</u>amera Mode |

_pages/plugins/snt/manual.md

@@ -365,9 +365,9 @@ For the most part, the secondary layer remains hidden because feedback on the pa
 
 Secondary layers are created/load using the "Layers" drop-down menu in the _Interactive Tracing_ panel. The most common way to create a new layer is by calling the _Secondary Layer Creation Wizard_:
 
-The wizard needs two types of information from the user: The type of filtering operation and the size(s) (scale(s)) of the structures being traced, which control the spatial scale of the filter (known as σ).
+The wizard needs two types of information from the user: The type of filtering operation and the size(s) (scale(s)) of the structures being traced, which control the spatial scale of the filter (known as σ). For _Spectral Similarity_, σ values are replaced by a reference color vector (see details below).
 
-- **Filter** The filtering operation, including *Tubeness*, *Frangi*, *Gaussian blur* and *Median*:
+- **Filter** The filtering operation, including *Tubeness*, *Frangi*, *Gaussian blur*, *Median*, and *Spectral Similarity*:
 
   - **Tubeness** This corresponds to the _Hessian-based analysis_ of older SNT versions. This filter enhances tube-like structures in the image, using an improved [Tubeness](/plugins/tubeness) approach, modified to support multiple scale(s)
 
@@ -376,6 +376,8 @@ The wizard needs two types of information from the user: The type of filtering o
   - **Gaussian blur** Filter for noise removal, capable of gentle smoothing with some ability to preserve neurite edges, specially under small σ values.
 
   - **Median** Filter for noise removal able to preserve neurite edges. Note that _Median_ accepts only one σ value, i.e., a single scale.
+
+  - **Spectral Similarity (Brainbow / Multichannel)** A filter designed for multichannel images in which neurites are labeled by multiple fluorophores such as Brainbow data. Instead of enhancing structural features, it computes how well each voxel's color (channel-intensity vector) matches a reference color derived from traced paths. The output combines cosine similarity (directional match) with an intensity factor (brightness match), producing a scalar map in [0, 1] where high values indicate voxels matching the target neuron's spectral signature. This filter does not require σ values: the _Scale(s)_ field is automatically set to "unused". See _Scale(s)_ below for how to define the reference color.
 
 - **Scale(s)** Also known as _sigma(s)_ (σ). These should reflect average radii of the structures being traced. If smaller values are specified, the filter becomes more sensitive to noise. Larger values on the other hand, make the filtering operation less sensitive to local shape characteristics. There are two ways to select this values:
 
@@ -384,6 +386,8 @@ The wizard needs two types of information from the user: The type of filtering o
   - **Estimate programmatically...**: This allows automated estimation of radii across the image, which can inform the choice of scale(s). The only parameter required is *Dimmest intensity (approx.)*: Pixel values below this value are treated as background when computing thicknesses. Use -1 to adopt the default cutoff value (half of the image max). After pressing *OK*, a color-mapped image (based off local radius) and a histogram showing the distribution of radii across the image are shown. The histogram can be used to validate values chosen _visually_ in the preview palette.
 
     NB: Analysis is performed via the *Local Thickness (complete process)* plugin ({% include bc path='Analyze|Local Thickness|Local Thickness (complete process)' %} in Fiji's menu bar).
+
+  NB: When _Spectral Similarity_ is selected, σ values are not applicable and the _Scale(s)_ field is set to "unused". Instead, the wizard needs a reference color vector. The button label changes to _"Now Select Path(s) Defining Avg. Color"_, and it operates in two modes: (1) Select one or more paths in the Path Manager, then press _Run_: the average color is computed from the selected paths. (2) Press _"Estimate Programmatically..."_ to compute the average color from all paths currently in the Path Manager. In both cases, the per-channel average intensities are displayed for verification before the similarity map is computed.
 
 NB: The wizard also allows you to use a backup copy of the image being traced as secondary layer. This is only useful if you intend to modify the original image during a tracing session, but want to have convenient access to the initial image at a later time.
 
@@ -954,6 +958,36 @@ This command sets fitting options and should be run before computing a fit. Opti
 <img align="right" width="550px" src="/media/plugins/snt/correct-radii.png" alt="Correct Radii..." title="Correct Radii..." />
 If the fitting fails at a certain location (e.g., because the shape of the cross-section is too irregular, or because the fitted centroid is too far off) the program will skip that node moving on to the next. Skipped nodes will retain their original coordinates but their radius may become unset (see _Radius fallback_ in [parameters](#parameters)). This command collects such nodes from selected paths, and assigns them new radii using linear interpolation based on remaining nodes with valid radii. It can apply the interpolation immediately, or simply preview it. Note that by default _NaN_ and negative values are always corrected. The criterion specified in the prompt is used as an extra correction condition.
 
+#### Multispectral Refinement...
+
+This command refines traced paths in multi-color labeled images such as Brainbow data. In such images, uneven overlap between fluorescent reporters can cause traces to deviate from the neurite's true centerline. The algorithm repositions nodes by scoring candidate positions around each node against a multi-criteria cost function that combines brightness, color fidelity, and cross-section compactness. It works in tandem with the [Spectral Similarity](#creating-secondary-layers) secondary layer: while the secondary layer improves the _tracing_ step by producing a scalar similarity map for A\* search, multispectral refinement improves the _post-hoc_ step by refining an already-traced path using the full channel-intensity vector.
+
+The refinement dialog groups its settings into several categories:
+
+- **Relative importance of matching criteria** Controls how much each criterion influences node placement. The algorithm repositions nodes to minimize a combined penalty based on brightness, color fidelity, and cross-section compactness. Each weight can be increased to make that criterion dominate:
+  - _Brightness importance_: How strongly voxels outside the expected brightness range are penalized. Higher values keep nodes in well-lit regions of the neurite
+  - _Color-match importance_: How strongly voxels whose hue differs from the reference color are penalized. Higher values keep nodes on the labeled neurite's spectral channel
+  - _Radius importance_: How strongly large radii are penalized, favoring tight cross-sections. Higher values prefer thinner fits; lower values allow wider ones
+
+- **Detection criteria** Define when a voxel is considered part of the neurite vs. background:
+  - _Color-match stringency_: How closely a voxel's color must match the neurite's reference color (0–1). Higher values are stricter, rejecting weakly colored voxels
+  - _Background sensitivity_: Fraction of dim voxels (in a local sphere) that flags a node as background (0–1). Lower values are more aggressive at discarding nodes in dim regions
+  - _Max. radius_: Largest cross-section radius tested during optimization (in physical units). As a rule of thumb, should be 2–3× the expected neurite thickness
+
+- **Reference color strategy** How the reference color vector is computed. Two modes are available:
+  - _Global_: A single reference color is computed per path from the average channel intensities of all its nodes. This is the default and works well for short paths or paths with consistent coloring
+  - _Sliding window_: The reference color is recomputed locally for each node using ±N neighboring nodes. This adapts to gradual color changes along long neurites where spectral drift is common. The _Window extent (±nodes)_ parameter controls how many neighbors on each side contribute to the local reference; larger values smooth more, smaller values track finer color shifts
+
+- **Signal intensity range** The expected brightness range of the neurite signal (summed across all channels). Can be auto-calibrated from the image bit-depth and number of channels, or specified manually. When auto-calibrating, the min/max fields are computed automatically and their manual values are ignored
+
+- **Brightness tolerance** How forgiving the brightness assessment is when deciding if a voxel belongs to the neurite. Dim neurites get a wider tolerance; bright neurites get a stricter one. The two parameters define the endpoints of this range:
+  - _Tolerance (bright signal)_: Strictest tolerance, applied to the brightest neurites
+  - _Tolerance (dim signal)_: Most permissive tolerance, applied to the dimmest neurites
+
+- **Global Options**
+  - _Auto-tune from traced paths_: Automatically adjusts max. radius, color-match stringency, and signal intensity range based on the actual path data. Manual values above are used as starting points and may be overridden per-path during refinement. This is recommended when processing many paths with varying properties.
+  - _No. of parallel threads_: Number of threads used during refinement. Defaults to the number available on your computer. Set to 0 to reset to the default.
+
 ### Fill ›
 
 This menu contains options to start the filling process for selected paths. For detailed instructions see [Filling: Step-By-Step Instructions](/plugins/snt/walkthroughs#filling).

_pages/plugins/snt/walkthroughs.md

@@ -403,6 +403,57 @@ Currently, only the output images/CSV summary of fills are exported. TRACES file
 {% endcapture %}
 {% include notice icon="info" content=text %}
 
+# Tracing in Multichannel (Brainbow) Images
+
+{% capture brainbow-demo%}
+You can follow these instructions using {% include bc path='File|Load Demo Dataset...' %} and choosing the _Brainbow zebrafish larva_ dataset. This is a 2D, 3-channel confocal image in which individual neurons are distinguished by their unique combination of fluorescent proteins.
+{% endcapture %}
+{% include notice icon="info" content=brainbow-demo %}
+
+In multichannel-labeled images (such as Brainbow, Tetbow, or other combinatorial labeling), each neuron expresses a unique combination of fluorescent proteins, giving it a distinct color. Standard tracing approaches based on single-channel intensity can struggle in these images because multiple neurites of similar brightness but different color overlap in the same region. SNT provides two complementary tools for this: a **Spectral Similarity** secondary layer that improves path _tracing_, and **Multispectral Refinement** that improves path _positioning_ after tracing.
+
+## Step 1: Creating a Spectral Similarity Secondary Layer
+
+The idea is to produce a scalar image where voxels matching the target neuron's color are bright, and everything else is dark. The A* search then operates on this filtered image instead of the raw multichannel data.
+
+1. Trace a short path along the neuron of interest using standard tracing (see [Semi-automated Tracing](#semi-automated-tracing)). This initial path does not need to be perfect — it only needs to run along the target neuron so its average color can be computed. Prefer a path that is **long enough** to yield a reliable color average and that stays within a **single compartment** (e.g., all dendrites or all axons), as color hues can differ between compartments
+
+2. Open the _Secondary Layer Creation Wizard_ from the _Layers_ drop-down in the [Interactive Tracing panel](./manual#tracing-on-secondary-image-layer). Choose **Spectral Similarity (Brainbow / Multichannel)** as the filter. The _Scale(s)_ field will change to "unused" (σ values are not applicable to this filter)
+
+3. Click **Now Select Path(s) Defining Avg. Color**  and select the path(s) you just traced in the [Path Manager](/plugins/snt/manual#path-manager)
+
+4. Press **Run**. The wizard computes the average per-channel intensity from the selected path(s), displays it for verification, and generates the similarity map. Alternatively, press **Estimate Programmatically...** to compute the average color from _all_ paths in the Path Manager
+
+5. Enable **Trace/Fill on Secondary Layer** (shortcut: {% include key key='L' %}) to trace subsequent paths using the similarity map. The A* search should now follow the target neuron's spectral signature, hopefully ignoring neurites of other colors
+
+{% capture spectral-tip%}
+You can ping-pong between the original and secondary layer by pressing {% include key key='L' %} at any time. This is useful when the similarity map works well for some parts of the neuron but not others (e.g., dim regions where the color signal is weak).
+{% endcapture %}
+{% include notice icon="info" content=spectral-tip %}
+
+## Step 2: Refining Traced Paths with Multispectral Refinement
+
+Even with a spectral similarity layer, traced paths may not follow the exact centerline of the neuron, particularly where fluorescent reporters overlap unevenly. Multispectral Refinement corrects node positions using the full channel-intensity vector (not just the scalar similarity map).
+
+1. Select the path(s) to refine in the [Path Manager](/plugins/snt/manual#path-manager). Paths should be **long enough** for a reliable reference color (very short fragments will be automatically skipped)
+
+2. Run {% include bc path='Refine/Fit|Multispectral Refinement...' %} from the Path Manager menu. This opens the [parameter dialog](/plugins/snt/manual#multispectral-refinement), which groups settings into several categories:
+
+   - **Relative importance of matching criteria**: Controls how much brightness, color fidelity, and cross-section compactness influence node placement. Save existing paths and start with the defaults: Adjust as needed, reverting to the backup if needed
+   - **Detection criteria**: Sets the color-match stringency, background sensitivity, and maximum cross-section radius. If unsure, start with defaults and enable **Auto-tune from traced paths** (see below)
+   - **Reference color strategy**: Choose _Global_ for short paths with consistent coloring, or _Sliding window_ for long neurites where the color drifts gradually
+   - **Auto-tune**: When enabled, the algorithm estimates max radius, color-match stringency, and intensity thresholds from the actual path data. This is recommended when processing many paths or when you are unsure about suitable parameter values
+
+3. Press **OK** to run the refinement. The algorithm iteratively repositions each interior node to the lowest-cost candidate position, converging when no further improvement is found. Progress is logged to the console.
+
+4. Inspect the result. Refined paths should follow the neuron's centerline more closely. If the refinement is too aggressive or too conservative, adjust the weights or detection criteria and re-run.
+
+{% capture refine-tip%}
+Multispectral Refinement and standard [Fitting](/plugins/snt/manual#refinefit) serve different purposes: Fitting estimates radii and snaps nodes using single-channel cross-section analysis, while Multispectral Refinement uses the full color vector to handle the unique challenges of multicolor-labeled images. You can use both sequentially: e.g., refine positions with Multispectral Refinement first, then fit radii with standard Fitting afterward.
+{% endcapture %}
+{% include notice icon="info" content=refine-tip %}
+
+
 # Detecting Crossovers
 
 Described in [Curation](curation#detecting-crossovers).