Crate pdfrum_page

Expand description

§pdfrum-page

The content layer (ISO 32000-1 §8). A page’s /Contents is a stream of painting operators in user space — points, origin bottom-left, y-up — and this crate turns those bytes into a page-object graph that both the renderer and the text extractor walk. Colour spaces, PDF functions, shadings 1 through 7, transparency groups, soft masks, patterns and Type 3 glyph procedures all resolve here.

bytes ──parse_content──▶ Vec<Op> ──build_page──▶ Page

use pdfrum_common::{Diagnostics, Limits};
use pdfrum_page::{Op, parse_content};

let ops = parse_content(b"0 0 100 50 re f", &Limits::default(), &mut Diagnostics::default());
assert_eq!(ops, vec![Op::Rectangle(0.0, 0.0, 100.0, 50.0), Op::Fill()]);

The two stages are separate pure functions, and that is the crate’s main design decision. parse_content tokenizes and emits one Op per recognised operator, knowing nothing about resources or state. build_page is the fold that turns those operators into page objects, and it is where /Resources, the graphics-state stack and form-XObject recursion live. Splitting them means a content stream can be inspected, diffed and fuzzed with no document behind it, and a page can be built from synthesized operators with no bytes.

parse_content is infallible. An unrecognised operator, a wrong operand count, or a truncated stream is a diagnostic and a skipped Op — a content stream is the part of a PDF most likely to be damaged, and refusing to parse it would mean refusing to draw pages that every viewer draws.

§Features

feature	adds
`jpeg2000`	JPEG 2000 images (`hayro-jpeg2000`)
`jbig2`	JBIG2 images (`hayro-jbig2`)
`ccitt`	CCITT Group 3/4 fax images

Flate and JPEG are always present. A stream in a codec this build left out decodes to a recorded failure, and the rest of the page still draws — the facade turns all three on together as codecs-all.

Part of pdfrum. #![forbid(unsafe_code)].

MIT OR Apache-2.0

Modules§

renderprofileprofiling: Where a whole page render goes, from the page dictionary to the pixels.

Structs§

Axial: A type 2 shading’s geometry.
BitImage: A one-bit-per-pixel image, packed MSB-first with each row starting on a byte boundary.
BuildContext: The caches and guards a build shares across the whole page.
ClipStack: The clipping state: an ordered list of contributions to intersect.
ColorValue: A colour in some space.
Content: A page object with the state and marks it was created under.
ContentMarks: The mark stack a page object is stamped with.
Converted: Components to premultiplied RGBA, one row at a time.
FormObject: A form XObject’s contents, already interpreted.
FunctionBased: A type 1 shading’s geometry.
FunctionCache: Session-scoped function memoization, keyed on the reference that named the function.
GeneralState: The /ExtGState parameters that reach compositing, plus the ones that do not.
GraphicsState: Everything q saves and Q restores.
ImageCache: A session-scoped cache of decoded images.
ImageData: A fully decoded image.
ImageObject: An image, decoded.
IndexOutOfRange: An object index that is not on the page.
InlineImage: An inline image (BI … ID … EI), already separated into its dictionary and its raw sample bytes by the tokenizer (ISO 32000-1 §8.9.7).
JpxImagejpeg2000: A decoded JPEG 2000 image.
Mark: One marked-content entry.
Mesh: A decoded mesh.
MeshParams: The bit widths and decode ranges a mesh stream declares.
MeshReader: A cursor over a mesh stream.
NotAQuarterTurn: The error Rotation’s FromStr returns: the string named no quarter turn.
OcContext: The visibility context: the catalog’s optional-content configuration plus the memoized answers.
Packed: Decoded-but-not-unpacked samples, with everything needed to walk them.
Page: An interpreted page.
PageEdit: One page’s object graph, opened for editing.
Palette: A palette with every entry already in the representation a row wants.
Patch: A Coons or tensor patch: twelve or sixteen control points and four corner colours.
PathObject: A path, as painted.
PatternSpace: A Pattern colorspace: a marker with, for uncoloured patterns, the space its scn operands live in.
PatternValue: A pattern colour: which pattern, and the components an uncoloured one paints with.
PostScript: A type 4 function.
Radial: A type 3 shading’s geometry.
Resources: The resource dictionaries a lookup consults.
Rgb: A colour in the device’s RGB space, each channel nominally in 0..=1.
Rgb8: Eight-bit red, green, blue.
Rgba8: Premultiplied RGBA, the representation the device buffer wants.
Row: A run of pixels in one representation.
Separation: A Separation colorspace: one tint driving an alternate space.
Shading: A loaded, validated shading.
ShadingObject: A shading painted directly by sh.
ShadingPattern: A /PatternType 2 pattern: a shading plus the matrix placing it.
SoftMask: A soft mask from an /ExtGState’s /SMask.
Source: The source stage: an image’s Samples walked one row at a time.
StateStack: The q/Q stack.
StreamBounds: Where each /Contents element’s operators begin, within one flat operator list.
StrokeParams: How a path is stroked.
TextClipLimit: A text-clip batch that would take the clip past MAX_TEXT_OBJECTS.
TextClipRun: One text run held for clipping, with the state its placement needs.
TextObject: One run of glyphs sharing a position and a font.
TextSegment: One string within a text object, and the adjustment that followed it.
TextState: The text-showing parameters (ISO 32000-1 table 105).
TileRange: The range of tile indices covering a clip rectangle.
TilingPattern: A /PatternType 1 pattern.
TransferFunc: Three 256-entry byte tables, one per channel.
Transparency: A transparency group’s attributes.
Triangle: A triangle from a type 4 or type 5 mesh.
Type3Metrics: What a Type 3 glyph procedure declares about one character, and what it paints.
Unpacked: The unpack stage: Packed samples widened to a byte per component, one row at a time into a buffer it owns and reuses.
Vertex: One vertex: where it is and what colour it carries.
Visibility: Which of a page’s objects optional content hides, shaped like the page.

