Merge pull request #349 from imagej/sntv5

snt: update legacy viewer-related content

_pages/plugins/snt/faq.md

@@ -76,6 +76,9 @@ Use the *Edit this page* option on the <a href="#top">top</a> of the documentati
 
 ## Tracing
 
+### Can I trace in 3D?
+Yes, always. Either using the XY,ZY,XZ [views](/plugins/snt/step-by-step-instructions#accurate-point-placement) or more interactively: using the [3D Viewer](/plugins/snt/manual#legacy-3d-viewer) (legacy), or [sciview](/plugins/snt/manual#sciview) (experimental).
+
 ### Having to confirm individual segments is too cumbersome. Is it possible to trace without interruption, by clicking in succession?
 Yes. Uncheck the *Confirm temporary segments* in the *Options* tab (*Temporary Paths* section).
 

_pages/plugins/snt/key-shortcuts.md

@@ -27,10 +27,10 @@ The Command Palette is the fastest way to access actions and discover their resp
 
 ### Interactive Prompt
 
-| {% include key key='Y' %}  | Confirms the current temporary path. *Mnemonic: <u>Y</u>es* |
-| {% include key key='N' %}  | Discards the current temporary path. *Mnemonic: <u>N</u>o*  |
-| {% include key key='F' %}  | <u>F</u>inishes a path. Note that you can finish a path by pressing {% include key key='Y' %} {% include key key='Y' %} twice |
 | {% include key key='C' %}  | <u>C</u>ancels a path. Note that you can finish a path by pressing {% include key key='N' %} {% include key key='N' %} twice |
+| {% include key key='F' %}  | <u>F</u>inishes a path. Note that you can finish a path by pressing {% include key key='Y' %} {% include key key='Y' %} twice |
+| {% include key key='N' %}  | Discards the current temporary path. *Mnemonic: <u>N</u>o*  |
+| {% include key key='Y' %}  | Confirms the current temporary path. *Mnemonic: <u>Y</u>es* |
 | {% include key key='Esc' %}| Aborts current operation / Exits current mode |
 
 
@@ -62,7 +62,7 @@ These shortcuts are available when running SNT in *Tracing Mode*:
 | {% include key key='L' %}                     | Toggles Tracing/Filling on Secondary <u>L</u>ayer (filtered image) |
 | {% include key key='V' %}                     | Finds the brightest <u>V</u>oxel above and below the current x,y position and automatically clicks on it. If multiple maxima exist, their average positioning is used. Note that this feature assumes that neurites are brighter than the background |
 | {% include key key='S' %}                     | Toggles cursor <u>S</u>napping: If enabled, the plugin will automatically move the cursor to the brightest voxel within the specified x,y,z snapping window<sup>1</sup>. When set correctly, this facilitates accurate [positioning of path points](/plugins/snt/step-by-step-instructions#accurate-point-placement) |
-| {% include key keys='Alt|Shift|Left Click' %} | Selects a point along the active path to be used as forking point (See [step-by-step instructions](/plugins/snt/step-by-step-instructions#branching-start-a-path-on-an-existing-path) for more details on joining and branching) |
+| {% include key keys='Alt|Shift|Left Click' %} | Selects a point along the active path to be used as forking point (See [step-by-step instructions](/plugins/snt/step-by-step-instructions#branching-start-a-path-on-an-existing-path) for more details on joining and branching). This shortcut can be [simplified](/plugins/snt/manual#temporary-paths) |
 | {% include key keys='Shift|B' %}              | <u>B</u>ookmarks cursor location |
 | {% include key keys='Shift|E' %}              | Activates *Edit Mode* (<u>E</u>diting of selected Path) |
 | {% include key keys='Shift|P' %}              | <u>P</u>auses tracing operations |
@@ -86,18 +86,20 @@ 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='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 |
 | {% include key key='D' %}        | Toggle <u>D</u>ark Mode |
 | {% include key key='F' %}        | <u>F</u>it View to Visible Objects |
+| {% include key key='H' %}        | <u>H</u>elp (as Notification) ({% include key key='F1' %} shows Help on a dedicated window) |
 | {% include key key='L' %}        | <u>L</u>og Scene Details to Console |
 | {% include key key='R' %}        | <u>R</u>eset View (1 press) or <u>R</u>eload Scene (double press) |
 | {% include key key='S' %}        | Save <u>S</u>creenshot |
 | {% include key keys='Shift|C' %} | Toggle <u>C</u>ontrol Panel |
 | {% include key keys='Shift|F' %} | Toggle <u>F</u>ull Screen ({% include key key='Esc' %} can also be used to exit) |
 | {% include key keys='Shift|S' %} | Toggle <u>S</u>tatus Bar |
-| {% include key key='H' %}        | <u>H</u>elp (as Notification) ({% include key key='F1' %} shows Help on a dedicated window) |
+| {% include key keys='Ctrl|Shift|P' %} / {% include key keys='Command|Shift|P' %}| Toggle Command <u>P</u>alette |
 
 ### sciview
 
@@ -112,11 +114,18 @@ See [sciview](/plugins/sciview)'s {% include bc path='Help| '%}menu for a full l
 
 ### Legacy 3D Viewer
 
-All shortcuts that are not specific to tracing canvases (XY, ZY and XZ views) *should* be recognized by the [Legacy 3D viewer](/plugins/snt/step-by-step-instructions#legacy-3d-viewer). In addition, the following are also implemented:
+The most important shortcuts for the [Legacy 3D viewer](/plugins/snt/step-by-step-instructions#legacy-3d-viewer) are:
+
+| {% include key key='H' %} | Selects the <u>H</u>and (pan) tool |
+| {% include key key='W' %} | Selects the <u>W</u>and (tracing) tool |
+| {% include key keys='Middle Drag' %} | Rotation |
+| {% include key keys='Shift|Middle Drag' %} | Pan (translation) |
+| {% include key keys='Mouse Wheel' %} | Zoom |
+| {% include key keys='Shift|Left Drag' %} | When Hand tool is active: Pan (translation) |
+| {% include key keys='Left Drag' %} | When Hand tool is active: Rotation |
+
+In addition, _most_ shortcuts that are not specific to tracing canvases (XY, ZY and XZ views) can be used in the 3D Viewer. When a key stroke is not recognized by the 3D Viewer, a mesage is displayed in the [status bar](/plugins/snt/manual#status-bar) of the main dialog. 
 
-| {% include key key='H' %}   | Selects the <u>H</u>and (rotation) tool |
-| {% include key key='W' %}   | Selects the <u>W</u>and (selection) tool |
-| {% include key key='Esc' %} | Shuttles between the Hand and Wand tool after both have been selected at least once |
 
 ### Other
 

_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 4.3.0**.<br>
+**This page was last revised for version 5.0.0**.<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 %}
@@ -332,6 +332,11 @@ The "Layers" drop-down menu in the auto-tracing panel also allows for importing
 
 The same menu also provides options to import a [Labkit/Weka](./machine-learning) model. In this case the model is applied to the image being traced, and the resulting 'p-map' is loaded as secondary layer.
 
+
+### Computation Settings
+This widget reports current settings (cost function, image statistics, etc.). Report can be copied to the clipboard, or logged to the [Script Recorder](./scripting/#script-recorder).  
+
+
 ### Filters for Visibility of Paths
 
 <img align="right" src="/media/plugins/snt/path-visibility-filters.png"  width="300" />
@@ -459,27 +464,31 @@ This option assumes [sciview](/plugins/sciview) to be successfully installed. sc
 
 ### Legacy 3D Viewer
 
-The Legacy 3D Viewer is a functional tracing canvas and allows images to be traced interactively in 3D. However, it is no longer actively maintained and _may_ not function reliably on certain hardware. For usage instructions, see [Tracing using the Legacy 3D Viewer](/plugins/snt/step-by-step-instructions#tracing-in-the-legacy-3d-viewer).
+The Legacy 3D Viewer is a functional tracing canvas and allows images to be traced interactively in 3D. However, it relies on libraries that are not actively maintained and _may_ not function reliably during complex tasks. That being said, SNTv5 has implemented several improvements that have restored/improved Legacy 3D Viewer functionality relatively to earlier versions. For usage instructions, see [Tracing using the Legacy 3D Viewer](/plugins/snt/step-by-step-instructions#tracing-in-the-legacy-3d-viewer).
 
 <span id="bookmarks"></span>
 <span id="bookmark-manager"></span>
 
 ## 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 ambiguos branching point, or an ambiguous cross-over between two neurites). 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). The basic usage is as follows:
 
 <img align="right" width="300" src="/media/plugins/snt/snt-bookmarks-tab.png" title="Bookmarks tab" />
 
-- Right click on the image and choose {% include bc path='Bookmark Cursor Position' %} from the image contextual menu (shortcut: {% include key key='Shift|B' %}). A new bookmark will be added logging the cursor X, Y, Z, C, T coordinates
-
-- To visit a bookmarked location double-click on its entry. The image will be centered at that position under the speficied zoom in {% include bc path='Preferred Zoom Level (%)' %}
+- Right-click on the image and choose {% include bc path='Bookmark Cursor Position' %} from the image contextual menu (shortcut: {% include key key='Shift|B' %}). A new bookmark will be added logging the cursor X, Y, Z, C, and T coordinates
 
-- Use {% include bc path='Import...' %} to load bookmars from a CSV file. Use {% include bc path='Export...' %} to store current list.
+- To visit a bookmarked location, double-click on its entry. The image will be centered at that position under the specified zoom in {% include bc path='Preferred Zoom Level (%)' %}
 
 - To rename an existing bookmark, select it and start typing its new label. Alternatively, use 
-{% include bc path='Rename Selected Bookmark..' %} command in the list righ-click menu
+{% include bc path='Rename Selected Bookmark..' %} command in the list right-click menu
+
+- Use {% include bc path='Import...' %} to load bookmars from either: 1) a CSV file, 2) Existing ROIs in ImageJ's ROI Manager, or 3) Existing ROIs in the overlay of the image being traced. Note that when loading an area ROI, the bookmark is registered at the ROI's centroid
+
+- Use {% include bc path='Export...' %} 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.
+
+## Status Bar
+The status bar at the bottom of the Main Dialog displays brief messages about ongoing operations. By default, the status bar reports the image title and the CT position being traced.
 
-- Bookmarks can also be transferred to ImageJ's ROI Manager using {% include bc path='Send Selected Bookmarks to ROI Manager...' %} in the list righ-click menu
 
 # Image Contextual Menu
 

_pages/plugins/snt/reconstruction-viewer.md

@@ -8,7 +8,7 @@ forum-tag: snt
 ---
 
 {% capture version%}
-**This page was last revised for version 4.3.0**.<br>
+**This page was last revised for version 5.0.0**.<br>
 Please help us to keep up-to-date documentation by [editing](https://github.com/imagej/imagej.github.io/edit/main/_pages/plugins/snt/reconstruction-viewer.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 %}

_pages/plugins/snt/step-by-step-instructions.md

@@ -11,7 +11,7 @@ tags: snt,reconstruction,tracing,arbor,neuron,morphometry,dendrite,axon,neuroana
 ---
 
 {% capture version%}
-**This page was last revised for version 4.3.0**.<br>
+**This page was last revised for version 5.0.0**.<br>
 Please help us to keep these walk-throughs up-to-date 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 %}
@@ -145,32 +145,45 @@ Accurate node placement requires <em>XY</em>, <em>ZY</em> and <em>XZ</em> views
 
 ## Tracing in the Legacy 3D Viewer
 
+The legacy 3D Viewer allows for tracing in an interactive 3D scene.
+
 ### I. Starting the Viewer
 
 <img align="right" src="/media/plugins/snt/snt-3d-dialog.png" title="The legacy 3D Viewer remains a functional canvas" width="300px"/>
-It remains possible to trace in the legacy 3D Viewer. To open it, select the *3D* menu tab in the SNT dialog and look for *Legacy 3D Viewer*. You will see 3 parameters:
+ To open the viewer, select the *3D* menu tab in the SNT dialog and look for *Legacy 3D Viewer*. You will see several parameters:
+
+- Select *New with image...* from the *Viewer* drop-down menu and press *Apply*. Note that you can re-use existing viewers you may have open by choosing their window titles from the drop-down menu. NB: Selecting *New without image* would only allow you to look at reconstructions without the underlying signal.
+
+- Large images may require downsampling for performance reasons. Once you *Apply* the viewer choice, a prompt will appear asking you to choose the downsampling factor for the image. E.g., a value of 2 means here that the image is downsampled by a factor of 2 in x-, y- and z-direction. Note that while downsampling speeds up rendering it often results in signal smoothing. Volumes should look crisper without downsampling. Original pixels are used with a resampling factor of 1. 
 
-- Select *New with image* from the *Viewer* drop-down menu (selecting *New without image* would only allow you to look at reconstructions without the underlying signal). Note that you can recycle existing viewers you may have open by choosing their window titles from the drop-down menu.
+- Once the downsampling factor is specified, the viewer window will appear with the currently open image (i.e., the current Channel/Frame being traced as specified in the [Data Source](/plugins/snt/manual#data-source) widget).
 
-- Select the preferred rendering style from the *Mode* drop-down menu.
+- Options in the _Mode_ drop-down menu specify how paths should be rendered. There are three possibilities: 1) *Lines*: Only the centerline of paths is displayed; 2) *Lines and disks*: Centerline of paths is displayed with disks at each node depicting the node radius;  and 3) *Surface reconstruction*: Paths are dispayed as surface meshes.
+
+{% include notice content="By default, the Legacy 3D Viewer displays warnings and errors in pop-up dialogs. You can toggle _Disable pop-up errors_ to have them displayed in a non-blocking Log window." %}
 
-- Once you *Apply* the viewer choice, a prompt will appear asking you to choose the resampling factor for the image. Then, the viewer window will appear with the currently open image.
-  <img align="right" src="/media/plugins/snt/snt-image-resampling-factor.png" title="Legacy 3D Viewer resampling prompt" width="300px"/>
 
 ### II. Tracing and Navigation
-<img  align="left" src="/media/plugins/snt/snt-legacy-3d-viewer.png" title="3D viewer showing OP_1.tif" width="300"/>
+<img  align="right" src="/media/plugins/snt/snt-legacy-3d-viewer.png" title="3D viewer showing OP_1.tif" width="350"/>
+
+#### Selecting points for tracing
+_Tracing_ mode is only active when the *Wand tool* in the main ImageJ toolbar is active. To activate it, press the {% include key key='W' %} [shortcut](/plugins/snt/key-shortcuts#legacy-3d-viewer)) and click over the region you want to trace. Tracing works the same way as in the XY, YZ, and XZ views, i.e., click somewhere in the image to create a starting point, then click further along the structure of interest to find a path between the two points, then confirm or deny the temporary segment as described [above](#iii-confirm-the-temporary-segment). Similarly, branching occurs as [described for 2D canvas(es)](#branching-start-a-path-on-an-existing-path), by holding the {% include key keys='Alt|Shift' %} modifier. NB: This shortcut can be simplified: See [Options Tab](/plugins/snt/manual#temporary-paths) for details.
+
+To interact with the scene without tracing, activate the *Hand tool* in the main ImageJ toolbar by pressing {% include key key='H' %}.
+
+
+#### Navigation
+
+- **Rotation**: Use {% include key keys='Middle Drag' %}. Alternatively, if the *Hand tool* ({% include key key='H' %}) is active in the ImageJ toolbar you can use {% include key keys='Left Drag' %}
 
-###### Selecting points for tracing
-Select the *Wand tool* ({% include key key='W' %} [shortcut](/plugins/snt/key-shortcuts#legacy-3d-viewer)) in the main ImageJ toolbar and click over the region you want to trace. Tracing works the same way as in the 2.5D view, i.e., click somewhere in the image to create a starting point, then click further along the structure of interest to find a path between the two points, then confirm or deny the temporary segment as described [above](#iii-confirm-the-temporary-segment). Similarly, branching occurs as [described for 2D canvas(es)](#branching-start-a-path-on-an-existing-path), by holding the {% include key keys='Alt|Shift' %} modifier.
+- **Translation**: Use {% include key keys='Shift|Middle Drag' %}. Alternatively, if the *Hand tool* ({% include key key='H' %}) is active in the ImageJ toolbar you can use {% include key keys='Shift|Left Drag' %}
 
-###### Navigation
-**Rotation** Either use the *Hand tool* ({% include key key='H' %} [shortcut](/plugins/snt/key-shortcuts#legacy-3d-viewer)) tool and left-click while dragging the mouse or drag mouse while holding the scroll wheel
+- **Zoom**: Use {% include key keys='Mouse Wheel' %}
 
-**Translation** Hold {% include key key='Shift' %} and the scroll wheel while dragging the mouse.
+See [Key Shortcuts](/plugins/snt/key-shortcuts#legacy-3d-viewer) for the list of all supported shortcuts.
 
-**Adjusting zoom depth** Scroll using the mouse wheel.
+{% include notice content="Note that the 3D Viewer is not aware of commands listed in the [Image Contextual Menu](/plugins/snt/manual#image-contextual-menu) (e.g., _Path Editing_). Such commands need to be accessed from the image canvas" %}
 
-NB: Once you have selected the Wand and Hand tools once, you should be able to switch between them by pressing the {% include key key='Esc' %} key. See [Key Shortcuts](/plugins/snt/key-shortcuts#legacy-3d-viewer) for the list of all supported shortcuts.
 
 # Merging/Joining Paths