estimator

func CountNonZeroACCoefficients ¶

func CountNonZeroACCoefficients(coeffs []DCTCoefficient) (totalNonZero, totalAbsH1 int)

CountNonZeroACCoefficients counts all non-zero AC coefficients across ALL JPEG components (Y, Cb, Cr) in raw coefficient data. This provides the global P (total non-zero) and global h(1) (total |value|=1) counts needed for message length estimation.

Why all channels (not just luminance) ¶

The Fridrich/Goljan/Hogea (2002) paper formulated its experiments on grayscale images, so the paper's text reads as if AC counts come from a single-channel histogram. But the REAL-world F5 implementations (F5.jar, the Android PixelKnot port) embed across all three channels — the embedder walks every non-zero AC coefficient regardless of component. Liu/Yang/Wang/Shi (2020) Eq. (1) likewise defines L over h_DCT, the total DCT count for the image, not per-channel.

Pre-2026 versions of this function only counted Y. That under-counted P by ~3× on typical 4:2:0 color JPEGs and made Liu Eq. (8) k-inference incorrectly diverge from F5's actual k choice on color stego artifacts. The fix here aligns the global capacity count with what F5 actually used at embed time. Per-mode histograms used by Eq. (3) β estimation remain luminance-only (BuildModeHistogram, BuildHistograms) — those follow the paper's literal formulation and don't share this concern.

func EffectiveCapacityL ¶

func EffectiveCapacityL(nonZeroAC, absH1 int) int

EffectiveCapacityL implements Liu et al. Eq. (1) — the F5-acknowledged embedding capacity in coefficient slots, accounting for shrinkage loss at |c|=1 coefficients:

L = P − 0.51·h(1)

where P is the count of non-zero AC coefficients and h(1) is the count of AC coefficients with |value| = 1. This is the same capacity F5 uses on the embed side to decide which k value will fit a given message.

Use this in place of plain P whenever you compute embedding ratio r = l/L or feed capacity into F5-style k selection. Plain P over-counts capacity because it ignores that ~half of |c|=1 coefs will shrink to 0 during embed.

Returns 0 if either input is non-positive.

func EmbeddingRatio ¶

func EmbeddingRatio(messageBits, nonZeroAC, absH1 int) float64

EmbeddingRatio computes Liu's r = l/L given a message-bit estimate and non-zero AC / h(1) counts. Useful for callers that want to inspect r directly to decide whether to trust an inference (Liu shows r → 1 breaks the underlying β estimator regardless of which k-rule is used).

func EstimateSimpleBeta ¶

func EstimateSimpleBeta(stegoHist, coverHist DCTHistogram) float64

EstimateSimpleBeta returns the H(0)-only β estimate for one DCT mode. This is the dominant term in Fridrich Eq. 3 and is typically a tiny bit MORE accurate than the full LSQ on natural JPEGs (the v₁ term injects noise more than it removes it on real cover-histogram estimates).

Returns 0 when h(1) is 0 (the mode has no |c|=1 coefs to use as reference; the simple formula degenerates).

The result is unclamped — values outside [0, 1] indicate the cover histogram estimate has diverged from reality (small image, very high Q, or double JPEG compression). Apply clampBeta if you need the clamped form.

func EstimateSimpleBetaCorrected ¶

func EstimateSimpleBetaCorrected(stegoHist, coverHist DCTHistogram, totalUsable, totalAbsH1 int) float64

EstimateSimpleBetaCorrected returns the H(0)-only β estimate adjusted for shrinkage via Fridrich §3.3's m = n·(1-P_S) factor where P_S = h(1)/P.

The plain β estimator counts every coefficient modification as a "successful embed", but matrix-encoded F5 with shrinkage actually produces n total modifications of which only n·(1-P_S) carry message bits — the rest are shrinkage retries. Multiplying by (1-P_S) brings the β estimate into agreement with the "useful modifications" interpretation the message-length formula already uses downstream.

On our boop test embed (truth β = 0.000495, P=440768 usable, h(1)=67770):

plain Eq.3:                +100% over truth
simple H(0) only:           +70% over truth
simple H(0) corrected:      +63% over truth   ← this function

totalUsable is the global P (sum of |c|≥1 across all AC modes, all channels). totalAbsH1 is the global h(1). Both are produced by CountNonZeroACCoefficients alongside the histograms.

When totalUsable is 0 the correction degenerates and the function returns the uncorrected simple β (the model can't say what fraction is shrinkage if there are no usable coefs).

func FoldedCount ¶

func FoldedCount(hist DCTHistogram, d int) int

FoldedCount returns the absolute-value folded histogram count for distance d. For d == 0, it returns counts[0] (the zero-coefficient count). For d > 0, it returns counts[d] + counts[-d], folding positive and negative coefficients at the same distance from zero.

func GetTranslator ¶

func GetTranslator() translator

GetTranslator returns the current translator, or nil if not set.

func LiuMatrixK ¶

func LiuMatrixK(r float64) int

LiuMatrixK implements Liu et al. Eq. (8): given an estimated embedding ratio r = l/L (message bits over Liu capacity), return the matrix-encoding parameter w that F5's optimal-k rule would have selected at embed time.

The rule: F5 picks the largest w whose matrix-rate w/(2^w − 1) is still ≥ r. As r grows toward 1, w shrinks toward 1 (no matrix encoding); as r shrinks toward 0, w grows toward maxK.

Returns 0 when r is outside [0, 1] or when no w in [1, maxK] satisfies the rate inequality (which corresponds to "the message can't fit at any k" — a saturation signal the caller should propagate).

func MessageLengthErrorTolerance ¶

func MessageLengthErrorTolerance(length, w int) (lowerExclusiveBits, upperInclusiveBits int)

MessageLengthErrorTolerance returns the message-length range that maps to a given matrix-encoding parameter w via Liu's Eq. (8) k-determinator.

Note on the paper's Eq. (8) typo ¶

Liu et al. (2020) state Eq. (8) as

(w−1)/(2^(w−1) − 1) < r ≤ w/(2^w − 1)

but this is impossible for any w ≥ 2 because the left side exceeds the right (rate(w) is monotonically DECREASING in w, so rate(w-1) > rate(w)). The intended form, given that F5 picks the largest w whose matrix-encoding rate w/(2^w − 1) is still ≥ r, is

(w+1)/(2^(w+1) − 1) < r ≤ w/(2^w − 1)

i.e. rate(w+1) < r ≤ rate(w). Translating from r-bounds back to bit bounds via r = msgBits / L gives the tolerance band returned here. We use the corrected form. (If a future paper version switches to "smallest w" semantics the formula here would flip; the constants in any pinned validation suite would need updating accordingly.)

Returns (lowerExclusiveBits, upperInclusiveBits] — the exclusive lower bound is rate(w+1)·L (the boundary at which F5 would switch to w+1), and the inclusive upper bound is rate(w)·L (the boundary above which F5 would switch to w-1). If w is out of range or L is non-positive the function returns (0, 0).

Callers can use this to gate auto-k decisions: if a candidate's predicted message length sits well inside its tolerance band, the inference is robust to small β-estimation error; if it sits near a boundary, a tiny β shift would flip the inferred k and the result should be flagged low-confidence.

func SetTranslator ¶

func SetTranslator(t translator)

SetTranslator sets the translator for this package. Pass nil to disable translations and use default English messages. The root steganalysis package calls this to propagate its translator.