JLISwift

A hardware-accelerated, native Swift implementation of Google's jpegli JPEG compression algorithm.

JLISwift provides encoding and decoding of JPEG images using the jpegli algorithm, achieving up to 35% better compression ratios compared to traditional JPEG encoders while maintaining full backward compatibility with every standard JPEG decoder. The library supports advanced features including 10+ bit per component encoding and XYB color space JPEG.

Features

Feature	Description
jpegli-compatible encoding	Adaptive quantization, optimised quantization matrices, floating-point precision pipeline
jpegli-compatible decoding	Auto-detects 10+ bit precision, XYB color space, progressive scans
10+ bit per component	Encode 16-bit and float32 sources; backward-compatible output viewable as standard 8-bit JPEG
XYB color space JPEG	Perceptual color space from JPEG XL for superior quality at low bitrates
Hardware acceleration	Accelerate (vDSP/vImage), ARM NEON, Apple AMX, Intel SSE/AVX, Metal GPU compute
Swift 6 strict concurrency	Sendable types throughout, data-race safe by design
Cross-platform	macOS, iOS, tvOS, watchOS, visionOS, and Swift on Linux
Universal Binary	Separately optimised paths for Apple Silicon (arm64) and Intel (x86_64)

Quick Start

Add JLISwift to your Package.swift:

dependencies: [
    .package(url: "https://github.com/Raster-Lab/JLISwift.git", from: "0.1.0"),
]

import JLISwift

// Encode an image
let encoder = JLIEncoder()
let jpegData = try encoder.encode(image, configuration: .default)

// Decode a JPEG
let decoder = JLIDecoder()
let image = try decoder.decode(from: jpegData)

// Inspect a JPEG for advanced features
let info = try decoder.inspect(data: jpegData)
if info.isExtendedPrecision {
    print("This JPEG uses 10+ bit precision")
}
if info.isXYB {
    print("This JPEG uses XYB color space")
}

Encoder Configuration

var config = JLIEncoderConfiguration.default

// Standard quality-based encoding
config.quality = 85.0

// Or use jpegli's distance parameter (overrides quality)
config.distance = 1.0  // visually lossless

// XYB color space for perceptual quality
config.colorSpace = .xyb

// Control chroma subsampling
config.chromaSubsampling = .yuv444  // no subsampling

// Enable adaptive quantization (default)
config.adaptiveQuantization = true

Pixel Formats

JLISwift supports multiple input/output precisions:

Format	Description	Use case
.uint8	8-bit unsigned integer	Standard JPEG, maximum compatibility
.uint16	16-bit unsigned integer	10+ bit encoding, medical/scientific imaging
.float32	32-bit floating point	HDR workflows, linear light processing

Platform Support

Platform	Architecture	Acceleration
macOS 14+	Apple Silicon (arm64)	Accelerate, NEON, AMX, Metal
macOS 14+	Intel (x86_64)	Accelerate, SSE/AVX, Metal
iOS 17+	arm64	Accelerate, NEON, Metal
tvOS 17+	arm64	Accelerate, NEON, Metal
watchOS 10+	arm64	Accelerate, NEON
visionOS 1+	arm64	Accelerate, NEON, Metal
Linux	x86_64	SSE/AVX
Linux	arm64	NEON

Universal Binaries are supported — swift build produces a fat binary with separately optimised code paths for each architecture, selected at compile time via #if arch(arm64) / #if arch(x86_64).

Architecture

JLISwift
├── Core/                  Types, errors, configuration
│   ├── JLIImage           Pixel buffer container (8/16/32-bit)
│   ├── JLIError           Typed error enum
│   ├── JLIConfiguration   Encoder & decoder settings
│   └── JLIJPEGInfo        Decoded JPEG metadata
├── Encoder/               JPEG compression pipeline
│   └── JLIEncoder         jpegli-compatible encoder
├── Decoder/               JPEG decompression pipeline
│   └── JLIDecoder         jpegli-compatible decoder (auto-detects features)
└── Platform/              Compile-time platform detection
    └── PlatformDetection  CPU architecture & acceleration capabilities

Progressive Roadmap

