Pixel Art Generator combines image models with a grid-aligned pipeline

Pixel Art Generator is an open-source command-line project for people who want to see what happens between image generation and pixelization. It splits the work into stages: an image model creates an illustration, colors are quantized to a palette, the result is vectorized, then rasterized back to a target grid as PNG and SVG. You can also skip image generation and process an existing picture. Think of it as an adjustable asset experiment pipeline, not a one-click guarantee of finished game sprites. Open the official Pixel Art Generator repository.

Choose a supported environment first

The README targets Python 3.12 and lists Cairo as a dependency; its installation example uses Homebrew on macOS. Windows users should not copy those environment commands verbatim: the repository does not provide a complete native Windows installer. Use a Linux/macOS environment or WSL, install Cairo for that system, and then create a Python virtual environment. The first run may also download model weights; download size, VRAM use, and speed depend on the selected model and your hardware.

The example below clones the repository, creates an environment, and installs development requirements. Activate the environment with the command for your shell:

git clone https://github.com/HannahLilyW/pixel-art-generator.git
cd pixel-art-generator
python3.12 -m venv venv
source venv/bin/activate
pip install -r requirements-dev.txt

The macOS README also installs Python 3.12 and Cairo with Homebrew first. On Linux, install the Cairo development package for your distribution. If a step fails, read the missing system library in the error instead of repeatedly reinstalling Python packages.

Generate pixel art from a text prompt

A basic command is python3.12 cli.py "beautiful landscape, cartoon, flat". For a first test, keep the subject simple, such as “an orange cat sitting on a windowsill, flat cartoon style, centered subject.” Avoid combining many characters, text, and a detailed background in one prompt. The project writes timestamped PNG and SVG files under output/. Its README suggests style words such as cartoon, anime, and flat to encourage clearer color regions. The generated composition still depends on the prompt and selected model.

Useful options include --resolution or -r for the square output canvas (default 200); --colors or -c for the palette size (default 32); --output or -o for a different output directory; and --save-intermediate to retain intermediate stages and see where detail was lost. Resolution is the processed pixel grid, not the input resolution used by the image model.

Turn an existing illustration into pixel art

If you already have an illustration, use --input to skip text-to-image generation, for example python3.12 cli.py --input ./my-character.png --resolution 128 --colors 24. This makes it easy to compare several grids and palette sizes on the same source. Start at 32 colors, then try 16 or 8. At a smaller palette, facial details, weapons, or leaves may merge. Increase the grid or simplify the source instead of always adding colors.

The project also exposes model, sampling-step, and guidance options. The README’s default model is Stable Diffusion 1.4. The author recommends trying Z-Image-Turbo for speed and documents a lower step count and guidance value for it. Guidance ranges differ by model, so do not reuse one model’s settings blindly. For gated Hugging Face models, complete the required login and model license steps on the model page.

Understand the four stages instead of judging only the PNG

1. Generate or import: A text prompt goes to an image model, or --input loads an existing image. Composition and silhouette are decided here; later pixel processing cannot repair an obscured face or misplaced hand.
2. Palette quantization: Continuous colors are mapped into a limited set. Fewer colors can feel more retro and make a set more consistent, but can merge skin shading, haze, and subtle shadows.
3. Vectorization: Color regions and boundaries are represented as shapes that can be scaled or saved as SVG. Complex textures may become many small paths, so the SVG is not necessarily smaller or easier to edit by hand.
4. Rasterization: The shapes are placed back on the target grid to produce PNG. Inspect both PNG and SVG. PNG is common for game and image workflows; SVG is useful for scaling or further vector work, but is not a layered source project.

A practical tuning sequence

Keep the prompt or input fixed and change one variable per run. First use a 128- or 200-pixel grid with 32 colors to check the silhouette. Then reduce the palette to 16 or 24 and see whether the value structure still reads. Finally compare a smaller grid such as 64 or 96 to test recognition at icon size. Save experiments in separate output directories so runs are easy to compare. With intermediate files enabled, place the original, quantized palette result, vector result, and final PNG side by side to identify whether the problem came from composition, color reduction, or vector boundaries.

Common issues and useful projects

It looks like a shrunk photograph: The source has too much texture and lighting; try a flatter prompt, fewer colors, or a simpler illustration. It is hard to read at small size: Remove ornaments, use a larger grid, or strengthen the silhouette. Model download stalls: Check network access, model permissions, and cache space; if VRAM is limited, try a smaller model or validate post-processing first with --input. The SVG is complex: Complex boundaries create more paths; PNG may still be the practical delivery format for pixel assets. The project is useful for concept illustrations, icons, pixelization experiments, and repeatable batch research. Character animation that needs exact per-pixel control will still benefit from manual cleanup in a pixel editor.

The GitHub repository does not clearly display a project license, so do not assume unrestricted commercial rights. Verify the current repository license, model weight terms, and rights to the input image before commercial use. Dependencies, CLI options, and output examples are in the official README.