Release 3.5.0 -- progressive partial decoding, and a region result that says no
decode(buf, { maxLevel: k }) returns the image reconstructed from level-directory
entries 0..k, at levelDimensions(width, height, nLevels-1-k). The directory is
coarsest-first, so entry 0 alone is the coarsest thumbnail, and a buffer TRUNCATED
after entry k's bytes is accepted -- a client that fetched only a byte prefix can
decode what it has. For a 64x64 thumbnail of a 256x256 ROI image that is 7.9% of
the file.
Verified 576/576 prefixes coefficient-exact and 216/216 truncated buffers, across
ROI and plain files, qualities 0/4/7, 1/3/4 channels and four geometries including
non-power-of-two. 130x70 at three levels gives 33x18, which refutes a floor-based
formula on its own.
READ THE LIMIT HONESTLY. This is verified by REDUCTION to the already
reference-verified full decode, not against a reference reduced decode. libpgf has
no level-selective decode mode and refuses byte-truncated files outright, so no
such comparison exists or can be made with this tooling. Whether libpgf's own
hypothetical reduced decode would agree is undetermined, and recorded as such.
Three findings that corrected earlier guesses:
- Partial decode is NOT ROI-only. A plain file's macroblocks straddle level
boundaries, but the straddler's payload lies wholly inside the byte range of
the entry it starts in, so plain prefixes decode at every k (241/288 straddle,
all exact). ROI's real advantage is that it is TIGHT: it never straddles and is
never vacuous, where plain has 21/288 vacuous prefixes and sometimes delivers a
whole extra level by accident. The shipped API promises only the floor.
- The slot plan must be built from the header's nLevels and only then stopped
early. A prefix-length plan collapses the per-band shift, and at quality 0
every shift is 0 -- so that mistake is INVISIBLE there and would have shipped.
Pinned in both directions by test.
- Spatial region decode is characterised and deliberately NOT shipped. An ROI
block is independently entropy-decodable but not independently reconstructable:
the inverse lifting crosses block seams, and the error penetrates
2^(nLevels-1)-1 pixels. A halo of one block at every directory entry makes the
region bit-exact -- the minimal halo was 0 or 1 on all 1197 measured cases,
never more, which refuted a prediction that it must grow past four levels. It
is not shipped because the payoff is absent at the depths real files use: at
three levels or fewer an exact region decode reads 100% of the file, an ROI file
is larger than its plain twin, and no corpus file is ROI-coded at all.
Reduced-scale chroma is the one place this returns pixels nothing can check. At
quality >= 4 with a subsampling format the chroma is upsampled at reduced scale,
and upsample() is measured at full size only, so those results carry
reducedScaleChroma: 'unverified'. That is not a specification gap -- no
implementation produces this output at all, so nothing is being guessed at -- and
CLEANROOM.md section 6 permits an explicitly marked value as the alternative to
refusing. Refusing would have denied reduced decoding to the most useful case, a
lossy colour thumbnail, while improving nothing checkable.
Also fixes stale capability claims that outlived the 3.4.0 quality work: README
and PGF-FORMAT.md still said quality 19 and above was refused and undetermined,
and errors.js still cited it as an example of an unsupported feature. The
supported range is the whole expressible one, 0 through 31.
617 tests, up from 595. Conformance unchanged where already established:
960/960 coefficient-exact against pgfa across qualities 0..31, the ROI matrix
green, and a full decode byte-identical to 3.4.0 on all 11 decodable corpus files
with all 11 refusals unchanged.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>