<p align="center"> <a href="https://github.com/gallantlab/autoflatten/actions/workflows/run_tests.yml"><img src="https://github.com/gallantlab/autoflatten/actions/workflows/run_tests.yml/badge.svg" alt="Tests"></a> <a href="https://codecov.io/gh/gallantlab/autoflatten"><img src="https://codecov.io/gh/gallantlab/autoflatten/graph/badge.svg" alt="codecov"></a> <a href="https://pypi.org/project/autoflatten/"><img src="https://img.shields.io/pypi/v/autoflatten.svg" alt="PyPI version"></a> <a href="https://pypi.org/project/autoflatten/"><img src="https://img.shields.io/pypi/pyversions/autoflatten.svg" alt="Python versions"></a> <a href="https://github.com/gallantlab/autoflatten/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/autoflatten.svg" alt="License"></a> <a href="https://doi.org/10.5281/zenodo.17933205"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.17933205.svg" alt="DOI"></a> </p>

autoflatten: automatically create cortical flatmaps from FreeSurfer surfaces

autoflatten is a Python pipeline for 🌟automatically🌟 flattening cortical surfaces generated by FreeSurfer

TL;DR: run autoflatten /path/to/your/freesufer/subject; done.

Features

• Automatic cut mapping from a template to individual subjects
• Two flattening backends: JAX-accelerated pyflatten (default) or FreeSurfer's mris_flatten
• Visualization with area distortion metrics
• Animation of the flattening process — capture snapshots and render videos

Quick Start

# Install
pip install autoflatten

# Run on a FreeSurfer subject (requires FreeSurfer 6.0+ for projection)
autoflatten /path/to/subjects/sub-01

Documentation

For full documentation, usage examples, and configuration options, visit the autoflatten website.

See example outputs to preview what autoflatten produces.

Citation

If you use autoflatten in your research, please cite both autoflatten and the original FreeSurfer flattening method:

Visconti di Oleggio Castello, M., & Gallant, J. L. (2025). autoflatten: automatically create cortical flatmaps from FreeSurfer surfaces. Zenodo. https://doi.org/10.5281/zenodo.17933205

@software{visconti_di_oleggio_castello_2025_autoflatten,
  author       = {Visconti di Oleggio Castello, Matteo and Gallant, Jack L.},
  title        = {autoflatten: automatically create cortical flatmaps from FreeSurfer surfaces},
  year         = 2025,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.17933205},
  url          = {https://doi.org/10.5281/zenodo.17933205}
}

Fischl, B., Sereno, M. I., & Dale, A. M. (1999). Cortical surface-based analysis II: Inflation, flattening, and a surface-based coordinate system. NeuroImage, 9(2), 195-207. https://doi.org/10.1006/nimg.1998.0396

@article{fischl1999cortical,
  author       = {Fischl, Bruce and Sereno, Martin I. and Dale, Anders M.},
  title        = {Cortical surface-based analysis {II}: Inflation, flattening, and a surface-based coordinate system},
  journal      = {NeuroImage},
  year         = 1999,
  volume       = 9,
  number       = 2,
  pages        = {195--207},
  doi          = {10.1006/nimg.1998.0396}
}

License

BSD 2-Clause License. See LICENSE file for details.

Acknowledgments

• Default fsaverage template cuts by Mark Lescroart and Natalia Bilenko
• Geodesic refinement step inspired by code from Bhavin Gupta and Alex Huth