jp3d

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 30, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package jp3d implements JPEG 2000 Part 10 (JP3D) volumetric image support as specified in ISO/IEC 15444-10.

JP3D extends JPEG 2000 to support three-dimensional volumetric data, commonly used in medical imaging (CT, MRI), scientific visualization, and geospatial applications.

Architecture

JP3D extends the standard JPEG 2000 codestream with:

  • Extended SIZ marker with Z-dimension parameters
  • 3D tile structures for volumetric partitioning
  • 3D wavelet decomposition (separable filtering in X, Y, and Z)
  • Slice-based access for efficient 2D rendering

3D Codestream

The JP3D codestream extends standard JPEG 2000 with additional parameters in the SIZ marker to describe the third (Z) dimension. The codestream maintains backward compatibility with Part-1 decoders that can extract 2D slices.

Wavelet Transform

JP3D uses separable 3D wavelet transforms, applying the standard JPEG 2000 wavelet filters (5/3 reversible, 9/7 irreversible) along all three axes. This creates an octave decomposition with LLL, LLH, LHL, LHH, HLL, HLH, HHL, and HHH subbands per level.

Usage

The JP3D parser integrates with the main JPEG 2000 decoder. When volumetric data is detected (extended SIZ marker), the parser extracts 3D metadata and provides slice extraction functionality.

Security

All operations validate input bounds and use safe integer conversions from the internal/safeconv package. The parser enforces security limits to prevent denial-of-service attacks.

References

  • ISO/IEC 15444-10:2011 - JPEG 2000 image coding system: Extensions for three-dimensional data
  • ITU-T Rec. T.809 (2008)

Index

Constants

View Source
const (
	// MarkerNSI is the extended SIZ marker for 3D (NSI segment).
	// Contains the Z-dimension parameters.
	MarkerNSI uint16 = 0xFF54

	// MarkerZOD is the Z-axis decomposition marker.
	MarkerZOD uint16 = 0xFF5C
)

JP3D marker codes and extensions per ISO/IEC 15444-10.

View Source
const (
	// MaxZDimension is the maximum Z-dimension (slices).
	MaxZDimension = 65535

	// MaxTileZ is the maximum Z-dimension of a tile.
	MaxTileZ = 4096

	// MaxDecompositionLevels is the maximum 3D decomposition levels.
	MaxDecompositionLevels = 16

	// MaxSliceSize is the maximum size of a single slice in bytes.
	MaxSliceSize = 256 * 1024 * 1024 // 256 MB
)

Maximum limits for validation.

View Source
const (
	// SubbandLLL is the low-low-low frequency subband (approximation).
	SubbandLLL = iota
	// SubbandLLH is the low-low-high frequency subband.
	SubbandLLH
	// SubbandLHL is the low-high-low frequency subband.
	SubbandLHL
	// SubbandLHH is the low-high-high frequency subband.
	SubbandLHH
	// SubbandHLL is the high-low-low frequency subband.
	SubbandHLL
	// SubbandHLH is the high-low-high frequency subband.
	SubbandHLH
	// SubbandHHL is the high-high-low frequency subband.
	SubbandHHL
	// SubbandHHH is the high-high-high frequency subband.
	SubbandHHH
)

3D wavelet subband identifiers.

Variables

