snt: document crossovers and navigation toolbar

Author: tferr

_pages/plugins/snt/manual.md

@@ -612,10 +612,44 @@ Waives all keyboard and mouse inputs to ImageJ, allowing you to interleave image
 # Path Manager
 
 <img align="right" width="300" src="/media/plugins/snt/snt-path-manager.png" title="Path Manager (v4.3)" />
-The Path Manager dialog displays all existing paths in a hierarchical structure (tree), where one path is "primary" or "root" (path 0) and all other paths (paths 1...N) are children of the primary path. This pattern repeats for each cell being traced. The dialog also contains several menus with various editing, tagging, refinement/fitting, filling and analysis options. Paths can be searched by name and/or tags in the text filter, with more sophisticated search capabilities in the Advanced Filtering Menu.
+The Path Manager dialog displays all existing paths in a hierarchical structure, where one path is "primary" or "root" (path 1) and all other paths (paths 2...N) are children of the primary path. This pattern repeats for each structure (arbor) being traced. The dialog also contains several menus with various editing, tagging, refinement/fitting, filling and analysis options. Paths can be searched by name and/or tags in the text filter, with more sophisticated search capabilities in the Advanced Filtering Menu.
 
 {% include notice icon="info" content="Path Manager commands are applied to all paths if no paths are selected." %}
 
