A pure Go implementation of the JPEG 2000 image codec (ISO/IEC 15444-1) with HTJ2K support (ISO/IEC 15444-15).

This package provides a native Go implementation of JPEG 2000 encoding and decoding, aiming for 100% parity with the OpenJPEG reference implementation. It supports both lossless (5-3 reversible wavelet) and lossy (9-7 irreversible wavelet) compression.

• Pure Go: No CGO dependencies, works on all Go-supported platforms
• Format Support: JP2 file format and raw J2K codestream
• HTJ2K Support: High-Throughput JPEG 2000 (ISO/IEC 15444-15) with full cleanup + refinement passes (SPP/MRP)
• Progressive Decode: Incremental decoding via ProgressiveDecoder — feed packets as they arrive, reconstruct at any point
• Float Image Output: FloatImage type preserves HDR float precision through the decode pipeline
• Packet Extraction: ExtractPackets / BuildPacketIndex for server-side progressive streaming
• Lossless & Lossy: Both compression modes supported
• Full Colorspace Support: All 19 ISO/IEC 15444-1 colorspaces with automatic conversion to sRGB
• 32-bit Float Encoding: EncodeFloat preserves IEEE 754 float32 values via NLT Type 3 markers (bitwise lossless)
• Flexible Precision: 1-32 bit component precision, including 4-bit, 10-bit, 12-bit, and 32-bit float
• Standard Library Integration: Implements image.Image interface
• Auto-registration: Registers with Go's image package for transparent decode

go get github.com/mrjoshuak/go-jpeg2000

package main

import (
    "image"
    "os"

    _ "github.com/mrjoshuak/go-jpeg2000" // Register format
)

func main() {
    file, _ := os.Open("image.jp2")
    defer file.Close()

    img, format, err := image.Decode(file)
    if err != nil {
        panic(err)
    }
    // Use img...
}

package main

import (
    "image"
    "os"

    "github.com/mrjoshuak/go-jpeg2000"
)

func main() {
    // Load or create an image
    img := createImage()

    file, _ := os.Create("output.jp2")
    defer file.Close()

    opts := jpeg2000.DefaultOptions()
    opts.Lossless = true

    err := jpeg2000.Encode(file, img, opts)
    if err != nil {
        panic(err)
    }
}

file, _ := os.Open("image.jp2")
meta, err := jpeg2000.DecodeMetadata(file)
if err != nil {
    panic(err)
}

fmt.Printf("Size: %dx%d\n", meta.Width, meta.Height)
fmt.Printf("Components: %d\n", meta.NumComponents)
fmt.Printf("ColorSpace: %v\n", meta.ColorSpace)
fmt.Printf("Tiles: %dx%d\n", meta.NumTilesX, meta.NumTilesY)

// Encode float32 data with bitwise-lossless preservation
floatImg := &jpeg2000.FloatImage{
    Width:      width,
    Height:     height,
    Components: [][]float32{rChannel, gChannel, bChannel},
    BitDepth:   32,
    Signed:     true,
}

opts := jpeg2000.DefaultOptions()
opts.Format = jpeg2000.FormatJ2K

err := jpeg2000.EncodeFloat(file, floatImg, opts)

Float encoding uses NLT Type 3 markers to reinterpret IEEE 754 float32 bits as int32 with a sign-magnitude transform, preserving all values including NaN, Inf, and -0.0.

// Preserve float precision through the decode pipeline
floatImg, err := jpeg2000.DecodeFloat(file)
// floatImg.Components[0] is []float32 for the first component (e.g. R)
// floatImg.Components[1] is []float32 for G, etc.

// With config options
cfg := &jpeg2000.Config{ReduceResolution: 2}
floatImg, err = jpeg2000.DecodeFloatConfig(file, cfg)

// Parse the codestream header, then feed packets incrementally
decoder, err := jpeg2000.NewProgressiveDecoderFromCodestream(codestreamBytes)

// Feed packets as they arrive (any order)
for _, pkt := range packets {
    decoder.FeedPacket(pkt)
}

// Reconstruct the best image from data received so far
floatImg, err := decoder.Reconstruct()

// Check progress
fmt.Printf("Received %d packets, complete: %v\n",
    len(decoder.ReceivedPackets()), decoder.Complete())

// Extract all packets from an encoded codestream
packets, err := jpeg2000.ExtractPackets(codestream)

// Or build a zero-copy index for memory-mapped files
index, err := jpeg2000.BuildPacketIndex(codestream)
pkt, err := index.GetPacket(addr)
addrs := index.AllAddresses()

