Skip to main content
Glama

PixelForge

Hybrid Edge-Aware Pixel Art Studio, 32-Thread Numba Python Core, Game-Asset Pipeline & 15-Tool MCP Engine

PixelForge Hero Pipeline

PixelForge turns images, sprite animations, and full-motion video into crisp, production-ready pixel art—running both in the browser at 60 FPS on WebGL 2 and headlessly in Python at 160+ FPS on multi-core Numba JIT (plus a 15-tool Model Context Protocol server for AI agents).


Key Capabilities

  • 4-Column PixelForge Workstation (/editor/) & Interactive Algorithm Lab (/playground/):

    • 5 Live Multi-Viewport Modes: Single (1), Vertical/Horizontal Split Curtain (2/C), Dual Sync Side-by-Side (3), 4-Up Snapshot/Preset Arena (4), and 3×3 Seamless Tile Wrap Checker (5).

    • 7 Non-Destructive Pixel Retouch Tools: Navigate/Pan (V), Pixel Pencil 1–4px (B), Procedural-Restore Pixel Eraser (E), Flood Bucket & Shift+Click Global Color Swap (K), 1px Bresenham Line (U), 1px Pixel Rectangle (R), and Smart Eyedropper (I)—composited non-destructively over the live WebGL 2 shader output with independent stroke undo/redo.

    • Scientific Color & Game-Asset Telemetry: Floating 12× Pixel Loupe Magnifier (L) with (X, Y), #HEX, and perceptual OKLab coordinates; live RGB + Luminance Canvas Histogram; 4 Style Snapshot Slots (A/B/C/D); built-in Procedural OKLab Harmony Ramp Generator; and a Live Mirror-Deduplicated Tileset Preview Studio & VRAM Savings Calculator.

    • Interactive WebGL 2 Lab (/playground/): 4 live browser labs comparing Bayesian Posterior vs 64×64 Blue Noise vs Bayer 8×8 vs Atkinson, OKLab-BGM vs Salient vs Median-Cut, mirror-deduplicated tilemaps, and procedural OKLab color ramps.

  • Hybrid Bimodal-Plateau Downsampler (hybrid):

    • Uses smooth alpha-premultiplied box averaging in low-contrast gradients and skies (zero sensor/starfield noise) while splitting high-contrast edges around the tile midpoint into foreground/background plateaus weighted by inverse gradient—snapping typography, thin strokes, and sprite silhouettes cleanly without muddy anti-aliasing halos.

    • Also includes sobel (gradient-salient pooling), box (16×16 supersampled average), nearest (center-texel), and automatic pixel-grid GCD detection (detect_pixel_grid) to recover exact 1× native art from already-upscaled sprites.

  • Regularized OKLab-BGM Palette Discovery (oklab-bgm / hybrid_bgm_oklab) & Harmony Synthesis:

    • Runs 7 regularized Bayesian Gaussian Mixture EM iterations in perceptual OKLab space (fitting anisotropic diagonal covariances + Dirichlet mixture priors) seeded by chroma- and edge-weighted k-means++ / Median-Cut—preserving tiny vivid neon highlights across WebGL 2 and Python with zero temporal flicker.

    • Includes generateHarmonyRamp for procedural cool-shadow / warm-highlight pixel-art color ramps, 43+ built-in palettes, .gpl / .pal / .hex / .txt / .json I/O, and live lospec:<slug> fetching.

  • 20 Perceptual Dithering Modes (WebGL 2 + CPU Parity):

    • WebGL 2 & CPU Bayesian Posterior Soft Dither (posterior / bgm_posterior): Evaluates exact perceptual distances (d₁, d₂) to the 2 nearest OKLab centroids and thresholds Boltzmann posterior probability P(c₁) over a 64×64 void-and-cluster Blue Noise field—guaranteeing zero 3rd-color bleed and seam-free Voronoi transitions.

    • Ordered & Halftone: 64×64 Void-and-Cluster Blue Noise (bluenoise), bayer2, bayer4, bayer8, bayer16, cluster4 & cluster8 halftone screens, lines, and arbitrary custom threshold matrices.

    • 7 Serpentine Error-Diffusion Kernels: floyd-steinberg, atkinson, sierra-lite, sierra, burkes, jarvis, and stucki.

  • SVD Low-Rank Denoise, Kuwahara Brush, Local CLAHE Contrast & 1px Comic Ink:

    • Dedicated SVD / Low-Rank Structural Noise Pre-Filter (adjust.svd: 0..1), edge-preserving Kuwahara flat-paint pre-brush (0..4), 5×5 adaptive CLAHE local micro-contrast punch, luminance-preserving tone controls, orphan stray-pixel removal, stroke-preserving 3×3 majority smoothing, and 1px outlines (outer, inner, and internal ink comic contours).

  • Real-Time 60-FPS WebGL 2 Screen Post-FX, 20 Categorized Studio Presets & 12 Procedural Styles:

    • Live WebGL 2 + CPU-parity Screen & Stylization Post-FX stage (fx.mode): Bioluminescent Bloom, CRT Arcade Phosphor, 3D Voxel Bevel, Handheld Dot-Matrix LCD, Oscilloscope P31 Vector Beam, and Cyber Blueprint Wireframe, plus continuous CRT Scanlines and RGB Chromatic Aberration (0..3 px).

    • Ships with 20 categorized Studio presets (bgm-posterior, svd-cel, hybrid-crisp, kurzgesagt, crt-arcade, chunky-ink, pc98-cyber, voxel-3d, oscilloscope-xy, cyber-blueprint, aloboi-dream, pico-8, game-boy, one-bit, faithful, balanced, sprite, cga, newsprint, soft), 4 bundled real scenic view photographs, and 12 Python procedural video/reel styles.

  • Game-Ready Asset & Video Exporters:

    • True 1/2/4/8-bit Indexed-Color PNG (PLTE + tRNS) (~53% smaller files), 1px pixel-grid overlays, Sprite Sheet Packer + TexturePacker/Aseprite JSON Atlas, Mirror-Deduplicated (X/Y/XY flip) Tileset & Tilemap Builder, animated GIF, WebM, and H.264 MP4 (with audio pass-through or external .wav soundtrack muxing).

  • Computer-Vision Video Event & Motion Detectors:

    • Built-in optical-flow motion energy, scene-cut detection, consonant camera-zoom interval extraction, 1D horizontal/vertical progress-bar fill curve tracking (bar_fills), progressive circle/contour/callout stroke drawing detection (stroke_draws), and audio-beat camera synchronization (sync_video_motion_to_audio).


