xiao-1011/dmc-brainmap-registration-predictor

DMC-BrainMap Registration Predictor

A convolutional model that proposes an initial projective alignment between a mouse histological section and its corresponding Allen Mouse Brain Atlas reference slice. The model is designed for the prediction-assisted registration workflow in DMC-BrainMap.

The verified v1.0.0 checkpoint is published as dmc-brainmap-registration-predictor-v1.0.0.pt. It is an inference-only checkpoint containing model_config and model_state_dict, and it supports safe loading with torch.load(..., weights_only=True).

Model details

Property	Value
Model version	v1.0.0
Model type	Pairwise 2D projective-registration regressor
Architecture	PairSpatialHomographyNet
Parameters	2,336,200
Framework	PyTorch
Supported atlas	Allen Mouse Brain Atlas 10 um, BrainGlobe version 1.2
Validated input size	1140 x 800 pixels (width x height)
Developed by	Xiao Cao
License	BSD-3-Clause

Training and model code are maintained in xiao-1011/sharpy-model. The v1.0.0 release is tied to source commit 0a80f4f and training run baseline-005-spatial-augmented-200ep.

Intended use

The model provides an initial registration suggestion inside DMC-BrainMap:

1. the user selects the appropriate atlas slice;
2. the model predicts a sample-to-atlas projective transformation;
3. DMC-BrainMap displays a preview of the alignment; and
4. the user reviews, accepts, or corrects the suggested registration points.

The prediction is an initialization aid, not a final registration or a replacement for visual quality control. It is not intended for clinical diagnosis, treatment decisions, or unattended quantitative analysis.

Model interface

Inputs

Name	Meaning	Shape	Type and range
sample	Green-channel epifluorescence image of a histological section	[batch, 1, 800, 1140]	float32, [0, 1]
reference	Corresponding grayscale atlas reference slice	[batch, 1, 800, 1140]	float32, [0, 1]

DMC-BrainMap converts image arrays to grayscale when required, divides pixel values by 255, and converts them to channels-first tensors. Although the network uses adaptive pooling, only 1140 x 800 pixel inputs have been trained and evaluated.

Output

The model returns [batch, 4, 2] sample-to-reference corner offsets in pixels. The corner order is:

1. top left;
2. top right;
3. bottom right; and
4. bottom left.

Offsets are bounded to +/-512 pixels with tanh. DMC-BrainMap converts the four displaced corners into a 3 x 3 projective homography and then into five editable registration-point pairs.

Architecture

The sample and reference tensors are concatenated into a two-channel input. Five convolution blocks each use a 3 x 3 stride-2 convolution, batch normalization, and ReLU:

2 -> 24 -> 48 -> 96 -> 96 -> 192 channels

The resulting feature map is adaptively pooled to 5 x 8, flattened, and passed through the regression head:

7680 -> 256 -> 256 -> 8

The eight outputs are reshaped into four (x, y) corner offsets. Exact machine-readable settings are provided in config.json.

Training data

The dataset contains 5,613 registered sections from 87 adult C57BL/6J mice of both sexes. Sections were imaged using epifluorescence microscopy in the green channel (EGFP spectral range). Reference slices were generated from the Allen Mouse Brain Atlas 10 um, BrainGlobe version 1.2.

Target registrations were created with SHARPy-track inside DMC-BrainMap and reviewed by Felix Jung, Xiao Cao, and Loran Heymans. Mean target registration error below 4 pixels (approximately 40 um at the atlas resolution) was considered acceptable. Projective fits with landmark-fit RMSE above 60 pixels were excluded, removing 296 candidate sections.

The split was performed by animal, so no animal appears in more than one split:

Split	Animals	Sections
Training	61	4,015
Validation	13	745
Test	13	853

The split used seed 42 with nominal 70%/15%/15% folder-level allocation.

The training images are owned by the DMC-BrainMap group but are unpublished and are not distributed with this model. Users can adapt the public training code to fine-tune the model with their own appropriately licensed paired images and registrations.

Training procedure

• Maximum epochs: 200; early stopping occurred after epoch 111.
• Selected checkpoint: epoch 91, chosen by validation composite loss.
• Batch size: 4.
• Optimizer: AdamW, learning rate 1e-4, weight decay 1e-4.
• Scheduler: ReduceLROnPlateau, factor 0.5, patience 6, minimum learning rate 5e-7.
• Early stopping: patience 20 and minimum improvement 0.03.
• Seed: 42.
• Hardware: NVIDIA GeForce RTX 3070 Ti.
• Software environment: Python 3.14, PyTorch 2.12.0 with CUDA 13.0.