JLISwift follows a multi-stage progressive roadmap. External C library dependencies are used initially for correctness and compatibility, then progressively replaced with native Swift implementations optimised for each platform.

---

Milestone 1 — Foundation & Project Setup ✅

Establish the Swift Package, core types, public API surface, and platform detection.

• Swift Package with strict concurrency enabled
• Core types: JLIImage, JLIPixelFormat, JLIColorModel
• Error handling: JLIError enum
• Configuration: JLIEncoderConfiguration, JLIDecoderConfiguration
• JPEG metadata: JLIJPEGInfo (width, height, bits, XYB detection, progressive)
• Encoder/decoder API surface: JLIEncoder, JLIDecoder
• Platform detection: JLIPlatformCapabilities (architecture, Accelerate, NEON, SSE, Metal)
• Test scaffolding with Swift Testing framework
• CI-ready package (builds and tests on Linux x86_64)

---

Milestone 2 — Baseline JPEG Codec ✅

Functional encode/decode implemented natively in Swift (C interop bypassed in favour of direct native implementation).

• Implement JLIEncoder.encode() — full baseline JPEG encoding pipeline
• Implement JLIDecoder.decode() — full baseline JPEG decoding pipeline
• Implement JLIDecoder.inspect() — parse SOF marker for dimensions, components, precision
• Support JLIPixelFormat.uint8 I/O
• Support all JLIChromaSubsampling modes (4:4:4, 4:2:2, 4:2:0, 4:0:0)
• Unit tests: ≥80% coverage for encoder, decoder, and inspection code
• Encode → decode round-trip validation

---

Milestone 3 — jpegli Feature Parity ✅

jpegli-compatible features implemented natively in Swift (C interop bypassed in favour of direct native implementation).

• Floating-point precision pipeline (jpegli-compatible)
• XYB color space conversion (RGB ↔ XYB transforms)
• Decoder: auto-detect precision from JPEG markers
• JLIJPEGInfo.isExtendedPrecision and JLIJPEGInfo.isXYB detection
• Distance parameter support (JLIEncoderConfiguration.distance)
• Quality-scaled quantization tables (IJG-compatible)
• Unit tests for all feature code

---

Milestone 4 — Native Swift DCT & Quantization ✅

Pure-Swift DCT and quantization with Accelerate optimisation on Apple platforms.

• Forward DCT (FDCT) — pure Swift matrix-multiplication implementation
• Inverse DCT (IDCT) — pure Swift implementation
• Accelerate-optimised FDCT/IDCT via vDSP_mmul
• Quantization table generation (standard JPEG luminance/chrominance tables)
• Quality scaling (IJG-compatible formula, quality 1–100)
• Zigzag scan ordering (forward and inverse)
• Floating-point precision pipeline (integer only at final quantization)
• Unit tests: FDCT/IDCT round-trip, energy preservation, orthonormality
• Unit tests: quantization tables, zigzag ordering, quantize/dequantize

---

Milestone 5 — Native Swift Entropy Coding ✅

Huffman entropy coding fully implemented in Swift.

• Huffman table construction from JPEG-standard bits/values arrays
• Standard JPEG Huffman tables (DC/AC luminance/chrominance, ITU-T T.81 Annex K)
• Huffman encoding (DC DPCM + AC run-length coding)
• Huffman decoding (symbol lookup with bit-length tables)
• BitWriter with MSB-first output and JPEG byte stuffing
• BitReader with byte-unstuffing and marker detection
• Category computation and additional bits encoding/decoding
• Unit tests: bit stream round-trip, Huffman encode/decode, DC/AC round-trips

---

Milestone 6 — Native Swift Color Space & Sampling ✅

Color space conversion and chroma subsampling, with Accelerate and Metal acceleration.

• RGB → YCbCr conversion (BT.601, floating-point precision)
• YCbCr → RGB inverse conversion
• RGB → XYB transform (JPEG XL perceptual color space)
• XYB → RGB inverse transform
• Image-level and pixel-level conversion functions
• Grayscale ↔ Y plane conversion
• Chroma downsampling (box filter) for 4:2:0, 4:2:2
• Chroma upsampling (bilinear interpolation)
• Accelerate-optimised RGB ↔ YCbCr via vDSP
• Metal compute shader for RGB ↔ YCbCr conversion
• Unit tests: color space round-trips, dimension checks, sampling factors

