hierarchical

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: 3 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// MarkerDHP is the Define Hierarchical Progression marker (0xDE)
	MarkerDHP = 0xDE

	// MarkerEXP is the Expand Reference Components marker (0xDF)
	MarkerEXP = 0xDF

	// MarkerSOF5 is Differential Sequential DCT, Huffman coding
	MarkerSOF5 = 0xC5

	// MarkerSOF6 is Differential Progressive DCT, Huffman coding
	MarkerSOF6 = 0xC6

	// MarkerSOF7 is Differential Lossless, Huffman coding
	MarkerSOF7 = 0xC7

	// MarkerSOF13 is Differential Sequential DCT, Arithmetic coding
	MarkerSOF13 = 0xCD

	// MarkerSOF14 is Differential Progressive DCT, Arithmetic coding
	MarkerSOF14 = 0xCE

	// MarkerSOF15 is Differential Lossless, Arithmetic coding
	MarkerSOF15 = 0xCF
)

Marker constants for hierarchical JPEG

View Source 
const (
	// MaxHierarchyLevels is the maximum number of hierarchy levels allowed
	MaxHierarchyLevels = 16

	// MaxFrameSize is the maximum pixels in a single frame (256M)
	MaxFrameSize = 268435456

	// MaxExpansionFactor is the maximum expansion factor (8x in each direction)
	MaxExpansionFactor = 8

	// MaxReferenceFrameSize is the maximum reference frame buffer size (512MB)
	MaxReferenceFrameSize = 536870912

	// MaxIterationsPerFrame limits processing iterations per frame
	MaxIterationsPerFrame = 268435456
)

Constants for hierarchical JPEG limits

Variables

View Source 
var (
	ErrInvalidMarker     = fmt.Errorf("invalid marker")
	ErrNoReferenceFrame  = fmt.Errorf("no reference frame available")
	ErrFrameSizeMismatch = fmt.Errorf("frame size mismatch")
	ErrMaxHierarchy      = fmt.Errorf("maximum hierarchy levels exceeded")
)

Errors for hierarchical coding

Functions

func FrameTypeName 

func FrameTypeName(frameType int) string

FrameTypeName returns a human-readable name for a differential SOF type.

func IsArithmeticFrame 

func IsArithmeticFrame(marker int) bool

IsArithmeticFrame returns true if the marker uses arithmetic coding.

func IsDifferentialFrame 

func IsDifferentialFrame(marker int) bool

IsDifferentialFrame returns true if the marker is a differential SOF type.

func IsLosslessFrame 

func IsLosslessFrame(marker int) bool

IsLosslessFrame returns true if the marker uses lossless coding.

func IsProgressiveFrame 

func IsProgressiveFrame(marker int) bool

IsProgressiveFrame returns true if the marker uses progressive DCT.

func RouteFrameType 

func RouteFrameType(frameType int) (codingMode, entropyMode string, err error)

RouteFrameType determines the base decoder type for a differential frame. Returns strings indicating the base coding mode.

Types

type DHP 

type DHP struct {
	// Precision is the sample precision in bits (8 or 12 typically)
	Precision int

	// Height is the final image height in pixels
	Height int

	// Width is the final image width in pixels
	Width int

	// ComponentCount is the number of image components
	ComponentCount int

	// Components holds the component specifications
	Components []DHPComponent
}

DHP represents a Define Hierarchical Progression marker (0xDE). This marker defines the overall image dimensions for the hierarchical sequence.

type DHPComponent 

type DHPComponent struct {
	// ID is the component identifier (1-255)
	ID int

	// HorizontalSampling is the horizontal sampling factor (1-4)
	HorizontalSampling int

	// VerticalSampling is the vertical sampling factor (1-4)
	VerticalSampling int

	// QuantTableID is the quantization table selector (0-3)
	QuantTableID int
}

DHPComponent represents a component in the DHP marker.

type DefaultValidator 

type DefaultValidator struct{}

DefaultValidator implements Validator with standard checks.

func NewValidator 

func NewValidator() *DefaultValidator

NewValidator creates a new default validator.

func (*DefaultValidator) SafeAdd 

func (*DefaultValidator) SafeAdd(a, b int) (int, error)

SafeAdd performs addition with overflow checking.

func (*DefaultValidator) SafeMultiply 

func (*DefaultValidator) SafeMultiply(a, b int) (int, error)

SafeMultiply performs multiplication with overflow checking.

func (*DefaultValidator) ValidateDimensions 

func (*DefaultValidator) ValidateDimensions(width, height int) error

ValidateDimensions validates width and height.

