Metadata-Version: 2.4
Name: kittyplot
Version: 0.1.0
Summary: Kitty graphics protocol backend for matplotlib
Keywords: matplotlib,terminal,graphics,kitty,ghostty,wezterm,tmux
Author: Doug Fritz
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: Matplotlib
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
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 :: Visualization
Classifier: Topic :: Terminals
Requires-Dist: matplotlib
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/doug/kittyplot
Project-URL: Repository, https://github.com/doug/kittyplot
Project-URL: Issues, https://github.com/doug/kittyplot/issues
Description-Content-Type: text/markdown

<p align="center">
  <img src="logo.jpeg" width="200" alt="kittyplot logo">
</p>

# kittyplot

Inline graphics backend for matplotlib. Renders plots directly in your terminal.

Supports the [Kitty graphics protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/) (Kitty, Ghostty, WezTerm) with automatic tmux passthrough.

## Install

```
uv add kittyplot
```

## Usage

Set the backend via `MPLBACKEND` environment variable or in code:

```python
import matplotlib
matplotlib.use('module://kittyplot')
import matplotlib.pyplot as plt

plt.plot([1, 2, 3], [1, 4, 9])
plt.show()
```

### Animation

Animations work automatically with `FuncAnimation`:

```python
import matplotlib
matplotlib.use('module://kittyplot')
import matplotlib.pyplot as plt
from matplotlib.animation import FuncAnimation
import numpy as np

x = np.linspace(0, 2 * np.pi, 100)
fig, ax = plt.subplots()
line, = ax.plot(x, np.sin(x))

def update(frame):
    line.set_ydata(np.sin(x + frame / 5.0))
    return line,

anim = FuncAnimation(fig, update, frames=200, interval=50, blit=False)
plt.show()
```

Press Ctrl-C to exit the animation. Set `fig.canvas.fullscreen = True`
before creating the animation to use an alternate screen buffer.

## tmux

Requires `allow-passthrough` in your tmux config:

```
set -g allow-passthrough on
```

Images use kitty virtual placements (unicode placeholders) so they
anchor to the text buffer and scroll naturally within tmux panes.

## Examples

Run with `uv run`:

```
uv run examples/simple.py
uv run examples/subplots.py
uv run examples/animation.py
uv run examples/lorenz.py
uv run examples/ggplot.py
```

## License

Apache-2.0
