feat: Add catmaid spatially indexed skeletons

docs/index.rst

@@ -7,6 +7,7 @@ Neuroglancer
    :caption: User Guide
 
    user-guide/navigation
+   user-guide/skeleton_editing
 
 .. toctree::
    :hidden:
@@ -42,4 +43,3 @@ Neuroglancer
 Neuroglancer is a WebGL-based viewer for volumetric data.  It is capable of
 displaying arbitrary (non axis-aligned) cross-sectional views of volumetric
 data, as well as 3-D meshes and line-segment based models (skeletons).
-

docs/spatial_skeleton_refresh_nodes.md

@@ -0,0 +1,167 @@
+# Why `refreshNodes()` Is Called So Often
+
+This note documents every current `refreshNodes()` call site in `src/ui/spatial_skeleton_edit_tab.ts` and whether it is strictly required by the current implementation.
+
+## What `refreshNodes()` actually recomputes
+
+`refreshNodes()` is not just a repaint helper. It rebuilds the tab's backing data by:
+
+- Recomputing `activeSegmentIds` from `getVisibleSegments(...)`.
+- Resolving the current spatial skeleton render layer and CATMAID client.
+- Clearing the full-skeleton cache when `layer.spatialSkeletonNodeDataVersion` changes.
+- Fetching full CATMAID skeletons for every active segment.
+- Fetching CATMAID "true end" labels and applying them to the node list.
+- Rebuilding `nodesBySegment`, `allNodes`, the summary text, and the selected node fallback.
+
+Because of that, a refresh is only fundamentally needed when one of those inputs changes.
+
+## Call sites
+
+### 1. `deleteNode(...)` success path
+
+Why it is called:
+
+- Deleting a node changes the local skeleton layer immediately.
+- A delete can also split one skeleton into new segment ids, so the active visible segment set may change.
+- The tab wants to re-fetch the authoritative CATMAID skeleton after the mutation instead of trusting only local chunk edits.
+
+Assessment:
+
+- Reasonable as an eager refresh.
+- Probably redundant in practice, because the same code path also updates `visibleSegments` and bumps `layer.spatialSkeletonNodeDataVersion`, and both already have refresh listeners below.
+
+### 2. `layer.displayState.segmentSelectionState.changed`
+
+Why it is called today:
+
+- Most likely defensive: segment selection changes often happen while the user is interacting with the Seg tab.
+
+Assessment:
+
+- This does not look required by the current code.
+- `refreshNodes()` does not read `segmentSelectionState`.
+- If only the selected segment changes while the visible segment set stays the same, the node list inputs have not changed.
+
+### 3. `segmentationGroupState.visibleSegments.changed`
+
+Why it is called:
+
+- This is a direct dependency.
+- `refreshNodes()` derives `activeSegmentIds` from the visible segment set, so adding or removing visible skeletons must rebuild the node list.
+
+Assessment:
+
+- Required.
+
+### 4. `segmentationGroupState.temporaryVisibleSegments.changed`
+
+Why it is called:
+
+- Merge/split previews can populate the temporary visible segment set.
+- When the tab is currently using the temporary set, those preview edits change which skeletons should be shown.
+
+Assessment:
+
+- Required for preview mode correctness.
+
+### 5. `segmentationGroupState.useTemporaryVisibleSegments.changed`
+
+Why it is called:
+
+- `getVisibleSegments(...)` switches between the normal and temporary visible sets based on this flag.
+- Flipping the flag changes the source of truth for `activeSegmentIds` even if neither set changed contents.
+
+Assessment:
+
+- Required.
+
+### 6. `layer.layersChanged`
+
+Why it is called:
+
+- `refreshNodes()` resolves the active spatial skeleton render layer on every run.
+- If render layers are rebuilt, added, removed, or swapped, the tab may need a different skeleton layer or CATMAID client.
+
+Assessment:
+
+- Required.
+
+### 7. `layer.manager.chunkManager.layerChunkStatisticsUpdated`
+
+Why it is called today:
+
+- Probably to keep the tab in sync with spatial skeleton loading progress.
+
+Assessment:
+
+- `updateGateStatus()` is definitely needed here because action availability depends on chunk loading.
+- The `refreshNodes()` part does not look required by the current implementation.
+- `refreshNodes()` does not consume chunk statistics directly; it fetches full skeletons from CATMAID based on visible segments.
+- This looks like defensive overlap or a holdover from an older "loaded nodes" model.
+
+### 8. `layer.displayState.spatialSkeletonGridLevel2d.changed`
+
+Why it is called today:
+
+- Likely meant to react when the user changes the skeleton grid resolution used by the render layers.
+
+Assessment:
+
+- Not a direct dependency of `refreshNodes()`.
+- Grid level changes do affect edit eligibility and chunk loading, but those are already covered by `spatialSkeletonActionsAllowed`, `layersChanged`, and chunk-stat updates.
+- For the current CATMAID-backed full-skeleton list, this refresh looks likely redundant.
+
+### 9. `layer.displayState.spatialSkeletonGridLevel3d.changed`
+
+Why it is called today:
+
+- Same rationale as the 2D grid-level watcher.
+
+Assessment:
+
+- Same conclusion as above: likely redundant for the current implementation.
+
+### 10. `layer.spatialSkeletonNodeDataVersion.changed`
+
+Why it is called:
+
+- This is the main explicit invalidation channel for real skeleton edits.
+- When the version changes, `refreshNodes()` clears the full-skeleton cache and re-fetches from CATMAID.
+- Other tools rely on this after add, move, merge, and split operations.
+
+Assessment:
+
+- Required.
+- This is the cleanest "the node topology changed" signal in the file.
+
+### 11. Constructor tail: initial `refreshNodes()`
+
+Why it is called:
+
+- The tab needs an initial population pass after wiring observers.
+- Without it, the list would stay empty until some later state change happens.
+
+Assessment:
+
+- Required.
+
+## Practical takeaway
+
+The clearly justified refresh triggers are:
+
+- `visibleSegments.changed`
+- `temporaryVisibleSegments.changed`
+- `useTemporaryVisibleSegments.changed`
+- `layersChanged`
+- `spatialSkeletonNodeDataVersion.changed`
+- the initial constructor call
+
+The calls that currently look redundant or at least weakly justified are:
+
+- `segmentSelectionState.changed`
+- the `refreshNodes()` inside `layerChunkStatisticsUpdated`
+- `spatialSkeletonGridLevel2d.changed`
+- `spatialSkeletonGridLevel3d.changed`
+- the direct refresh after successful delete, because that path already triggers other refresh signals
+
+If we want to reduce refresh churn safely, those are the first places to verify with tests or manual UI checks.