+
+## Navigation Toolbar
+<img align="right" width="400" src="/media/plugins/snt/snt-navigation-toolbar.png" title="Navigation Toolbar (v5.0)" />
+
+The navigation toolbar allows for better handling of multiple arbors. An arbor is a primary (root‑level) path together with all of its children. In the Path Manager list, each arbor appears as a top‑level entry containing its dependent paths. The toolbar is designed to help you quickly navigate, filter, zoom, and bookmark image locations in larger projects. It includes the following controls:
+
+### Sort Arbors / Root‑level Structures
+<i class="fas fa-arrow-up-a-z"></i> Reorders the arbors in the Path Manager using sorting options such as _Arbor ID_, _Cell label_, _Traced channel_, etc.
+
+### Arbor Chooser
+This section of the toolbar allow for filtering the display of arbors in the Path Manager list. It includes the following controls:
+
+- <i class="fas fa-undo"></i> **Show All Arbors**: Clears any filtering and shows all paths in the list
+
+- **Drop‑down Choice**: Allows you to 'Jump to' a specific arbor in the list. If _Hide others_ (see below) is active, choosing an arbor limits the list to only that arbor’s paths
+
+- <i class="fas fa-sort"></i> **Next Arbor**: Cycles the Arbor choice to the next entry
+
+- <i class="fas fa-arrows-to-eye"></i> **Hide Others**: Shows only the arbor chosen in the drop‑down. If selected the Path Manager list is filtered to the select choice. If unselected all arbors are shown. Toolbar actions (Zoom, Bookmark, see below) honor this filter.
+
+## Zoom to Selected Path(s)
+<i class="fas fa-object-group"></i> Centers and zooms the image view to encompass the selected paths
+
+## Zoom to Selected Node(s)
+<i class="fas fa-crosshairs"></i> Navigates to specific node locations on the selected paths, such as their midpoint, first/last branch point, etc. When a single path is selected, it is also possible to navigate to its node with the smallest/largest radius
+
+## Bookmark Menu
+<i class="fas fa-bookmark"></i> This menu creates [bookmarks](#bookmarks-tab) at important locations. Two types of bookmarks are possible: 1) Topological locations (branch points, end-points, etc.), and 2) Quality-Control (QC) locations. The latter are locations pertinent to inspection, and review of traced paths, and include:
+
+- **Manually Tagged Nodes**: Nodes you previously color‑tagged (e.g., via the tracing canvas)
+- **Nodes With Invalid Radius**: Nodes whose radius is [unset or invalid](#correct-radii)
+- **Putative Crossovers**: These are “apparent crossings” (two or more paths passing very near without being topologically connected), automatically detected by SNT's algorithms. These are described in more detail in [Walkthroughs](./walkthroughs#detecting-crossovers). Note that detecting putative crossovers can be computationally heavy for large datasets. Start with a modest selection of paths and widen it as needed
+
+
 ## Menu Commands
 
 ### Edit ›
@@ -965,7 +999,7 @@ Filters can be combined using the <i class="fa fa-filter"></i> button: It restri
 
 ## Contextual Menu
 
-The Path Manager contextual menu offers convenience options to sort Paths, collapse/expand selections, and access children of Paths.
+The Path Manager contextual menu offers convenience options to collapse/expand selections, access children of Paths, etc.
 
 # Fill Manager
 

_pages/plugins/snt/walkthroughs.md

@@ -525,6 +525,68 @@ In addition to defined delineations, plots and tables may include two other cate
 {% 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." %}
 
 
+# Detecting Crossovers
+
+A crossover is a spot where at least two neurites pass very close to each other in space (so they may look like they intersect in the image) but they are not connected in the reconstructed graph (i.e., there is no shared node / true topological join). Identification of crossover sites is thus useful to disambiguate overlaps between neurites and spot possible tracing mistakes, such as missed branch-points or false merges.
+
+{% include img align="center" src="/media/plugins/snt/snt-crossover.svg" caption="Overview of a crossover between two neurites.<br>Left: Seem from top, the two neurites seem to intersect. Right: rotation to front view reveals that the two paths are juxtaposed in the XZ plane." %}
+
+
+## Algorithm
+
+Crossover events between two paths, _Path A_ and _Path B_, are detected as follows:
+1. Seeds:<br>
+    All tracing nodes from both paths plus segment midpoints are used as seed points (midpoints help catch “T‑like” geometries where a node lies near the middle of another path’s segment). Midpoints are flagged so they can be treated specially later
+2. Proximity mining:<br>
+    A uniform 3‑D grid is built with cell size equal to the _proximity radius_. For each seed, the 27‑cell neighborhood (the seed’s cell ± 1 in x/y/z) is queried; candidate pairs are kept if their Euclidean distance ≤ _proximity_ and they satisfy a series of optional criteria
+3. Candidate grouping:<br>
+    Candidate pairs are grouped by unordered (_Path A_, _Path B_) pairs, then sorted by index (_iA_, _iB_) and deduplicated. Each group is split into monotonic "runs". A run is accepted if its length is within a specified cutoff, or if it is a single‑pair run that touches an endpoint
+4. Geometric verification:<br>
+    For each accepted run, all corresponding segment pairs are examined: the closest points and distances between segments are computed, as well as an orientation‑invariant approach angle (0–90°) from local tangents. The center of the crossover event is the mean of closest‑point midpoints; the median distance and median angle summarize the run. Optional angle thresholds can be applied
+5. Merging:<br>
+    Nearby events (centers within _proximity_) are merged: the center is averaged, participants are unioned, index windows are merged, the distance becomes the minimum of medians, and the angle becomes the mean of medians
+6. Validation:<br>
+    A final post‑hoc filter keeps an event only if at least one path node from a participant path is near the event center. This removes spurious “floating” events
+
+## Obtaining Crossover Locations
+
+From the GUI, the easiest way to list crossover events is to use the [Bookmark option](./manual#bookmark-menu) in the [Navigator Toolbar](./manual#navigation-toolbar). For advanced detections, [scripting](./scripting) is advised.
+
+In a script, detection settings are specified in a _Config_ object, example:
+
+{% highlight java %}
+// groovy
+import sc.fiji.snt.util.CrossoverFinder
+
+cfg = new CrossoverFinder.Config()
+    .proximity(2.0) // The Neighborhood radius [real‑world units (e.g., µm)] used 1) for the coarse grid query during candidate mining, and 2) to merge nearby events
+    .thetaMinDeg(0.0) // Minimum approach angle (0–90°) required to accept an event. Use 10–20° to suppress nearly parallel neurites
+    .minRunNodes(2) // Minimum length of a “near‑pair run”. Neurites need to have at list this no. of nodes at the crossover site for it to be detected
+    .sameCTOnly(true) // Only compare paths with the same channel and frame?
+    .includeSelfCrossovers(false) // Allow detections within the same neurite? Generally keep false
+    .includeDirectChildren(false) // Allow detections within a path and its direct child? Generally keep false
+    .nodeWitnessRadius(-1.0); // Post‑hoc filter: A crossover event is only kept if at least one participant path has an actual node (not a midpoint) within this radius of the event center. Default (-1) instructs proximity value
+{% endhighlight %}
+
+Once the config is defined, events can be detected from any collection of paths:
+
+
+{% highlight java %}
+// groovy
+import sc.fiji.snt.Tree
+
+tree = Tree.fromFile("path/to/a/swc/file.swc")
+paths = tree.list()
+
+var events = CrossoverFinder.find(paths, cfg)
+for (ev in events) {
+    System.out.printf("x=%.2fµm, y=%.2fµm, z=%.2fµm, angle=%.1f°, d=%.2fµm, paths=%d%n",
+        ev.x, ev.y, ev.z, ev.medianAngleDeg, ev.medianMinDist, ev.participants.size());
+    double[] xyzct = ev.xyzct(); // pixel-space + avg C/T
+    // Optional: create a bookmark or navigate to xyzct[0..2]
+}
+{% endhighlight %}
+
 # Generating *Filtered Images* in Bulk
 
 This section describes how to generate [Filtered Images](/plugins/snt/manual#tracing-on-secondary-image-layer) outside SNT in bulk. Note that there are [many tutorials](/scripting/batch) on this topic. Arguably, the easiest way to process multiple images is to 1) record a macro that processes a single image, then 2) wrap it in a loop to iterate over all files in a directory. For example, using IJ1 macro language: