# Retro Dither & Machine Palette Converter

> Dither images to 1-bit, CGA, EGA, C64-, NES- or handheld-style palettes. Resample a photo to a machine-style resolution, then quantise it with ordered (Bayer, blue noise) or error-diffusion dithering (Floyd–Steinberg, Atkinson, Jarvis, Stucki, Burkes, Sierra). Optional attribute cells imitate C64 and NES colour limits. Download a crisp PNG and a reusable recipe.

Part of usefulweb.app (https://usefulweb.app/). Part of [Flipline](https://flipline.usefulweb.app/) (ownerApp: flipline). Results are deterministic calculations from the inputs and the listed assumptions; the API returns exactly what the web page shows.

## Use it
- Human interface: https://fliplineditherlab.usefulweb.app/ (interactive tool at https://fliplineditherlab.usefulweb.app/tool)
- JSON API: POST https://fliplineditherlab.usefulweb.app/api/v1/calculate with a JSON object of inputs (schema: https://fliplineditherlab.usefulweb.app/api/v1/tool)
- OpenAPI: https://fliplineditherlab.usefulweb.app/openapi.json
- MCP (Streamable HTTP): https://fliplineditherlab.usefulweb.app/mcp - tool `flipline_dither_lab`

## Inputs
- image (file, required): Image (PNG, JPEG or WebP)
- resolution (select): Machine resolution
- width (integer): Working width (px)
- fit (select): Image fit for machine resolutions
- scale (integer): Output scale (whole pixels)
- palette (select): Retro palette
- customPalette (textarea): Custom palette (HEX list, GPL or JASC-PAL)
- dither (select): Dithering method
- strength (number): Dither strength (%)
- serpentine (boolean): Serpentine scanning for error diffusion
- match (select): Colour matching
- cells (select): Attribute cells
- brightness (number): Brightness
- contrast (number): Contrast
- gamma (number): Gamma
- saturation (number): Saturation (%)

## Method
- Decode, auto-orient and convert to sRGB (4 MB, 2 MP). Area-resample to the working grid in linear light; machine resolutions crop, pad (black) or stretch to their logical size. Transparent pixels are composited over black.
- Brightness, contrast, gamma and saturation use the Retro Lab development step. Palettes: CGA/EGA from RGBI and rgbRGB signal bits, the NES-style set decoded from the 2C02 composite levels on NESdev, C64 from Pepto’s VIC-II measurements; handheld greens are an authored interpretation.
- Ordered dithering adds a threshold bias (Bayer 2/4/8, or a 32 × 32 void-and-cluster map) scaled by the palette’s mean nearest-colour spacing. Error diffusion uses the published kernels, optionally serpentine; Atkinson drops a quarter of the error. Matching uses sRGB, redmean-weighted RGB or linear-light distance.
- Attribute cells pick colours per cell greedily (largest error reduction first); NES and C64 multicolour share the most frequent colour as background. Wide-pixel modes double pixels horizontally. Integer output scaling repeats pixels.

## Limits
- Machine palettes are colour values only. The cell modes approximate colour limits; they do not produce files for real hardware.