Add a button to facilitate sharing of downscaled registered projects, for the sake of building automated registration models

[NicoKiaru]

It would be nice to have a simple button that would generate a small zip containing all the information required in the optics of training a an automated registration model.

What I image is the following:

• all images downscaled to 10 micron resolution
• unregistered original image data (2D only)
• resampled registered image data to 10 um
• selection by the user of a subset of channels to avoid sharing irrelevant data for the registration
• atlas name
• generation date
• user description
• user contact
• lab contact
• data share agreement (potentially delegated to Zenodo)
• one or several hash to avoid duplicates
• registration info:
  • atlas slicing angle
  • affine registration
  • spline registration (optional)

Potentially follow quicknii +visualign format

Where to share these data easily ? Zenodo looks like a good fit, a community could be created to collect all of these

[NicoKiaru]

Hi @carlocastoldi and @PolarBean,

I've made some good progress on this functionality in this branch.

Here's how an exported brain looks like at the moment:

https://drive.google.com/file/d/1__cGVXg8l1x93kCTYrbTR6hVHTwH9Vi2/view?usp=sharing

The metadata looks like this:

{
  "version": "0.10.8-SNAPSHOT",
  "experiment_information": "dataset original url:\nhttps://zenodo.org/records/14918378\nfirst channel: DAPI\nsecond channel: Autofluorescence",
  "atlas_name": "allen_mouse_10um_java",
  "timestamp": "2025-09-24T14:16:50.220Z",
  "resolution_um": 10.0,
  "n_slices": 25,
  "downscale_deformation_field": 4,
  "x_axis": "RL (Right-Left)",
  "y_axis": "SI (Superior-Inferior)",
  "z_axis": "AP (Anterior-Posterior)"
}

And all slices are exported resampled to 10 micrometers + a map of the registered atlas coordinates of each pixel of the original image (float 32 bits 3 channels for xyz) is saved. The coordinates map is downsampled 4 times because it is heavy in memory, and we expect a smooth transform so that should not be a big issue.

An abba state file is also there in order to re-open the registration completely in ABBA, but I think it's not strictly necessary given that the transform is already exported.

It's still an early idea. What do you think ? Are there some obvious things missing ? I have no plans for where to store these dataset, and I don't know if/how people will accept to share them.

[PolarBean]

This seems great. Nothing obvious missing in my opinion.
I think minimally what you would need is

• the coordinates of the four corners of the image in atlas space (prior to deformation).
• A deformation matrix (either image to atlas space or vice cersa, they are reversible so it shouldn't be a problem). I think you can also apply lossless compression to this if it's saved as something like nii.gz.
• 10 micron resolution images of the original images prior to any registration

The coordinates for each pixel is nice but can be computed from the above 3 so is not strictly necessary.

I think this is a really good step. In the future we should think about something like BIDS which defines the structure spatial histology datasets. Ideally this would contain point clouds, etc. This is of course a long way off just a thought.

[NicoKiaru]

Hi Harry, thanks for your input!

By deformation matrix do you mean a 3D matrix transform ?

The thing is that ABBA outputs spline transforms, so you can't encode that in a single matrix.

Here's how they look like using a sinus LUT for 2 coordinates:

[carlocastoldi]

Hi! I think that's a great direction towards a standard.
Perhaps some talks with other atlas registration software might be favourable. This would help in noticing clear shortcomings of the format while easing its adoption, with the ultimate goal to create generic registration datasets.
I am thinking of people like @alessandrofelder or @IgorTatarnikov from https://github.com/brainglobe/brainreg (I hope not to bother excessively, by summoning you like this)

Two small thing that I'd think of would be to:

• add metadata about each channel in the image
• put the downsampled images and the deformation field in two separate folders (e.g. original and deformation_field), each containing files with the same name
• consider using HDF5 file format?

[NicoKiaru]

add metadata about each channel in the image

You're right, I wasn't sure how strictly to enforce this requirement. In theory, ABBA allows slices with different numbers of channels or different channel types. This isn't ideal from a standardization perspective, but ABBA provides this flexibility, and enforcing identical channel counts across all slices would add some complexity.

I was thinking we could use a relatively open string metadata field with some basic guidelines (like "describe each channel"), then leverage LLM capabilities to classify datasets based on the user metadata descriptions.

Just an early thought. This could very well be a bad approach.

[carlocastoldi]

Mmh I think I'd prefer to have a format that is as tool-agnostic as possible.
Would it be a good alternative to export each image channel separately and enforce the user to give basic information about each channel, if not available from the original image metadata? Something like what (e.g. DAPI or cFos) and where (e.g. 488nm)

[PolarBean]

By deformation matrix I'm referring to a 2D deformation matrix which transforms a given section to a target atlas slice. This atlas slice would be defined by the XYZ position of each corner in atlas space.

perhaps also the atlas name in the metadata should ideally correspond to an atlas in the brainglobe api (the _java suffix here may cause confusion).

@adamltyson and @Tevemadar may also be interested in this

[PolarBean]

can a spline not be encoded in a 2D matrix which says for each pixel how much it should be displaced? This is the output of many registration tools such as elastix and Ants

[PolarBean]

I should of course spruik openminds here as it is a metadata standard designed to capture many of things we are discussing. It could either be used directly or serve as inspiration. It has an extension called ATOM which is designed specifically for capturing atlas related metadata. Maybe this is useful

[NicoKiaru]

(the _java suffix here may cause confusion)

Yep! That's for historical reasons because brainglobe did not exists at the start of ABBA. Besides brainglobe does not support multiresolution (yet?) and that makes the software more hungry for resource when using a brainglobe atlas vs its equivalent in java. However I do not plan to add more atlases on the Java side, so the number of names not matching brainglobe atlases will remain limited (even though now I release that the version of the atlas should also be written.

I can't remove the java atlases - for backward compatibility - and also because making python work with java does not work on mac osx, so that would let mac users without any atlas.

can a spline not be encoded in a 2D matrix which says for each pixel how much it should be displaced?

Ah, sorry, I think it could be my misunderstanding because I thought matrix meant a linear 3x3 matrix (+3 args for translation) - setting the transform of unit vectors into another space, thus supporting affine transform only.

But now I understand that you mean matrix in a more general sense, like an array.

If I understand correctly, what you suggest is to split the transform into first, an affine matrix that maps the image coordinates to an atlas slice, and then second, non-linear corrections (displacement matrix) within the atlas section ?

[PolarBean]

If I understand correctly, what you suggest is to split the transform into first, an affine matrix that maps the image coordinates to an atlas slice, and then second, non-linear corrections (displacement matrix) within the atlas section ?

Yes exactly! the two things we need to know are

• What plane in the atlas does the slice correspond
• what non linear deformation must be applied to the section

[NicoKiaru]

Ok, I think that can probably be extracted simply the raster position field. One advantage of exporting the field is that it's already using built-in functions from ABBA so I do not have to rewrite anything. Another point, even if it's not used right now, is that no change is required if you want to encode out of plane deformations, like bending. If you want to allow for this in the non linear deformation field, this would mean including a z coordinate deformation as well.