Enums§

BlendMode: A separable blend mode (ISO 32000-1 table 136).
ClipEntry: One clipping contribution.
ClipRule: Which rule decides a clipping path’s interior (ISO 32000-1 §8.5.4).
ColorSpace: A loaded colour space.
Depth: Bits per component, as the sample stream carries them.
Error: What went wrong in a page-level operation that can actually fail.
Family: The eleven colour space families, with the integer tags PDFium exposes through its public API.
FillRule: How a path-painting operator fills its interior (ISO 32000-1 §8.5.3.3).
FormFontsKey: Which interactive form a set of cached form faces belongs to.
FoundPattern: What scn found when it named a pattern.
Function: A loaded PDF function.
Geometry: A shading’s geometry.
ImageMask: An image’s alpha, however it was expressed.
LineCap: Line-cap style (J, /LC; ISO 32000-1 table 52).
LineJoin: Line-join style (j, /LJ; ISO 32000-1 table 53).
MarkProperties: The property list a BDC operator carries: a name into /Properties, or an inline dictionary.
Op: One content-stream operator with its operands already extracted.
PageObject: One thing to paint.
Pattern: A loaded pattern.
Pixels: Decoded pixels, in whichever shape the source produced.
RequestedSize: The resolution an image was decoded at.
Rotation: A page’s /Rotate, normalized to one of four quarter turns (ISO 32000-1 §7.7.3.3).
Samples: An image’s samples, in whichever state the decode ladder left them.
SetComponentsError: Why ColorValue::set_components refused the values.
ShadingKind: Which geometry a shading paints.
ShadingSource: Which entry point reached a shading, which decides whether /Background is honoured.
SoftMaskKind: Which channel of the group a soft mask reads.
TextItem: One element of a TJ array: a string to show, or an adjustment in thousandths of a text-space unit.
TextRenderMode: How glyphs are painted (Tr; ISO 32000-1 table 106).
UsageType: Which use an optional-content configuration is being read for.

Constants§

CHANNEL_SAMPLES: Entries per channel.
DEFAULT_MEDIA_BOX: The default page size when /MediaBox is missing or empty: US Letter.
MAX_BYTES: Byte budget, 100 MiB.
MAX_FORM_LEVEL: The most form parses that may be in flight at once.
MAX_IMAGE_PIXELS: Largest pixel grid (width × height) this crate will materialize from file-declared dimensions.
MAX_TEXT_OBJECTS: The most text objects a clipping path may accumulate.

Traits§

Rows: Whatever yields an image’s samples one row at a time, at source width.

Functions§

adobe_cmyk_to_srgb: The Adobe CMYK -> sRGB table lookup, byte in and byte out.
apply_ext_gstate: Apply an /ExtGState dictionary to state.
build_form_object: Build one form XObject as a standalone page object, placed by matrix.
build_form_object_with: The same build, told whether the appearance is a live edit’s.
build_page: Build a page from its operators.
build_page_from_dict: Build a page from its operators and its dictionary.
build_page_streams: Build a page whose /Contents boundaries are known, so every object records which element it came from.
cmyk_profile_bytes: A CMYK ICC profile, encoded as an output profile, for the same writer.
coons_interior: The four interior control points a Coons patch implies, from ISO 32000-2 §8.7.4.5.8.
decode_image: Decode an image XObject.
decode_jbig2jbig2: Decode an embedded JBIG2 image.
decode_jpxjpeg2000: Decode a JPEG 2000 codestream or JP2 file.
derive_boxes: Derive a page’s boxes from its inherited attributes.
display_size_from_dict: A page’s displayed size, read from its dictionary rather than from a built Page.
eliminate_redundant_clips: The clip-elimination post-pass a page runs after interpretation.
image_area_is_workable: Whether a file-declared width and height are small enough to convert, reduce, or unpack into a dense plane.
load_colorspace: Load the colorspace obj names.
load_pattern: A pattern named in a colour value, looked up through the resources.
page_visibility: Resolve which of a page’s objects optional content hides.
parse_content: Parse content-stream bytes into operators.
parse_program: Build a function from a bare program, for tests and for callers that hold a program rather than a stream.
srgb_profile_bytes: An sRGB ICC profile, encoded, for a writer that must embed one.
transform_object: Move object by transform, composed before whatever it already had — the body of PageEdit::transform, for an object not yet on a page.
uncolored_pattern_rgb: The colour an uncoloured pattern paints with, and the fallbacks when none resolves.