func (*DefaultValidator) ValidateExpansionFactors 

func (*DefaultValidator) ValidateExpansionFactors(expandH, expandV int) error

ValidateExpansionFactors validates EXP marker expansion factors.

func (*DefaultValidator) ValidateFrameType 

func (*DefaultValidator) ValidateFrameType(frameType int) error

ValidateFrameType validates the differential SOF type.

func (*DefaultValidator) ValidatePrecision 

func (*DefaultValidator) ValidatePrecision(precision int) error

ValidatePrecision validates sample precision (8 or 12 typically, 2-16 for lossless).

type DifferentialDecoder 

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

DifferentialDecoder decodes differential frames in hierarchical JPEG. It manages the reference frame buffer and applies differential values to reconstruct the final image.

func NewDifferentialDecoder 

func NewDifferentialDecoder(validator Validator) *DifferentialDecoder

NewDifferentialDecoder creates a new differential decoder.

func (*DifferentialDecoder) ApplyDifferential 

func (d *DifferentialDecoder) ApplyDifferential(reference, differential []int) ([]int, error)

ApplyDifferential applies differential values to the reference frame.

Per T.81 hierarchical mode, each reconstructed sample is the reference sample plus the differential, taken modulo 2^(P+1) where P is the sample precision. The mask is applied unconditionally here so that precision > 8 wraps per the standard; at precision ≤ 8 the mask is a no-op for non-negative 8-bit samples and is retained for consistency.

func (*DifferentialDecoder) ApplyExpansion 

func (d *DifferentialDecoder) ApplyExpansion(exp *EXP) error

ApplyExpansion applies EXP marker expansion to the reference frame.

func (*DifferentialDecoder) DecodeDifferentialFrame 

func (d *DifferentialDecoder) DecodeDifferentialFrame(frame *DifferentialFrame, differential []int) ([]int, error)

DecodeDifferentialFrame decodes a complete differential frame. This method: 1. Checks if reference frame needs resizing 2. Applies differential values to reference 3. Updates the reference frame for the next hierarchy level

func (*DifferentialDecoder) DecodeInitialFrame 

func (d *DifferentialDecoder) DecodeInitialFrame(differential []int) ([]int, error)

DecodeInitialFrame decodes the initial frame of a hierarchical sequence. For the initial frame, there is no reference, so differential values are used directly as the absolute values.

func (*DifferentialDecoder) GetHierarchyLevel 

func (d *DifferentialDecoder) GetHierarchyLevel() int

GetHierarchyLevel returns the current hierarchy level.

func (*DifferentialDecoder) GetReferenceFrame 

func (d *DifferentialDecoder) GetReferenceFrame() *ReferenceFrameBuffer

GetReferenceFrame returns the current reference frame buffer.

func (*DifferentialDecoder) InitializeReferenceFrame 

func (d *DifferentialDecoder) InitializeReferenceFrame(width, height, componentCount, precision int) error

InitializeReferenceFrame initializes the reference frame buffer with the given dimensions.

func (*DifferentialDecoder) IsInitialFrame 

func (d *DifferentialDecoder) IsInitialFrame() bool

IsInitialFrame returns true if no frames have been processed yet.

func (*DifferentialDecoder) Reset 

func (d *DifferentialDecoder) Reset()

Reset resets the decoder state for processing a new hierarchical sequence.

func (*DifferentialDecoder) SetDHP 

func (d *DifferentialDecoder) SetDHP(dhp *DHP) error

SetDHP sets the DHP (Define Hierarchical Progression) parameters. This must be called before processing differential frames.

func (*DifferentialDecoder) SetPrecision 

func (d *DifferentialDecoder) SetPrecision(precision int) error

SetPrecision sets the sample precision used by modular differential add. Callers that drive ApplyDifferential directly (outside the frame-decoder entry points) must call this to activate the correct 2^(P+1) mask.

type DifferentialFrame 

type DifferentialFrame struct {
	// FrameType is the SOF marker type (SOF5, SOF6, SOF7, SOF13, SOF14, SOF15)
	FrameType int

	// Precision is the sample precision in bits
	Precision int

	// Height is the frame height in pixels
	Height int

	// Width is the frame width in pixels
	Width int

	// Components holds the component specifications
	Components []FrameComponent

	// IsArithmetic indicates if arithmetic coding is used
	IsArithmetic bool

	// IsProgressive indicates if progressive DCT is used
	IsProgressive bool

	// IsLossless indicates if lossless coding is used
	IsLossless bool
}

DifferentialFrame represents a frame in the hierarchical sequence.

