goopenjpeg

README

goopenjpeg

Go JPEG 2000 decoder — no CGO for callers (purego + embedded native library).

Aligned with pylibjpeg-openjpeg for DICOM transfer syntaxes:

UID	Description
1.2.840.10008.1.2.4.90	JPEG 2000 Lossless Only
1.2.840.10008.1.2.4.91	JPEG 2000
1.2.840.10008.1.2.4.201–203	HTJ2K

Status

Phase 1 (current): project scaffold + decode API + CI native builds.

• Done: DecodeImage, GetImageParameters, DecodePixelData, purego loader
• Next: compliance tests from ref/pylibjpeg-openjpeg, encode API (Phase 2)

API

func DecodeImage(stream any, codec Codec) (*Image, error)
func GetImageParameters(stream any, codec Codec) (*Params, error)
func DecodePixelData(src []byte, opts PixelDataOptions) ([]byte, error)
func OpenJPEGVersion() (string, error)

Codec: CodecJ2K (0), CodecJPT (1), CodecJP2 (2).

Layout

goopenjpeg/           # public Go API
native/               # purego + go:embed prebuilt libs
lib/
  openjpeg/           # submodule → uclouvain/openjpeg
  interface/          # decode glue (from pylibjpeg-openjpeg, memory streams)
  capi/               # C ABI for purego
ref/pylibjpeg-openjpeg/

Development

git clone --recurse-submodules https://github.com/godicom-dev/goopenjpeg.git
cd goopenjpeg
go test ./...          # uses stub or CI-built libs in native/libs/
make build-native      # requires CMake

CI (build.yml): build-native → commit native/libs/ on main → test → release on tags.

References

• golibjpeg — same purego architecture for ISO 10918 / JPEG-LS
• pylibjpeg-openjpeg — behaviour and tests reference

Documentation

Index

• func DecodePixelData(src []byte, opts PixelDataOptions) ([]byte, error)
• func OpenJPEGVersion() (string, error)
• func ReadStream(stream any) ([]byte, error)
• type Codec
• type Image
  • func Decode(data []byte) (*Image, error)
  • func DecodeImage(stream any, codec Codec) (*Image, error)
  • func (img *Image) ByteAt(y, x, c int) byte
  • func (img *Image) BytesPerSample() int
  • func (img *Image) Uint16At(y, x, c int) uint16
• type Params
  • func GetImageParameters(stream any, codec Codec) (*Params, error)
  • func GetParameters(data []byte) (*Params, error)
  • func (p *Params) Columns() int
  • func (p *Params) NrComponents() int
  • func (p *Params) Rows() int
• type PixelDataOptions
• type PixelDataVersion

Functions

func DecodePixelData

func DecodePixelData(src []byte, opts PixelDataOptions) ([]byte, error)

DecodePixelData decodes encapsulated JPEG 2000 pixel data for DICOM. Version 2 returns raw decoded bytes; version 1 matches pylibjpeg v1 behaviour.

func OpenJPEGVersion

func OpenJPEGVersion() (string, error)

OpenJPEGVersion returns the linked openjpeg library version.

func ReadStream

func ReadStream(stream any) ([]byte, error)

ReadStream reads JPEG 2000 data from bytes, a file path, or an io.Reader.

Types

type Codec

type Codec int

Codec selects the JPEG 2000 container format (pylibjpeg-openjpeg codec argument).

const (
	CodecJ2K Codec = 0 // codestream (.j2k, .jpc, .j2c)
	CodecJPT Codec = 1 // JPT-stream
	CodecJP2 Codec = 2 // JP2 file format (.jp2)
)

type Image

type Image struct {
	Pixels      []byte
	Width       int
	Height      int
	Components  int
	Precision   int
	IsSigned    bool
	ColourSpace int
}

Image holds decoded pixel data in native precision, planar-interleaved (DICOM order).

func Decode

func Decode(data []byte) (*Image, error)

Decode is a shorthand for DecodeImage with CodecJ2K.

func DecodeImage

func DecodeImage(stream any, codec Codec) (*Image, error)

DecodeImage decodes JPEG 2000 data (pylibjpeg-openjpeg decode()).

func (*Image) ByteAt

func (img *Image) ByteAt(y, x, c int) byte

func (*Image) BytesPerSample

func (img *Image) BytesPerSample() int

func (*Image) Uint16At

func (img *Image) Uint16At(y, x, c int) uint16

type Params

type Params struct {
	Width       int
	Height      int
	Components  int
	Precision   int
	IsSigned    bool
	ColourSpace int
}

Params holds JPEG 2000 image parameters without decoding pixels.

func GetImageParameters

func GetImageParameters(stream any, codec Codec) (*Params, error)

GetImageParameters reads JPEG 2000 parameters without decoding pixels.

func GetParameters

func GetParameters(data []byte) (*Params, error)

GetParameters is a shorthand for GetImageParameters with CodecJ2K.

func (*Params) Columns

func (p *Params) Columns() int

func (*Params) NrComponents

func (p *Params) NrComponents() int

func (*Params) Rows

func (p *Params) Rows() int

type PixelDataOptions

type PixelDataOptions struct {
	Version                   PixelDataVersion
	Codec                     Codec
	PhotometricInterpretation string
}

PixelDataOptions configures DecodePixelData for DICOM handlers.

type PixelDataVersion

type PixelDataVersion int

PixelDataVersion selects decode_pixel_data behaviour.

const (
	PixelDataV1 PixelDataVersion = 1
	PixelDataV2 PixelDataVersion = 2
)