Related MCP server: pixelworks

12 Built-In Presets Showcase

PixelForge 12 Presets Showcase


Architecture Overview

flowchart LR
    SRC["Image / Sprite / Video"] --> PREP["Prep & Kuwahara Brush\nHybrid / Sobel / Box / Nearest"]
    PREP --> TONE["Tone, CLAHE & Alpha Cut"]
    TONE --> PAL["OKLab-BGM Salient Palette\nor 43+ Built-In / Lospec / .gpl"]
    PAL --> DITH["19 Perceptual Dithers\nBlue Noise / Bayer / 7 Diffusions"]
    DITH --> CLEAN["Orphan & Stroke-Safe Smooth\n+ Outer / Inner / 1px Ink Outline"]
    CLEAN --> EXP["Indexed PNG / Sprite Sheet Atlas\nMirror Tileset / GIF / MP4"]

Installation

Python Engine, CLI & MCP Server

Requires Python 3.10+ (numpy, scipy, scikit-learn, numba, Pillow, imageio, imageio-ffmpeg):

pip install -e .

Real-Time WebGL 2 Browser Studio & JS/TS Library

Requires Node.js 18+:

npm install
npm run build:site
npm run preview      # Launches Studio at http://localhost:8080/editor/

Usage

1. Real-Time WebGL 2 Studio