type EXP 

type EXP struct {
	// ExpandHorizontal specifies horizontal expansion (0=none, 1=2x)
	ExpandHorizontal int

	// ExpandVertical specifies vertical expansion (0=none, 1=2x)
	ExpandVertical int
}

EXP represents an Expand Reference Components marker (0xDF). This marker specifies expansion parameters for the reference frame.

type FrameComponent 

type FrameComponent struct {
	// ID is the component identifier (1-255)
	ID int

	// HorizontalSampling is the horizontal sampling factor (1-4)
	HorizontalSampling int

	// VerticalSampling is the vertical sampling factor (1-4)
	VerticalSampling int

	// QuantTableID is the quantization table selector (0-3)
	QuantTableID int
}

FrameComponent represents a component in a differential frame.

type HierarchicalDecoder 

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

HierarchicalDecoder coordinates decoding of a complete hierarchical JPEG.

func NewHierarchicalDecoder 

func NewHierarchicalDecoder(validator Validator) *HierarchicalDecoder

NewHierarchicalDecoder creates a new hierarchical decoder.

func (*HierarchicalDecoder) DecodeFrame 

func (h *HierarchicalDecoder) DecodeFrame(frame *DifferentialFrame, differential []int) ([]int, error)

DecodeFrame decodes a single differential frame.

func (*HierarchicalDecoder) GetFinalDimensions 

func (h *HierarchicalDecoder) GetFinalDimensions() (width, height int)

GetFinalDimensions returns the final image dimensions. If DHP is set, returns DHP dimensions; otherwise returns last frame dimensions.

func (*HierarchicalDecoder) GetFrameCount 

func (h *HierarchicalDecoder) GetFrameCount() int

GetFrameCount returns the number of frames decoded so far.

func (*HierarchicalDecoder) Reset 

func (h *HierarchicalDecoder) Reset()

Reset resets the decoder for a new hierarchical sequence.

func (*HierarchicalDecoder) SetDHP 

func (h *HierarchicalDecoder) SetDHP(dhp *DHP) error

SetDHP sets the DHP marker parameters.

func (*HierarchicalDecoder) SetPendingExpansion 

func (h *HierarchicalDecoder) SetPendingExpansion(exp *EXP)

SetPendingExpansion sets an EXP marker to be applied before the next frame.

type HierarchicalParser 

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

HierarchicalParser parses DHP and EXP markers for hierarchical JPEG.

func NewHierarchicalParser 

func NewHierarchicalParser(validator Validator) *HierarchicalParser

NewHierarchicalParser creates a new hierarchical parser with the given validator.

func (*HierarchicalParser) DetectDifferentialFrames 

func (p *HierarchicalParser) DetectDifferentialFrames(data []byte) []int

DetectDifferentialFrames returns a list of differential SOF markers found in the data.

func (*HierarchicalParser) DetectHierarchicalMode 

func (p *HierarchicalParser) DetectHierarchicalMode(data []byte) bool

DetectHierarchicalMode checks if a JPEG uses hierarchical mode by looking for DHP marker. Returns true if hierarchical mode is detected.

func (*HierarchicalParser) ParseDHP 

func (p *HierarchicalParser) ParseDHP(r io.Reader) (*DHP, error)

ParseDHP parses a DHP (Define Hierarchical Progression) marker. The reader should be positioned at the start of the marker (0xFF 0xDE).

DHP marker structure (ITU-T T.81 Section B.3.2): 

Marker: 0xFF 0xDE (2 bytes)
Length: 2 bytes (includes length field, excludes marker)
Precision: 1 byte (sample precision in bits)
Height: 2 bytes (final image height)
Width: 2 bytes (final image width)
Component Count: 1 byte (number of components)
Component Specs: 3 bytes each (ID, sampling factors, quant table)

func (*HierarchicalParser) ParseDifferentialSOF 

func (p *HierarchicalParser) ParseDifferentialSOF(r io.Reader, expectedMarker byte) (*DifferentialFrame, error)

ParseDifferentialSOF parses a differential SOF marker (SOF5, SOF6, SOF7, SOF13, SOF14, SOF15). The reader should be positioned at the start of the marker.

The structure is the same as non-differential SOF markers, but the decoded coefficients/samples are differential values to be added to the reference frame.

func (*HierarchicalParser) ParseEXP 

func (p *HierarchicalParser) ParseEXP(r io.Reader) (*EXP, error)

ParseEXP parses an EXP (Expand Reference Components) marker. The reader should be positioned at the start of the marker (0xFF 0xDF).

