ZX Spectrum Image Converter

A Go implementation of a Python tool that converts PNG images to ZX Spectrum .SCR format with accurate color matching and dithering.

Features

• ✅ Converts GIF/PNG images to ZX Spectrum .SCR format (6912 bytes)
• ✅ Supports multiple color palettes (Pulsar, Alone, custom JSON)
• ✅ Advanced color matching with perceptual distance calculations
• ✅ Multiple resize modes: fit, fill, stretch
• ✅ Gamma correction and brightness adjustment
• ✅ Bias control for bright color selection
• ✅ Preview image generation
• ✅ Cross-platform (Linux, Windows, macOS)

Technical Details

Color Matching: Uses perceptual distance in linear RGB space

Dithering: Error diffusion based on color distance

ZX Format: 6144 bytes bitmap + 768 bytes attributes

Color Depth: 2 colors per 8x8 cell (ink + paper)

Brightness: Controlled via BRIGHT bit in attribute byte

Installation

From Source

Using Go

Usage basic

Usage advanced

./img2zxscr \
  --i input.png \
  --o output.scr \
  --palette-file custom-palette.json \
  --fit-mode fill \
  --gamma 1.2 \
  --brightness 1.1 \
  --bright-bias -0.5 \
  --preview preview.png

Command Line Options

Palette format

Custom palettes use JSON format with 16 colors (8 normal + 8 bright)

{
  "colors": [
    [0, 0, 0],      // Black (normal)
    [0, 0, 205],    // Blue (normal)
    [205, 0, 0],    // Red (normal)
    [205, 0, 205],  // Magenta (normal)
    [0, 205, 0],    // Green (normal)
    [0, 205, 205],  // Cyan (normal)
    [205, 205, 0],  // Yellow (normal)
    [205, 205, 205],// White (normal)
    [0, 0, 0],      // Black (bright)
    [0, 0, 255],    // Blue (bright)
    [255, 0, 0],    // Red (bright)
    [255, 0, 255],  // Magenta (bright)
    [0, 255, 0],    // Green (bright)
    [0, 255, 255],  // Cyan (bright)
    [255, 255, 0],  // Yellow (bright)
    [255, 255, 255] // White (bright)
  ]
}

License

MIT License — see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Acknowledgments

Based on the original vibecoded Python implementation by sq.

ZX Spectrum is a trademark of Sinclair Research Ltd.