Metadata-Version: 2.4
Name: autoflatten
Version: 1.0.6
Summary: Automatically create cortical flatmaps from FreeSurfer surfaces
Author-email: Matteo Visconti di Oleggio Castello <mvdoc@berkeley.edu>
License-Expression: BSD-2-Clause
Project-URL: Repository, https://github.com/gallantlab/autoflatten
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: networkx
Requires-Dist: scikit-learn
Requires-Dist: packaging
Requires-Dist: jax>=0.4.0
Requires-Dist: libigl>=2.5.0
Requires-Dist: nibabel>=5.0.0
Requires-Dist: numba>=0.58.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: tqdm>=4.65.0
Requires-Dist: matplotlib>=3.7.0
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: codecov; extra == "test"
Provides-Extra: docs
Requires-Dist: mkdocs-material; extra == "docs"
Dynamic: license-file

![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
