Metadata-Version: 2.5
Name: anatplot
Version: 0.1.0.dev0
Summary: Simple anatomical surface scenes with PyVista
Project-URL: Repository, https://github.com/const7/anatplot
Project-URL: Documentation, https://chenkun.me/anatplot/
Project-URL: Issues, https://github.com/const7/anatplot/issues
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: ipywidgets>=8.1.9
Requires-Dist: matplotlib>=3.6
Requires-Dist: nest-asyncio2<2,>=1.7
Requires-Dist: neuromaps<0.1,>=0.0.7
Requires-Dist: nibabel>=5
Requires-Dist: nilearn<0.15,>=0.12
Requires-Dist: numpy>=1.24
Requires-Dist: pooch<2,>=1.8
Requires-Dist: pyvista<0.50,>=0.49
Requires-Dist: templateflow<26,>=25.1
Requires-Dist: trame-pyvista<0.3,>=0.2
Description-Content-Type: text/markdown

# anatplot

anatplot is a Python package for plotting data on brain surfaces and
visualizing anatomical regions in 3D. You can optionally add electrode
contacts to any plot, then save a Matplotlib figure or explore and export
the 3D scene.

> This project is under active development; some features may need further refinement.

Requires Python 3.10 or newer. Install from GitHub:

```bash
uv add "git+https://github.com/const7/anatplot.git"
# Or with pip:
pip install "git+https://github.com/const7/anatplot.git"
```

![Examples of SurfacePlot, ROIPlot, and VolumePlot](https://raw.githubusercontent.com/const7/anatplot/main/docs/assets/images/plot-types.png)

## Quick start

Plot a public Neurosynth default-mode association map and an example electrode
contact on inflated cortical surfaces. Dataset helpers download and cache the
public data on first use.

```python
import matplotlib.pyplot as plt
import numpy as np

from anatplot import SurfacePlot, datasets

# Fetch surfaces and a map with matching fsLR 32k vertex order.
surfaces = datasets.fetch_surfaces("fsLR", surface="inflated", density="32k")
left, right = datasets.fetch_dmn_map_fslr32k()
association = {
    # Hide this map's zero background so the underlying surface stays visible.
    "left": np.ma.masked_equal(left, 0),
    "right": np.ma.masked_equal(right, 0),
}

# The with block closes the 3D scene and releases graphics resources.
with SurfacePlot(
    **surfaces,
    views=["lateral", "medial"],
    layout="grid",
    window_size=(1000, 600),
    zoom=1.5,
) as plot:
    plot.add_layer(association, cmap="YlOrRd", cbar=True, cbar_label="Association Z")
    # Use the original anatomy's RAS coordinates in millimetres;
    # the fetched projection surfaces transfer contacts to the inflated display.
    plot.add_contacts([[-64, -13, 23]], radius=4, color="royalblue")
    fig = plot.to_figure(figsize=(10, 7))

fig.savefig("surface-map.png", dpi=300)
plt.close(fig)
```

See the [documentation](https://chenkun.me/anatplot/) for more.

## Acknowledgements

`SurfacePlot` was inspired by [surfplot](https://github.com/danjgale/surfplot).
Public templates and atlases come from [neuromaps](https://netneurolab.github.io/neuromaps/),
[TemplateFlow](https://www.templateflow.org/), [Nilearn](https://nilearn.github.io/),
and [NetNeuroLab](https://osf.io/udpv8/). Cite the data used in your figure;
see [dataset sources](https://chenkun.me/anatplot/datasets/#provenance).

## Contributing

Issues and pull requests are welcome. Please see the
[contributing guide](https://chenkun.me/anatplot/development/contributing/) before getting started.
