Skip to content

Treat unci pixel_size as an exact stride for sub-byte pixel groups - #25

Merged
laurenspriem merged 1 commit into
ente:mainfrom
laurens-pilot:fix/unci-pixel-size-stride
Nov 2, 2026
Merged

laurenspriem merged 1 commit into
ente:mainfrom
laurens-pilot:fix/unci-pixel-size-stride

Conversation

@laurens-pilot

Copy link
Copy Markdown

pixel_size layouts whose components don't fill whole bytes decoded wrongly, for example 10-bit RGB in pixel_size 4 or 7-bit mono in pixel_size 2. The reader counted whole bytes and kept the leftover bits, so after 30 bits it skipped one byte and started the next pixel at bit 38 instead of bit 32.

A stride-sized payload could fail as truncated or decode to incorrect pixels, depending on the group size and row width. For 10-bit RGB in pixel_size 4, widths divisible by 4 decoded incorrectly, including 18 of 24 pixels on an 8×3 fixture. The compressed versions showed the same failures after decompression. For the 2×1 RGB10 example, the nine-byte payload expected by the old reader also exceeded the eight-byte decompression budget. Each pixel now starts exactly pixel_size bytes after the previous one, including multi-Y groups. A group that doesn't fit is rejected even when it overflows by less than a byte, which matches libheif and GPAC.

Diverging from libheif

This intentionally differs from libheif's generic pixel path, and that is the right call. The crate never matched that path on these layouts anyway. Here is a 2x1 image of 10-bit RGB in pixel_size 4, from an 8-byte payload:

Decoder Second pixel starts at Result
This crate, before bit 38 truncated error
libheif generic pixel path bit 30 wrong pixels, no error
libheif block pixel path (block_size 4) bit 32 right samples, with R and B swapped
GPAC (source read, not run) bit 32 not run
This crate, after bit 32 correct

libheif's byte index rounds a partial byte up, so after 30 bits it skips nothing and pixel_size has no effect. Its own get_tile_data_sizes, block pixel decoder and encoder all use an exact pixel_size stride, so its generic reader is the odd one out. Tested at b97c8b5f and the pinned 78638f4; upstream master has the same code.

Not checked against the spec text: the public preview of ISO/IEC 23001-17:2024 stops at 5.2.1.6.2, before the pixel-interleaving clause, 5.2.1.7 and the 5.2.3 semantics. The decision rests on the implementations above, so someone with the full text should confirm the pixel_size wording before this goes upstream.

The verify job's heif-dec comparison can't see this divergence. None of 651 local HEIF/HEIC/AVIF files has a sub-byte group with pixel_size set, and decode output for libheif's 170 unci files is byte-identical before and after.

Source fork PR: laurens-pilot#13

@laurenspriem

handle_pixel_alignment counted whole bytes and kept any leftover bit
offset, so a 30-bit RGB group in a 4-byte pixel skipped one byte and
started the next pixel at bit 38 instead of bit 32. A payload of
pixel_size x width bytes could fail as truncated or decode to wrong
pixels with no error, depending on the group size and row width. For
30-bit RGB in a 4-byte pixel, widths divisible by 4 decoded wrongly.
Generically compressed items failed the same way after decompression,
and for a 2x1 image the nine bytes the old reader expected also
exceeded the eight-byte decompression budget.

Track the pixel start in bits and advance to exactly pixel_size bytes
past it. A group that does not fit pixel_size is now rejected even when
it overflows by less than a byte, as libheif and GPAC already do.

This deliberately differs from libheif's generic pixel path, which
starts the next pixel at bit 30 because its byte index rounds a partial
byte up. That path disagrees with libheif's own tile sizing, block
pixel decoder and encoder, and with GPAC. No file in the libheif or
local HEIC corpora uses such a layout, and decode output for libheif's
170 unci files is unchanged.
@laurenspriem laurenspriem reopened this Nov 2, 2026
@laurenspriem
laurenspriem merged commit f01db3d into ente:main Nov 2, 2026
1 of 3 checks passed
@laurens-pilot
laurens-pilot deleted the fix/unci-pixel-size-stride branch November 2, 2026 10:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants