Module coefcode 

Context-modelled coding of quantized wavelet coefficients.

Every coefficient q is binarized as: significance |q| > 0, then |q| > k for k = 1 … KB, an adaptive Elias-gamma escape for |q| − KB − 1, and a sign. Each binary decision is coded by the integer range coder in crate::abac with a probability supplied by a CoefModel:

• HandModel: classic hand-designed contexts — subband class (level × orientation), causal neighbour activity in the same band, and the parent coefficient’s neighbourhood one level up — each indexing a two-rate adaptive BitModel;
• the learned models in crate::learned, which predict the bins from the same Feat vector with a fixed-point network.

Encoder and decoder run the same traversal (code_bands) through the Bits trait, so the context computation cannot drift between them.

Structs

Feat

Context features of one coefficient — all causal (already coded).

HandModel

Hand-designed context model (adaptive bit models per context).

Meter

Cost meter: models adapt exactly as in the real coder, ideal code lengths are tallied per Bits::tag.

Pred

Per-band causal linear predictor of the quantized value (integer weights, Q12). Smooth fields leave highpass bands smooth along their lowpass axes (neighbour correlation ≈ 0.9) and anticorrelated (≈ −0.5) along the highpass axis — structure significance coders such as SPECK leave on the table. The coder codes q − pred; contexts are computed on the residuals.

Constants

CAP

Neighbour magnitudes are capped at this before use.

KB

Unary magnitude bins after significance (|q| > 1 … |q| > KB).

NCLASS

Number of subband classes: 3 level groups × 3 orientation counts + LL.

NE

Magnitude-scale classes (see mag_scale).

NSV

Signed context values per coefficient.

NTAP

Number of in-band linear-prediction taps: W, N, U, NW, UW, UN, parent.

PSHIFT

Fixed-point shift of predictor weights (Q12).

Traits

Bits

Symmetric encode/decode of single decisions.

CoefModel

A probability model for one quantized coefficient.

Functions

activity

Neighbour activity used by the hand model.

band_class

Subband class of a band.

code_bands

Code (encode or decode) every band of q (volume layout) in pyramid order with per-band predictors. When decoding, q must be zeroed and is filled in.

code_bands_tiled

code_bands with a tile layer: at the start of each band a flag per tile (context: band class × previous tile’s flag) says whether any residual in it is nonzero, and the coefficients of dead tiles are skipped (residual 0, value = prediction). Large all-zero regions then cost one flag per tile instead of one significance decision per coefficient. live is tile_live when encoding and ignored (decoded) otherwise.

decode_hand

Decode what encode_hand produced.

encode_hand

Encode q with the hand model; returns the arithmetic-coded bytes.

features

Gather the features of position (z, y, x) in band bi.

fit_predictors

Fit per-band predictors by least squares on the quantized values the decoder will see, and keep a band’s predictor only when it lowers the Σ log₂(1+|r|) cost proxy by > 2%.

mag_scale

Expected-magnitude class ⌊log₂(1 + 2μ)⌋ from the weighted mean μ of the causal neighbours’ and parent’s magnitudes (an adaptive-Golomb parameter: the low e − 2 bits of |q| − 1 are coded near-raw).

read_preds

Parse predictors for nbands bands.

tile_live

Per band, which tiles hold a nonzero residual (encoder side of code_bands_tiled).

visit

Visit every coefficient in coding order: f(features, residual) (for training and analysis).

write_preds

Serialize predictors.