update documentation for sntv5.1.21

_includes/snt-modes

@@ -0,0 +1,14 @@
+{%- comment -%}
+Defines {{ crop }} and {{ stream }}, the inline icons that mark SNT features
+restricted to one kind of tracing canvas. Include once, at the top of a page:
+
+  {% include snt-modes %}
+
+crop:   requires an image loaded in memory (classic canvas or a stream-mode crop)
+stream: SNT Stream only
+
+Variables assigned in an include persist in the including page, so they can be
+used anywhere below it
+{%- endcomment -%}
+{%- capture crop -%}<i class="fas fa-crop-alt" style="font-size:0.7em;" title="Requires an in-memory image (traditional image or stream-mode crop)"></i>{%- endcapture -%}
+{%- capture stream -%}<i class="fas fa-water" style="font-size:0.7em;" title="SNT Stream only"></i>{%- endcapture -%}

_pages/editing/index.md

@@ -263,6 +263,7 @@ The following tables list all of this site's general-purpose includes:
 | [timeline](timelines)                | Insert a horizontal timeline         |
 | [tooltip](tooltips)                  | Add a tooltip appearing on mouseover |
 | [echo](debugging)                    | For debugging                        |
+| [snt-modes](/plugins/snt/key-shortcuts) | Define the crop/stream icons of SNT |
 {:.skinny}
 
 #### MARKED FOR REMOVAL

_pages/plugins/snt/analysis.md

