LenkRaster

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.

lenkraster quantize docs/examples/hammer-cycle-source.png \
  --palette-file docs/examples/hammer-cycle-palette.json \
  --root <absolute-path-to-repository> \
  --out hammer-cycle-local-output.png

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:

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.

Color construction

Seven-stop OKLCH material ramp	Ordered 4x4 Bayer dither

lenkraster ramp --color "#FF6B35" --stops 7 --drift -10 \
  --out docs/examples/material-ramp.png
lenkraster dither --a "#2196F3" --b "#FFEB3B" --size 256 --order 4 \
  --out docs/examples/ordered-dither.png

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.

From a checked-out source tree:

python -m venv .venv
.venv/Scripts/python -m pip install --upgrade pip
.venv/Scripts/python -m pip install .

On macOS or Linux, use .venv/bin/python in place of
.venv/Scripts/python.

For development:

python -m pip install -c requirements/ci.txt -e ".[dev]"
python -m pytest tests -q
python -m pip check
python -m pip_audit --skip-editable

CLI

lenkraster critique sprite.png
lenkraster critique sheet.png --json report.json
lenkraster ramp --color "#d77643" --stops 5 --drift -8 --out swatches.png
lenkraster dither --a "#ac530b" --b "#ffe0cc" --order 4 --out gradient.png
lenkraster check --file sprite.png
lenkraster quantize frame.png --palette lenk-studio-32 --out snapped.png
lenkraster quantize frame.png --palette-file palettes/my-palette.json \
  --root <absolute-path-to-sprite-workspace> --out snapped-custom.png
lenkraster palettes
lenkraster cycle "frame-*.png"
lenkraster shadow corpus/manifest.json --manifest-sha256 <sha256>

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:

{
  "name": "My fixed palette",
  "author": "Local user",
  "colors": ["102030", "f0e0d0"]
}

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.

Optional Aseprite bridge

Set the executable to an absolute path:

LENKRASTER_ASEPRITE_EXECUTABLE=<absolute-path-to-aseprite>
LENKRASTER_ASEPRITE_SHA256=<sha256-of-that-executable>

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:

lenkraster aseprite-export hero.aseprite \
  --root <absolute-path-to-sprite-workspace> \
  --out-dir exports/hero \
  --tag walk

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.

Run cycle QA without retaining exported files:

lenkraster aseprite-cycle hero.aseprite \
  --root <absolute-path-to-sprite-workspace> \
  --tag walk \
  --motion-threshold 12 \
  --min-motion-pixels 6

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:

{
  "mcpServers": {
    "lenkraster": {
      "command": "<absolute-path-to-venv>/Scripts/lenkraster-mcp.exe",
      "args": [],
      "env": {
        "LENKRASTER_TRUSTED_ROOT": "<absolute-path-to-disposable-sprite-workspace>",
        "LENKRASTER_ASEPRITE_EXECUTABLE": "<absolute-path-to-aseprite>",
        "LENKRASTER_ASEPRITE_SHA256": "<sha256-of-that-executable>"
      }
    }
  }
}

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:

Project-specific adapters and private art corpora are intentionally outside the MCP
surface and the distribution.

Python API

from lenkraster import (
    critique,
    export_aseprite_document,
    load_palette_file,
    make_ramp,
    qa_aseprite_document,
    qa_cycle,
    quantize_file,
)

report = critique("sprite.png")
print(report["score"], report["retry_hints"])

ramp = make_ramp("#d77643", stops=5, drift=-8.0)
quantize_file("frame.png", "lenk-studio-32", "snapped.png")
load_palette_file("palettes/my-palette.json", trusted_root="sprite-workspace")
quantize_file(
    "frame.png",
    None,
    "snapped-custom.png",
    palette_file="palettes/my-palette.json",
    palette_root="sprite-workspace",
)

motion = qa_cycle(
    ["base.png", "frame-1.png", "frame-2.png"],
    roi=(12, 8, 44, 40),
    transition_groups={"walk": [(0, 1), (1, 2)]},
)

export_manifest = export_aseprite_document(
    "hero.aseprite",
    "exports/hero",
    trusted_root="sprite-workspace",
)

aseprite_motion = qa_aseprite_document(
    "hero.aseprite",
    trusted_root="sprite-workspace",
    tag="walk",
)

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.

Development and release

Contributions are welcome; read
CONTRIBUTING.md.
Public artifact checks
and release provenance steps are documented in
docs/release-checklist.md.

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.