autoflatten 1.0.6
Automatically create cortical flatmaps from FreeSurfer surfaces
Requires Python: >=3.10

![autoflatten logo](https://raw.githubusercontent.com/gallantlab/autoflatten/main/docs/autoflatten-logo.png)

<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

## Quick Start

```bash
# 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](https://gallantlab.org/autoflatten)**.

See **[example outputs](https://gallantlab.org/autoflatten/example-output)** 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

```bibtex
@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

```bibtex
@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](https://figshare.com/articles/dataset/fsaverage_subject_for_pycortex/) by Mark Lescroart and Natalia Bilenko
- Geodesic refinement step inspired by code from Bhavin Gupta and Alex Huth