Documentation
¶
Overview ¶
Package trellis implements trellis quantization for JPEG 2000 Part 2 (JPX).
Trellis quantization is an advanced quantization technique that uses Viterbi-like path decoding to find the optimal quantization values across a sequence of coefficients. This approach considers the dependencies between adjacent coefficients and finds a globally optimal solution for rate-distortion trade-off.
Unlike scalar quantization used in JPEG 2000 Part 1, trellis quantization: - Models the encoding cost of coefficient transitions - Uses dynamic programming to find optimal paths through the trellis - Achieves better rate-distortion performance at the same bitrate
The trellis has multiple states representing possible quantization levels, and transitions between states have associated costs based on: - Distortion (difference between original and quantized values) - Rate (bits needed to encode the transition)
Integration with EBCOT:
Trellis quantization integrates with the EBCOT (Embedded Block Coding with Optimized Truncation) tier-1 coder. After wavelet transform coefficients are computed, trellis quantization can be applied before EBCOT encoding to optimize the quantization indices for better coding efficiency.
Usage:
decoder := trellis.NewDecoder(8) // 8 states
decoded, err := decoder.DecodeCodeBlock(codeBlock)
if err != nil {
// handle error
}
Security Considerations:
The trellis decoder validates input dimensions against security limits defined in the security package. Invalid or oversized inputs return errors rather than panicking.
Index ¶
- Constants
- Variables
- type Decoder
- func (d *Decoder) CalculateDistortion(original, quantized int32) float64
- func (d *Decoder) CalculateRDCost(original, quantized int32, rate, lambda float64) float64
- func (d *Decoder) CalculateTotalRDCost(original, quantized []int32, lambda float64) float64
- func (d *Decoder) DecodeCodeBlock(cb *ebcot.CodeBlock) ([]int32, error)
- func (d *Decoder) EstimateBits(quantized []int32) float64
- func (d *Decoder) FindOptimalPath(coefficients []int32, lambda float64) ([]int32, error)
- func (d *Decoder) GetTransitionProbabilities(state int) []float64
- func (d *Decoder) IsInitialized() bool
- func (d *Decoder) NumStates() int
- type DecoderConfig
- type PathNode
- type State
- type Transition
Constants ¶
const ( // MinStates is the minimum number of trellis states. MinStates = 2 // MaxStates is the maximum number of trellis states allowed. MaxStates = 256 // MaxCoefficients is the maximum number of coefficients in a path. MaxCoefficients = 1 << 20 // 1 million coefficients // MaxPathLength is the maximum trellis path length. MaxPathLength = 65536 // DefaultStates is the default number of states if not specified. DefaultStates = 8 // DefaultStepSize is the default quantization step size. DefaultStepSize = 8 // DefaultLambda is the default rate-distortion trade-off parameter. DefaultLambda = 0.5 )
Security limits for trellis quantization.
Variables ¶
var ( // ErrInvalidCodeBlock indicates an invalid or nil code block was provided. ErrInvalidCodeBlock = errors.New("trellis: invalid code block") // ErrInvalidStates indicates an invalid number of states was specified. ErrInvalidStates = errors.New("trellis: invalid number of states") // ErrInvalidDimensions indicates coefficient array has invalid dimensions. ErrInvalidDimensions = errors.New("trellis: invalid coefficient dimensions") // ErrPathTooLong indicates the path exceeds maximum allowed length. ErrPathTooLong = errors.New("trellis: path length exceeds maximum") // ErrTooManyCoefficients indicates too many coefficients provided. ErrTooManyCoefficients = errors.New("trellis: too many coefficients") // ErrNotInitialized indicates the decoder was not properly initialized. ErrNotInitialized = errors.New("trellis: decoder not initialized") // ErrInvalidLambda indicates an invalid lambda value. ErrInvalidLambda = errors.New("trellis: invalid lambda value") )
Errors returned by trellis quantization.
Functions ¶
This section is empty.
Types ¶
type Decoder ¶
type Decoder struct {
// contains filtered or unexported fields
}
Decoder implements trellis quantization using Viterbi-like path decoding.
func NewDecoder ¶
NewDecoder creates a new trellis decoder with the specified number of states.
func NewDecoderWithConfig ¶
func NewDecoderWithConfig(config *DecoderConfig) (*Decoder, error)
NewDecoderWithConfig creates a new decoder with custom configuration.
func (*Decoder) CalculateDistortion ¶
CalculateDistortion computes the distortion between original and quantized values.
func (*Decoder) CalculateRDCost ¶
CalculateRDCost computes the rate-distortion cost.
func (*Decoder) CalculateTotalRDCost ¶
CalculateTotalRDCost computes the total RD cost for a quantization path.
func (*Decoder) DecodeCodeBlock ¶
DecodeCodeBlock applies trellis quantization to an EBCOT code block.
func (*Decoder) EstimateBits ¶
EstimateBits estimates the number of bits needed to encode quantized coefficients.
func (*Decoder) FindOptimalPath ¶
FindOptimalPath finds the optimal quantization path for given coefficients.
func (*Decoder) GetTransitionProbabilities ¶
GetTransitionProbabilities returns the transition probabilities from a state.
func (*Decoder) IsInitialized ¶
IsInitialized returns whether the decoder is properly initialized.
type DecoderConfig ¶
type DecoderConfig struct {
// NumStates is the number of states in the trellis.
NumStates int
// StepSize is the base quantization step size.
StepSize int32
// Lambda is the rate-distortion trade-off parameter.
// Higher lambda favors lower rate (more compression).
Lambda float64
// DeadZone enables dead-zone quantization for small coefficients.
DeadZone bool
}
DecoderConfig holds configuration for the trellis decoder.
func DefaultConfig ¶
func DefaultConfig() *DecoderConfig
DefaultConfig returns a default decoder configuration.
type PathNode ¶
type PathNode struct {
// State is the state index at this position.
State int
// Value is the quantized coefficient value.
Value int32
// Distortion is the distortion at this node.
Distortion float64
// Rate is the estimated bit cost at this node.
Rate float64
}
PathNode represents a node in the Viterbi path.
type State ¶
type State struct {
// Index is the state index (0 to NumStates-1).
Index int
// Level is the quantization level associated with this state.
Level int32
// PathCost is the accumulated path cost to reach this state.
PathCost float64
// PrevState is the index of the previous state in the optimal path.
PrevState int
}
State represents a single state in the trellis.
type Transition ¶
type Transition struct {
// From is the source state index.
From int
// To is the destination state index.
To int
// Cost is the transition cost (rate component).
Cost float64
// Probability is the transition probability.
Probability float64
}
Transition represents a transition between two states.
Source Files