Feature: example linear registration pipeline

[seankmartin]

Summary

1. Adds a new Python script to the Python examples. This script allows for a number of transformation estimations to help estimate image registration based on points placed in the viewer by the script user.
2. Change to the Python ViewerState to expose the displayDimensions of the Neuroglancer viewer state.
3. Introduces a method for annotations to change the clip weighting of non-display dimensions, the weight for this is stored in the state.

Setup

From the repository main directory:

npm run build-python
python -m pip install .
python -m pip install scipy

Linear registration workflow

The workflow is described in more detail in the docstring in the example file. But in short the most likely use path is as follows:

1. Open neuroglancer as normal and setup layers representing the reference/fixed data and the moving data that you want to align to the fixed data.
2. Copy the url and launch the example script here via python -i example_linear_registration.py --url https://neuroglancer.demo.appspot.com/...
3. Follow the instructions in the new viewer to put fixed data in the left panel, and moving data in the right panel. Then start placing registration points. The affine transform will automatically update when the viewer state updates and the annotation points are different, but debounced.
4. When finished, dump the state for later reference.

In images that might look like this. This image is after placing the fixed and reference layers in the right layer groups:

And then after placing a number of points:

Here is a video of using the tool on the default included demo data, the points placed here could be a bit better, this is moreso to give an idea of the different steps of estimation and actions on pressing the custom functions bound to keys for the workflow:
https://github.com/user-attachments/assets/41f27c77-94d9-452d-9317-8fda9c2c3827

New annotation layer state - clipDimensionsWeight

One problem arose during this script setup. As part of the script we created a second coordinate space. The annotations representing the registration points would contain information for both coordinate spaces. This allowed to conveniently know which points were linked, allow moving to the same spot in the fixed image and moving image quickly, allowing adjusting the points easily etc. There was one issue with this though, which is that the non-display dimension clipping meant that moving in the left panel caused the annotations in the right panel to disappear, and vice versa. Here shows the issue, and the state change proposed to allow changing the default weight on dimensions that are non-display dimensions. Setting that weight to zero means that no clipping happens on the specified dimension when it is a non display dimension.

2026-02-05.12-39-31.mp4

There are a few points to note about this though:

1. We did consider having this instead be on the user defined shader instead, since clipping happens at the shader level. The awkward part about that though is that because for optimization the shader clips early, it means that the shader clipping of annotations runs before the user main runs. As such we'd lose some important optimization, especially if the user shader is heavy. It could instead be a new kind of shader directive like the #uicontrol directive, but unsure if we want to introduce that kind of pattern. Either way, it could be something like #dimweight[0]=0.0 #dimweight[2]=0.5.
2. In the current state, the mapping is done by name. But right now there is not a link setup so that if the user renames a dimension in the viewer then the corresponding name will update in any annotation layer's clipDimensionsWeight. This is definitely a bit undesirable, but considering that I would imagine this state feature is likely only used by advanced users that might be ok. Regardless, thought it would be good to agree on the state representation / overall strategy here before worrying too much about those details.

[Copilot]

Pull request overview

This PR implements a feature to support linear registration workflows with custom clipping behavior for annotation layers across different coordinate spaces. The implementation adds a clipDimensionsWeight property that allows fine-grained control over which dimensions should be clipped during annotation rendering.

Changes:

• Added clipDimensionsWeight tracking and state management across viewer components
• Implemented Python bindings for clip_dimensions_weight in annotation layers and viewer state
• Created a comprehensive example script demonstrating interactive linear registration using point annotations

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/layer_groups_layout.ts	Added clipDimensionsWeight to common viewer state
src/layer_group_viewer.ts	Added clipDimensionsWeight property and type import
src/layer/annotation/index.ts	Added JSON key constant and state management for clipDimensionsWeight
src/data_panel_layout.ts	Added clipDimensionsWeight to ViewerUIState interface and common state
src/annotation/renderlayer.ts	Implemented clip dimension weight application in annotation projection parameters
src/annotation/annotation_layer_state.ts	Created TrackableClipDimensionsWeight class for state management
python/neuroglancer/viewer_state.py	Added Python bindings for clip_dimensions_weight and LinkedDisplayDimensions
python/neuroglancer/init.py	Exported LinkedDisplayDimensions
python/examples/example_linear_registration.py	Added comprehensive linear registration workflow example

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[afonsobspinto]

Clicking 't' right away with the

[afonsobspinto]

The happy flow looks correct to me.
If the user doesn't follow the instructions the script crashes but I don't think that's a problem.

I only tried the demo mode following the video example and it worked similarly 👍