opts := &jpeg2000.Options{
    Format:           jpeg2000.FormatJP2,      // or FormatJ2K, FormatJPX
    Lossless:         true,                     // Use 5-3 reversible wavelet
    Quality:          75,                       // 1-100, for lossy mode
    CompressionRatio: 20,                       // Alternative to Quality (20:1)
    NumResolutions:   6,                        // Decomposition levels + 1
    NumLayers:        1,                        // Quality layers
    ProgressionOrder: jpeg2000.LRCP,           // Packet ordering
    CodeBlockSize:    image.Point{6, 6},       // 64x64 code blocks
    TileSize:         image.Point{512, 512},   // Tile dimensions
    ColorSpace:       jpeg2000.ColorSpaceSRGB, // Output colorspace
    Precision:        12,                       // Override bit depth (1-16)
    EnableSOP:        true,                     // Start of packet markers
    EnableEPH:        true,                     // End of packet header markers
    Comment:          "Created with go-jpeg2000",
}

Full support for all colorspaces defined in ISO/IEC 15444-1 Annex M:

• Automatic Conversion: All colorspaces are automatically converted to sRGB during decode
• OpenJPEG Compatible: API values 0-5 match OpenJPEG's OPJ_COLOR_SPACE enum
• Unspecified vs Unknown:
  • ColorSpaceUnspecified (0): Returned for raw J2K codestreams without JP2 container
  • ColorSpaceUnknown (-1): Returned for unrecognized enumcs values

The decoder applies mathematically correct color transformations based on the specifications:

Supported profiles (RSIZ parameter):

jpeg2000/
├── jpeg2000.go          # Public API, types, image registration
├── decoder.go           # JP2/J2K decoding, colorspace detection
├── encoder.go           # JP2/J2K encoding (integer + float32)
├── nlt.go               # Non-Linearity Transform (NLT Type 3 for float)
├── colorspace.go        # Color conversion functions
├── floatimage.go        # FloatImage type for HDR output
├── progressive.go       # ProgressiveDecoder for incremental decode
├── packets.go           # Packet extraction and indexing
└── internal/
    ├── bio/             # Bit I/O utilities
    ├── box/             # JP2 file format box handling
    ├── codestream/      # J2K codestream marker parsing
    ├── dwt/             # Discrete Wavelet Transform (5-3, 9-7)
    ├── entropy/         # MQ coder, EBCOT tier-1, HTJ2K (cleanup + SPP/MRP)
    ├── mct/             # Multi-Component Transform (RCT, ICT)
    └── tcd/             # Tile Coder/Decoder, tier-2

Overall Test Coverage: 91-100% across all packages

• image.Gray / image.Gray16 - Grayscale
• image.RGBA / image.RGBA64 - RGB with alpha
• image.NRGBA / image.NRGBA64 - Non-premultiplied RGBA
• jpeg2000.FloatImage - Planar float32 components (via DecodeFloat)

• image.Gray / image.Gray16
• image.RGBA / image.RGBA64
• image.NRGBA / image.NRGBA64
• image.YCbCr
• image.Paletted
• jpeg2000.FloatImage - Planar float32 components (via EncodeFloat)

# Run all tests
go test ./...

# Run with coverage
go test -cover ./...

# Run with race detection
go test -race ./...

# Run benchmarks
go test -bench=. ./...

# Verbose output
go test -v ./...

The implementation prioritizes correctness and Go idioms over raw performance. For performance-critical applications, consider:

• Using appropriate tile sizes for your workload
• Reducing resolution levels for preview generation
• Using lossless mode only when necessary

This implementation aims to conform to:

• ISO/IEC 15444-1:2019 - JPEG 2000 Part 1 (Core)
• ISO/IEC 15444-15:2019 - JPEG 2000 Part 15 (HTJ2K)
• ITU-T Rec. T.800 - Equivalent ITU specification
• OpenJPEG behavior - API compatibility where applicable

• Part 2 (JPX) extensions are not fully supported
• Some advanced features (ROI, progression order changes mid-stream) are limited

This library implements the JPEG 2000 standards as defined by ISO/IEC 15444. The OpenJPEG project serves as the official ISO/IEC reference implementation and was consulted for clarification of standard behavior.

Contributions are welcome! Please ensure:

• All tests pass (go test ./...)
• Code coverage remains above 90%
• New features include tests
• Documentation is updated

Apache License 2.0. See LICENSE file for details.

• ITU-T Rec. T.800 | ISO/IEC 15444-1 - JPEG 2000 Part 1: Core
• ISO/IEC 15444-1:2019 - Latest standard revision
• ISO/IEC 15444-15:2019 - HTJ2K (High-Throughput JPEG 2000)
• OpenJPEG - Reference implementation
• ExifTool JPEG2000 Tags - Metadata reference