View Source
var (
	// ErrInvalidZDimension indicates the Z-dimension value is invalid.
	ErrInvalidZDimension = errors.New("jp3d: invalid z-dimension")

	// ErrVolumetricError indicates a general volumetric data error.
	ErrVolumetricError = errors.New("jp3d: volumetric data error")

	// ErrSliceError indicates an error extracting a slice.
	ErrSliceError = errors.New("jp3d: slice extraction error")

	// ErrTruncatedData indicates the volumetric data is incomplete.
	ErrTruncatedData = errors.New("jp3d: truncated data")

	// ErrInvalidSIZ indicates an invalid extended SIZ marker.
	ErrInvalidSIZ = errors.New("jp3d: invalid extended SIZ marker")

	// ErrInvalid3DTile indicates a 3D tile structure is invalid.
	ErrInvalid3DTile = errors.New("jp3d: invalid 3D tile structure")

	// ErrWaveletOverflow indicates wavelet coefficient overflow.
	ErrWaveletOverflow = errors.New("jp3d: wavelet coefficient overflow")

	// ErrSliceOutOfBounds indicates the slice index is out of bounds.
	ErrSliceOutOfBounds = errors.New("jp3d: slice index out of bounds")

	// ErrMaxSlicesExceeded indicates too many slices were requested.
	ErrMaxSlicesExceeded = errors.New("jp3d: maximum slices exceeded")

	// ErrUnsupportedProfile indicates an unsupported JP3D profile.
	ErrUnsupportedProfile = errors.New("jp3d: unsupported profile")

	// ErrInvalidDecomposition indicates invalid 3D wavelet decomposition.
	ErrInvalidDecomposition = errors.New("jp3d: invalid decomposition structure")
)

JP3D-specific errors for volumetric parsing operations.

Functions

This section is empty.

Types

type Component3DSpec

type Component3DSpec struct {
	// BitDepth is the bit depth (with sign bit in MSB).
	BitDepth int

	// Signed indicates signed samples.
	Signed bool

	// XSeparation is the horizontal sub-sampling.
	XSeparation int

	// YSeparation is the vertical sub-sampling.
	YSeparation int

	// ZSeparation is the depth sub-sampling.
	ZSeparation int
}

Component3DSpec represents a component specification in 3D SIZ.

type Decomposition3D

type Decomposition3D struct {
	// XYLevels is the number of XY decomposition levels.
	XYLevels int

	// ZLevels is the number of Z decomposition levels.
	ZLevels int

	// Subbands contains all subbands at all levels.
	Subbands []*Subband3D
}

Decomposition3D represents a 3D wavelet decomposition structure.

type Parser

type Parser struct{}

Parser parses JP3D (JPEG 2000 Part 10) volumetric codestreams.

func NewParser

func NewParser() *Parser

NewParser creates a new JP3D parser.

func (*Parser) ParseDecomposition

func (p *Parser) ParseDecomposition(data []byte) (*Decomposition3D, error)

ParseDecomposition parses a 3D wavelet decomposition structure.

func (*Parser) ParseExtendedSIZ

func (p *Parser) ParseExtendedSIZ(data []byte) (*SIZ3D, error)

ParseExtendedSIZ parses an extended SIZ marker with 3D parameters.

type Reader

type Reader struct {
	// contains filtered or unexported fields
}

Reader reads JP3D volumetric JPEG 2000 codestreams.

func NewReader

func NewReader(data []byte) *Reader

NewReader creates a new JP3D reader.

func (*Reader) GetSlice

func (r *Reader) GetSlice(z int) (*Slice, error)

GetSlice extracts a 2D slice at the given Z index.

func (*Reader) GetVolumeInfo

func (r *Reader) GetVolumeInfo() *VolumeInfo

GetVolumeInfo returns information about the 3D volume.

func (*Reader) SliceCount

func (r *Reader) SliceCount() int

SliceCount returns the number of slices in the volume.

type SIZ3D

type SIZ3D struct {
	// Standard SIZ parameters
	Capabilities uint16 // Profile capabilities

	// 2D dimensions
	Width  int // Image width (X)
	Height int // Image height (Y)

	// 3D extension
	Depth int // Image depth (Z) - number of slices

	// 2D offsets
	XOffset int
	YOffset int

	// 3D offset
	ZOffset int

	// 2D tile dimensions
	TileWidth  int
	TileHeight int

	// 3D tile dimension
	TileDepth int

	// Tile offsets
	TileXOffset int
	TileYOffset int
	TileZOffset int

	// Component information
	ComponentCount int
	ComponentSpecs []Component3DSpec
}

SIZ3D represents an extended SIZ marker with 3D parameters.

func (*SIZ3D) NumTilesX

func (s *SIZ3D) NumTilesX() int

NumTilesX returns the number of tiles in the X direction.

func (*SIZ3D) NumTilesY

func (s *SIZ3D) NumTilesY() int