EXP marker structure (ITU-T T.81 Section B.3.3): 

Marker: 0xFF 0xDF (2 bytes)
Length: 2 bytes (always 3, includes length field)
Expand: 1 byte (Eh in high nibble, Ev in low nibble)

Eh and Ev can be 0 (no expansion) or 1 (2x expansion).

func (*HierarchicalParser) ParseSOF5 

func (p *HierarchicalParser) ParseSOF5(r io.Reader) (*DifferentialFrame, error)

ParseSOF5 parses a SOF5 (Differential Sequential DCT, Huffman) marker.

func (*HierarchicalParser) ParseSOF6 

func (p *HierarchicalParser) ParseSOF6(r io.Reader) (*DifferentialFrame, error)

ParseSOF6 parses a SOF6 (Differential Progressive DCT, Huffman) marker.

func (*HierarchicalParser) ParseSOF7 

func (p *HierarchicalParser) ParseSOF7(r io.Reader) (*DifferentialFrame, error)

ParseSOF7 parses a SOF7 (Differential Lossless, Huffman) marker.

func (*HierarchicalParser) ParseSOF13 

func (p *HierarchicalParser) ParseSOF13(r io.Reader) (*DifferentialFrame, error)

ParseSOF13 parses a SOF13 (Differential Sequential DCT, Arithmetic) marker.

func (*HierarchicalParser) ParseSOF14 

func (p *HierarchicalParser) ParseSOF14(r io.Reader) (*DifferentialFrame, error)

ParseSOF14 parses a SOF14 (Differential Progressive DCT, Arithmetic) marker.

func (*HierarchicalParser) ParseSOF15 

func (p *HierarchicalParser) ParseSOF15(r io.Reader) (*DifferentialFrame, error)

ParseSOF15 parses a SOF15 (Differential Lossless, Arithmetic) marker.

type ReferenceFrameBuffer 

type ReferenceFrameBuffer struct {
	// Data holds the pixel/coefficient data
	Data []int

	// Width is the current frame width
	Width int

	// Height is the current frame height
	Height int

	// ComponentCount is the number of components
	ComponentCount int

	// Precision is the sample precision in bits
	Precision int

	// IsInitialized indicates if there is valid reference data
	IsInitialized bool
}

ReferenceFrameBuffer manages reference frames between hierarchy levels.

func NewReferenceFrameBuffer 

func NewReferenceFrameBuffer(width, height, componentCount, precision int) (*ReferenceFrameBuffer, error)

NewReferenceFrameBuffer creates a new reference frame buffer.

func (*ReferenceFrameBuffer) Expand 

func (r *ReferenceFrameBuffer) Expand(expandH, expandV bool) (*ReferenceFrameBuffer, error)

Expand performs horizontal and/or vertical 2x expansion of the reference frame using the T.81 J.1.1 weighted-averaging upsample filter.

Expansion is applied separably per component: the 1D J.1.1 filter is first applied along rows (when expandH is true) and then along columns of the intermediate result (when expandV is true).

func (*ReferenceFrameBuffer) GetPixel 

func (r *ReferenceFrameBuffer) GetPixel(x, y, component int) int

GetPixel retrieves a pixel value from the reference frame. Returns 0 if coordinates are out of bounds or buffer not initialized.

func (*ReferenceFrameBuffer) Resize 

func (r *ReferenceFrameBuffer) Resize(newWidth, newHeight int) (*ReferenceFrameBuffer, error)

Resize resizes the reference frame to new dimensions. Used when frame sizes change between hierarchy levels.

func (*ReferenceFrameBuffer) SetData 

func (r *ReferenceFrameBuffer) SetData(data []int) error

SetData sets the reference frame data.

func (*ReferenceFrameBuffer) SetPixel 

func (r *ReferenceFrameBuffer) SetPixel(x, y, component, value int) error

SetPixel sets a pixel value in the reference frame.

type Validator 

type Validator interface {
	// ValidatePrecision validates sample precision.
	ValidatePrecision(precision int) error

	// ValidateDimensions validates width and height.
	ValidateDimensions(width, height int) error

	// ValidateExpansionFactors validates EXP marker expansion factors.
	ValidateExpansionFactors(expandH, expandV int) error

	// ValidateFrameType validates the differential SOF type.
	ValidateFrameType(frameType int) error

	// SafeMultiply performs multiplication with overflow checking.
	SafeMultiply(a, b int) (int, error)

	// SafeAdd performs addition with overflow checking.
	SafeAdd(a, b int) (int, error)
}

Validator provides validation for hierarchical JPEG parameters.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.