pixelplotlib 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,608 @@
1
+ Metadata-Version: 2.5
2
+ Name: pixelplotlib
3
+ Version: 0.1.0
4
+ Summary: Scientific plotting with 8-bit and 16-bit pixel-art graphics
5
+ Project-URL: Homepage, https://github.com/ap--/pixelplotlib
6
+ Project-URL: Source, https://github.com/ap--/pixelplotlib
7
+ Project-URL: Issues, https://github.com/ap--/pixelplotlib/issues
8
+ Project-URL: Changelog, https://github.com/ap--/pixelplotlib/releases
9
+ Author-email: Andreas Poehlmann <andreas@poehlmann.io>
10
+ Maintainer-email: Andreas Poehlmann <andreas@poehlmann.io>
11
+ License-Expression: MIT
12
+ License-File: LICENSE
13
+ Keywords: 16-bit,8-bit,pixel-art,plotting,retro,visualization
14
+ Classifier: Development Status :: 3 - Alpha
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Intended Audience :: Science/Research
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3 :: Only
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Programming Language :: Python :: 3.14
24
+ Classifier: Programming Language :: Python :: 3.15
25
+ Classifier: Topic :: Multimedia :: Graphics
26
+ Classifier: Topic :: Scientific/Engineering :: Visualization
27
+ Requires-Python: >=3.11
28
+ Requires-Dist: numpy>=1.23.2
29
+ Requires-Dist: pillow>=9.2
30
+ Provides-Extra: rich
31
+ Requires-Dist: rich>=12; extra == 'rich'
32
+ Provides-Extra: textual
33
+ Requires-Dist: textual>=0.86; extra == 'textual'
34
+ Description-Content-Type: text/markdown
35
+
36
+ # pixelplotlib
37
+
38
+ **Scientific plots as 8-bit and 16-bit pixel art.**
39
+
40
+ pixelplotlib is a small plotting library with a matplotlib-like API. Every figure is
41
+ rendered on a low-resolution canvas with bitmap fonts, palettes from retro consoles,
42
+ ordered dithering and sprite markers, then upscaled with crisp nearest-neighbour pixels.
43
+ It depends only on [NumPy](https://numpy.org) and [Pillow](https://python-pillow.org).
44
+
45
+ ![Line plot](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/line_plot.png)
46
+
47
+ ## Features
48
+
49
+ - **Familiar API**: `fig, ax = ppl.subplots()`, `ax.plot(...)`, `ax.set(...)`, `fig.save(...)`,
50
+ plus a pyplot-style state machine (`ppl.plot`, `ppl.show`, ...).
51
+ - **Many plot types**: line, step, scatter, bar/barh, histograms (1-D and 2-D), fill_between,
52
+ error bars, stem, imshow, pcolormesh, contour/contourf, quiver, pie, box, violin,
53
+ annotations, reference lines/spans, log scales, colorbars, legends and subplot grids.
54
+ - **Retro styles**: `8bit` (NES), `16bit` (SNES-style 5-bit colour), `gameboy`, `pico8`,
55
+ `c64`, `cga` and `1bit`, each with its own resolution, palette, fonts and decorations.
56
+ - **Pixel-art rendering**: bitmap fonts, Bayer dithering for gradients and transparency,
57
+ palette-snapped colormaps, sprite markers (hearts, stars, skulls, UFOs, ...).
58
+ - **Output**: PNG (or any Pillow format) at integer scale, optional CRT scanlines, animated
59
+ GIFs, sixel graphics for plotting straight into the terminal, and
60
+ [Rich](https://github.com/Textualize/rich) / [Textual](https://github.com/Textualize/textual)
61
+ integration for terminal apps.
62
+
63
+ ## Installation
64
+
65
+ pixelplotlib is available on [PyPI](https://pypi.org/project/pixelplotlib/). Add it to your
66
+ project with [uv](https://docs.astral.sh/uv/):
67
+
68
+ ```bash
69
+ uv add pixelplotlib
70
+ ```
71
+
72
+ or install it into the current environment with `uv pip install pixelplotlib` (or `pip install pixelplotlib`).
73
+ To try the latest development version use `uv add git+https://github.com/ap--/pixelplotlib`.
74
+ Python 3.11 or newer is required.
75
+
76
+ ## Quick start
77
+
78
+ ```python
79
+ import numpy as np
80
+ import pixelplotlib as ppl
81
+
82
+ x = np.linspace(0, 10, 200)
83
+ fig, ax = ppl.subplots(style="16bit")
84
+ ax.plot(x, np.sin(x), label="sin")
85
+ ax.plot(x, np.cos(x), label="cos")
86
+ ax.set(title="HELLO WAVES", xlabel="t", ylabel="A")
87
+ ax.legend()
88
+ fig.save("waves.png") # upscaled by the style's default scale
89
+ fig.save("waves_crt.png", scale=4, scanlines=True)
90
+ ```
91
+
92
+ The pyplot-style interface works too:
93
+
94
+ ```python
95
+ import pixelplotlib.pyplot as plt # or: import pixelplotlib as plt
96
+
97
+ plt.figure(style="gameboy")
98
+ plt.plot([1, 3, 2, 4])
99
+ plt.title("GB")
100
+ plt.savefig("gb.png")
101
+ plt.show() # inline in Jupyter, else the system image viewer
102
+ ```
103
+
104
+ Figures can also be returned as data: `fig.to_array()` gives the native-resolution RGB
105
+ array and `fig.to_image(scale=...)` a `PIL.Image`.
106
+
107
+ ### Plotting in the terminal
108
+
109
+ In a terminal with [sixel](https://en.wikipedia.org/wiki/Sixel) graphics (xterm `-ti vt340`,
110
+ foot, WezTerm, mlterm, Konsole, iTerm2, Windows Terminal, tmux 3.4+, ...) figures are drawn
111
+ right in the terminal:
112
+
113
+ ```python
114
+ fig.show(backend="sixel") # always write sixel to stdout
115
+ fig.show() # auto: Jupyter, else sixel if supported, else viewer
116
+ print(fig.to_sixel(scale=2)) # or grab the escape sequence yourself
117
+ ```
118
+
119
+ `show()` detects sixel support by querying the terminal. Set `PIXELPLOTLIB_SIXEL=1` to force
120
+ sixel output (e.g. on Windows or through ssh/multiplexers that hide the reply) or
121
+ `PIXELPLOTLIB_SIXEL=0` to disable it.
122
+
123
+ ### Rich and Textual
124
+
125
+ Figures also work in [Rich](https://github.com/Textualize/rich) and
126
+ [Textual](https://github.com/Textualize/textual), so they render in any terminal with
127
+ colour support (no sixel support needed). Each character cell shows two pixels as a
128
+ half block. Install the extras with `uv add "pixelplotlib[rich,textual]"`.
129
+
130
+ A `Figure` is a Rich renderable. Wrap it in `pixelplotlib.rich.Plot` to choose its size
131
+ in cells (`width=`, `height=`, or `expand=True` to fill the space):
132
+
133
+ ```python
134
+ from rich import print
135
+ from rich.panel import Panel
136
+ from pixelplotlib.rich import Plot
137
+
138
+ print(fig) # native size, shrunk to fit the terminal width
139
+ print(Panel(Plot(fig, width=60), title="pixels"))
140
+ ```
141
+
142
+ `pixelplotlib.textual.PixelPlot` is a Textual widget that fills its space (`1fr` by
143
+ default). Use `width: auto; height: auto` to show the figure at its native size instead:
144
+
145
+ ```python
146
+ from textual.app import App
147
+ from pixelplotlib.textual import PixelPlot
148
+
149
+ class PlotApp(App):
150
+ def compose(self):
151
+ fig, ax = ppl.subplots(style="pico8")
152
+ ax.plot([1, 3, 2, 4])
153
+ yield PixelPlot(fig)
154
+
155
+ PlotApp().run()
156
+ ```
157
+
158
+ Assign a new figure to `widget.figure` to replace the plot, or call `widget.refresh()`
159
+ after changing the current figure. Both integrations re-render the figure at the size
160
+ they draw it, so text and one-pixel lines stay sharp. `fig.to_array(size=(w, h))` gives
161
+ the same re-rendered pixels as an array. [`examples/textual_app.py`](https://github.com/ap--/pixelplotlib/blob/v0.1.0/examples/textual_app.py)
162
+ is a live dashboard: run it with `uv run --extra textual python examples/textual_app.py`.
163
+
164
+ ## Styles
165
+
166
+ Pick a style per figure (`ppl.subplots(style="pico8")`), globally (`ppl.use("c64")`) or
167
+ temporarily (`with ppl.context("1bit"): ...`). The canvas size in the table is the
168
+ native resolution, which is upscaled when saving.
169
+
170
+ <!-- styles:start -->
171
+ <table>
172
+ <tr><td align="center"><img src="https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/style_8bit.png" width="320"><br><code>8bit</code> (256x224)</td><td align="center"><img src="https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/style_16bit.png" width="320"><br><code>16bit</code> (320x224)</td></tr>
173
+ <tr><td align="center"><img src="https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/style_gameboy.png" width="320"><br><code>gameboy</code> (160x144)</td><td align="center"><img src="https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/style_pico8.png" width="320"><br><code>pico8</code> (192x160)</td></tr>
174
+ <tr><td align="center"><img src="https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/style_c64.png" width="320"><br><code>c64</code> (320x200)</td><td align="center"><img src="https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/style_cga.png" width="320"><br><code>cga</code> (320x200)</td></tr>
175
+ <tr><td align="center"><img src="https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/style_1bit.png" width="320"><br><code>1bit</code> (256x192)</td></tr>
176
+ </table>
177
+
178
+ <details><summary>Code for the style demo</summary>
179
+
180
+ ```python
181
+ rng = np.random.default_rng(0)
182
+ x = np.linspace(0, 10, 100)
183
+ fig, (ax1, ax2) = ppl.subplots(1, 2, style="16bit")
184
+ ax1.fill_between(x, np.sin(x) - 0.4, np.sin(x) + 0.4)
185
+ ax1.plot(x, np.sin(x), label="sin")
186
+ ax1.plot(x, np.cos(x), label="cos")
187
+ ax1.set(title=style, xlabel="t")
188
+ ax2.hist(rng.normal(size=300), bins=8)
189
+ ax2.set(title="hist")
190
+ ```
191
+
192
+ </details>
193
+ <!-- styles:end -->
194
+
195
+ ### Custom styles
196
+
197
+ Styles are dataclasses. Derive a new one with `Style.replace` and register it:
198
+
199
+ ```python
200
+ neon = ppl.get_style("16bit").replace(
201
+ name="neon",
202
+ background="#000000",
203
+ series=["#ff00ff", "#00ffff", "#ffff00"],
204
+ cmap="plasma",
205
+ )
206
+ ppl.register(neon)
207
+ fig, ax = ppl.subplots(style="neon")
208
+ ```
209
+
210
+ Useful fields include `size`, `scale`, `palette` (snap every colour to a fixed palette),
211
+ `bits` (bits per colour channel), `font`/`tick_font`, `line_width`, `line_shadow`,
212
+ `line_halo`, `bar_shading`, `panel` and `dither`.
213
+
214
+ ## Plot types
215
+
216
+ Every image below was produced by the code shown next to it
217
+ (see [`examples/gallery.py`](https://github.com/ap--/pixelplotlib/blob/v0.1.0/examples/gallery.py)).
218
+
219
+ <!-- gallery:start -->
220
+ ### Line plot
221
+
222
+ ![Line plot](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/line_plot.png)
223
+
224
+ ```python
225
+ x = np.linspace(0, 4 * np.pi, 200)
226
+ fig, ax = ppl.subplots(style="16bit")
227
+ ax.plot(x, np.sin(x), label="sin(x)")
228
+ ax.plot(x, np.cos(x), label="cos(x)")
229
+ ax.plot(x[::12], np.sin(x[::12]) * np.cos(x[::12]), "o--", label="product")
230
+ ax.set(title="TRIG FUNCTIONS", xlabel="x [rad]", ylabel="amplitude")
231
+ ax.legend(loc="lower left")
232
+ fig.save("line_plot.png")
233
+ ```
234
+
235
+ ### Scatter plot
236
+
237
+ ![Scatter plot](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/scatter_plot.png)
238
+
239
+ ```python
240
+ rng = np.random.default_rng(1)
241
+ x, y = rng.normal(size=(2, 150))
242
+ fig, ax = ppl.subplots(style="8bit")
243
+ sc = ax.scatter(x, y, c=np.hypot(x, y), cmap="fire")
244
+ ax.set(title="RANDOM ENCOUNTERS", xlabel="x", ylabel="y")
245
+ ax.colorbar(sc, label="r")
246
+ fig.save("scatter_plot.png")
247
+ ```
248
+
249
+ ### Sprite markers
250
+
251
+ ![Sprite markers](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/sprite_markers.png)
252
+
253
+ ```python
254
+ fig, ax = ppl.subplots(style="pico8")
255
+ markers = ["heart", "star", "skull", "ufo", "drop", "o", "s", "^", "D", "x"]
256
+ for i, m in enumerate(markers):
257
+ ax.scatter([i % 5], [i // 5], marker=m, size=2, color=f"C{i}")
258
+ ax.text(i % 5, i // 5 - 0.45, m, ha="center", va="top")
259
+ ax.set(title="MARKERS", xlim=(-0.6, 4.6), ylim=(-0.9, 1.5))
260
+ ax.axis("off")
261
+ fig.save("sprite_markers.png")
262
+ ```
263
+
264
+ ### Bar chart
265
+
266
+ ![Bar chart](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/bar_chart.png)
267
+
268
+ ```python
269
+ labels = ["Fire", "Ice", "Bolt", "Cure"]
270
+ fig, ax = ppl.subplots(style="16bit")
271
+ x = np.arange(len(labels))
272
+ ax.bar(x - 0.2, [42, 27, 35, 18], width=0.4, label="Lv 10")
273
+ ax.bar(x + 0.2, [65, 48, 51, 33], width=0.4, label="Lv 20")
274
+ ax.set_xticks(x, labels)
275
+ ax.set(title="SPELL DAMAGE", ylabel="HP")
276
+ ax.legend(loc="upper right")
277
+ fig.save("bar_chart.png")
278
+ ```
279
+
280
+ ### Horizontal bars
281
+
282
+ ![Horizontal bars](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/barh_chart.png)
283
+
284
+ ```python
285
+ fig, ax = ppl.subplots(style="c64")
286
+ langs = ["BASIC", "C", "ASM", "PASCAL", "FORTH"]
287
+ ax.barh(langs, [91, 64, 48, 27, 12], color=[f"C{i}" for i in range(5)])
288
+ ax.set(title="Favourite language", xlabel="votes")
289
+ fig.save("barh_chart.png")
290
+ ```
291
+
292
+ ### Histogram
293
+
294
+ ![Histogram](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/histogram.png)
295
+
296
+ ```python
297
+ rng = np.random.default_rng(7)
298
+ fig, ax = ppl.subplots(style="gameboy")
299
+ ax.hist(rng.normal(0, 1, 2000), bins=24, label="normal")
300
+ ax.hist(rng.normal(1.5, 0.6, 1000), bins=24, histtype="step", label="shifted")
301
+ ax.set(title="HISTOGRAM", xlabel="value", ylabel="count")
302
+ ax.legend()
303
+ fig.save("histogram.png")
304
+ ```
305
+
306
+ ### 2-D histogram
307
+
308
+ ![2-D histogram](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/histogram_2d.png)
309
+
310
+ ```python
311
+ rng = np.random.default_rng(3)
312
+ x = rng.normal(size=20000)
313
+ y = 0.6 * x + rng.normal(scale=0.7, size=20000)
314
+ fig, ax = ppl.subplots(style="16bit")
315
+ _, _, _, mesh = ax.hist2d(x, y, bins=32, cmap="magma")
316
+ ax.colorbar(mesh, label="counts")
317
+ ax.set(title="DENSITY", xlabel="x", ylabel="y")
318
+ fig.save("histogram_2d.png")
319
+ ```
320
+
321
+ ### Filled areas
322
+
323
+ ![Filled areas](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/fill_between.png)
324
+
325
+ ```python
326
+ x = np.linspace(0, 10, 120)
327
+ y = np.sin(x) * np.exp(-x / 8)
328
+ fig, ax = ppl.subplots(style="1bit")
329
+ ax.fill_between(x, y - 0.3, y + 0.3, label="95% band")
330
+ ax.plot(x, y, label="model")
331
+ ax.set(title="Confidence band", xlabel="time", ylabel="signal")
332
+ ax.legend()
333
+ fig.save("fill_between.png")
334
+ ```
335
+
336
+ ### Error bars
337
+
338
+ ![Error bars](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/error_bars.png)
339
+
340
+ ```python
341
+ rng = np.random.default_rng(5)
342
+ x = np.arange(1, 9)
343
+ y = 2.0 * x + rng.normal(0, 1.5, x.size)
344
+ fig, ax = ppl.subplots(style="8bit")
345
+ ax.errorbar(x, y, yerr=rng.uniform(1, 3, x.size), label="data")
346
+ ax.plot(x, 2.0 * x, "--", label="fit")
347
+ ax.set(title="MEASUREMENTS", xlabel="dose", ylabel="response")
348
+ ax.legend(loc="upper left")
349
+ fig.save("error_bars.png")
350
+ ```
351
+
352
+ ### Step and stem plots
353
+
354
+ ![Step and stem plots](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/step_and_stem.png)
355
+
356
+ ```python
357
+ n = np.arange(16)
358
+ fig, (ax1, ax2) = ppl.subplots(1, 2, style="snes")
359
+ ax1.step(n, np.cumsum(n % 3), where="post")
360
+ ax1.set(title="step", xlabel="n")
361
+ ax2.stem(n, np.sin(n / 2.5))
362
+ ax2.set(title="stem", xlabel="n")
363
+ fig.save("step_and_stem.png")
364
+ ```
365
+
366
+ ### Image / heatmap
367
+
368
+ ![Image / heatmap](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/heatmap.png)
369
+
370
+ ```python
371
+ y, x = np.mgrid[-2:2:64j, -3:3:96j]
372
+ z = np.sin(x * 2) * np.cos(y * 3) * np.exp(-(x**2 + y**2) / 4)
373
+ fig, ax = ppl.subplots(style="16bit")
374
+ im = ax.imshow(z, cmap="coolwarm", extent=(-3, 3, -2, 2), origin="lower")
375
+ ax.colorbar(im)
376
+ ax.set(title="WAVE PACKET", xlabel="x", ylabel="y")
377
+ fig.save("heatmap.png")
378
+ ```
379
+
380
+ ### Mandelbrot (imshow without dithering)
381
+
382
+ ![Mandelbrot (imshow without dithering)](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/mandelbrot.png)
383
+
384
+ ```python
385
+ y, x = np.mgrid[-1.2:1.2:150j, -2.1:0.9:200j]
386
+ c = x + 1j * y
387
+ z = np.zeros_like(c)
388
+ count = np.zeros(c.shape)
389
+ for _ in range(40):
390
+ z = np.where(np.abs(z) < 4, z * z + c, z)
391
+ count += np.abs(z) < 4
392
+ fig, ax = ppl.subplots(style="pico8")
393
+ ax.imshow(count, cmap="pico", dither=False, origin="lower", extent=(-2.1, 0.9, -1.2, 1.2))
394
+ ax.set(title="MANDELBROT", xlabel="Re", ylabel="Im")
395
+ fig.save("mandelbrot.png")
396
+ ```
397
+
398
+ ### Pixelated RGB image
399
+
400
+ ![Pixelated RGB image](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/rgb_image.png)
401
+
402
+ ```python
403
+ y, x = np.mgrid[0:1:96j, 0:1:128j]
404
+ sky = np.stack([40 + 120 * y, 60 + 140 * y, 200 - 60 * y], axis=-1)
405
+ sun = np.hypot(x - 0.7, y - 0.55) < 0.18
406
+ sky[sun] = (255, 200, 60)
407
+ ground = y > 0.75 + 0.05 * np.sin(x * 20)
408
+ sky[ground] = np.stack([30 + 20 * x, 120 + 60 * x, 40 + 0 * x], axis=-1)[ground]
409
+ fig, ax = ppl.subplots(style="gameboy")
410
+ ax.imshow(sky.astype(np.uint8))
411
+ ax.set(title="RGB -> 4 SHADES")
412
+ ax.axis("off")
413
+ fig.save("rgb_image.png")
414
+ ```
415
+
416
+ ### Pcolormesh (irregular grid)
417
+
418
+ ![Pcolormesh (irregular grid)](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/pcolormesh.png)
419
+
420
+ ```python
421
+ xe = np.geomspace(1, 100, 17)
422
+ ye = np.linspace(0, 1, 11)
423
+ c = np.log10(xe[:-1])[None, :] * np.sin(np.pi * ye[:-1])[:, None]
424
+ fig, ax = ppl.subplots(style="c64")
425
+ mesh = ax.pcolormesh(xe, ye, c, cmap="fire")
426
+ ax.set_xscale("log")
427
+ ax.colorbar(mesh)
428
+ ax.set(title="Log-spaced cells", xlabel="frequency")
429
+ fig.save("pcolormesh.png")
430
+ ```
431
+
432
+ ### Contour lines
433
+
434
+ ![Contour lines](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/contour_lines.png)
435
+
436
+ ```python
437
+ y, x = np.mgrid[-2:2:80j, -3:3:120j]
438
+ z = np.exp(-((x - 1) ** 2 + y**2)) - np.exp(-((x + 1) ** 2 + (y - 0.5) ** 2))
439
+ fig, ax = ppl.subplots(style="1bit")
440
+ ax.contour(x, y, z, levels=10, colors="fg")
441
+ ax.set(title="Dipole potential", xlabel="x", ylabel="y")
442
+ fig.save("contour_lines.png")
443
+ ```
444
+
445
+ ### Filled contours
446
+
447
+ ![Filled contours](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/filled_contours.png)
448
+
449
+ ```python
450
+ y, x = np.mgrid[-3:3:90j, -3:3:120j]
451
+ z = np.sin(x) ** 2 + np.cos(y + x / 2) + 0.1 * x
452
+ fig, ax = ppl.subplots(style="16bit")
453
+ cs = ax.contourf(x, y, z, levels=8, cmap="terrain")
454
+ ax.contour(x, y, z, levels=8, colors="#000000")
455
+ ax.colorbar(cs)
456
+ ax.set(title="TERRAIN MAP", xlabel="x", ylabel="y")
457
+ fig.save("filled_contours.png")
458
+ ```
459
+
460
+ ### Vector field (quiver)
461
+
462
+ ![Vector field (quiver)](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/quiver.png)
463
+
464
+ ```python
465
+ y, x = np.mgrid[-2:2:9j, -2:2:11j]
466
+ u, v = -y, x
467
+ fig, ax = ppl.subplots(style="8bit")
468
+ ax.quiver(x, y, u, v, C=np.hypot(u, v), cmap="rainbow")
469
+ ax.set(title="VORTEX", xlabel="x", ylabel="y")
470
+ ax.set_aspect("equal")
471
+ fig.save("quiver.png")
472
+ ```
473
+
474
+ ### Pie chart
475
+
476
+ ![Pie chart](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/pie_chart.png)
477
+
478
+ ```python
479
+ fig, ax = ppl.subplots(style="16bit")
480
+ ax.pie([45, 25, 20, 10], labels=["HP", "MP", "XP", "GP"], autopct="%d%%")
481
+ ax.set_title("INVENTORY")
482
+ fig.save("pie_chart.png")
483
+ ```
484
+
485
+ ### Box plot
486
+
487
+ ![Box plot](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/box_plot.png)
488
+
489
+ ```python
490
+ rng = np.random.default_rng(11)
491
+ data = [rng.normal(mu, sd, 200) for mu, sd in [(0, 1), (1, 0.5), (-0.5, 1.5), (2, 0.8)]]
492
+ fig, ax = ppl.subplots(style="cga")
493
+ ax.boxplot(data, labels=["A", "B", "C", "D"])
494
+ ax.set(title="BOX PLOT", ylabel="value")
495
+ fig.save("box_plot.png")
496
+ ```
497
+
498
+ ### Violin plot
499
+
500
+ ![Violin plot](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/violin_plot.png)
501
+
502
+ ```python
503
+ rng = np.random.default_rng(12)
504
+ data = [rng.normal(0, 1, 300), np.concatenate([rng.normal(-1.5, 0.5, 150),
505
+ rng.normal(1.5, 0.5, 150)]), rng.gamma(2, 1, 300) - 2]
506
+ fig, ax = ppl.subplots(style="pico8")
507
+ ax.violinplot(data, labels=["normal", "bimodal", "skewed"])
508
+ ax.set(title="VIOLINS", ylabel="value")
509
+ fig.save("violin_plot.png")
510
+ ```
511
+
512
+ ### Log scales
513
+
514
+ ![Log scales](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/log_scales.png)
515
+
516
+ ```python
517
+ n = np.geomspace(1, 1e4, 40)
518
+ fig, ax = ppl.subplots(style="gameboy")
519
+ ax.plot(n, n, label="O(n)")
520
+ ax.plot(n, n * np.log2(n), label="O(n log n)")
521
+ ax.plot(n, n**1.5, label="O(n^1.5)")
522
+ ax.set(xscale="log", yscale="log", title="COMPLEXITY", xlabel="n", ylabel="ops")
523
+ ax.legend(loc="upper left")
524
+ fig.save("log_scales.png")
525
+ ```
526
+
527
+ ### Annotations, reference lines and spans
528
+
529
+ ![Annotations, reference lines and spans](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/annotations.png)
530
+
531
+ ```python
532
+ x = np.linspace(0, 10, 200)
533
+ y = np.exp(-((x - 6) ** 2)) + 0.3 * np.exp(-((x - 2.5) ** 2) / 0.5)
534
+ fig, ax = ppl.subplots(style="16bit")
535
+ ax.axvspan(5, 7, color="C2", alpha=0.25)
536
+ ax.axhline(0.5, color="C3", linestyle="--")
537
+ ax.plot(x, y)
538
+ ax.annotate("PEAK!", xy=(6, 1.0), xytext=(8.3, 0.85))
539
+ ax.text(2.5, 0.38, "shoulder", ha="center")
540
+ ax.set(title="SPECTRUM", xlabel="energy", ylabel="intensity", ylim=(0, 1.15))
541
+ fig.save("annotations.png")
542
+ ```
543
+
544
+ ### Subplot grid
545
+
546
+ ![Subplot grid](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/subplot_grid.png)
547
+
548
+ ```python
549
+ rng = np.random.default_rng(2)
550
+ fig = ppl.Figure(size=(320, 240), style="16bit")
551
+ fig.suptitle("MISSION REPORT")
552
+ ax1 = fig.add_subplot(2, 2, 1)
553
+ ax1.plot(np.cumsum(rng.normal(size=100)))
554
+ ax1.set_title("walk")
555
+ ax2 = fig.add_subplot(2, 2, 2)
556
+ ax2.bar(["A", "B", "C"], [3, 5, 2])
557
+ ax2.set_title("loot")
558
+ ax3 = fig.add_subplot(2, 2, (3, 4))
559
+ ax3.hist(rng.normal(size=500), bins=30)
560
+ ax3.set_title("damage rolls")
561
+ fig.save("subplot_grid.png")
562
+ ```
563
+
564
+ ### Animated GIF
565
+
566
+ ![Animated GIF](https://raw.githubusercontent.com/ap--/pixelplotlib/v0.1.0/docs/images/animation.gif)
567
+
568
+ ```python
569
+ x = np.linspace(0, 2 * np.pi, 120)
570
+
571
+ def frame(i):
572
+ fig, ax = ppl.subplots(style="gameboy")
573
+ ax.plot(x, np.sin(x + i * np.pi / 8))
574
+ ax.scatter([x[i * 6]], [np.sin(x[i * 6] + i * np.pi / 8)], marker="heart", size=2)
575
+ ax.set(title="ANIMATION", ylim=(-1.2, 1.2))
576
+ return fig
577
+
578
+ ppl.animate(frame, 16, "docs/images/animation.gif", fps=8)
579
+ ```
580
+ <!-- gallery:end -->
581
+
582
+ ## Colormaps, palettes, fonts and sprites
583
+
584
+ - **Colormaps**: `viridis`, `magma`, `inferno`, `plasma`, `coolwarm`, `gray`, `fire`, `ice`,
585
+ `ocean`, `terrain`, `rainbow`, `gameboy` and `pico`. Colormaps are quantised to
586
+ `Style.cmap_levels` steps and snapped to the style's palette. Register your own with
587
+ `ppl.register_cmap(ppl.Colormap(...))`, or pass any list of colours as `cmap=`.
588
+ - **Palettes** (`ppl.palettes`): `NES`, `PICO8`, `C64`, `CGA`, `GAMEBOY` and `ONE_BIT`.
589
+ - **Fonts**: `ppl.FONT_5X7` (mixed case) and `ppl.FONT_3X5` (tiny, upper case).
590
+ - **Markers** (`ppl.MARKERS`): `o`, `s`, `^`, `v`, `D`, `x`, `+`, `*`, `.`, `p`, plus the sprites
591
+ `heart`, `star`, `skull`, `ufo` and `drop`. Use `size=2` or more to scale a sprite.
592
+ - **`ppl.pixelate(image, palette=..., size=..., dither=True)`** turns any RGB array into
593
+ pixel art.
594
+
595
+ ## Development
596
+
597
+ ```bash
598
+ uv sync # create .venv with the package and dev tools
599
+ uv run pytest # run the test suite
600
+ uv run ruff check # lint
601
+ uv build # build the sdist and wheel into dist/
602
+ uv run python examples/gallery.py # re-render docs/images and the README gallery
603
+ ```
604
+
605
+ `examples/gallery.py` is the single source of truth for the images and snippets in this
606
+ README. Add a function decorated with `@example("Title")` and re-run it to extend the
607
+ gallery. Pass example names to render only those, or `--no-readme` to leave this file
608
+ untouched.
@@ -0,0 +1,22 @@
1
+ pixelplotlib/__init__.py,sha256=LJdGnp_brEFfdDhuUAJFkIxYOy7j7-xy10AsuLZHIwY,1396
2
+ pixelplotlib/animation.py,sha256=iaQKEOo0triRB_WYw-QCOVTiZ5fLSX9ImqgRq5Yyx5Y,2748
3
+ pixelplotlib/artists.py,sha256=yb4V75-yKGJLTGwwuGWQKg7yAVDDVFZnQaRENpMlAHY,51298
4
+ pixelplotlib/axes.py,sha256=v63JATc5xHJC3Wu4fKq2TCejyRUiljpz5GkSySSjxUc,48212
5
+ pixelplotlib/canvas.py,sha256=8DBtC4oROhZVbpPWn9kx2XA4c0bYRvqS_uQr1vA4iic,14523
6
+ pixelplotlib/colormaps.py,sha256=e7UI2VBBII5Z6kI6B2hxpaGjBKeAL_VtoYxFnA1blYI,6589
7
+ pixelplotlib/colors.py,sha256=Dx7H1EBa5rV3ORPP4SCOcqOjFp9u2yclmcWcEjUqaPU,5048
8
+ pixelplotlib/dither.py,sha256=jaBW_MK60Xmh2SK1ro4IwPg7GD5lKF6fM38wdtLmrgQ,3056
9
+ pixelplotlib/figure.py,sha256=jOhnNljBWxOY1guXdbdaVZfeHvNJhqg2uUYWkayKZ8I,9756
10
+ pixelplotlib/fonts.py,sha256=oRTKs0Ah6OfKXKJvkXnVktE9FQqot_fOcEdXFJ-zXkU,13950
11
+ pixelplotlib/markers.py,sha256=nstTJZgo-c5xNjI79GBicvhIJm98sUdNXEZC2aIOSog,2212
12
+ pixelplotlib/palettes.py,sha256=BTkU3CJeGKjScjj6p3hov6zZALO7lnRyk-nHGuW87CQ,2070
13
+ pixelplotlib/pyplot.py,sha256=V0ypxnx12iHC3rImYhUKQZwljR5xACSveCBIiAZ2NTc,3067
14
+ pixelplotlib/rich.py,sha256=bIUaTe5l3DaENkMTwZzL-7FhDTFV6hJQCaI9bmxlZxg,5758
15
+ pixelplotlib/sixel.py,sha256=X_Qh7k5PhGn-DnAYMUqPFB2WVQwKPpVddkkjuIIJFDo,5480
16
+ pixelplotlib/styles.py,sha256=KymJPKDvKj9IOL3WGobZTouM1dKULjEoPobRodhTL-o,9875
17
+ pixelplotlib/textual.py,sha256=Yzqhwh8KgX5MmPj2uswFr5ycpv7Ap514T0-_hrwgOls,2736
18
+ pixelplotlib/ticks.py,sha256=htIqL7tOO6yYp-qOlaRwyNb9mNKz9KB3HG2iqI45vDs,3344
19
+ pixelplotlib-0.1.0.dist-info/METADATA,sha256=OLKfFqRGv9ADvvuzHSztjCddcbtYTqIs9gn-izl4e8A,22030
20
+ pixelplotlib-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
21
+ pixelplotlib-0.1.0.dist-info/licenses/LICENSE,sha256=MHZozT2R238_ZZrhyEIQnxbjr1OQRlfX7251Sk3Djvs,1074
22
+ pixelplotlib-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,18 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Andreas Poehlmann
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
6
+ associated documentation files (the "Software"), to deal in the Software without restriction, including
7
+ without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8
+ copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
9
+ following conditions:
10
+
11
+ The above copyright notice and this permission notice shall be included in all copies or substantial
12
+ portions of the Software.
13
+
14
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
15
+ LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
16
+ EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
17
+ IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
18
+ USE OR OTHER DEALINGS IN THE SOFTWARE.