perf(layout): Process multi-frame images one frame at a time

Merged
CY
25d ago
+171-19

Summary

Multi-page TIFF, GIF and APNG images now go through layout one frame at a time instead of having every frame decoded up front. On a synthetic many-frame TIFF, peak memory during decoding drops to roughly a quarter, and the file completes under a constrained memory limit where main runs out of memory. Output is identical.

What changed

  • Each frame is converted and sent through inference. Its RGB buffer is closed before the next frame is decoded.
  • Page order, dimensions, format metadata and pixel contents are unchanged.

Behavior change

  • A corrupt later frame is now found after the earlier frames have been inferred, not before inference starts. The same exception is raised, and neither version returns a partial document.
  • Decoded page layouts still accumulate in the returned document, so memory still grows with output size.

Validation

  • Inference suite (non-slow) passes on the rebased branch. New tests cover frame order and metadata, closing each converted frame before the next frame is inferred, cleanup when inference fails, and a corrupt later frame.
  • Ten main-vs-branch comparisons across TIFF color modes, GIF/APNG, mixed frame sizes and error paths.
  • Matched trials in isolated, CPU-limited Linux containers on a synthetic multi-frame TIFF:
    • Output hashes are identical.
    • Decode time roughly halves.
    • Peak RSS drops to roughly a quarter.
    • These runs use a fixed empty layout to isolate decoding, so they don't measure end-to-end inference latency.
  • Under a constrained memory limit, main runs out of memory and this branch completes.
  • Real YOLOX inference on a three-frame text TIFF gives matching output on main and this branch.

Release

Targets 1.6.17: sets __version__ to 1.6.17 and adds its entry under a new ## 1.6.17 CHANGELOG section, since 1.6.16 is released.