The training-curve figure annotates the lowest validation mean reprojection error, reached at epoch 111. The released checkpoint is epoch 91 because validation composite loss, rather than mean reprojection error, was the configured selection metric.

The primary objective is Smooth L1 reprojection loss over an 8 x 8 grid sampled within the non-black tissue bounding box, inset by 2%. A second Smooth L1 loss on the four projected image corners is included with weight 0.25.

Training-only moderate damage augmentation simulates missing tissue, tears, cracks, folds, exposure changes, brightness and contrast variation, gamma variation, and image noise. The full settings are recorded in training/training_config.json.

Evaluation

The selected checkpoint was evaluated once on the held-out test split of 853 sections from 13 animals. Errors compare the predicted projective transform with the quality-controlled target transform on an 8 x 8 grid inside the non-black tissue bounding box.

Test metric	Pixels	Approximate atlas distance
Mean point error	18.964	189.6 um
Median point error	14.211	142.1 um
95th percentile point error	49.035	490.3 um
Maximum point error	552.370	5.52 mm
Mean corner error per image	37.983	379.8 um

Pixel-to-distance values use the 10 um atlas resolution and are provided only as scale approximations. See evaluation/test_summary.json for the full aggregate results.

Limitations

• The model was trained and evaluated only on adult C57BL/6J mouse sections imaged in the green/EGFP-range epifluorescence channel.
• Only Allen Mouse Brain Atlas 10 um version 1.2 reference slices are supported.
• The training and test images originate from the same overall data-creation workflow, although animals are separated across splits.
• Performance may degrade for other strains, developmental stages, staining protocols, microscopes, channels, atlases, image sizes, or tissue preparation methods.
• Damaged or incomplete sections, unusual contrast, acquisition artifacts, or selection of the wrong atlas slice may produce poor predictions.
• The large maximum test error shows that individual predictions can fail substantially. Every prediction must be reviewed before use.
• Evaluation measures agreement with fitted, manually reviewed target registrations; it is not an independent biological ground truth.

The model's approximately 19-pixel mean test error should not be confused with the less-than-4-pixel mean TRE acceptance criterion applied to the manually reviewed target registrations. The model output is intended to initialize the subsequent reviewed registration.

Using the model with DMC-BrainMap

To use the released checkpoint:

1. Download dmc-brainmap-registration-predictor-v1.0.0.pt from Files and versions.
2. Start DMC-BrainMap in napari.
3. Open the registration widget and select Browse Model.
4. Select the downloaded checkpoint and start the registration GUI.
5. Use Predict to preview the alignment.
6. Inspect and, when needed, correct the suggested registration points before saving.

The versioned artifact can also be downloaded programmatically:

from huggingface_hub import hf_hub_download

checkpoint_path = hf_hub_download(
    repo_id="xiao-1011/dmc-brainmap-registration-predictor",
    filename="dmc-brainmap-registration-predictor-v1.0.0.pt",
    revision="v1.0.0",
)

Release artifact SHA-256: f24893d0a5d335ccfee2c354245cfefef935424f0d7c8010e9efbc0560496d18

Reproducibility files

• config.json: inference interface and model architecture.
• training/training_config.json: dataset, optimization, loss, augmentation, and provenance settings.
• training/history.jsonl: per-epoch aggregate training and validation history.
• training/epoch_curves.png: training curves.
• evaluation/test_summary.json: aggregate held-out test metrics.

Per-image metrics, manifests, and unpublished images are intentionally not distributed.

License

The model repository and released weights are licensed under the BSD 3-Clause License. This license does not grant rights to the unpublished training images or modify the terms of the Allen Mouse Brain Atlas and other third-party resources.

Copyright (c) 2026, DMC-BrainMap developers.

Citation

If this model or DMC-BrainMap contributes to scientific work, please cite:

Jung, F., Cao, X., Heymans, L., & Carlén, M. (2026). DMC-BrainMap is an open-source, end-to-end tool for multi-feature brain mapping in different species. Cell Reports Methods, 6(2), 101302. https://doi.org/10.1016/j.crmeth.2026.101302

Acknowledgment

Developed by Xiao Cao with assistance from OpenAI GPT-5.5.

Links

• DMC-BrainMap source code
• DMC-BrainMap documentation
• Training and model code
• Issues and support