docs/user-guide/skeleton_editing.rst

@@ -0,0 +1,190 @@
+Skeleton Editing
+================
+
+Neuroglancer supports interactive editing of skeleton annotations, including
+adding, moving, and deleting nodes, as well as merging and splitting skeletons.
+
+.. _skeleton-editing-sources:
+
+Supported Sources
+-----------------
+
+Skeleton editing is currently only supported on CATMAID data sources. See the
+CATMAID documentation to set up a CATMAID server. At minimum you will need:
+
+- A CATMAID project
+- A linked project stack
+- ``AnonymousUser`` permissions to read and edit the data on that project
+- Skeletons initialised for that project
+
+The project stack dimensions and resolution are used to inform the bounding box
+of the data in neuroglancer as their product. Skeletons in CATMAID are in 1 nm
+units. Optionally, you can also configure stack metadata, which is intended to be used alongside the CATMAID multiple-LOD cache
+grid for faster fetches of spatially indexed skeletons. The stack metadata can specify the key ``spatial_skeleton_chunk_sizes`` to define the chunk sizes at each LOD level in neuroglancer in nm. These chunk sizes are not required to be the same as the CATMAID LOD cache grid chunk sizes, and chunks are not required to have an exact match in the cache. Neuroglancer will always request to CATMAID to provide nodes from a cache if present. In addition, neuroglancer will request chunks at:
+
+.. math::
+
+   \mathrm{lod}\!\left(\frac{k}{n - 1}\right)
+
+in CATMAID, where :math:`k` is the LOD index level in neuroglancer, and :math:`n` is the number of LOD levels.
+
+After setting this up, enter ``catmaid:<your-catmaid-server-url>/<your-catmaid-project-id>`` as a data source in neuroglancer.
+
+.. _skeleton-editing-subsources:
+
+Layer Subsources
+----------------
+
+The data source exposes two skeleton subsources. The first is a spatially indexed
+skeleton source, which is required for editing. The second is the regular skeleton
+subsource from the pre-existing pipeline for rendering precomputed format skeletons.
+
+In the **Render** tab you can adjust:
+
+- **Opacity (3d)** — controls the opacity of fully loaded, visible skeletons.
+- **Hidden Opacity (3d)** — controls the opacity of hidden skeletons, which represent
+  LOD-influenced spatial indicators of nodes in space.
+
+When you make a skeleton visible, a full fetch is triggered and you are guaranteed
+to see all nodes and details of that skeleton. Otherwise you see whatever is
+provided by the LOD spatial information. The selected LOD is controllable via the
+**Resoltion (skeleton grid 2D)** and **Resolution (skeleton grid 3D)** resolution settings.
+
+The **Seg** tab works as normal for a segmentation layer, allowing you to set the
+visibility of segments/skeletons by their ID or by label if one has been assigned.
+
+.. _skeleton-editing-tab:
+
+Skeleton Tab
+------------
+
+The **Skeleton** tab is used for editing and viewing information about skeletons.
+It is only available for CATMAID sources with an active spatially indexed skeleton
+subsource, and only visible skeletons appear here.
+
+You can find a node by ID or by description, and filter nodes to show only:
+
+- Leaves
+- Virtual ends
+- True ends
+- Nodes with descriptions
+
+You can also pick a subset of the visible skeletons to display information about in this menu.
+
+Skeleton Navigation
+~~~~~~~~~~~~~~~~~~~
+
+The skeleton tab provides buttons for navigating through the skeleton tree:
+
+- Go to the root
+- Go to the start of the current branch
+- Go to the end of the current branch
+- Cycle through nodes at the current level
+- Go to the parent or child of the current node (if there are multiple children,
+  one is chosen at random)
+- Go to the nearest node that is a leaf but not marked as a true end
+
+You can also interact with nodes in the details viewer by right-clicking to move
+to a node, or left-clicking to select it and move to it.
+
+.. _skeleton-node-types:
+
+Node Types
+----------
+
+Nodes use symbols to indicate their type:
+
+- **Root** — the root node of the skeleton
+- **Regular node** — an interior node along a branch
+- **Branch point** — a node with more than one child
+- **Virtual end** — a leaf node that has not been marked as a true end
+- **True end** — a leaf node manually marked by a reviewer as the end of a branch
+
+You can toggle a node between virtual end and true end by clicking its type icon
+in the skeleton tab table. This only applies to visible segments.
+
+.. _skeleton-node-properties:
+
+Node Properties
+---------------
+
+To edit the detailed properties of a node, first make the segment visible, then
+select the node by either:
+
+- Right-clicking on it in the viewer while holding :kbd:`Control`
+- Left-clicking on it in the skeleton tab table
+
+Once a node is selected, you can:
+
+- Delete the node *
+- Change the node type *
+- Make the node the root of the skeleton *
+- Change the radius
+- Change the confidence level
+- Add or edit a free-text description
+
+.. note::
+   * These actions can also be performed from the skeleton tab table.
+
+.. _skeleton-editing-tools:
+
+Editing Tools
+-------------
+
+To make structural edits to nodes, you must bind at least some of the editing
+tools available in the skeleton tab. The available tools are **Edit**, **Merge**,
+and **Split**.
+
+To bind a tool, click on it in the UI and hold down a key. To activate the tool,
+press :kbd:`Shift` + the bound key. For example, if you bind :kbd:`E` to the Edit
+tool, pressing :kbd:`Shift+E` activates it.
+
+An important concept throughout editing is the *selected node*. The selected node
+is highlighted with a border in the viewer, highlighted in the skeleton tab table,
+and its details are shown in the selection details panel.
+
+Edit Tool
+~~~~~~~~~
+
+With the Edit tool active:
+
+- **Move a node** — select the node, then hold :kbd:`Alt` and left-click and drag
+  it to the new location. This does not use picking to snap to nearby objects.
+- **Add a child node** — select an existing node, then :kbd:`Control`-click where
+  you want to place the new node. The new node is added as a child of the selected
+  node.
+- **Start a new skeleton** — :kbd:`Control`-click with no node selected to add a
+  root node with no parent.
+
+Merge Tool
+~~~~~~~~~~
+
+With the Merge tool active, select the "from" node first and then the "to" node. You must merge from a visible skeleton, but the "to" node may belong to a non-visible skeleton.
+The surviving skeleton ID will be the ID of the skeleton containing the "from"
+node. The only exception to this is if the CATMAID skeleton has annotations, and one of the skeletons is annotated as ``stable`` -- in this case, the surviving skeleton ID is from the one that was annotated as ``stable``. It is not currently possible to set these annotations within neuroglancer.
+
+Split Tool
+~~~~~~~~~~
+
+With the Split tool active, select the node at which to split. The selected node
+is included in the newly created skeleton, not the surviving original skeleton.
+The edge between the selected node and its parent is deleted, and the selected
+node becomes the root of the new skeleton. A split always produces exactly two
+skeletons, regardless of whether the selected node is a branch point or a leaf.
+You can only split visible skeletons.
+
+.. _skeleton-editing-undo:
+
+Undo and Redo
+-------------
+
+The skeleton tab provides **Undo** and **Redo** buttons. When any operation is
+performed, its inverse is stored in the history. Note that the inverse of an
+atomic operation is not necessarily atomic: for example, undoing a merge involves
+a split followed by a reroot. Without the reroot step, the split skeleton could
+end up with a different root than it had before the merge.
+
+Undo does not restore the skeleton ID to its pre-operation value, so a merge
+followed by an undo will result in one of the skeletons having a new ID compared
+to before the merge (specifically, the skeleton that did not "survive" the
+original merge).

package.json

@@ -140,6 +140,12 @@
       "neuroglancer/datasource/boss:disabled": "./src/util/false.ts",
       "default": "./src/datasource/boss/backend.ts"
     },
+    "#datasource/catmaid/backend": {
+      "default": "./src/datasource/catmaid/backend.ts"
+    },
+    "#datasource/catmaid/register_default": {
+      "default": "./src/datasource/catmaid/register_default.ts"
+    },
     "#datasource/boss/async_computation": {
       "neuroglancer/datasource/boss:enabled": "./src/datasource/boss/async_computation.ts",
       "neuroglancer/datasource:none_by_default": "./src/util/false.ts",
@@ -534,4 +540,4 @@
       "default": "./src/util/false.ts"
     }
   }
-}
+}