brainglobe-registration

Registration to a BrainGlobe atlas using Elastix

---

Warning

This tool is in very early development. The interface may change and some features are not yet available.

A napari plugin for registering images to a BrainGlobe atlas.

Usage

1. Open napari.
2. Install the plugin if you haven't already.
3. Install an atlas if you haven't already (required before using the plugin).
4. Open the widget by selecting Plugins > BrainGlobe Registration in the napari menu bar near the top left of the window. The BrainGlobe Registration plugin will appear on the right hand side of the napari window.
5. Open the image you want to register in napari (a sample 2D image can be found by selecting File > Open Sample > Sample Brain Slice).
6. Select the atlas you want to register to from the dropdown menu. The atlas will appear in the napari viewer. Select the approximate Z slice of the atlas that you want to register to, using the slider at the bottom of the napari viewer.
7. Adjust the sample image to roughly match the atlas image. You can do this by adjusting X and Y translation as well as rotating around the centre of the image. You can overlay the two images by toggling Grid mode in the napari viewer (Ctrl+G). You can then adjust the color map and opacity of the atlas image to make manual alignment easier. The sample image can be reset to its original position and orientation by clicking Reset Image in the BrainGlobe Registration plugin window.
8. Select the transformations you want to use from the dropdown menu. Set the transformation type to empty to remove a step. Select from one of the three provided default parameter sets (elastix, ARA, or IBL). Customise the parameters further in the Parameters tab.
9. Click Run to register the image. The registered image will appear in the napari viewer.

Installation

We strongly recommend to use a virtual environment manager (like conda or venv). The installation instructions below will not specify the Qt backend for napari, and you will therefore need to install that separately. Please see the napari installation instructions for further advice on this.

Installing the Plugin

You can install brainglobe-registration via pip:

pip install brainglobe-registration

or via the napari interface:

1. Open napari
2. Go to Plugins > Install/Uninstall Plugins...
3. Search for brainglobe-registration
4. Click Install

For detailed instructions on finding and installing plugins in napari, see the napari plugin installation guide.

To install the latest development version:

pip install git+https://github.com/brainglobe/brainglobe-registration.git

Installing an Atlas

Important: Before you can use the plugin, you must download at least one BrainGlobe atlas. The plugin requires an atlas to be installed on your system.

Option 1: GUI Installation

You can install atlases through the napari interface using the brainrender-napari plugin. For detailed instructions, see the BrainGlobe atlas management tutorial.

Option 2: Command Line Installation (CLI)

You can also install an atlas using the brainglobe command-line tool. For example, to install the Allen Mouse Brain Atlas at 25μm resolution:

brainglobe install -a allen_mouse_25um

To see all available atlases, run:

brainglobe list

License

Distributed under the terms of the BSD-3 license, "brainglobe-registration" is free and open source software

Seeking help or contributing

We are always happy to help users of our tools, and welcome any contributions. If you would like to get in contact with us for any reason, please see the contact page of our website.

Citation

If you find this package useful, and use it in your research, please cite the following:

Igor Tatarnikov, Alessandro Felder, Kimberly Meechan, & Adam Tyson. (2025). brainglobe/brainglobe-registration. Zenodo. https://doi.org/10.5281/zenodo.14750325

Acknowledgements

This napari plugin was generated with Cookiecutter using @napari's cookiecutter-napari-plugin template.