* M2: a JPX image on a rotated page draws instead of crashing (#3884)
The decode-size hint `image_draw_size` hands hayro-jpeg2000 mapped the
image's corners (w, 0) and (0, h) as points, so it took in the
translation. On a /Rotate 90 page (Acrobat Paper Capture scans) one
corner lands on the device origin, the hint gets a side of 0, and
hayro-jpeg2000 0.3.5 divides the image size by it: "renderer crashed on
page N: attempt to divide by zero" on every rotated JPX page.
The hint now comes from the transform's linear part (the axis lengths
the preview tiny-image check already used, now computed once), and each
side is at least 1. As a side effect, translated JPX images no longer get
an overestimated hint, so they can decode at a reduced resolution level
when drawn small, which is what the hint is for.
Regression test: a 1x1 JPX image filling a 40x40 page at /Rotate 0, 90,
180 and 270, rendered at 0.5x, 1x and 1.5x. It fails before the fix
(/Rotate 90 at 0.5x: attempt to divide by zero) and passes after.
Supersedes the guard in #1883 and does not depend on the hayro-jpeg2000
bump in #2309; both are open and conflicting with main.
Fixes #3884
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C19EMwwBCMSkqew7KepPV2
* M2: decode an offset JPX image area at full size (#3884 review)
hayro-jpeg2000 0.3.5 places a reduced resolution's samples using the
image area's reference-grid offset (XOsiz, YOsiz) unscaled. When a size
hint skips a level, an offset image either loses rows (offset 7, 7: no
reduced row is copied) or is sliced past a reduced row and panics
(offset 7, 0: "range start index 3 out of range for slice of length 2"
at decode.rs:486). The accurate hint from the previous commit makes
reduced decoding more common, so this matters more now.
filter::jpx::decode now passes the hint only when both offsets are 0,
read from the SIZ segment of a raw codestream or a JP2 jp2c box;
codestreams without an offset keep reduced decoding.
Tests: jpx_size_hint_is_dropped_only_for_an_offset_image_area fails
before the fix (the panic above, and 2x2 instead of 4x4 for the other
offsets) and passes after; the (0, 0) case pins that reduced decoding
is kept. image_area_offset_reads_raw_codestreams_and_jp2_files covers
raw, JP2 and truncated inputs.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C19EMwwBCMSkqew7KepPV2
* M2: pin invalid /Rotate values in the rotated JPX test (#3884 review)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C19EMwwBCMSkqew7KepPV2
* M2: restore the /UserUnit test's rotations (#3884 review)
7928399 widened the rotation list in the rotated-JPX test with a sed that
also matched the identical loop in user_unit_scales_the_page_and_everything_on_it,
which then failed on /Rotate 45. Only the JPX test was meant to change.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C19EMwwBCMSkqew7KepPV2
* M2: decode a colour-keyed JPX image at full size (#3884 review)
A colour-key /Mask (ISO 32000-2 8.9.6.4) is matched against the decoded
samples in resolve_alpha. A JPX image decoded at a reduced resolution for
the size hint has wavelet low-pass averages instead of its samples, so
keyed pixels next to unkeyed ones turned opaque, and unkeyed averages
could fall in the key range. The accurate hint from the first commit
makes reduced decodes more common.
ImageXObject::decoded_raster now drops the hint when a colour key is the
image's mask (no /SMask stream and no /SMaskInData 1, the precedence
resolve_alpha uses), so it is decoded at full size and resampled with its
mask like an image under any other filter. A /SMask keeps the reduced
decode. The decode cache key follows, since it is built from the same
hint.
Test: jpx_with_a_colour_key_mask_is_decoded_at_full_size decodes a 4x4
one-level JPX image with a 2x2 hint: without a mask, with /Mask [0 0],
and with /Mask [0 0] plus /SMask. The /Mask case gave 2x2 before the fix
and gives 4x4 after; the other two stay 2x2.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C19EMwwBCMSkqew7KepPV2
* M2: pin a colour-keyed JPX image's transparency as drawn (#3884 review)
The colour-key test checked the size the image was decoded at. This one
checks the page: a 4x2 JPX checkerboard of samples 0 and 1 with
/Mask [0 0], drawn over red at 2x1 pixels, where the size hint skips a
resolution level. Half of each pixel's samples are keyed, so both pixels
come out half red (128, 1, 1).
With the fix in decoded_raster reverted, the reduced decode's averaged
samples no longer match the key and the image covers the red: both
pixels are (1, 1, 1) and the test fails.
The codestream is the one inside the 4x2 JP2 fixture in hayro-syntax's
filter::jpx tests.
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: FredApps <153173854+FredApps@users.noreply.github.com>
hayro-syntax
A low-level library for reading PDF files.
This crate implements the Syntax chapter of the PDF reference, and therefore
serves as a very good basis for building various abstractions on top of it, without having to reimplement
the PDF parsing logic.
This crate does not provide more high-level functionality, such as parsing fonts or color spaces.
Such functionality is out-of-scope for hayro-syntax, since this crate is supposed to be
as light-weight and application-agnostic as possible.
Functionality-wise, this crate is therefore close to feature-complete. The main missing feature is support for password-protected documents. In addition to that, more low-level APIs might be added in the future.
The crate is no_std compatible but requires an allocator to be available.
Example
This short example shows you how to load a PDF file and iterate over the content streams of all pages.
use hayro_syntax::Pdf;
use std::path::PathBuf;
// First load the data that constitutes the PDF file.
let data = std::fs::read(
PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../hayro-tests/pdfs/custom/text_with_rise.pdf"),
)
.unwrap();
// Then create a new PDF file from it.
//
// Here we are just unwrapping in case reading the file failed, but you
// might instead want to apply proper error handling.
let pdf = Pdf::new(data).unwrap();
// First access all pages, and then iterate over the operators of each page's
// content stream and print them.
let pages = pdf.pages();
for page in pages.iter() {
let mut ops = page.typed_operations();
while let Some(op) = ops.next() {
println!("{op:?}");
}
}
Safety
When the unsafe feature is disabled, there is only use of unsafe in hayro-syntax.
We also unconditionally use the smallvec crate which uses unsafe internally, but that's
it.
For better performance, it is strongly recommended to enable the unsafe feature,
which does result in slightly more unsafe code being, but does give better performance:
- We will use the
flate2crate for decoding flate streams. - SIMD will be enabled to accelerate decoding of images.
memchrwill be used to accelerate some of the fallback parsing code.
Features
The supported features include:
- Parsing xref tables in all its possible formats, including xref streams.
- Best-effort attempt at repairing PDF files with broken xref tables.
- Parsing of all objects types (also in object streams).
- Parsing and decoding PDF streams.
- Iterating over pages as well as their content streams in a typed or untyped fashion.
- The crate is very lightweight, especially in comparison to other PDF crates.
Limitations
- There are still a few features missing, for example, support for password-protected PDFs. In addition to that, many properties (like page annotations) are currently not exposed.
- This crate is for read-only processing, you cannot directly use it to manipulate PDF files. If you need to do that, there are other crates in the Rust ecosystem that are suitable for this.
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.