CALHippo Framework - Codebase of the Cellular Annotation Library for the Hippocampus
Important
CALHippo has been accepted at MICCAI 2026! The current preprint version is available here. See the citation below.
This repository contains the official framework associated with the CALHippo dataset. It provides a multiscale workflow that bridges microscopic cell instances and macroscopic brain architecture, enabling the generation of biologically plausible 3D cellular point clouds from BigBrain histological sections.
The framework preprocesses raw high-resolution (HR) (a) and low-resolution (LR) (e) BigBrain slices, segments and classifies HR cells (b), maps the annotations into LR space (c), trains LR density models (d), runs full-slice LR inference (f), and reconstructs 3D point-cloud outputs (g).
Results
Setup
Clone this repo, cd into the repository root and install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh #or if you don't have curl installed: wget -qO- https://astral.sh/uv/install.sh | sh
Then install the dependencies:
Optionally activate the environment:
source .venv/bin/activateor run .py files directly using uv run instead of python.
Pipeline Usage
To reproduce and/or use the pipeline, read the following documents in order:
| Document | Use it for |
|---|---|
| Data setup | Data sources, setup script, folder structure, transform notes |
| Pipeline instructions | Reproducibility path and inference-stage commands after data setup |
| HR/LR coordinate conventions | Coordinate and affine rules for HR to LR mapping |
| HR/LR mapping notebook | Visual/debug reference for HR/LR mapping |
Data Layout
The maintained documentation uses a single configurable <DATA_ROOT> convention.
The canonical tree is specified in Data setup.
Key folders:
- raw inputs live under
<DATA_ROOT>/raw/high_res,<DATA_ROOT>/raw/low_res, and<DATA_ROOT>/raw/masks - preprocessing outputs live under
<DATA_ROOT>/input/all_regionsand<DATA_ROOT>/input/single_regions - optional manually adjusted HR ROI masks can live under
<DATA_ROOT>/input/custom_masks/high_resand be used explicitly during HR single-region extraction - pipeline outputs live under
<DATA_ROOT>/output/segmentation,<DATA_ROOT>/output/classification,<DATA_ROOT>/output/lr_density_dataset,<DATA_ROOT>/output/test_lr_density_gt,<DATA_ROOT>/output/lr_gt_eval,<DATA_ROOT>/output/full_lr_predictions, and<DATA_ROOT>/output/mesoscale_reconstruction - density-estimator training runs live under
<DATA_ROOT>/density_estimator_training - released and trained model artifacts live under
<DATA_ROOT>/models
The maintained LR inference output is
<DATA_ROOT>/output/full_lr_predictions/allCA_best_model_128_96_smooth_b05_k5_roi.
Point-cloud reconstruction consumes a prediction folder such as
<DATA_ROOT>/output/full_lr_predictions/<PREDICTIONS_NAME> plus LR bbox JSONs and
raw LR MINC files, then writes
<DATA_ROOT>/output/mesoscale_reconstruction/<PREDICTIONS_NAME>/point_cloud.csv.
Maintained region names are RCA1, RCA2, RCA3, and RCA4.
Development
Install the dev dependencies:
Use ruff to check and format the code:
uv run ruff check . uv run ruff format .
Developer reference:
- Test pipeline Smoke test for the pipeline with few example datae
- Utils function usage audits shared
src/utilsfunctions and cleanup candidates.
See AGENTS.md for repository-specific development guidance.
License
Original CALHippo source code is released under the Apache License 2.0.
Code authors: Giovanni Casari and Ettore Candeloro, equal contribution.
Model weights, trained checkpoints, datasets, derived annotations, rendered figures, notebook outputs, and other BigBrain-derived artifacts are not covered by the Apache License 2.0. These artifacts are released under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0) for non-commercial academic research use only.
Some parts of this repository include copied or modified code from upstream
model projects used by the pipeline, including Cellpose, HoVer-Net, InstanSeg,
StarDist, and related dependencies. Those files remain subject to their original
upstream licenses and copyright notices. Where applicable, upstream notices are
retained in the corresponding source folders and/or in THIRD_PARTY_NOTICES.md.
UNI2-h weights are not redistributed by this repository. Users who need the UNI2-h classification path must request access from the upstream provider and authenticate locally.
The CALHippo framework, released weights, and derived artifacts are intended for non-commercial research use and are not intended for clinical diagnosis, medical decision-making, or commercial deployment.
Citations
If you use our dataset/code you must cite the following:
@inproceedings{2026MICCAI_calhippo, title={CALHippo: Cell Segmentation for Neuronal Density Inference in the Human Hippocampus}, author={Casari, Giovanni and Candeloro, Ettore and Gandolfi, Daniela and Mapelli, Jonathan and Bolelli, Federico and Grana, Costantino}, year={2026}, month={June}, book={Medical Image Computing and Computer Assisted Intervention – MICCAI 2026}, booktitle={Medical Image Computing and Computer Assisted Intervention – MICCAI 2026}, venue={Strasbourg, France}, keywords={Human Brain, Cell Segmentation, Density Estimation} }