---

Milestone 7 — Full Native Encoder ✅

Complete encoding pipeline in native Swift, no C dependencies.

• JPEG marker writing (SOI, APP0, SOF0, DHT, DQT, SOS, EOI)
• MCU (Minimum Coded Unit) block processing for all subsampling modes
• Full encode pipeline: color convert → downsample → block extract → level shift → DCT → quantize → zigzag → Huffman encode → bitstream
• Edge padding for non-multiple-of-8 image dimensions
• Grayscale encoding support
• RGBA input support (alpha channel ignored)
• YCbCr pass-through input support
• Quality-controlled output (quality 1–100)
• Standard Huffman table embedding in DHT markers
• Unit tests: valid JPEG output, dimension handling, quality validation

---

Milestone 8 — Full Native Decoder ✅

Complete decoding pipeline in native Swift, no C dependencies.

• JPEG marker parsing (SOI, SOF0/SOF2, DHT, DQT, SOS, APP segments, EOI)
• MCU block reconstruction for all subsampling modes
• Full decode pipeline: marker parse → Huffman decode → inverse zigzag → dequantize → IDCT → level unshift → chroma upsample → color convert
• Auto-detect: dimensions, component count, precision, chroma subsampling
• inspect() for metadata-only parsing without full decode
• Standard Huffman table fallback when DHT markers are absent
• Grayscale JPEG decoding
• Configurable output pixel format and color model
• Unit tests: round-trip encode/decode, metadata inspection, error handling

---

Milestone 9 — GPU Acceleration (Metal) ✅

Metal compute shaders for pipeline stages on Apple platforms.

• Metal compute kernel: forward DCT (8×8 block batches)
• Metal compute kernel: inverse DCT
• Metal compute kernel: RGB ↔ YCbCr conversion
• Metal pipeline orchestration (JLIMetalPipeline class)
• Runtime Metal shader compilation from embedded MSL source
• Batch GPU processing for multiple blocks
• #if canImport(Metal) conditional compilation
• Automatic fallback to CPU when Metal is unavailable
• Accelerate vDSP backend for DCT and color conversion on Apple platforms

---

Milestone 10 — Optimisation & Production Readiness ✅

Production-hardened codec with comprehensive testing and documentation.

• Floating-point precision pipeline throughout (jpegli-compatible)
• Strict concurrency: all public types are Sendable
• Input validation at all API boundaries (no crashes on bad input)
• Comprehensive unit test suite (87 tests across 7 suites)
• ≥80% test coverage across all modules
• Cross-platform support (macOS, iOS, tvOS, watchOS, visionOS, Linux)
• DocC documentation on all public symbols
• Apache 2.0 license compliance on all source files
• Swift 6.2 strict concurrency enabled by default

---

Relationship to Google jpegli

JLISwift is a clean-room native Swift implementation that targets compatibility with Google's jpegli. The progressive roadmap begins by wrapping the C library to ensure correctness and API compatibility, then replaces each pipeline stage with hardware-accelerated Swift code. The goal is to produce output that is compatible with — and benchmarked against — the reference implementation.

Key jpegli innovations reproduced in JLISwift:

• Floating-point precision pipeline — color conversion, chroma subsampling, and DCT all performed in floating point; integer quantization only at the final step
• Adaptive dead-zone quantization — spatially varying quantization thresholds based on image content
• Optimised quantization matrices — tables tuned per distance/quality and subsampling mode
• XYB color space JPEG — ICC-tagged JPEG using JPEG XL's perceptual color space
• 10+ bit encoding — 16-bit/float32 input with backward-compatible 8-bit JPEG output

Requirements

• Swift 6.2+ (strict concurrency mode)
• macOS 14+ / iOS 17+ / tvOS 17+ / watchOS 10+ / visionOS 1+ / Linux
• Xcode 16.3+ (for Apple platforms)

License

JLISwift is licensed under the Apache License 2.0.

Acknowledgements

• Google jpegli — the reference C implementation
• JPEG XL — origin of the XYB color space and adaptive quantization heuristics
• libjpeg-turbo — baseline JPEG codec used in early milestones