feat: Add catmaid spatially indexed skeletons

[afonsobspinto]

Summary

Adds a new CATMAID datasource for reading and writing skeletons in neuroglancer. These skeletons are a new kind of skeleton, a spatially indexed skeleton source. For rendering these skeletons, on each render frame we first draw a "browse" pass, followed by an "overlay" pass.

The browse pass is designed to provide lightweight skeleton context to the user without requiring full skeleton fetches. Data is retrieved in spatial chunks, where each chunk contains nodes within that AABB and direct children/parent nodes of edges intersection the edges of the AABB. The renderer performs fragment discarding to avoid duplicate rendering. Skeletons that will be rendered in the overlay are discarded during the browse pass. Below is an example browse pass result, with each chunk rendering in its own color:

The overlay pass renders complete skeletons on top of the browse data. A skeleton enters the overlay when it becomes visible in Neuroglancer, which signals the client to fetch the full skeleton. A fetched skeleton enables tree traversal in the "skeleton" tab, and rendering the complete skeleton independent of browse chunk coverage. Below is an example from the overlay in red, with the browse in gray, the side tab shows the skeleton traversal options:

Editing

Edits are supported for visible skeletons present in the overlay pass. Editing includes client-side undo/redo support and edit state synchronisation with CATMAID to detect conflicting multi-user edits. Edit actions include moving nodes, deleting nodes, adding nodes, merging skeletons, splitting skeletons, rerooting skeletons, and some property modifications on nodes (changing radius, confidence, description, and if the node is the true end of a branch or needs to be continued).

When an edit is made:

1. A request is sent to CATMAID
2. The client waits for the response
3. The updated skeleton state is rendered in the overlay pass
4. Spatial chunks affected by the change are invalidated

Trying this out

We have some documentation in the new user guides about setting up a CATMAID project for neuroglancer and using it as a data source. However, the easiest path if you want to serve something locally to try it is likely to follow the CATMAID docker guides.

Known issues

1. New changes only work with uint32 segment IDs and node IDs, needs to change to expand to the full range of seg IDs (uint64) and change node IDs to be uint64.
2. The overlay skeleton memory management needs to be updated, the memory is capped, but not disposed. And does not recognise the layer source changing so can show you stale skeleton information if you change the catmaid source on a segmentation layer.
3. If the skeleton itself is yellow-ish, then it is hard to see the current node highlight as that is fixed color yellow.
4. The spatial index cache in CATMAID can take time to update, and we don't know when it is ready. This means that when we invalidate chunks affected by edits, the fetch might still be getting old data.
5. The cursor position can lag behind the node position slightly when moving or adding nodes.
6. When working with transparent skeletons and transparent image rendering, it can get very difficult to pick the nodes from the skeleton for any edits.
7. Starting from a blank CATMAID project with skeletons setup but no treenodes, adding the first node in neuroglancer causes neuroglancer to hang. On refresh, the node is usually there and can continue from that point.
8. Nodes in visible skeletons highlight when hovering them. But nodes from non-visible skeletons in the browse pass do not highlight on hover.
9. Spatial skeletons do not adhere to the "spatial object selection" flag on segmentation layers.

Plans

Outside of working on the known issues, we have ideas for the below:

Features

1. Allow a soft delete of full skeletons or subtrees (subtree delete would be a split followed by a soft delete)
2. Change the spatial skeleton grid resolution to be instead be spatial skeleton resolution in pixels, and also inherit the "zoom-relative" setting from neuroglancer panels.
3. Maybe - show optimistic preview of edit action to user instead of waiting on request.
4. Maybe - store last active node/last active position on skeletons so that you can snap back to that position easily.
5. Maybe - the skeleton traversal only shows a collapsed view of the skeleton, so root, branch points, and leaves. In between these nodes, the skeleton traversal tab could provide information like - on node 3/20 on this branch or similar.
6. Maybe - allowing setting radius at the skeleton level, not node level.
7. Maybe - not specific to this PR, but could introduce better skeleton rendering. Such as a cylinder and ball mode, more control over the skeleton via an API for radius and radius clipping etc.

Planned changes and refactorings

1. Extract the general picking fixes from this PR as a separate one to help reviewing, and hopefully get those fixes in faster.
2. Remove the regular skeleton source from CATMAID. While this has some use, a very similar behaviour can be found by making non-visible skeletons completely transparent. So it's not worth the maintenance burden.
3. Update attribute handling in skeleton/frontend.ts once we fix the uint64 seg ID support.
4. Add integration tests which spin up CATMAID with lightweight data.
5. A bit more improvement on types. In some cases in the interest of moving quickly/prototyping our typing is a bit loose.
6. Remove LOD from the general skeleton interface. CATMAID has a version of LOD which is a bit different to neuroglancer. We've cleaned this up a bit in the API for CATMAID, and the generic neuroglancer skeleton/api.ts but some leftovers of this remain which we want to remove.

Acknowledgements

This feature was developed collaboratively with @seankmartin , who contributed heavily to the editing model, renderer behaviour, and CATMAID integration design.

[chrisj]

seems like we either need to squash some commits or have Jeremy manually approve the CLA