Metadata-Version: 2.4
Name: bsplot
Version: 0.0.10
Summary: Plotting utilities for neuroscience: styles, palettes, surfaces, glass-brain, and panel helpers.
License-Expression: EUPL-1.2
Project-URL: Repository, https://github.com/leon-k-martin/bsplot
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib
Requires-Dist: pybtex
Requires-Dist: pyaml
Requires-Dist: scikit-image
Requires-Dist: nibabel
Requires-Dist: nilearn
Requires-Dist: templateflow
Requires-Dist: graphviz
Requires-Dist: cmap
Provides-Extra: docs
Requires-Dist: quarto; extra == "docs"
Requires-Dist: quartodoc; extra == "docs"
Requires-Dist: griffe<1.0; extra == "docs"
Requires-Dist: jupyter-cache; extra == "docs"
Requires-Dist: cairosvg; extra == "docs"
Provides-Extra: tvbo
Requires-Dist: xarray; extra == "tvbo"
Requires-Dist: h5netcdf; extra == "tvbo"
Requires-Dist: h5py; extra == "tvbo"
Dynamic: license-file

<h1>
  bsplot
  <img src="docs/Usage/_output/anim1.gif" alt="Sagittal volume animation" height="55" align="right">
  <img src="docs/Usage/_output/anim4.gif" alt="Surface rotation animation" height="55" align="right">
</h1>

Neuroscience plotting utilities built on **matplotlib**.

## Overview

![](docs/overview_figure.png)

- Brain surfaces and glass-brain visualizations
- Volume slicing with anatomical overlays
- Tractography rendering
- Publication-ready styles and scientific colormaps
- Panel helpers for multi-figure layouts
- Terminal (ASCII) surface backend — render a lit brain as text, with data overlays

## Terminal (ASCII) rendering

Render a cortical surface straight to text — no matplotlib figure — as a lit
"surface of letters", with optional scalar overlays and parcellations in colour.
The default is the folded **pial** cortex, and the output adapts to wherever it
is drawn: **terminal** (ANSI colour), **notebook/website** (`color_mode="html"`,
auto-selected in a notebook), or **README/plain-text** (`color_mode="none"`).

```python
import bsplot

bsplot.plot_surf_ascii()                       # pial template brain, lateral
bsplot.plot_surf_ascii(data=my_stat_map)       # scalar overlay, colour-mapped
bsplot.plot_surf_ascii(parcellation=labels)    # coloured regions
bsplot.plot_surf_ascii(width=140)              # width = resolution knob
bsplot.plot_surf_ascii(background="light")     # for a white background
```

```bash
bsplot-ascii                          # pial fsaverage, lateral (or: python -m bsplot.ascii)
bsplot-ascii --view top --hemi both   # both hemispheres, dorsal
bsplot-ascii --html > brain.html      # emit an HTML block
bsplot-ascii --sphere                 # offline demo (no download)
```

See the [Terminal surface guide](docs/Usage/AsciiSurface.qmd) for ramps, colormaps, views, and resolution.

### Timeseries — recordings and simulations

Surface colouring over time, cheap enough to stream live. The geometry is
prepared once, so each frame only re-colours the visible faces: **~0.7 ms/frame
(>1000 fps)** against ~184 ms for a full render.

```python
mov = bsplot.AsciiSurfaceMovie(data, hemi="lh", view="lateral", width=80)
mov.play(fps=20)                    # live in the terminal
mov.to_gif("sim.gif"); mov.to_html("sim.html"); mov.to_cast("sim.cast")

# region-level data (TVB-style) mapped onto the surface by an atlas
bsplot.AsciiSurfaceMovie(data, atlas="DesikanKilliany", region_labels=labels)

# straight from a tvbo simulation result
bsplot.AsciiSurfaceMovie.from_tvbo("exp-3_result.h5", atlas="dk").play()
```

```bash
bsplot-ascii-movie data.npy --atlas Destrieux --fps 20     # play
bsplot-ascii-movie result.h5 --tvbo -o sim.gif             # or export
```

See the [Timeseries guide](docs/Usage/AsciiTimeseries/AsciiTimeseries.qmd).
Reading tvbo result files needs `pip install "bsplot[tvbo]"`.

![alt text](docs/figures/brain_network_with_insets.png)


## Installation

```bash
pip install bsplot
```

## Dependencies

- `matplotlib`
- `nibabel`
- `nilearn`
- `templateflow`
- `scikit-image`

