simcortex-v2 / README.md
KavehMoradkhani's picture
Add SimCortex v2 Hugging Face model card
bbc968d verified
|
Raw History Blame
5.71 kB
metadata
language: en
tags:
  - pytorch
  - medical-imaging
  - neuroimaging
  - brain-mri
  - cortical-surface-reconstruction
  - 3d-mesh
  - arxiv:2610.07378

SimCortex v2

Joint Cortical Surface Reconstruction with Near-Zero Collisions and Self-Intersections

Paper (arXiv) 路 Pretrained Model Archive (Zenodo) 路 Source Code 路 Website 路 3D Slicer Extension

Model overview

SimCortex v2 is a deep-learning pipeline for joint reconstruction of the left and right cortical white-matter and pial surfaces from structural T1-weighted MRI. It combines a nine-class 3D U-Net segmentation stage, topology-correct surface initialization, and simultaneous learned deformation of four cortical surfaces using multi-scale stationary velocity fields.

The released pipeline operates on MRI preprocessed into the expected MNI152 reference space. Its four-surface ordering is:

lh_pial
lh_white
rh_pial
rh_white

The complete preprocessing, surface initialization, and inference workflow is implemented in the SimCortex source repository.

Released checkpoints

The model files are located under zenodo-v2/, which preserves the original Zenodo archive structure.

Component File Role
Segmentation zenodo-v2/seg/seg_best_dice.pt Released nine-class segmentation checkpoint
Deformation (recommended) zenodo-v2/deform/deform_best_rmse.pth Checkpoint used for the final paper evaluation
Deformation (alternative) zenodo-v2/deform/deform_best_model.pth Alternative checkpoint retained for comparison and reproducibility

These .pt and .pth files are PyTorch state dictionaries, not stand-alone applications or Hugging Face Transformers models. The repository also includes the frozen configurations, split manifests, provenance metadata, and checksum manifest under zenodo-v2/. The archive does not include optimizer states or training-resume checkpoints.

Downloading the checkpoints

Use the Hugging Face Hub client to retrieve individual files:

from huggingface_hub import hf_hub_download

repo_id = "SimCortexAI/simcortex-v2"

segmentation_weights = hf_hub_download(
    repo_id=repo_id,
    filename="zenodo-v2/seg/seg_best_dice.pt",
)

recommended_deformation_weights = hf_hub_download(
    repo_id=repo_id,
    filename="zenodo-v2/deform/deform_best_rmse.pth",
)

This example downloads checkpoints only; it is not a complete inference command. For preprocessing, network construction, inference, and output conversion, follow the SimCortex code and documentation. While this repository remains private, authorized users must authenticate to Hugging Face before downloading. For a reproducible deployment, pin a tested Hugging Face commit or release tag instead of relying on the latest main revision.

Training and evaluation

The archived development split comprises 515 HCP-YA and OASIS-1 subjects: 361 training, 77 validation, and 77 test subjects. The exact split is preserved in zenodo-v2/splits/dataset_split.csv.

The paper evaluates SimCortex v2 on 560 MRI cases across 14 cohorts (40 cases per cohort). The case selection is recorded in zenodo-v2/splits/evaluation_sample40.csv.

The accompanying paper reports:

Measure Reported result
Average symmetric surface distance (ASSD) 0.253 mm
Cases with no detected inter-surface collision 92.14%
Self-intersection fraction 0.044%

These are paper-level results; see the manuscript for the evaluation protocol, baseline comparisons, definitions, and limitations.

Reproducibility and data

The files in zenodo-v2/ mirror the version-specific Zenodo release. The original zenodo-v2/SHA256SUMS and zenodo-v2/provenance.json document integrity and checkpoint provenance. All 15 files listed in the checksum manifest were verified after downloading the archive from Hugging Face at commit 63929b9d4dd3dd37ec3b98a615a7382cbbfd6631.

The model archive does not redistribute the source MRI scans or the MNI152 template. The associated research dataset is archived separately in the Federated Research Data Repository (FRDR); users must observe the applicable dataset access and redistribution conditions.

License

The Zenodo record displays a CC BY 4.0 license. The Hugging Face license metadata should be set only after confirming that this license applies to the checkpoint files and that their redistribution is permitted. No separate license is asserted by this model card.

Citation

Moradkhani, K., & Bouix, S. (2026). SimCortex v2: Joint Cortical Surface Reconstruction with Near-Zero Collisions and Self-Intersections. arXiv:2610.07378. https://doi.org/10.48550/arXiv.2610.07378

@misc{moradkhani2026simcortexv2,
  title={SimCortex v2: Joint Cortical Surface Reconstruction with Near-Zero Collisions and Self-Intersections},
  author={Moradkhani, Kaveh and Bouix, Sylvain},
  year={2026},
  eprint={2610.07378},
  archivePrefix={arXiv},
  primaryClass={cs.CV},
  doi={10.48550/arXiv.2610.07378}
}

For the exact pretrained files, also cite the Zenodo model archive.