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 ¶
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.
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.
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 ¶
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 (*Parser) ParseDecomposition ¶
func (p *Parser) ParseDecomposition(data []byte) (*Decomposition3D, error)
ParseDecomposition parses a 3D wavelet decomposition structure.
type Reader ¶
type Reader struct {
// contains filtered or unexported fields
}
Reader reads JP3D volumetric JPEG 2000 codestreams.
func (*Reader) GetVolumeInfo ¶
func (r *Reader) GetVolumeInfo() *VolumeInfo
GetVolumeInfo returns information about the 3D volume.
func (*Reader) SliceCount ¶
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) SliceCount ¶
SliceCount returns the number of 2D slices in the volume.
func (*SIZ3D) TotalTiles ¶
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.