NumTilesY returns the number of tiles in the Y direction.

func (*SIZ3D) NumTilesZ

func (s *SIZ3D) NumTilesZ() int

NumTilesZ returns the number of tiles in the Z direction.

func (*SIZ3D) SliceCount

func (s *SIZ3D) SliceCount() int

SliceCount returns the number of 2D slices in the volume.

func (*SIZ3D) TotalTiles

func (s *SIZ3D) TotalTiles() int

TotalTiles returns the total number of 3D tiles.

type Slice

type Slice struct {
	// Index is the slice index (Z coordinate).
	Index int

	// Width is the slice width.
	Width int

	// Height is the slice height.
	Height int

	// Components is the number of components.
	Components int

	// Data contains the slice pixel data.
	// Organized as [component][y][x] or interleaved depending on format.
	Data [][]byte
}

Slice represents a 2D slice extracted from the 3D volume.

type Subband3D

type Subband3D struct {
	// Type identifies the subband (LLL, LLH, etc.).
	Type int

	// Level is the decomposition level.
	Level int

	// Width is the subband width.
	Width int

	// Height is the subband height.
	Height int

	// Depth is the subband depth.
	Depth int

	// Data contains the wavelet coefficients.
	Data []int32
}

Subband3D represents a 3D wavelet subband.

type Tile3D

type Tile3D struct {
	// TileX is the tile X index.
	TileX int

	// TileY is the tile Y index.
	TileY int

	// TileZ is the tile Z index.
	TileZ int

	// Width is the tile width in samples.
	Width int

	// Height is the tile height in samples.
	Height int

	// Depth is the tile depth in samples.
	Depth int

	// Components contains per-component data.
	Components []*TileComponent3D
}

Tile3D represents a 3D tile in the volumetric data.

type TileComponent3D

type TileComponent3D struct {
	// ComponentIndex is the component index.
	ComponentIndex int

	// Subbands contains the 3D wavelet subbands.
	Subbands []*Subband3D
}

TileComponent3D represents a component within a 3D tile.

type VolumeData

type VolumeData struct {
	// Width is the volume width.
	Width int

	// Height is the volume height.
	Height int

	// Depth is the volume depth (number of slices).
	Depth int

	// Components is the number of components.
	Components int

	// Data contains the volume pixel data.
	// Organized as [z * width * height * components + y * width * components + x * components + c]
	Data []byte
}

VolumeData represents reconstructed 3D volume data.

func (*VolumeData) ExtractSlice

func (v *VolumeData) ExtractSlice(z int) (*Slice, error)

ExtractSlice extracts a 2D slice from the volume.

type VolumeInfo

type VolumeInfo struct {
	// Width is the volume width (X dimension).
	Width int

	// Height is the volume height (Y dimension).
	Height int

	// Depth is the volume depth (Z dimension / number of slices).
	Depth int

	// Components is the number of components.
	Components int

	// BitDepth is the sample bit depth.
	BitDepth int

	// Signed indicates if samples are signed.
	Signed bool

	// TileSize contains the 3D tile dimensions.
	TileSize [3]int

	// DecompositionLevels is the number of wavelet decomposition levels.
	DecompositionLevels int

	// IsReversible is true for lossless compression.
	IsReversible bool
}

VolumeInfo contains information about the 3D volume.

type WaveletInverse3D

type WaveletInverse3D struct {
	// Transform type: 0 = 9/7 irreversible, 1 = 5/3 reversible
	Transform int

	// XYLevels is the number of XY decomposition levels.
	XYLevels int

	// ZLevels is the number of Z decomposition levels.
	ZLevels int
}

WaveletInverse3D performs 3D inverse wavelet transform.

func NewWaveletInverse3D

func NewWaveletInverse3D(transform, xyLevels, zLevels int) *WaveletInverse3D

NewWaveletInverse3D creates a new 3D wavelet inverse transformer.

func (*WaveletInverse3D) Inverse

func (w *WaveletInverse3D) Inverse(width, height, depth int, subbands []*Subband3D) ([]int32, error)

Inverse performs the inverse 3D wavelet transform on the subbands.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL