LenkRaster is a deterministic, bounded toolkit for inspecting and preparing pixel art.
It combines craft critique, palette operations, animation-cycle QA, an optional Aseprite
CLI bridge, a command-line interface, a Python API, and a trusted-local stdio MCP server.
LenkRaster is designed for agent workflows without turning an agent into an art director:
its reports are advisory evidence and retry hints. It does not approve artwork, replace
human review, or replace a project's composition, provenance, and release gates.
What it does
Scores bounded PNG sprites against explainable pixel-craft checks.
Builds OKLCH hue-shifted material ramps.
Quantizes PNGs against original built-ins or bounded user-owned palette JSON without
overwriting existing files.
Reports same-hue contrast and palette structure.
Measures animation motion and visibility using rendered-pixel math.
Exports and directly checks trusted local .ase/.aseprite documents through a
separately installed Aseprite CLI.
Exposes the same bounded operations to local MCP clients over stdio.
Replays user-owned, SHA-256-pinned golden corpora without promoting results to approval.
No GPU, API key, model download, browser, network service, or persistent daemon is
required.
See it in action
These are real outputs from the current LenkRaster CLI. The public source art and its
provenance are documented in
docs/examples.
One fixed palette across an animation
Palette normalization is constraint enforcement for asset pipelines, not an attempt to
"improve" an artist's source image. This four-frame hammer cycle intentionally contains
frame-exclusive RGB variation. LenkRaster maps it to one repository-owned 48-color target
without changing the poses or overwriting the source.
Source cycle
Fixed target
Verified output
77,766 distinct visible RGB values
48 user-owned colors
48/48 used; every visible output color belongs to the target
Use the same palette file and settings for separately stored frames. cycle measures
rendered-pixel motion and visibility; it does not claim to judge visual quality or prove
palette membership.
Aseprite export and cycle QA
The same four poses were assembled into a tagged hammer animation and exercised through
the separately installed, SHA-256-pinned Aseprite CLI bridge:
Validated export
Advisory cycle report
4 frames; 543x724 each; 120 ms per frame
PASS; 3/3 adjacent transitions detected; no issues
LenkRaster exported the horizontal sheet and sanitized metadata into a new directory, then
ran the cycle check from a separate transient export. The .aseprite working document is
not distributed in the package or public repository.
These examples demonstrate deterministic transformations, not artwork approval; critique
and animation QA remain advisory evidence for human review.
Security model
LenkRaster processes image files, so limits and containment are part of its public
contract:
MCP file operations require an explicit, existing LENKRASTER_TRUSTED_ROOT.
Resolved inputs and outputs must remain beneath that root; traversal and symlink escapes
fail closed.
PNG encoded bytes, decoded pixels, dimensions, frame discovery, frame count, total
pixels, pair work, JSON size, and MCP request size are bounded.
CLI file exports, MCP PNG exports, and Aseprite exports are create-only. Existing
files and directories are never overwritten.
Public errors are fixed messages and do not include local paths or subprocess output.
The server is trusted-local stdio only. It is not a network service and must not be
exposed as public HTTP.
The optional Aseprite bridge executes a native application and is not an operating-system
sandbox. Only process documents you trust. Use an OS sandbox for hostile or untrusted
Aseprite files.
See SECURITY.md for
reporting and the maintained threat boundary.
Requirements
Python 3.10 or newer
NumPy 2.x
Pillow 12.3 or newer within the 12.x line
Optional: Aseprite 1.3.17.2 or newer in the 1.3 line for .ase/.aseprite
integration
Aseprite is not bundled, downloaded, or redistributed by LenkRaster. It is a separate
product with its own license. LenkRaster is compatible with its documented CLI and is not
affiliated with or endorsed by Aseprite.
Install
From PyPI:
python -m pip install lenkraster
The distribution and installed Python package are both lenkraster. The command-line
entry points are lenkraster and lenkraster-mcp.
cycle returns exit code 0 for PASS and 1 for REVIEW. A review result is
not a release rejection unless your project has separately adopted that policy.
CLI exports create new files only: critique --json writes JSON, while ramp --out,
dither --out, and quantize --out write PNGs. This also applies to the default
dither_out.png and derived quantize filename. If an output already exists, the
command fails without changing it; choose another filename.
User-owned palette files
lenkraster palettes lists the four original built-ins: lenk-cinder-16, lenk-fern-4,
lenk-signal-16, and lenk-studio-32. A user-owned palette is a UTF-8 JSON file below an
explicit trusted root:
Palette files are limited to 16 KiB, 2-64 unique six-digit RGB colors, exact keys, and
bounded path-free metadata. MCP callers use palette_file relative to
LENKRASTER_TRUSTED_ROOT; CLI callers use --palette-file with --root.
Common 4-, 16-, and 32-color external palette workflows were exercised during
pre-publication compatibility testing. Users may place any lawfully obtained palette in
their own local JSON file and use the same palette_file interface. Users remain
responsible for the provenance and permitted use of supplied palettes.
The SHA-256 pin is strongly recommended. LenkRaster checks it before the version probe
and again immediately before export, and rejects unsupported Aseprite versions. Recompute
the pin whenever Aseprite is intentionally updated.
Export a horizontal sheet and sanitized manifest into a directory that does not yet exist:
For an output such as exports/hero, LenkRaster may create the one missing
immediate parent directory (exports) below the trusted root. It will not
recursively create a deeper missing directory tree; create any earlier directories
explicitly. The final output directory (hero) remains create-only.
The bridge passes a fixed argument vector to Aseprite batch mode. Callers cannot supply
scripts, arbitrary flags, output filenames, or shell fragments. Tag and layer selections
are optional bounded labels; nested layers use / (for example,
characters/hero body) and Unicode names are supported. Each invocation uses a fresh
disposable Aseprite user/configuration folder and a snapshotted input document, so the
operator's normal Aseprite extensions and preferences are not loaded. Validated output is
written to a hidden staging directory and becomes visible with one final create-only
directory rename.
MCP server
Any MCP-speaking client can launch the installed one-shot stdio server. Always use
absolute paths in the client configuration:
The Aseprite variables are optional when those tools are not used. The trusted-root
variable is required for every tool call. MCP clients cannot override the configured
executable or its SHA-256 pin.
LenkRaster exposes seven tools:
Tool
Purpose
critique_sprite
Score one bounded PNG and return findings/retry hints.
make_ramp
Generate a bounded OKLCH material ramp.
palette_quantize
Create a new PNG using an original built-in or trusted user palette.
contrast_report
Report same-hue lightness separation.
qa_cycle
Check 2-32 same-size PNG frames matched by a relative glob.
aseprite_export
Create a validated sheet and path-free manifest.
qa_aseprite_cycle
Export transiently and run bounded cycle QA.
Project-specific adapters and private art corpora are intentionally outside the MCP
surface and the distribution.
For the Aseprite Python API, configure LENKRASTER_ASEPRITE_EXECUTABLE or pass an
absolute executable path through the trusted local API. MCP clients cannot choose the
executable.
Design laws
Rendered-pixel law: RGB beneath fully transparent pixels does not affect critique,
contrast, quantization, or motion.
Shared-palette law: animation frames should use the same fixed target palette and
settings.
Motion-group law: every authored gesture group must independently contain a
qualifying transition.
Vision-is-not-QA law: animation correctness is computed from pixels, not inferred
from thumbnails.
Bounded-work law: encoded bytes, decoded pixels, frames, discovery, and comparisons
fail closed at explicit ceilings.
Advisory law: LenkRaster produces evidence and retry hints, never art approval.
Golden-corpus regression
lenkraster shadow accepts a bounded, caller-hash-pinned manifest containing
user-owned PNG fixtures. Automated cases report BASELINE_MATCH or DRIFT;
contextual cases remain HUMAN_REVIEW. Do not commit proprietary or private artwork to
this public repository.
The source and repository-authored assets are MIT licensed. See
ASSET_LICENSE.md
for palette and image scope, and
THIRD_PARTY_NOTICES.md
for dependency, method, and optional-tool notices. User-supplied palettes and Aseprite
itself are not part of this distribution.