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/user-guide/skeleton_editing.rst

@@ -0,0 +1,218 @@
+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.
+
+The linked CATMAID stack may define spatial skeleton metadata. When present,
+Neuroglancer uses this metadata to build the spatially indexed skeleton source
+required for editing. Add a ``spatial`` array to the stack metadata, with one
+entry for each spatial index level:
+
+.. code-block:: json
+
+   {
+     "spatial": [
+       {
+         "chunk_size": [11168145, 11168145, 11168145],
+         "limit": 500
+       },
+       {
+         "chunk_size": [3939000, 3939000, 3939000],
+         "limit": 7000
+       }
+     ],
+     "cache_provider": "cached_msgpack_grid",
+     "read_only": false
+   }
+
+``chunk_size`` is specified in CATMAID project-space nanometers. ``limit`` is
+the maximum node count expected for that spatial level and is required.
+``cache_provider`` is optional and, when present, is passed to CATMAID node-list
+requests. If ``read_only`` is not set to ``false``, Neuroglancer treats the
+source as read-only: skeletons can be inspected, but edit actions are disabled.
+
+If ``spatial`` is absent or empty, Neuroglancer derives a default chunk size
+from the CATMAID project-space bounds and uses ``limit: 0`` for the generated
+spatial level.
+
+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
+  spatially indexed 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 spatial index level selected for the current view. The selected
+grid size is controlled via the **Resolution (skeleton grid 2D)** and
+**Resolution (skeleton grid 3D)** 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. If the CATMAID stack metadata
+does not set ``read_only`` to ``false``, inspection remains available but edit
+actions are disabled.
+
+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

@@ -141,6 +141,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",
@@ -535,4 +541,4 @@
       "default": "./src/util/false.ts"
     }
   }
-}
+}

python/examples/example_spatial_skeletons.py

@@ -0,0 +1,61 @@
+import argparse
+
+import neuroglancer
+import neuroglancer.cli
+import numpy as np
+
+voxel_size = np.array([10, 10, 10])
+
+shape = (100, 100, 100)
+
+segmentation = np.arange(np.prod(shape), dtype=np.uint32).reshape(shape)
+
+viewer = neuroglancer.Viewer()
+dimensions = neuroglancer.CoordinateSpace(
+    names=["x", "y", "z"],
+    units="nm",
+    scales=[10, 10, 10],
+)
+with viewer.txn() as s:
+    s.layers.append(
+        name="a",
+        layer=neuroglancer.SegmentationLayer(
+            source=[
+                neuroglancer.LocalVolume(
+                    data=segmentation,
+                    dimensions=dimensions,
+                ),  # example of segmentation that could accompany the skeleton
+                "catmaid://http://localhost:8000/4",  # replace with your catmaid URL/project ID
+            ],
+            tab="skeleton",
+        ),
+    )
+    # Can adjust the skeleton rendering options
+    s.layers[0].skeleton_rendering.mode2d = "lines"
+    s.layers[0].skeleton_rendering.line_width2d = 3
+    s.layers[0].skeleton_rendering.mode3d = "lines_and_points"
+    s.layers[0].skeleton_rendering.line_width3d = 10
+
+    # Can adjust visibility of layer side panel
+    s.selected_layer.layer = "a"
+    s.selected_layer.visible = True
+
+    # Can set the new spatial related options
+    layer = s.layers[0]
+    layer.spatial_skeleton_node_query = "1"
+    layer.spatial_skeleton_node_filter = neuroglancer.SpatialSkeletonNodeFilterType.LEAF
+    layer.hidden_object_alpha = 0.8
+    layer.skeleton_cross_section_render_scale = 4.0
+    layer.skeleton_perspective_render_scale = 4.0
+    layer.visible_segments = [649]
+
+    # Can pick a specific segment and node to select
+    selection_for_layers = s.selection.layers
+    selection_for_layers["a"] = {"value": "649", "nodeId": "131"}
+
+if __name__ == "__main__":
+    ap = argparse.ArgumentParser()
+    neuroglancer.cli.add_server_arguments(ap)
+    args = ap.parse_args()
+    neuroglancer.cli.handle_server_arguments(args)
+    print(viewer)

python/neuroglancer/__init__.py

@@ -91,6 +91,7 @@
     InvlerpParameters,  # noqa: F401
     TransferFunctionParameters,  # noqa: F401
     ImageLayer,  # noqa: F401
+    SpatialSkeletonNodeFilterType,  # noqa: F401
     SkeletonRenderingOptions,  # noqa: F401
     StarredSegments,  # noqa: F401
     VisibleSegments,  # noqa: F401

python/neuroglancer/catmaid_credentials.py

@@ -0,0 +1,38 @@
+# @license
+# Copyright 2026 Google Inc.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import json
+import urllib.request
+
+from . import credentials_provider
+from .futures import run_on_new_thread
+
+
+class CatmaidAnonymousCredentialsProvider(credentials_provider.CredentialsProvider):
+    def __init__(self, parameters):
+        super().__init__()
+        self.server_url = (parameters or {}).get("serverUrl", "")
+
+    def get_new(self):
+        server_url = self.server_url
+
+        def func():
+            token_url = f"{server_url}/accounts/anonymous-api-token"
+            with urllib.request.urlopen(token_url) as response:
+                data = json.loads(response.read().decode())
+            if not isinstance(data, dict) or not isinstance(data.get("token"), str):
+                raise RuntimeError(f"Unexpected response from {token_url}: {data!r}")
+            return {"token": data["token"]}
+
+        return run_on_new_thread(func)

python/neuroglancer/credentials_provider.py

@@ -27,7 +27,10 @@ def register(self, key, credentials_provider_getter):
         self._providers[key] = credentials_provider_getter
 
     def get(self, key, parameters):
-        return self._providers[key](parameters)
+        getter = self._providers.get(key)
+        if getter is None:
+            return None
+        return getter(parameters)
 
 
 class CredentialsProvider:

python/neuroglancer/default_credentials_manager.py

@@ -14,6 +14,7 @@
 
 from . import (
     boss_credentials,
+    catmaid_credentials,
     credentials_provider,
     dvid_credentials,
     google_credentials,
@@ -46,6 +47,13 @@
     ),
 )
 
+default_credentials_manager.register(
+    "CATMAID",
+    lambda parameters: catmaid_credentials.CatmaidAnonymousCredentialsProvider(
+        parameters
+    ),
+)
+
 
 def set_boss_token(token):
     """Sets the authentication token for connecting to bossDB.