Launch the browser studio either from Python or npm:

python -m pixelforge studio --port 8765
# Open http://localhost:8765/editor/

2. Command-Line Interface (pixelforge)

# List all presets, styles, built-in palettes, and dithering methods
python -m pixelforge catalog

# Convert an image using a preset or custom pipeline flags
python -m pixelforge convert input.png output.png --preset kurzgesagt-pixel --upscale 4
python -m pixelforge convert input.png inked.png --width 160 --resample hybrid --kuwahara 2 --palette 24 --dither bluenoise --outline ink --orphans

# Convert a video with locked temporal palette (and optional external WAV soundtrack)
python -m pixelforge convert clip.mp4 pixel_clip.mp4 --preset pc98-cyber-dither --upscale 4 --audio soundtrack.wav

# Pack animation frames into a Sprite Sheet PNG + TexturePacker JSON Atlas
python -m pixelforge spritesheet run_0.png run_1.png run_2.png run_3.png -o character_sheet.png --width 64 --outline outer

# Slice & mirror-deduplicate a level mockup into a Tileset PNG + JSON Tilemap
python -m pixelforge tileset mockup.png -o level_tileset.png --tile-size 16

3. Python API

import imageio.v3 as iio
from pixelforge import PixelForge, save_png, pack_sprite_sheet, build_tileset

img = iio.imread("illustration.png")

engine = PixelForge(
    width=160,
    resample="hybrid",          # Bimodal-Plateau + Box edge-crisp downsampler
    kuwahara=2,                 # Flat-paint cartoon pre-brush
    palette=24,                 # Deterministic Salient OKLab-BGM extraction
    dither="bluenoise",         # 64x64 Void-and-Cluster Blue Noise
    dither_strength=0.42,
    remove_orphans=True,
    outline_mode="ink",         # 1px internal comic contour outlines
    outline_color="#100c1c",
)

pixel_1x = engine.fit_transform(img)
save_png("illustration_pixel.png", pixel_1x, scale=4, indexed=True)  # True Indexed PLTE+tRNS PNG

4. JavaScript / TypeScript WebGL 2 & CPU Engine

import { createPixelator } from 'pixelforge';

const px = await createPixelator(); // WebGL 2 GPU pipeline with automatic CPU fallback
const result = await px.process(imageElementOrBuffer, {
  size: { width: 160, resample: 'hybrid' },
  adjust: { kuwahara: 2, contrast: 0.1, saturation: 0.14 },
  palette: { source: 'extract', count: 24, distance: 'oklab' },
  dither: { method: 'bluenoise', strength: 0.42 },
  cleanup: { orphans: true, smooth: false },
  outline: { mode: 'ink', color: '#100c1c' },
});

document.body.append(result.toCanvas(4));          // 4x nearest-neighbor canvas
const blob = await result.toBlob({ scale: 4 });    // Compact Indexed-Color PNG

15-Tool Model Context Protocol (MCP) Server

Start the headless JSON-RPC 2.0 stdio MCP server for Claude Desktop, Cursor, or custom AI agents:

{
  "mcpServers": {
    "pixelforge": {
      "command": "python",
      "args": ["-m", "pixelforge.mcp_server"]
    }
  }
}

Tool Name

Purpose

catalog_list

Lists all 14 presets, 12 procedural styles, 43+ palettes, 19 dithers, 4 resamplers, and 4 outline modes.

image_convert

Full pixel-art pipeline with Kuwahara brush, 19 dithers, outlines, pixel grid, and Indexed PLTE PNG export.

image_stylize_reel

Applies any of the 12 procedural styles (kurzgesagt_glow, pc98_cyber, oscilloscope_xy, etc.) + cleanup/outlines.

image_showcase

