pixcel

Convert images into HTML table-based pixel art.

Image By Grok 4.20 (beta)

pixcel is a Go SDK and CLI tool that transforms any PNG, JPEG, or GIF image into a self-contained HTML file using an optimised <table> layout with 2D greedy meshing (colspan + rowspan) for minimal DOM output.

Performance

pixcel uses a 2D greedy meshing algorithm to pack identical-color pixel regions into the fewest possible <td> elements by calculating both colspan (horizontal) and rowspan (vertical) spans.

Given an image matrix $I$ of dimensions $W \times H$, the algorithm finds maximal rectangles of uniform color:

$$w = \max \lbrace ; n \geq 1 \mid \forall ; k \in [0, n) : I(x_0+k, ; y_0) = c_0 ; \rbrace$$

$$h = \max \lbrace ; m \geq 1 \mid \forall ; j \in [0, m), ; \forall ; k \in [0, w) : I(x_0+k, ; y_0+j) = c_0 ; \rbrace$$

Each rectangle emits a single cell: <td colspan="w" rowspan="h">, achieving $O(W \times H)$ amortised time complexity with up to 95%+ payload reduction (for images with large uniform-colour regions) compared to naive pixel-per-cell output.

Installation

CLI

go install github.com/H0llyW00dzZ/pixcel/cmd/pixcel@latest

SDK

Note

The SDK requires Go 1.25.7 or later.

go get github.com/H0llyW00dzZ/pixcel

Usage

CLI

# Basic conversion
pixcel convert photo.png

# Custom dimensions
pixcel convert logo.jpg -W 80 -o art.html

# Fixed width and height (stretches to exact dimensions)
pixcel convert icon.gif -W 100 -H 50 -o stretched.html

# Table-only mode (no HTML wrapper)
pixcel convert sprite.png --no-html -o table.html

# Custom page title
pixcel convert art.png -t "My Pixel Art" -o gallery.html

# Smooth load (hides content until fully rendered)
pixcel convert art.png -W 600 -H 306 -o art.html --smooth-load

# High-quality scaling (CatmullRom for photos/logos)
pixcel convert photo.png -W 300 --scaler catmullrom -o photo.html

# Generate bot-resistant HTML (randomized inline CSS for CAPTCHAs)
pixcel convert noise.png -W 120 --obfuscate -o captcha.html

# Limit animated GIF to 5 frames (uniformly sampled)
pixcel convert animation.gif -W 64 --max-frames 5 -o anim.html

SDK

package main

import (
    "context"
    "image"
    _ "image/png"
    "os"

    "github.com/H0llyW00dzZ/pixcel/src/pixcel"
)

func main() {
    // Open and decode the image
    f, _ := os.Open("photo.png")
    defer f.Close()
    img, _, _ := image.Decode(f)

    // Create a converter with options
    converter := pixcel.New(
        pixcel.WithTargetWidth(64),
        pixcel.WithTargetHeight(32),            // optional: fixed height
        pixcel.WithHTMLWrapper(true, "Art"),    // full HTML page with title
        pixcel.WithSmoothLoad(true),            // optional: hide until loaded
        pixcel.WithObfuscation(true),           // optional: randomize CSS formats
    )

    // Convert and write to file
    out, _ := os.Create("output.html")
    defer out.Close()
    converter.Convert(context.Background(), img, out)
}

Options

Option	CLI Flag	Default	Description
WithTargetWidth	-W, --width	56	Output width in table cells
WithTargetHeight	-H, --height	proportional	Output height in table cells
WithHTMLWrapper	--no-html	true	Include full HTML document wrapper
WithSmoothLoad	--smooth-load	false	Hide content until fully loaded to prevent progressive rendering
WithScaler	--scaler	nearest	Scaling algorithm: nearest, catmullrom, bilinear, approxbilinear
WithObfuscation	--obfuscate	false	Randomize inline CSS styling formats for CAPTCHA/scraping protection
WithMaxFrames	--max-frames	10	Maximum GIF frames to process (excess frames are sampled uniformly)
—	-t, --title	Go Pixel Art	HTML page title
—	-o, --output	go_pixel_art.html	Output file path

Project Structure

pixcel/
├── cmd/pixcel/         # CLI entry point — minimal main
├── internal/cli/       # CLI layer — Cobra commands, flag binding
├── src/pixcel/         # Core SDK — Converter, options, HTML generation
├── .github/workflows/  # CI configuration
└── Makefile            # Test and build targets

Testing

# Clone the repository
git clone https://github.com/H0llyW00dzZ/pixcel.git
cd pixcel

# Run tests with race detector
make test

# Run tests with verbose output
make test-verbose

# Run tests with coverage report
make test-cover

# View coverage in browser
go tool cover -html=coverage.txt

# Clean generated files
make clean

License

BSD-3-Clause © H0llyW00dzZ