Module reference 

The committed reference contract of this crate, re-expressed over the crate’s own pipeline.

tools/gen-reference recomputes everything in this module and either writes reference.json (repo root) or verifies the committed copy against the recomputation; CI runs the verify mode on every commit, and CD ships the file with every SDK artifact. Python, Node and Go SDKs test against the same bytes.

File schema (version 1)

Two sections, both sorted by name, two-space indentation, LF line endings, one trailing newline — byte-identical across regenerations:

• digests — one entry per committed tests/fixtures/*.jpg conformance fixture: pith_digest::fnv1a64 over the decoded sample bytes in row-major, channel-interleaved order (the crate’s own output layout, exactly what the .raw companions hold). Digests must match bit-for-bit.
• vectors — the DCT/dequant numerics in the suite’s numeric schema (the pith-math convention): every f64 is its raw IEEE-754 bit pattern as 16-digit lowercase hex, so consumers never see a decimal round-trip. Each vector records exact plus the two tolerance budgets tol_abs/tol_rel (hex f64 like everything else). Verification policy:
  • exact: true — the pipeline is pure integer arithmetic (de-zigzag, dequantize, the islow IDCT transcription), so any correct implementation must reproduce the recorded bits.
  • exact: false — the f64 trig kernel (pith_math::idct2_2d, the orthonormal oracle documented in crate) depends on the platform libm’s sin/cos, which may differ in the last ulp across platforms; verification bounds the per-value error by max(tol_abs, tol_rel · |expected|). The absolute floor (1e-13) covers the cancellation noise of near-zero bins, where platform differences move the value by a few ulps of the summands, not of the tiny result.

Vector input layouts (documented here because the file carries no per-field prose): all inputs are built from integer arithmetic alone, so input generation is itself platform-independent.

• dequant.zigzag.8x8 — input: 64 DQT-payload values in JPEG scan order; output: the same values in natural (row-major) order, i.e. out[ZIGZAG[k]] = in[k].
• dequant.8x8 — input: 64 natural-order coefficients followed by 64 natural-order quantizer values (one flat 128-value buffer); output: the 64 i64 products, exactly representable in f64.
• idct.islow.8x8 — same input layout as dequant.8x8; output: the 64 u8 samples of the [crate::idct] islow transcription (dequantize + two-pass fixed-point IDCT + level shift + clamp), written into a stride-8 block.
• idct.oracle.8x8 — input: the 64 dequantized coefficients (the dequant.8x8 output, so SDK tests chain the two); output: the raw pith_math::idct2_2d result, no level shift, no clamp.

Structs

Digest

One committed conformance fixture and its expected decode digest.

Vector

One recorded numeric vector: the named kernel, its input, and the output the committed file must carry.

Constants

TOL_ABS

Absolute tolerance floor for the f64 oracle vector: covers the cancellation noise of near-zero trig bins (see the module docs).

TOL_REL

Relative tolerance for the f64 oracle vector, applied to the expected magnitude.

Functions

digest_of

Decodes a committed fixture and digests the pixel output.

digest_values

Every fixture digest, recomputed.

digests

The eleven committed fixtures, in fixture-table order (the conformance suite’s own order); reference_json sorts by name when it serializes.

hx

f64 → canonical 16-digit lowercase hex of the raw bit pattern.

reference_json

Serializes the canonical reference.json bytes.

vectors

Every numeric vector the suite shares, recomputed on each invocation.

verify

Compares the committed reference.json against a fresh recomputation, per-value and per-policy (never a whole-file byte compare: the oracle vector’s bits are platform-libm-shaped).

verify_str

The comparison underlying verify: a committed render against a fresh recomputation.