Renders a labeled 12-panel contact sheet comparing presets or procedural styles on an input image.

image_detect_grid

Detects the pixel block factor of upscaled pixel art via border-difference GCD and recovers 1× native art.

palette_tool

Extracts hybrid_bgm_oklab / oklab_median_cut palettes, fetches lospec:<slug>, or converts .gpl/.pal/.hex/.json.

export_spritesheet

Packs images or video frames into a Sprite Sheet PNG + TexturePacker/Aseprite JSON Atlas.

export_tileset

Slices pixel art into an N×N mirror-deduplicated (X/Y/XY flip) Tileset PNG + JSON Tilemap.

video_convert

Converts MP4/GIF video with locked temporal palette (zero flicker) and audio pass-through or WAV muxing.

video_analyze_motion

Extracts optical-flow motion energy, scene cuts, and consonant camera-zoom intervals (±5, ±7, ±12).

video_detect_bar_fills

Detects 1D horizontal & vertical progress-bar/meter fill curves ([0.0 .. 1.0]).

video_detect_stroke_draws

Standalone detector for progressive circle, contour-outline, and callout-line drawings (start_s to finish_s).

video_extract_sound_triggers

Extracts generalized visual-to-audio event triggers and arrangement regimes from video footage.

video_sync_motion_to_audio

Beat-locks camera micro-zooms and pan curves to an external .wav soundtrack prior to pixelization.

trigger_catalog_list

Returns the universal visual-to-sound trigger catalog schema.


Testing

# Python core, exporters, CV detectors & live stdio MCP handshake tests
python -m unittest tests/test_pixelforge.py -v

# Build JS bundles & static WebGL 2 Studio site
npm run build:site

License

MIT License — see LICENSE.

Available Tools

15 tools
catalog_listB

Lists all merged PixelForge capabilities: 14 presets, 12 Reel styles, 43+ built-in Lospec/Hardware/Reel palettes, 19 dithering methods (incl. Blue Noise & 7 error-diffusion kernels), 4 downsamplers (incl. Hybrid Edge-Medoid), and 4 outline modes.

Inputs: no named parameters.

export_spritesheetC

Pixelizes and packs multiple input images OR sampled video frames into a single Sprite Sheet PNG + TexturePacker/Aseprite JSON coordinate atlas.

Inputs: output_png (required), input_paths (required), width, dither, +7 more.

export_tilesetB

Slices a pixel-art (or newly pixelized) image into fixed tiles (e.g. 8x8 or 16x16), deduplicates identical & X/Y/XY mirrored tiles, and writes a compact Tileset PNG + Tilemap JSON.

Inputs: input_path (required), output_png (required), width, palette, +5 more.

image_convertC

Converts an image to pixel art using the full unified PixelForge pipeline (Hybrid/Sobel/Box/Nearest downsampling, Hybrid OKLab-BGM or Lospec/.gpl/.hex/.pal palette, 19 dithering modes, Kuwahara pre-brush, tone controls, orphan/majority cleanup, 1px inner/outer/ink outlines, indexed PNG, and pixel grid).

Inputs: input_path (required), output_path (required), hue, grid, +21 more.

image_detect_gridA

Detects the pixel-block factor of an already-upscaled pixel-art image (e.g. 4x sprite) and optionally exports its exact 1x native pixel grid.

Inputs: input_path (required), tolerance, recover_1x_output_path.

image_showcaseC

Renders a labeled multi-panel contact sheet comparing all 12 Reel styles or top PixelForge presets on an input image.

Inputs: input_path (required), output_path (required), mode, tile_width, +1 more.

image_stylize_reelC

Applies one of the 12 procedural Reel visual styles (kurzgesagt_glow, chunky_cartoon, pc98_cyber, oscilloscope_xy, aloboi_dreamcore, bitwonder_bayer, etc.) with optional post-cleanup & 1px outlines.

