Module img 

Overfitted image codec (Phase 2, Track D): Cool-chic 5 style decoder in exact 32-bit integer arithmetic, so the CPU reference and the GPU kernels ([crate::imggpu]) decode the same bytes to the same pixels.

The encoder side is the Cool-chic 5 reference (PyTorch, per-image overfitting); tools/coolchic/export_cc.py dumps a trained image as a Ccx file (integer latents + dequantized nets). encode turns that into a TCI1 stream:

• Nets (ARM, IFCEs, upsampling, synthesis): each tensor as its quantization exponent s plus integers k = v·2^s (zigzag varints), then fixed point with a per-layer weight precision fw chosen by the encoder so that no accumulation leaves i32 on this image (checked in i64; the decoder re-checks).
• Latents: per grid (coarse → fine), Laplace probabilities from the integer ARM (spatial causal context + IFCE inter-feature context), quantized to NFB μ-fraction × NLB log-scale buckets, coded with 16-bit-word rANS. Rows are spread over lanes independent rANS streams and decoded in a wavefront (t = x + s·y, s from the context template), so every lane advances in lockstep; optional column tiles (tile_w) cut contexts at tile borders for more parallel blocks.
• Synthesis: learned separable upsampling pyramid, then the synthesis MLP / 3×3 residual convs, all QA-bit fixed point; pixels are clamp(⌊255·v⌉, 0, 255).

Structs

Ccx

A model exported by export_cc.py: named f64 arrays with shapes.

Conv

A synthesis convolution (k×k, replicate padding).

Filt

A symmetric 1-D upsampling / pre-concatenation filter.

Guard

Overflow guard: every accumulation is computed in i64 and must fit i32 (so the GPU’s wrapping i32 gives the same bits).

Layout

Wavefront layout of one grid: tiles of th × tw, lanes lanes per tile.

Lin

One linear layer out × inp (w[o·inp + i]), fixed point.

Mlp

ARM / IFCE MLP: hidden ReLU layers (square hidden layers residual inside the ReLU when residual), a linear output layer, and an optional linear stabiliser branch over the input added to the output.

Model

Everything the decoder needs except the latent payload.

Parsed

Parsed stream.

QT

A quantized tensor: values k · 2^{−s}.

RansDec

Decoder side of one lane.

Stats

Encoder statistics.

Constants

CTX_ORDER

Cool-chic’s context priority order (get_priority_order, 9×9 causal mask) as (dy, dx).

FB_SHIFT

μ-fraction bucket width 2^FB_SHIFT / 256.

LB_SHIFT

Log-scale bucket width 2^LB_SHIFT / 256.

MAGIC

Stream magic.

NFB

μ-fraction buckets.

NLB

Log-scale buckets over ln b ∈ [−5, 5].

NSYM

Symbols per table.

PB

rANS probability precision.

QA

Fractional bits of upsampling / synthesis activations.

QA_ARM

Fractional bits of ARM activations (latents enter as v << QA_ARM).

R

Residual alphabet r ∈ [−R, R] plus two escapes.

Functions

arm_input

Gather the ARM input for global (y, x) of a grid (values so far in lat, context cut at the tile border) into buf (Q8).

bucket

(base, table offset) from the ARM output (μ, ln b in Q8).

dec_sym

Decode one latent value with the table at off (cum[0..=NSYM]).

decode

Full CPU decode: stream → RGB8 (h·w·3). Errors if any accumulation leaves i32 (the GPU would wrap).

decode_latents

Decode the latent grids (finest first) on the CPU. Lane l’s rANS state runs on across grids (coarse → fine).

encode

Encode an export into a TCI1 stream with the given lanes / tile width.

ifce_ctx

Inter-feature context of grid g ([h·w][nifce], Q8) from the already-decoded coarser grids, or empty when the grid has no IFCE.

parse

Parse a TCI1 stream.

psnr

PSNR (dB) of two RGB8 buffers.

segment_graph

A synthesis segment: one (possibly 3×3) conv followed by 1×1 convs. Params: the first conv’s taps [cin][k][k] (replicate-padded gather), then (if it is residual) its cin centre values; when last, then the stab input channels. Outputs: the segment’s channels, or (when last) the three 8-bit pixel values.

segments

Synthesis split into segments (each starts at a 3×3 conv or the input).

slope_of

Smallest s with t(y, x) = x + s·y strictly after every context.

synthesize

Synthesis → interleaved RGB8.

tables

Laplace CDF tables [fb][lb][sym+1] (cumulative, Q(PB)), built with plain IEEE f64 ops on the host and shared by both decoders.

upsample

Upsampling pyramid → dense synthesis input [C][h·w] (Q(QA)).