Documentation
¶
Overview ¶
Package jpx provides JPEG 2000 Part 2 (JPX) extended file format support.
JPX (ISO/IEC 15444-2) extends the base JP2 file format with additional features for more complex imaging applications:
Extended Features ¶
Color Spaces:
- Extended enumerated color spaces (e-sRGB, ROMM-RGB, etc.)
- Any ICC profile support (not just restricted profiles)
- Multiple color specification boxes
Animation and Composition:
- Multiple composition layers
- Layer positioning and opacity
- Animation timing and frame sequencing
Trellis Quantization:
- Improved rate-distortion optimization
- Enhanced quality at lower bit rates
Multiple Codestreams:
- Multiple embedded JPEG 2000 codestreams
- Fragment tables for external data references
Usage ¶
To parse a JPX file:
reader := jpx.NewReader(data)
if err := reader.Parse(); err != nil {
return err
}
jpxFile := reader.GetJPXFile()
for _, cs := range jpxFile.ColourSpecs {
fmt.Printf("Color method: %d\n", cs.Method)
}
To extract the primary codestream:
codestream, err := reader.ExtractCodestream()
if err != nil {
return err
}
Security ¶
This package enforces security limits to prevent denial-of-service attacks:
- Maximum box nesting depth: 32
- Maximum box count: 10,000
- Maximum box size: 1 GB
- Maximum composition layers: 1,000
- Maximum animation frames: 100,000
All integer conversions use the internal/safeconv package to prevent integer overflow vulnerabilities.
Compatibility ¶
JPX files are backward-compatible with JP2. A JPX reader can read JP2 files, but JP2 readers may not be able to read all JPX features. The Reader Requirements (rreq) box indicates which features must be supported to correctly decode the file.
Package jpx provides JPEG 2000 Part 2 (JPX) extended file format support. JPX extends the JP2 file format with additional features including: - Extended color spaces and ICC profiles - Animation and composition layers - Trellis quantization - Multiple codestreams
This package implements parsing and decoding of JPX-specific box types while maintaining compatibility with the base JP2 format.
Index ¶
- Constants
- Variables
- func Validate(data []byte) error
- type Box
- type ChannelDef
- type ColourSpec
- type ComponentMapping
- type CompositionLayer
- type FragmentEntry
- type Frame
- type ImageInfo
- type JPXFile
- type Layer
- type Palette
- type Reader
- func (r *Reader) ExtractCodestream() ([]byte, error)
- func (r *Reader) GetColourSpaces() []*ColourSpec
- func (r *Reader) GetComposition() *CompositionLayer
- func (r *Reader) GetImageInfo() (*ImageInfo, error)
- func (r *Reader) GetJPXFile() *JPXFile
- func (r *Reader) IsJPX() bool
- func (r *Reader) Parse() error
- func (r *Reader) Verify() error
- type ReaderRequirements
- type Resolution
- type TrellisQuantization
Constants ¶
const ( // Base JP2 box types (for reference and compatibility) BoxTypeSignature = 0x6A502020 // 'jP ' - JP2 Signature BoxTypeFileType = 0x66747970 // 'ftyp' - File Type BoxTypeJP2Header = 0x6A703268 // 'jp2h' - JP2 Header BoxTypeImageHeader = 0x69686472 // 'ihdr' - Image Header BoxTypeColourSpec = 0x636F6C72 // 'colr' - Colour Specification BoxTypeCodestream = 0x6A703263 // 'jp2c' - Contiguous Codestream // JPX-specific box types BoxTypeReaderReq = 0x72726571 // 'rreq' - Reader Requirements BoxTypeChannelDef = 0x63646566 // 'cdef' - Channel Definition BoxTypeResolution = 0x72657320 // 'res ' - Resolution BoxTypeCaptureRes = 0x72657363 // 'resc' - Capture Resolution BoxTypeDefaultDisplayRes = 0x72657364 // 'resd' - Default Display Resolution BoxTypePalette = 0x70636C72 // 'pclr' - Palette BoxTypeComponentMapping = 0x636D6170 // 'cmap' - Component Mapping BoxTypeCompositionOptions = 0x636F7074 // 'copt' - Composition Options BoxTypeInstructionSet = 0x696E7374 // 'inst' - Instruction Set BoxTypeCompositionLayer = 0x6A706C68 // 'jplh' - Compositing Layer Header BoxTypeCodestreamReg = 0x63726567 // 'creg' - Codestream Registration BoxTypeROIDescription = 0x726F6964 // 'roid' - ROI Description BoxTypeAssociation = 0x61736F63 // 'asoc' - Association BoxTypeLabel = 0x6C626C20 // 'lbl ' - Label BoxTypeNumberList = 0x6E6C7374 // 'nlst' - Number List BoxTypeOpacity = 0x6F706374 // 'opct' - Opacity BoxTypeFragmentTable = 0x66746262 // 'ftbl' - Fragment Table BoxTypeFragmentList = 0x666C7374 // 'flst' - Fragment List BoxTypeCrossReference = 0x63726566 // 'cref' - Cross Reference BoxTypeDesiredReproduct = 0x64726570 // 'drep' - Desired Reproductions BoxTypeGraphicsTechnology = 0x67747473 // 'gtts' - Graphics Technology Standard Output BoxTypeUUIDInfo = 0x75696E66 // 'uinf' - UUID Info BoxTypeUUID = 0x75756964 // 'uuid' - UUID BoxTypeUUIDList = 0x756C7374 // 'ulst' - UUID List BoxTypeURL = 0x75726C20 // 'url ' - URL BoxTypeFree = 0x66726565 // 'free' - Free space BoxTypeMediaData = 0x6D646174 // 'mdat' - Media Data )
JPX box types extending JP2. These are in addition to the base JP2 box types.
const ( ColourMethodEnumCS = 1 // Enumerated Colourspace ColourMethodRestrictedICC = 2 // Restricted ICC Profile (JP2) ColourMethodAnyICC = 3 // Any ICC Profile (JPX extension) ColourMethodVendor = 4 // Vendor-specific (JPX extension) )
Colour specification methods.
const ( ColourSpaceUnknown = 0 ColourSpaceBilevel1 = 1 // Bi-level (0=white, 1=black) ColourSpaceBilevel2 = 2 // Bi-level (0=black, 1=white) ColourSpaceYCbCr1 = 3 // YCbCr (1) ColourSpaceYCbCr2 = 4 // YCbCr (2) ColourSpaceYCbCr3 = 5 // YCbCr (3) ColourSpacePhotoYCC = 9 // PhotoYCC ColourSpaceCMY = 11 // CMY ColourSpaceCMYK = 12 // CMYK ColourSpaceYCCK = 13 // YCCK ColourSpaceCIELab = 14 // CIELab with D50 illuminant ColourSpaceSRGB = 16 // sRGB ColourSpaceGray = 17 // Greyscale ColourSpaceSYCC = 18 // sYCC (YCbCr) - same as JP2 ColourSpaceYCC = 18 // Alias for sYCC ColourSpaceCIEJab = 19 // CIEJab ColourSpaceESRGB = 20 // e-sRGB (extended sRGB) ColourSpaceROMMRGB = 21 // ROMM-RGB (ProPhoto RGB) ColourSpaceYPbPr60 = 22 // YPbPr (60 Hz) ColourSpaceYPbPr50 = 23 // YPbPr (50 Hz) ColourSpaceESYCC = 24 // e-sYCC )
Enumerated colour spaces. JPX extends JP2 with additional color spaces.
const ( MaxBoxNestingDepth = 32 // Maximum superbox nesting depth MaxBoxCount = 10000 // Maximum number of boxes in file MaxBoxSize = 1 << 30 // Maximum box size (1 GB) MaxCompositionLayers = 1000 // Maximum composition layers MaxAnimationFrames = 100000 // Maximum animation frames MaxColorChannels = 256 // Maximum color channels MaxICCProfileSize = 10 << 20 // Maximum ICC profile size (10 MB) )
Security limits for JPX parsing.
Variables ¶
var ( BrandJP2 = [4]byte{'j', 'p', '2', ' '} // JP2 format BrandJPX = [4]byte{'j', 'p', 'x', ' '} // JPX format )
Brand identifiers for file type detection.
var ( ErrEmptyData = errors.New("jpx: empty data") ErrInvalidBox = errors.New("jpx: invalid box structure") ErrBoxNestingTooDeep = errors.New("jpx: box nesting exceeds maximum depth") ErrTooManyLayers = errors.New("jpx: too many composition layers") ErrTooManyFrames = errors.New("jpx: too many animation frames") ErrBoxTooLarge = errors.New("jpx: box size exceeds maximum") ErrInvalidColorSpace = errors.New("jpx: invalid color space") ErrInvalidMethod = errors.New("jpx: invalid colour method") ErrTruncatedData = errors.New("jpx: truncated data") ErrInvalidTrellis = errors.New("jpx: invalid trellis quantization data") ErrInvalidSignature = errors.New("jpx: invalid file signature") ErrMissingHeader = errors.New("jpx: missing JP2/JPX header") ErrMissingCodestream = errors.New("jpx: missing codestream") ErrInvalidICCProfile = errors.New("jpx: invalid ICC profile") )
Errors for JPX parsing.
var Signature = [4]byte{0x0D, 0x0A, 0x87, 0x0A}
Signature is the JP2/JPX signature box content.
Functions ¶
Types ¶
type Box ¶
type Box struct {
Type uint32 // Box type (4-byte identifier)
Length uint64 // Box length including header
Data []byte // Box content
Children []*Box // For superboxes
Offset int64 // Byte offset in file
}
Box represents a JP2/JPX box structure.
type ChannelDef ¶
type ChannelDef struct {
Index uint16 // Channel index
ChannelType uint16 // 0=color, 1=opacity, 2=premultiplied opacity, 65535=not specified
Association uint16 // Component association (1-based)
}
ChannelDef represents a channel definition from cdef box.
type ColourSpec ¶
type ColourSpec struct {
Method int // Colour specification method
Precedence uint8 // Precedence value
Approx uint8 // Approximation value
EnumCS int // Enumerated colour space (if Method == 1)
ICCProfile []byte // ICC profile data (if Method == 2 or 3)
}
ColourSpec represents a colour specification from colr box.
func ParseColourSpec ¶
func ParseColourSpec(data []byte) (*ColourSpec, error)
ParseColourSpec parses a colour specification from colr box data.
type ComponentMapping ¶
type ComponentMapping struct {
Component uint16 // Component index
MapType uint8 // Mapping type (0=direct, 1=palette)
Palette uint8 // Palette column (if MapType==1)
}
ComponentMapping represents component mapping from cmap box.
type CompositionLayer ¶
type CompositionLayer struct {
Layers []Layer // Individual layers
Frames []Frame // Animation frames (if animated)
}
CompositionLayer represents a composition layer.
func ParseCompositionLayer ¶
func ParseCompositionLayer(data []byte) (*CompositionLayer, error)
ParseCompositionLayer parses composition layer data.
type FragmentEntry ¶
type FragmentEntry struct {
Offset uint64 // Offset in file or URL
Length uint32 // Fragment length
DataRefIdx uint16 // Data reference index (0=this file)
}
FragmentEntry represents a fragment in fragment table.
type Frame ¶
type Frame struct {
Duration uint32 // Frame duration in ticks
TicksPerSecond uint32 // Time base
LayerIdx int // Index of layer for this frame
}
Frame represents an animation frame.
type ImageInfo ¶
type ImageInfo struct {
Width uint32
Height uint32
NumComps uint16
BitsPerComp uint8
Signed bool
ColourSpace int
}
ImageInfo contains image information from JP2/JPX header.
type JPXFile ¶
type JPXFile struct {
Brand [4]byte // File brand (jp2 or jpx)
MinorVersion uint32 // Minor version
Compat [][4]byte // Compatibility list
ImageInfo *ImageInfo // Image information
ColourSpecs []*ColourSpec // Colour specifications
ChannelDefs []*ChannelDef // Channel definitions
Composition *CompositionLayer // Composition information
Palettes []*Palette // Palettes
CompMappings []*ComponentMapping // Component mappings
Codestreams [][]byte // Embedded codestreams
Trellis *TrellisQuantization // Trellis quantization settings
ReaderReq *ReaderRequirements // Reader requirements
CaptureRes *Resolution // Capture resolution
DisplayRes *Resolution // Default display resolution
}
JPXFile represents a parsed JPX file.
type Layer ¶
type Layer struct {
OffsetX int32 // X offset in composition
OffsetY int32 // Y offset in composition
Width uint32 // Layer width
Height uint32 // Layer height
Opacity uint8 // Layer opacity (0-255)
}
Layer represents a single layer in composition.
type Palette ¶
type Palette struct {
NumEntries uint16 // Number of palette entries
NumColumns uint8 // Number of columns (components)
BitDepths []uint8 // Bit depth per column
Signed []bool // Signedness per column
Entries [][]int32 // Palette entries [entry][column]
}
Palette represents a palette definition from pclr box.
type Reader ¶
type Reader struct {
// contains filtered or unexported fields
}
Reader reads and parses JPX file format.
func (*Reader) ExtractCodestream ¶
ExtractCodestream extracts the first codestream from the JPX file.
func (*Reader) GetColourSpaces ¶
func (r *Reader) GetColourSpaces() []*ColourSpec
GetColourSpaces returns all colour specifications.
func (*Reader) GetComposition ¶
func (r *Reader) GetComposition() *CompositionLayer
GetComposition returns composition layer information.
func (*Reader) GetImageInfo ¶
GetImageInfo extracts image information from the JPX header.
func (*Reader) GetJPXFile ¶
GetJPXFile returns the parsed JPX file structure.
type ReaderRequirements ¶
type ReaderRequirements struct {
MaskLength uint8 // Mask length in bytes
FullyUnderstand []byte // Features that must be fully understood
DecodeCompletely []byte // Features that must be decoded completely
StandardFeatures []uint16 // List of standard feature IDs
VendorFeatures [][]byte // List of vendor feature UUIDs
}
ReaderRequirements represents the rreq box contents.
type Resolution ¶
type Resolution struct {
VResNumerator uint16 // Vertical resolution numerator
VResDenominator uint16 // Vertical resolution denominator
HResNumerator uint16 // Horizontal resolution numerator
HResDenominator uint16 // Horizontal resolution denominator
VResExponent int8 // Vertical resolution exponent
HResExponent int8 // Horizontal resolution exponent
}
Resolution represents resolution information.
type TrellisQuantization ¶
type TrellisQuantization struct {
Enabled bool // Whether trellis quantization is enabled
States uint8 // Number of states in trellis
Reserved []byte // Reserved bytes
}
TrellisQuantization represents trellis quantization settings.
func ParseTrellisQuantization ¶
func ParseTrellisQuantization(data []byte) (*TrellisQuantization, error)
ParseTrellisQuantization parses trellis quantization marker data.
Source Files