Inputs: input_path (required), output_path (required), style, factor, +4 more.

palette_toolA

Extracts an optimal palette from an image (via hybrid_bgm_oklab or oklab_median_cut), fetches a Lospec palette ('lospec:'), or converts any palette to .gpl, .hex, or .json.

Inputs: palette (required), name, input_image, output_file, +1 more.

studio_infoC

Returns information and launch commands for the upgraded PixelForge WebGL 2 Real-Time Browser Studio.

Inputs: no named parameters.

video_analyze_motionC

Analyzes a video for scene cuts, camera zoom-ins/outs, object inflation/shrinking, and per-frame motion energy for SoundBit audio sync.

Inputs: video_path (required), max_frames.

video_convertB

Converts a video file to frame-coherent pixel-art MP4 or GIF using any PixelForge preset, custom palette/dither, or 12 Reel styles, keeping original audio or muxing a custom WAV.

Inputs: input_video (required), output_path (required), style, width, +9 more.

video_detect_bar_fillsB

Detects 1D horizontal & vertical progress bars, meters, gauges, and column fills, returning frame-accurate fill_curve trajectories in [0.0, 1.0].

Inputs: video_path (required), max_frames, min_duration_s.

video_detect_stroke_drawsC

Detects progressive indicator drawings (circle_draw, contour_outline_draw, callout_line_draw) with exact start_s, finish_s, and draw_curve.

Inputs: video_path (required), max_frames, allowed_shapes, min_duration_s, +1 more.

video_extract_sound_triggersC

Extracts configurable movement-to-sound triggers (bar fills, sparse camera zooms, HUD text ticks, risers, bursts) and musical arrangement regimes.

Inputs: video_path (required), config, zoom_mode, max_frames, +6 more.

video_sync_motion_to_audioC

Locks video camera zooms, pullbacks, focal tracking, and sub-bass micro-zoom punches in pre-pixel space onto a WAV soundtrack, then stylizes and muxes MP4.

Inputs: audio_wav (required), input_video (required), output_video (required), bpm, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 15 tools

    Disambiguation4/5

    Each tool targets a fairly distinct operation (convert vs. export vs. detect vs. sync), and the video-analysis tools split cleanly by feature (bar fills, stroke draws, motion, sound triggers). Minor ambiguity exists between studio_info and catalog_list (both informational) and between image_convert and image_stylize_reel, but descriptions clarify the boundaries.

    Naming Consistency4/5

    Most tools follow a resource_action pattern (image_convert, video_convert, video_detect_bar_fills, image_stylize_reel), which is readable and predictable. A few deviate with verb-first (export_spritesheet, export_tileset) or noun_noun (studio_info, catalog_list, palette_tool) forms, but the overall convention is coherent.

    Tool Count4/5

    15 tools sits at the top of the well-scoped range for a rich pixel-art/video pipeline. Each tool maps to a real capability (conversion, detection, export, sync, info), so none feel redundant, though the set is on the heavier side.

    Completeness4/5

    Coverage is broad: image and video conversion, palette handling, spritesheet/tileset export, multiple detection/analysis tools, motion-audio sync, and catalog/info. Minor gaps exist (e.g., no standalone audio extraction or batch orchestration), but core lifecycle workflows are covered without obvious dead ends.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to create, inspect, edit, and export pixel art, sprites, animations, and spritesheets using headless Aseprite, and to convert arbitrary images into indexed pixel art.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Gives AI assistants headless control of the pixel-art editor by wrapping its command line and complete Lua scripting API. It enables inspecting sprite metadata, creating new sprites, exporting frames and packed spritesheets, and editing pixels, layers, frames, tags and palettes.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to create layered pixel-art sprites and animations, inspect pixels, and export images, spritesheets, GIFs, APNGs, and TrueType pixel fonts. Documents and edits stay local, accessible over stdio MCP or callable directly from a shell.
      43
      MIT