Important
CALHippo has been accepted at MICCAI 2026! The current preprint version is available here. See the citation below.
The released dataset includes preprocessed HR crops, classified cell annotations, and a mesoscale point cloud. Use it to skip HR data preprocessing, segmentation, and classification; see Data setup.
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).
|
|
| HR Segmentation, Merging and Classification (b) | LR Full-Slice Density Prediction and Sampling (f) |
|
|
| All CA Class Resolved Point Cloud Reconstruction (g) | |
|
|
| All CA Mesocale Volumes (left) and predicted point cloud (right) | |
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 | shThen install the dependencies:
uv syncOptionally activate the environment:
source .venv/bin/activateor run .py files directly using uv run instead of python.
The released CALHippo dataset is available at https://ditto.ing.unimore.it/calhippo/. It includes 24 high-resolution BigBrain slices with CA1-CA4 cell annotations and a mesoscale point cloud. If you download it, you can skip HR preprocessing, HR segmentation, and HR classification. The dataset also includes the final released point cloud.
uv run python scripts/setup_data.py --data-root data --calhippo-dataset-zip CALHippo_Dataset_v1.0.zipChoose a setup path:
| Goal | Start here |
|---|---|
| Use the released dataset and skip the HR pipeline | Use The Released CALHippo Dataset |
| Reproduce the full process from raw data | Download All Raw Data, then Pipeline Instructions |
Reference documents:
| 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 |
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.
Install the dev dependencies:
uv sync --devUse 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.
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.
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}
}