#image - Pure MoonBit Image Decoding Library

#Supported Formats

#Installation

moon add shunge/image

#Quick Start

fn main {
  // Auto-detect format and decode
  let img = @image.decode(data)

  println("Image: \{img.width} x \{img.height}")
  println("Format: \{@image.pixel_format_name(img.format)}")

  // Access individual pixels
  let pixel = img.get_pixel(10, 20)
  println("Pixel: R=\{pixel.r} G=\{pixel.g} B=\{pixel.b} A=\{pixel.a}")
}

#API Reference

#Unified Decode

// Auto-detect format and decode
pub fn decode(data : Bytes) -> Image raise Failure

// Decode with known format
pub fn decode_by_format(data : Bytes, format : ImageFormat) -> Image raise Failure

// Detect format from magic bytes
pub fn detect_format(data : Bytes) -> Option[ImageFormat]

// Check if the header resembles a supported format; this does not validate pixels
pub fn is_supported_format(data : Bytes) -> Bool

// Get human-readable pixel format name
pub fn pixel_format_name(format : PixelFormat) -> String

#Format-Specific Decoders

pub fn decode_bmp(data : Bytes) -> Image raise Failure
pub fn decode_qoi(data : Bytes) -> Image raise Failure
pub fn decode_tga(data : Bytes) -> Image raise Failure
pub fn decode_png(data : Bytes) -> Image raise Failure
pub fn decode_gif(data : Bytes) -> Image raise Failure
pub fn decode_jpeg(data : Bytes) -> Image raise Failure
pub fn decode_gif_all(data : Bytes) -> AnimatedImage raise Failure  // animated GIF

#Image Type

pub struct Image {
  width : Int
  height : Int
  format : PixelFormat
  data : Bytes  // Raw pixel data, row-major
}

// Constructors & methods
pub fn Image::new(width : Int, height : Int, format : PixelFormat, data : Bytes) -> Image
pub fn Image::get_pixel(self : Image, x : Int, y : Int) -> Color
pub fn Image::to_rgba8(self : Image) -> Image
pub fn Image::bytes_per_pixel(self : Image) -> Int

#PixelFormat

pub enum PixelFormat {
  Gray8   // 8-bit grayscale
  GrayA8  // 16-bit grayscale + alpha
  RGB8    // 24-bit RGB
  RGBA8   // 32-bit RGBA
}

#Architecture

shunge/image
├── lib.mbt                    # Main entry: format detection + dispatch
├── types.mbt                  # Core types: Image, Color, PixelFormat, BitReader
├── utils.mbt                  # Byte reading utilities, CRC32, Adler32
├── color.mbt                  # IDCT, YCbCr→RGB color conversion
├── transform.mbt              # Image transform utilities (crop/flip/resize/rotate)
│
├── bmp.mbt                    # BMP decoder
├── qoi.mbt                    # QOI decoder
├── tga.mbt                    # TGA decoder
├── png.mbt                    # PNG decoder + DEFLATE decompressor
├── gif.mbt                    # GIF decoder + LZW decompressor
├── jpeg.mbt                   # JPEG baseline decoder (DCT/IDCT/Huffman)
│
├── bmp_writer.mbt             # BMP encoder
├── qoi_writer.mbt             # QOI encoder
│
├── image_test.mbt             # Core tests: format-specific decoders + error paths
├── medium_image_test.mbt      # Medium-size tests: 64×64 images
├── complex_image_test.mbt     # Complex pattern tests: 128×128 checkerboard, noise, Mandelbrot
├── comprehensive_test.mbt     # Comprehensive tests: GIF/JPEG features, animated GIF, errors
├── fuzz_test.mbt              # Fuzz testing (random bytes → decoders, must not crash)
├── roundtrip_test.mbt         # Round-trip encode/decode tests
├── jpeg_real_test.mbt         # Embedded JPEG photographs with Pillow reference pixels
├── real_photo_test.mbt        # Embedded photographs in BMP/PNG/TGA/QOI/GIF
├── *_regression_test.mbt      # Format-specific independent pixel and malformed-input cases
├── decoder_stability_test.mbt # Structured malformed-input stability checks
│
├── example/                   # CLI example: image_info
├── tools/                     # Test image generation scripts
├── test_images/               # Test images (up to 2048×2048 + real photos)
├── ARTICLE.md                 # Article: hand-writing DEFLATE in MoonBit
└── LICENSE                    # MIT

#Supported BMP Features

