hayro

hayro-postscript is a lightweight PostScript scanner designed to tokenize PostScript programs into typed objects. Its primary purpose is to provide enough parsing capability to handle CMAP files.

Supported Types:

• Integers
• Real numbers
• Name objects
• Strings
• Arrays

Limitations:

• It implements only a small subset of the PostScript language.
• It does not support dictionaries, procedures, or other PostScript constructs. Encountering unsupported types will result in an error.

hayro is a lightweight PDF rasterizer written in pure Rust. It is designed to render PDF pages into bitmaps using only the CPU, avoiding any dependencies on the GPU.

While the project aims to be a performant and feature-complete rasterizer, it is currently focused on feature implementation rather than performance optimization. It is designed to handle a wide variety of PDF files, supported by a large regression test suite, but has the following current limitations:

• No support for encrypted or password-protected PDF files.
• No support for blending and isolation.
• No support for knockout groups.
• Missing support for smaller features like color key masking.

Capabilities

hayro-syntax is a low-level, application-agnostic library for reading PDF files, implementing the Syntax chapter of the PDF reference. Key features include:

• Parsing all xref table formats, including xref streams.
• Best-effort repair of PDF files with broken xref tables.
• Parsing all object types (including those in object streams).
• Parsing and decoding PDF streams.
• Iterating over pages and content streams in both typed and untyped fashions.

Limitations

• Read-only: This crate is designed for read-only processing. It cannot be used to manipulate or write PDF files.
• No Password Support: It does not currently support password-protected documents.
• Limited Scope: It does not handle high-level abstractions like fonts or color spaces. Many properties, such as page annotations, are not currently exposed.

The hayro-cmap crate is a parser for CMap files commonly found in PDF documents. It enables two primary mapping operations:

1. Character Code to CID Mapping: Map character codes from text-showing operators to CID (Character Identifier) values.
2. CID to Unicode Mapping: Map CIDs to their corresponding Unicode characters or strings.

This crate is written in safe Rust and forbids the use of unsafe code at the crate level.

The hayro-interpret crate provides an abstraction layer for interpreting the content of PDF files. It works by interpreting PDF data and rendering it into an abstract [Device].

Clients implement the Device trait to define how the interpreted content should be rendered. Common use cases include:

• Rendering to bitmaps (as seen in the hayro crate).
• Rendering to vector formats like SVG (as seen in the hayro-svg crate).

Note: The API is currently in active development and is primarily optimized for PNG or SVG rendering workflows.

The Hayro test suite is divided into several categories based on the source of the PDFs and the type of validation performed.

Test Categories by Source

• Custom tests: PDFs selected manually (e.g., from the hayro issue tracker).
• pdf.js tests: Regression tests copied from the pdf.js suite.
• PDFBox tests: Tests copied from the PDFBox issue tracker.
• Corpus tests: Tests taken from the large-scale PDF corpus.

Test Types by Functionality

• Load tests: Verify that files can be loaded and rendered without crashing. These are best run in debug mode.
• Render tests: The primary test type; ensures PDFs render correctly.
• SVG tests: Specifically tests hayro-svg by rendering the output SVGs using resvg.
• Write tests: Tests for the hayro-write crate (internal; can be ignored by most users).

The hayro project is modular and consists of several crates that can be used independently depending on your requirements:

• hayro: The main crate for rendering PDF pages into bitmaps.
• hayro-syntax: Low-level parsing and reading of PDF files.
• hayro-interpret: A PDF interpreter that emits commands into an abstract Device.
• hayro-svg: Converts PDF pages into SVG images.
• hayro-jpeg2000: A JPEG2000 image decoder.
• hayro-jbig2: A JBIG2 image decoder.
• hayro-ccitt: A decoder for group 3 and group 4 CCITT-encoded images.
• hayro-postscript: A lightweight scanner for a specific subset of PostScript.
• hayro-cmap: A parser for CMap files in PDFs.

Snapshots are PNG images stored under snapshots/ used to verify decoder output. To seed the baseline or update existing snapshots when the decoder output changes intentionally, run the test harness with the REPLACE=1 environment variable set.

Note: Ensure the decoder is built from a known-good revision before seeding the baseline.

To verify changes after a baseline is established, run the test suite normally.

# To seed or update snapshots
REPLACE=1 cargo test --release

# To verify changes against existing snapshots
cargo test --release