pixelart-py 2.0.0

Create pixel art programmatically — PNG + HTML/CSS export, browser-based editor.

pixelart-py

A simple, expressive Python library for creating pixel art programmatically — with PNG export, HTML/CSS export, and a browser-based hand-drawing editor that generates Python code.

---

Installation

pip install pixelart-py

Or locally:

git clone https://github.com/yourname/pixelart-py
cd pixelart-py
pip install -e .

---

Quick Start

from pixelart_py import Canvas

canvas = Canvas(16, 16, pixel_size=20)
canvas.fill("#1a1a2e")
canvas.draw_circle(8, 8, 6, "#e63946", filled=True)
canvas.save("art.png")

---

Features

• Canvas — configurable grid size and pixel scale
• Drawing primitives — draw_rect, draw_line, draw_circle, flood_fill
• Palette — define and reuse named colors
• PNG export — pixel-perfect output via Pillow
• HTML/CSS export — three styles: grid, table, custom-properties
• to_code() — convert any canvas back to Python source code
• Browser editor — draw by hand, get Python code automatically

---

Project Structure

pixelart-py/
├── pixelart_py/
│   ├── __init__.py      ← Public API
│   ├── canvas.py        ← Canvas class
│   ├── palette.py       ← Palette + color parsing
│   ├── drawing.py       ← Drawing primitives
│   ├── exporter.py      ← PNG + HTML/CSS + code generation
│   └── editor.py        ← Browser-based hand-drawing editor
├── examples/
│   ├── heart.py
│   ├── showcase.py
├── output/
├── pyproject.toml
└── README.md

---

API Reference

Canvas

canvas = Canvas(width, height, pixel_size=1, background=None)

Pixel manipulation

canvas.set_pixel(x, y, color)    # Set a pixel
canvas.get_pixel(x, y)           # Returns (r, g, b, a)
canvas.fill(color)               # Fill entire canvas
canvas.flood_fill(x, y, color)   # Flood fill from (x, y)
canvas.clear()                   # Reset to transparent

Drawing

canvas.draw_rect(x, y, w, h, color, filled=True)
canvas.draw_line(x1, y1, x2, y2, color)
canvas.draw_circle(cx, cy, radius, color, filled=False)

Export

canvas.save("output.png")
canvas.save_html("output.html", style="grid")       # CSS Grid
canvas.save_html("output.html", style="table")      # HTML table
canvas.save_html("output.html", style="custom-properties")  # CSS vars
html_str = canvas.to_html(style="grid")
code_str = canvas.to_code()                         # Python source
img = canvas.to_image()                             # PIL.Image

Utilities

copy = canvas.copy()
canvas.paste(other_canvas, x, y)
canvas.preview()   # opens image viewer

---

Palette

from pixelart_py import Palette

palette = Palette({
    "sky":    "#87ceeb",
    "ground": "#4a7c3f",
})

canvas.fill(palette["sky"])

Built-in palettes: CLASSIC, PASTEL, EARTHY

from pixelart_py import PASTEL
canvas.draw_rect(0, 0, 8, 8, PASTEL["mint"])

---

Color formats

All color arguments accept:

Format	Example
6-digit hex	"#ff0000"
3-digit hex	"#f00"
8-digit hex	"#ff0000ff"
RGB tuple	(255, 0, 0)
RGBA tuple	(255, 0, 0, 128)

---

Hand-drawing editor

from pixelart_py.editor import open_editor

canvas = open_editor(width=16, height=16, pixel_size=24)
# A browser window opens — draw your art, click "Save & Get Code"
# The function returns the canvas and prints Python code to the terminal

canvas.save("my_drawing.png")
print(canvas.to_code())

Editor features:

• ✏️ Draw, 🧹 Erase, 🪣 Fill, 💉 Eyedrop tools
• Keyboard shortcuts: D draw, E erase, F fill, I eyedrop, Ctrl+Z undo
• Color picker + 15-color quick palette
• Grid overlay toggle
• Zoom in/out
• On save: returns canvas + prints Python code

---

HTML/CSS Export Styles

"grid" — CSS Grid (recommended)

<div class="pixel-grid">
  <div class="p" style="background:#1a1a2e"></div>
  ...
</div>

"table" — HTML Table (max browser compatibility)

<table class="pixel-table">
  <tr><td style="background:#1a1a2e"></td>...</tr>
</table>

"custom-properties" — CSS Variables (easy to re-theme)

:root {
  --c0: #1a1a2e;
  --c1: #e63946;
}

Lets you change the entire color scheme by editing just the CSS variables.

---

Publishing to PyPI

pip install build twine
python -m build
twine upload dist/*

---

License

MIT