@@ -270,7 +270,7 @@ The analysis can be performed from the [Analysis menu](/plugins/snt/manual#root-
 Growth Analysis provides detailed time-lapse analysis of neuronal  patterns and requires traced paths to be matched across time frames, as detailed in the [Time-lapse analysis](./walkthroughs#time-lapse-analysis) walkthrough. The Analysis is accessed through the [Path Manager](./manual#path-manager)'s [Time-lapse Utilities](./manual#time-lapses-) menu.
 
 {% capture timelapse-demo%}
-For parameter validation and configuration comparisons, load the _Hippocampal neuron (DIC timelapse)_ demo dataset ({% include bc path='File|Load Demo Dataset...' %})
+For parameter validation and configuration comparisons, load the _Hippocampal neuron (DIC timelapse)_ demo dataset ({% include bc path='File|Load Demo Dataset/Tutorial...' %})
 {% endcapture %}
 {% include notice icon="info" content=timelapse-demo %}
 

_pages/plugins/snt/auto-tracing.md

@@ -42,7 +42,7 @@ For technical implementation details and references, see the [SNT technical note
 
 
 {% capture op1-demo%}
-You can follow these instructions using {% include bc path='File|Load Demo Dataset...' %} and choosing either 1) the _Drosophila OP neuron_, a Drosophila olfactory projection neuron and respective ground truth reconstruction (single cell); or the _Microglia cells_ dataset, a 2D image with multiple ramified microglia in the mouse retina.
+You can follow these instructions using {% include bc path='File|Load Demo Dataset/Tutorial...' %} and choosing either 1) the _Drosophila OP neuron_, a Drosophila olfactory projection neuron and respective ground truth reconstruction (single cell); or the _Microglia cells_ dataset, a 2D image with multiple ramified microglia in the mouse retina.
 {% endcapture %}
 {% include notice icon="info" content=op1-demo %}
 
@@ -334,7 +334,7 @@ The algorithm works by first skeletonizing the segmented image to extract its to
 
 
 {% capture ddac-demo%}
-You can follow these instructions using {% include bc path='File|Load Demo Dataset...' %} and choosing the _Drosophila ddaC neuron (Autotrace demo)_. It will load a binary (thresholded) image of a Drosophila space-filling neuron (ddaC) displaying autotracing options for automated reconstruction.
+You can follow these instructions using {% include bc path='File|Load Demo Dataset/Tutorial...' %} and choosing the _Drosophila ddaC neuron (Autotrace demo)_. It will load a binary (thresholded) image of a Drosophila space-filling neuron (ddaC) displaying autotracing options for automated reconstruction.
 {% endcapture %}
 {% include notice icon="info" content=ddac-demo %}
 

_pages/plugins/snt/big-data.md

@@ -17,7 +17,7 @@ tags: snt,tracing,segmentation,neuroanatomy,big-data,snt-stream
 # Big Data Support
 
 SNTv5 implemented _preliminary_ support for big data: images too large to fit in CPU/GPU memory (BDV XML/HDF5, N5, and OME-Zarr/OME-NGFF containers) can be opened virtually and browsed or reconstructed without ever loading the full volume.
-Most of this support is provided through [Big Data Viewer](./manual#big-data-viewer) and [Big Volume Viewer](./manual#big-volume-viewer).
+Most of this support is provided through [Big Data Viewer](./manual#big-data-viewer) and [Big Volume Viewer](./manual#big-volume-viewer). Tracing on streamed images is handled by [SNT Stream](./snt-stream), which is the page to read once data is loaded.
 The following operations are currently supported:
 
 | Operation | Status | Comments |
@@ -28,6 +28,7 @@ The following operations are currently supported:
 | [Path optimization](./manual#refinefit-) | Supported | |
 | 3D Visualization: Interactive re-slicing browser | Supported via [BigDataViewer](./manual#big-data-viewer) | |
 | 3D Visualization: Interactive volume viewer | Supported via [BigVolumeViewer](./manual#big-volume-viewer) and [sciview](./manual#sciview) | Includes [Slab View](#slab-view) for restricting rendering to a thin, adjustable region of the volume |
+| Stream-specific workflows | Supported (experimental) | [Materialized crops](./snt-stream#materialized-crops), [channel unmixing](./snt-stream#channel-unmixing), and [Quick Connect](./snt-stream#editing): see [SNT Stream](./snt-stream) |
 | Multidimensional operations | Limited support | Tracing handles one active channel/frame at a time for performance reasons. Commands that require exposing all channels/frames to be available at once [may not be supported](#limitations-and-idiosyncrasies) |
 
 <sup>1</sup>For collaborative tracing, please use [HortaCloud](https://hortacloud.org/): This is SNT's development team recommended tool for tracing Terabyte-size datasets in a collaborative environment
@@ -39,19 +40,32 @@ The following operations are currently supported:
 
 Choose _Big Data..._ from the [Shortcuts Window](./manual#snt-commands). In the prompt you can specify:
 
-- **Main volume**: The local path _or_ remote URL to the primary image volume. Supported files include: standard files, IMS, BDV XML/HDF5, N5, and OME-Zarr/OME-NGFF containers
+- **Main volume**: The local path _or_ remote URL to the primary image volume. See [Supported File Formats](#supported-file-formats) for the formats that are directly supported, and for what happens if the volume is not a multi-resolution pyramid
 
-- **Secondary volume**: The local path _or_ remote URL to a second, optional image volume. Useful for loading a processed version of the main volume, or a secondary channel saved as a separated file
+- **Secondary volume**: Optional. The local path _or_ remote URL to a second image volume. Useful for loading a processed version of the main volume, or a secondary channel saved as a separate file
 
-- **Reconstruction file(s)**: Optional. Either a single file ([TRACES, SWC, JSON, etc.](./manual#load-tracings-)), or a folder containing multiple reconstruction files. Reconstructions can also be [imported later](./manual#load-tracings-). Remote URLs are also supported.
+- **Reconstruction file(s)**: Optional. Either a single file ([TRACES, SWC, JSON, Neurolucida XML](./manual#load-tracings-)), or a folder/.zip archive of several such files. Coordinates are assumed to be properly scaled: use the _Import_ commands if an offset/scaling factor is needed. Reconstructions can also be [imported later](./manual#load-tracings-) when tracing is enabled
 
-- **Markers file**: Optional. A CSV file containing [bookmarked](./manual#bookmarks-tab) locations. Markers can also be imported later on. Remote URLs are also supported.
+- **Markers file**: Optional. A CSV file containing [bookmarked](./manual#bookmarks-tab) locations. Markers can also be imported later on
 
-- **Viewer type**: Defines the viewer type. Either:
-  - **Big Data Viewer (BDV): Interactive reslicing**: Interactive re-slicing browser
-  - **Big Volume Viewer (BVV): 3D rendering**: Interactive volume viewer, no tracing
-  - **Big Volume Viewer (BVV): 3D rendering w/ tracing capabilities**: Same as _Big Volume Viewer (BVV): 3D rendering_, but a new SNT instance is initialized as **[SNT Stream](./snt-stream)**, turning the BVV viewer into a functional tracing canvas
-  - **Big Data Viewer (BDV): Interactive reslicing w/ tracing capabilities**: A fallback option to the previous choice for when no discrete graphics card is available, or SNT is running on hardware without GPU support
+- **Seeds file**: Optional. A CSV file with candidate tracing [seeds](./seeds). Requires _Enable tracing (SNT Stream)_
+
+- **Viewer type**: Either **Big Data Viewer (BDV)**, an interactive re-slicing browser, or **Big Volume Viewer (BVV)**, a 3D volume renderer. The main differences are:
+
+  | | **Big Volume Viewer (BVV)** | **Big Data Viewer (BDV)** |
+  |---|---|---|
+  | **Display** | 3D volume rendering | Interactive reslicing |
+  | **Hardware** | Discrete graphics card recommended | No GPU needed |
+  | **[Slab View](#slab-view)** | Available | N/A |
+  | **[Channel unmixing](./snt-stream#channel-unmixing)** | Computed per slab | Live |
+
+  Choose BVV for sparsely labeled data, modern hardware, and a fast disk or network connection. Choose BDV for dense, feature-rich images, modest hardware, or slow connections.
+
+- **Enable tracing (SNT Stream)**: If checked, the viewer becomes the main tracing canvas (see [SNT Stream](./snt-stream)). If not, a plain, lightweight viewer is opened with no SNT session attached
+
+- **Load Remote Demo**: Pre-fills all fields with a remote demo (marmoset neurons, OME-Zarr, with autotracings and soma markers, using BVV with tracing enabled)
+
+All inputs can be local paths or remote URLs (including http and s3 links). Only _Main volume_ is mandatory.
 
 {% include notice icon="info" content="**[SNT Stream](./snt-stream) remains experimental**." %}
 
@@ -71,13 +85,30 @@ Slab View restricts BVV's rendering to a thin, adjustable region of the volume,
 Also, it may reduce data fetched from remote sources, depending on BVV's internal caching behavior.
 It is a general rendering feature, available in _Scene Controls_ whenever a BVV canvas is open, even outside active [SNT Stream](./snt-stream) tracing sessions.
 
-- **Controls**: toggle with the _Slab View_ button; a _Position_ slider moves the slab through the volume, and a _Thickness_ spinner controls how much of the volume is included around that position
-- **Orientation**: Slab View must be activated from one of the three canonical planes (XY/XZ/ZY), needed to give the slab an initial axis to work from. Once active, the view can be freely rotated; Slab View only turns itself off if the volume genuinely rotates out of the visible slab
-- **Slab Paths / Slab Annotations**: optional toggles that restrict rendered reconstructions/markers to the same slab window, so paths outside the slab don't clutter the view. _Slab Paths_' on/off state is remembered as a preference across Slab View activations; _Slab Annotations_ resets each time
+1. Align the view to one of the three canonical planes (XY, XZ, or ZY) and toggle **Slab View**. The canonical plane gives the slab an initial axis to work from: once active, the view can be freely rotated
+2. Set the slab's **Thickness** with the spinner, and move it through the volume with the **Position** slider (or its spinner). Both are in calibrated units
+3. Toggle **Slab Paths** to hide paths outside the slab. This also improves performance on large datasets. Equivalently, **Slab Annotations**, in the toolbar of the Bookmark Manager, restricts the markers to the slab. _Slab Paths_' on/off state is remembered as a preference across Slab View activations; _Slab Annotations_ resets each time
+
+Slab View switches itself off if the view no longer intersects the slab, and when the view is reset. It is also required by [channel unmixing](./snt-stream#channel-unmixing) of multi-resolution data.
 
 ## Supported File Formats
 
 [Big volume viewer](./manual#big-volume-viewer) and [Big data viewer](./manual#big-data-viewer) are at the core of Big-data support. Standard formats (TIFF, and anything readable via [Bio-Formats](/formats/bio-formats)) are loaded as regular in-memory volumes, with an option to downsample automatically if a volume exceeds the GPU's 3D texture limits.
 Imaris (.ims) files are supported via an automatically generated BDV-XML sidecar written next to the original file.
 
 For genuinely large datasets, BDV XML/HDF5, N5, and OME-Zarr/OME-NGFF containers are opened virtually: data is streamed from disk in blocks as needed. N5 and Zarr containers are read directly, with no XML sidecar required. Remote data can be also be loaded using URLs.
+
+### Non-pyramidal and oversized volumes
+
+BVV's 3D renderer requires a multi-resolution pyramid, and a single GPU texture has size limits. If the _Main volume_ does not satisfy these and BVV is chosen, SNT prompts you for how to proceed:
+
+- **Non-pyramidal N5/Zarr**: Choose _Build Pyramid_ to have SNT compute the coarser levels on demand (volumes that fit in memory are first copied locally, which may take a while for remote datasets)
+- **Image too large for a single GPU texture**: This happens when a dimension exceeds the 3D texture limit of your graphics card, or when the volume has too many voxels per channel. You can choose between:
+  - _Downsample_: Shrinks the image so that it fits. Opens quickly, but fine detail is lost
+  - _Load at full resolution_: Loads every voxel into memory as a tiled pyramid. Requires substantial memory, and is a rendering only: it cannot be used for tracing
+  - _Convert to multi-resolution OME-Zarr_: Writes an OME-Zarr folder next to the original image and opens it. May take several minutes, but the result is streamed from disk, so it opens quickly and needs little memory
+
+## See Also
+
+- [SNT Stream](./snt-stream): Tracing on streamed data, differences from in-core tracing, channel unmixing, materialized crops, and editing
+- [Key Shortcuts](./key-shortcuts): Shortcuts for both traditional and streamed canvases

_pages/plugins/snt/delineations.md

@@ -29,7 +29,7 @@ Delineations aggregate sections of reconstructions into groups to allow measurin
 {% capture ml-demo %}
 You can use the _MouseLight dendrites_ demo dataset to follow the delineation tutorials. While this dataset does not include counterstaining images, it can still be used for both ROI-based and Atlas-based delineations:
 
-1. Open {% include bc path='File|Load Demo Dataset...' %} and choose _MouseLight dendrites (Reconstructions only)_
+1. Open {% include bc path='File|Load Demo Dataset/Tutorial...' %} and choose _MouseLight dendrites (Reconstructions only)_
 2. Right-click on the _Display Canvas_ and choose _Pause SNT_ from the contextual menu
 3. Follow the instructions below
 {% endcapture %}