• DIB header sizes 40, 52, 56, 108 and 124 bytes
• 32-bit BGRA (uncompressed and canonical byte-aligned BITFIELDS masks)
• 24-bit BGR (uncompressed)
• 1/4/8-bit indexed images, respecting biClrUsed and actual palette extent
• RLE4/RLE8 encoded runs, absolute runs, deltas, word padding and end markers
• Top-down and bottom-up uncompressed rows; compressed images must be bottom-up
• Checked header/pixel offsets, planes, compression/depth combinations and row strides

#Supported QOI Features

• RGB (3-channel) and RGBA (4-channel)
• All QOI chunk types: INDEX, DIFF, LUMA, RUN, RGB, RGBA
• The 64-entry color cache, channel wraparound and bounded run lengths
• Header channel/colorspace validation and required eight-byte end marker
• RGBA8 output regardless of the informative header channel count

#Supported TGA Features

• Types 2/10: raw/RLE truecolor at 16/24/32 bits per pixel
• Types 3/11: raw/RLE grayscale at 8 bits, or grayscale+alpha at 16 bits
• All four horizontal/vertical origins, normalized to top-left output
• 16-bit BGR555 with an optional one-bit attribute; truecolor output is RGBA8
• Checked image ID/color-map extents, descriptors, packet sizes and pixel counts

#Supported PNG Features

• All standard color/depth combinations: grayscale (1/2/4/8/16-bit), indexed (1/2/4/8-bit), RGB/RGBA/grayscale+alpha (8/16-bit)
• Packed grayscale samples expand to Gray8; 16-bit samples use their high byte to fit the existing 8-bit pixel formats
• tRNS transparency for grayscale, RGB and indexed images, including partial palette alpha tables; transparent colors are compared at original precision
• Full DEFLATE decompression (RFC 1951)
  • Uncompressed blocks (BTYPE=0)
  • Fixed Huffman codes (BTYPE=1)
  • Dynamic Huffman codes (BTYPE=2)
• All five PNG filter types: None, Sub, Up, Average, Paeth
• zlib wrapper (RFC 1950) with header, window-size and Adler32 verification
• Multiple DEFLATE blocks with preserved bit alignment and cross-block back-references
• CRC32 verification for critical chunks and tRNS, chunk ordering/length checks, and palette index validation
• Adam7 interlaced images at every supported depth, including narrow images and empty passes
• Checked image/scanline sizes and decompression bounded by the expected filtered image size

#Supported GIF Features

• GIF87a and GIF89a formats
• LZW decompression with variable-length codes (up to 12 bits)
• Global and local color tables
• 4-pass interlacing
• Transparency via Graphic Control Extension
• Logical-screen composition, frame rectangles and disposal methods 0 through 3
• Frame delays and NETSCAPE/ANIMEXTS loop metadata
• Output format: RGBA8 (palette expansion)

#Supported JPEG Features

• Baseline JPEG (SOF0) with 8-bit precision
• Grayscale (Gray8) and YCbCr color (RGB8) images in a single scan
• Huffman-coded DC and AC coefficients with O(1) prefix table lookup
• Zigzag deordering, dequantization, and IDCT
• Sub-sampling: 4:4:4, 4:2:2, 4:2:0
• Restart marker (RST) support
• Grayscale sampling factors 1 through 4, normalized to noninterleaved blocks
• APPn/COM metadata segments before or after the scan
• Checked segment/table/scan structure, entropy padding and restart sequence
• Output formats: Gray8 / RGB8

#Resource Limits

#Other Limitations

• Preserving 16-bit PNG output precision (PNG input is supported and reduced to 8-bit samples)
• PNG color management (gAMA/cHRM/sRGB/ICC) and APNG animation
• Streaming/incremental decode
• Image encoders for PNG/JPEG/GIF/TGA (BMP and QOI encoding available)
• Formats such as WebP, TIFF and AVIF

#License

#Testing

moon check --deny-warn
moon fmt --check
moon info
git diff --exit-code -- pkg.generated.mbti
moon test --deny-warn --target wasm-gc
moon test --deny-warn --target js
moon test --deny-warn --target native

python -m pip install Pillow==12.3.0
python -B -m unittest discover -s tools -p test_pillow_reference.py
python tools/verify_decoders.py
python tools/verify_decoders.py --corpus /path/to/photos --max-side 128

python tools/generate_png_regression_fixtures.py
python tools/generate_png_deflate_fixtures.py
python tools/generate_bmp_regression_fixtures.py
python tools/generate_gif_regression_fixtures.py
python tools/generate_jpeg_regression_fixtures.py
python tools/generate_qoi_tga_fixtures.py
python tools/generate_photo_references.py
moon fmt
moon test --deny-warn

#Contributing

• Additional formats (WebP, TIFF, AVIF)
• Additional image processing filters (resize and rotation already exist)
• CLI/Web demo application