@laminapdf/sdk 0.2.0-alpha.2 → 0.2.0-alpha.3

package/docs/pages/recipes/extract-markdown.md

@@ -0,0 +1,114 @@
+---
+title: "Extract text for an LLM"
+description: "Turn a PDF into Markdown in reading order, JSON with a box for every block, and chunks sized for retrieval, in TypeScript and Rust."
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/recipes/extract-markdown/"
+---
+
+# Extract text for an LLM
+
+Turn a PDF into Markdown in reading order, JSON with a box for every block, and chunks sized for retrieval, in TypeScript and Rust.
+
+You'll turn a PDF into three outputs an LLM or a search index can use: Markdown in reading order, JSON giving every paragraph and table its page and box, and 400-token chunks.
+
+In TypeScript the function returns the three outputs and needs the extract module, `init({ extract: true })`. In Rust, the program instead extracts once and writes the three files. Both give the same JSON:
+
+<TabItem label="TypeScript">`packages/sdk/examples/extract-markdown.ts`:
+
+```ts
+// Extract a PDF's text for an LLM: Markdown in reading order, JSON with a box for every block,
+// and chunks sized for retrieval.
+//
+// Tables drawn with lines come out as Markdown tables, and text a reader can't see (white,
+// invisible or off the page) is left out of all three.
+import { type Chunk, Document, type Extraction } from "@laminapdf/sdk";
+
+/** What a PDF gives an LLM or a search index. */
+export interface ForAnLlm {
+  /** The text in reading order, with a `<!-- page N -->` comment before each page. */
+  readonly markdown: string;
+  /** Every block with its page and box, the text left out, the file's warnings and the chunks. */
+  readonly json: Extraction;
+  /** About 400 tokens each, a new one at each heading. */
+  readonly chunks: readonly Chunk[];
+}
+
+/** The Markdown, the JSON and the chunks of `bytes`. Needs `init({ extract: true })`. */
+export function extractForAnLlm(bytes: Uint8Array): ForAnLlm {
+  using doc = Document.open(bytes);
+  // Page markers let a reader cite the page a passage came from.
+  const markdown = doc.extract({ format: "markdown", pageMarkers: true });
+  // The JSON carries the same chunks, and each block's place in the Markdown.
+  const json = doc.extract({ format: "json", pageMarkers: true, chunk: { maxTokens: 400 } });
+  return { markdown, json, chunks: json.chunks ?? [] };
+}
+```</TabItem>
+<TabItem label="Rust">`crates/laminapdf/examples/extract_markdown.rs`:
+
+````rust
+//! Extract a PDF's text for an LLM: Markdown in reading order, JSON with a box for every
+//! block, and chunks sized for retrieval.
+//!
+//! Tables drawn with lines come out as Markdown tables, and text a reader can't see (white,
+//! invisible or off the page) is left out of all three.
+//!
+//! ```sh
+//! cargo run -p laminapdf --example extract_markdown -- <file.pdf> [out-dir]
+//! # writes <out-dir>/<file>.md, <file>.json and <file>.chunks.jsonl
+//! ```
+
+use std::error::Error;
+use std::path::{Path, PathBuf};
+
+use laminapdf::extract::{ChunkOptions, ExtractOptions, MarkdownOptions, chunks_jsonl};
+use laminapdf::{Document, OpenOptions};
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let mut args = std::env::args().skip(1);
+    let input = PathBuf::from(args.next().ok_or("usage: extract_markdown <file.pdf> [out-dir]")?);
+    let out = PathBuf::from(args.next().unwrap_or_else(|| "target/examples-out".into()));
+    std::fs::create_dir_all(&out)?;
+    let stem = input.file_stem().and_then(|s| s.to_str()).unwrap_or("document");
+    write_outputs(&std::fs::read(&input)?, &out, stem)
+}
+
+/// Writes the Markdown, the JSON and the chunks of `bytes` into `out`.
+pub(crate) fn write_outputs(bytes: &[u8], out: &Path, stem: &str) -> Result<(), Box<dyn Error>> {
+    let doc = Document::open_bytes(bytes.to_vec(), OpenOptions::new())?;
+    let extraction = doc.extract(&ExtractOptions::new())?;
+
+    // Page markers let a reader cite the page a passage came from.
+    let markdown = extraction.to_markdown(&MarkdownOptions::new().with_page_markers(true));
+    std::fs::write(out.join(format!("{stem}.md")), &markdown.text)?;
+
+    // About 400 tokens a chunk, starting a new one at each heading.
+    let chunks = extraction.chunks(&markdown, &ChunkOptions::new().with_max_tokens(400));
+    std::fs::write(out.join(format!("{stem}.chunks.jsonl")), chunks_jsonl(&chunks))?;
+
+    let json = doc.extract_json(&extraction, &markdown, Some(chunks));
+    std::fs::write(out.join(format!("{stem}.json")), json)?;
+    Ok(())
+}
+````</TabItem>
+
+Run the Rust program on any PDF: `cargo run -p laminapdf --example extract_markdown -- report.pdf out`.
+
+## How it works
+
+- `extract` (`doc.extract` in TypeScript) reads every page's text, joins it into lines and paragraphs, and puts the paragraphs in reading order. A two-column page reads down the left column, then the right; a title across both columns comes first.
+- Tables drawn with lines become table blocks with their cells, and Markdown writes them as tables. A cell that spans columns or rows makes the table HTML, since Markdown tables can't span.
+- Text a reader can't see never reaches the outputs: invisible text (such as the hidden layer of a scanned page), text off the page and text too small to read. The JSON lists each such run under `dropped`, with the reason and how many characters it held.
+- `to_markdown` (`format: "markdown"` in TypeScript) writes headings, paragraphs and tables, with a `<!-- page N -->` comment before each page, so a passage can be traced to its page.
+- `chunks` (`format: "chunks"`, or the `chunk` option with the JSON) groups whole paragraphs and tables up to the budget, starting a new chunk at each heading. Each chunk records the blocks, pages and boxes it came from, and where its text sits in the Markdown.
+- `extract_json` (`format: "json"`) writes the `laminapdf.extract/1` document: the pages, every block with its box in points from the top-left corner, the dropped text, the file's warnings and the chunks.
+
+## What to change
+
+- **Only some pages:** `pages: [0, 1]` in TypeScript, `ExtractOptions::new().with_pages(vec![0, 1])` in Rust (page indexes start at 0).
+- **Tables without lines:** `tables: "lattice-and-stream"` (`.with_tables(TableMode::LatticeAndStream)`) also looks for text lined up in columns. It finds more tables, and now and then a pair of columns that isn't one.
+- **Bigger or smaller chunks:** change `maxTokens` (`with_max_tokens`). A token here is about four characters, a rough count that runs low for code, numbers and scripts other than Latin, so leave room.
+- **Overlap between chunks:** `overlap: 80` (`.with_overlap(80)`) repeats up to about 80 tokens of whole paragraphs from the end of the previous chunk.
+- **One output (TypeScript):** set `format` to `"markdown"`, `"text"`, `"json"` or `"chunks"`.
+- **A long file in steps (Rust):** `doc.extract_job(&options)` and `step` do a page per unit of work, so a long file can report progress or stop between steps.
+
+Next: [all recipes](../../pages/recipes.md).

package/docs/pages/recipes/generate-then-edit.md

@@ -0,0 +1,135 @@
+---
+title: "Generate, then edit"
+description: "Build a one-page draft, open its bytes, retitle it in one transaction and save the edit as a revision after the original bytes."
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/recipes/generate-then-edit/"
+---
+
+# Generate, then edit
+
+Build a one-page draft, open its bytes, retitle it in one transaction and save the edit as a revision after the original bytes.
+
+You'll generate a one-page draft report, then open its bytes, retitle it and save the edit as a revision after them. You need this whenever your app changes a PDF it already has, such as a file a user uploads or one it wrote earlier.
+
+One function builds and saves the draft. Another opens those bytes, changes the title and author, and saves again. In TypeScript the draft needs the text module, `init({ text: true })`. Both languages write the same bytes:
+
+<TabItem label="TypeScript">`packages/sdk/examples/generate-then-edit.ts`:
+
+```ts
+// Generate a document, then open its bytes, edit them and save incrementally. The edit changes
+// the Info dictionary in one transaction, and the incremental save keeps the generated bytes as
+// they are, with one revision appended.
+import { Builder, type BuilderOptions, Document, Font } from "@laminapdf/sdk";
+
+/**
+ * The generated file followed by the edit's revision. Needs `init({ text: true })`.
+ *
+ * @param options - can fix the file ID, the producer and the creation date.
+ * @param editedAt - the modification date to record, as a PDF date string.
+ */
+export function generateThenEdit(options: BuilderOptions = {}, editedAt?: string): Uint8Array<ArrayBuffer> {
+  return edit(generate(options), editedAt);
+}
+
+/** A one-page draft, saved (a new document is always saved as a full rewrite). */
+export function generate(options: BuilderOptions = {}): Uint8Array<ArrayBuffer> {
+  using b = new Builder(options);
+  const page = b.page("A4");
+  page.surface().text("Draft report", { font: Font.standard("Helvetica"), size: 20, at: [72, 96] });
+  page.finish();
+  b.metadata({ title: "Draft report" });
+  using doc = b.finish();
+  return doc.save();
+}
+
+/** Opens `bytes`, edits the Info dictionary in one transaction (which `undo` could revert) and saves incrementally. */
+function edit(bytes: Uint8Array, editedAt?: string): Uint8Array<ArrayBuffer> {
+  using doc = Document.open(bytes);
+  doc.transact((tx) => tx.setInfo({ title: "Final report", author: "Ada Lovelace" }, editedAt));
+  return doc.save({ mode: "incremental" });
+}
+```</TabItem>
+<TabItem label="Rust">`crates/laminapdf/examples/generate_then_edit.rs`:
+
+````rust
+//! Generate a document, then open its bytes, edit them and save incrementally.
+//!
+//! The edit changes the Info dictionary with an op (undoable and serialisable), and the
+//! incremental save keeps the generated bytes as they are, with one revision appended.
+//!
+//! ```sh
+//! cargo run -p laminapdf --example generate_then_edit -- [out-dir]   # writes <out-dir>/generate_then_edit.pdf
+//! ```
+
+use std::error::Error;
+use std::path::PathBuf;
+
+use laminapdf::{
+    BuildOptions, Builder, Document, InfoPatch, Metadata, Op, OpenOptions, PageSize, PdfDate, PointPt, Pt, SaveMode,
+    SaveOptions, SetInfo, Standard14,
+};
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let out = PathBuf::from(std::env::args().nth(1).unwrap_or_else(|| "target/examples-out".into()));
+    std::fs::create_dir_all(&out)?;
+    let bytes = build(BuildOptions::new(), None)?;
+    std::fs::write(out.join("generate_then_edit.pdf"), bytes)?;
+    Ok(())
+}
+
+/// The generated file followed by the edit's revision. `edited_at` is recorded as the
+/// modification date; `options` can fix the file ID, the producer and the creation date.
+pub(crate) fn build(options: BuildOptions, edited_at: Option<PdfDate>) -> Result<Vec<u8>, Box<dyn Error>> {
+    let generated = generate(options)?;
+    edit(generated, edited_at)
+}
+
+/// A one-page draft, saved (a new document is always saved as a full rewrite).
+pub(crate) fn generate(options: BuildOptions) -> Result<Vec<u8>, Box<dyn Error>> {
+    let mut b = Builder::new(options);
+    let helvetica = b.standard_font(Standard14::Helvetica)?;
+    let mut page = b.page(PageSize::A4);
+    page.surface().text(
+        "Draft report",
+        &helvetica,
+        Pt::new(20.0),
+        PointPt::from_points(72.0, 96.0),
+    )?;
+    page.finish()?;
+    b.metadata(Metadata::default().with_title("Draft report"));
+    Ok(b.finish()?.save(&SaveOptions::new())?.bytes)
+}
+
+/// Opens `bytes`, edits the Info dictionary in one transaction (which `undo` could revert) and
+/// saves incrementally: `bytes` unchanged, then the appended revision.
+fn edit(bytes: Vec<u8>, edited_at: Option<PdfDate>) -> Result<Vec<u8>, Box<dyn Error>> {
+    let mut doc = Document::open_bytes(bytes, OpenOptions::new())?;
+    let patch = InfoPatch::new()
+        .title(Some("Final report"))
+        .author(Some("Ada Lovelace"));
+    doc.apply(vec![Op::from(SetInfo::new(patch, edited_at))])?;
+    let options = SaveOptions::new().with_mode(SaveMode::Incremental);
+    Ok(doc.save(&options)?.bytes)
+}
+````</TabItem>
+
+The result is the draft's bytes, unchanged, followed by one revision that retitles it "Final report" and names Ada Lovelace as its author: [open the reference PDF](https://docs.laminapdf.com/examples/pdf/generate_then_edit.pdf).
+
+## How it works
+
+- A new document has no original bytes to append to, so the draft's save is a [full rewrite](../../pages/reference/glossary.md#full-rewrite).
+- `Document.open` (`Document::open_bytes` in Rust) reads the draft. Your edits sit beside its bytes and never change them; see [How Lamina PDF thinks about a PDF](../../pages/concepts/how-lamina-thinks.md).
+- `setInfo` changes the Info dictionary: the title, author and other facts a viewer shows in a file's properties. `transact` applies it as one transaction, which `undo` reverts as a whole. In Rust, `apply` takes the list of ops as one transaction.
+- `mode: "incremental"` (`SaveMode::Incremental`) asks for an [incremental save](../../pages/reference/glossary.md#incremental-save): the draft's bytes first, then one revision with the edit.
+- `editedAt` is the modification date to record, a PDF date such as `D:20261030120000Z`. Leave it out and no date is written, because Lamina PDF never reads the clock.
+- The builder also wrote the draft's title into its XMP metadata, an XML copy of the same facts. `setInfo` leaves that copy alone, so it still says "Draft report".
+
+## What to change
+
+- **More edits in the same revision:** add them inside the callback, such as `tx.rotatePage(doc.page(0).id, 90)` (`RotatePage` in Rust). See [Edit a PDF](../../pages/guides/edit-a-pdf.md).
+- **Removing an entry:** pass `null` for it, as in `{ author: null }` (`.author(None)` in Rust).
+- **Your own file:** open its bytes in place of the draft's. A signed, repaired or encrypted file limits how it saves; [Save a PDF](../../pages/guides/save-a-pdf.md#when-a-file-refuses-a-save) lists the cases.
+- **A whole new file:** pass `mode: "fullRewrite"` (`SaveMode::FullRewrite`), or leave `mode` out and let the save choose. See [Choose a save mode](../../pages/guides/save-a-pdf.md#choose-a-save-mode).
+- **Edits stored as JSON:** replay a saved log with `doc.applyLog({ v: 1, ops })` (`apply_log` in Rust), as [Edit a PDF](../../pages/guides/edit-a-pdf.md#replay-edits-stored-as-json) shows.
+
+Next: [a PDF/UA report](../../pages/recipes/pdf-ua-report.md), an accessible report checked as it's built.

package/docs/pages/recipes/hello.md

@@ -0,0 +1,94 @@
+---
+title: "Hello, world"
+description: "One A4 page with a line of text in a standard 14 font, the smallest PDF Lamina PDF writes, in TypeScript and Rust."
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/recipes/hello/"
+---
+
+# Hello, world
+
+One A4 page with a line of text in a standard 14 font, the smallest PDF Lamina PDF writes, in TypeScript and Rust.
+
+You'll make the smallest PDF Lamina PDF writes: one A4 page that says "Hello, world!" in Helvetica. Start from it to check that a new setup works, or as the skeleton of a document of your own.
+
+The function builds the page and returns the PDF's bytes. In TypeScript it needs the text module, `init({ text: true })`. Both languages write the same bytes:
+
+<TabItem label="TypeScript">`packages/sdk/examples/hello.ts`:
+
+```ts
+// The smallest document: one A4 page with a line of text in a standard 14 font.
+import { Builder, type BuilderOptions, Font } from "@laminapdf/sdk";
+
+/**
+ * The document's bytes. Needs `init({ text: true })`.
+ *
+ * @param options - can fix the file ID, the producer and the creation date, so that the same
+ *   input gives the same bytes on every run.
+ */
+export function hello(options: BuilderOptions = {}): Uint8Array<ArrayBuffer> {
+  using b = new Builder(options);
+  const page = b.page("A4");
+  // Page space: points from the top-left corner, y down; `at[1]` is the text's baseline.
+  page.surface().text("Hello, world!", { font: Font.standard("Helvetica"), size: 24, at: [72, 96] });
+  page.finish();
+  using doc = b.finish();
+  return doc.save();
+}
+```</TabItem>
+<TabItem label="Rust">`crates/laminapdf/examples/hello.rs`:
+
+````rust
+//! The smallest document: one A4 page with a line of text in a standard 14 font.
+//!
+//! ```sh
+//! cargo run -p laminapdf --example hello -- [out-dir]   # writes <out-dir>/hello.pdf (default target/examples-out)
+//! ```
+
+use std::error::Error;
+use std::path::PathBuf;
+
+use laminapdf::{BuildOptions, Builder, PageSize, PointPt, Pt, SaveOptions, Standard14};
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let out = PathBuf::from(std::env::args().nth(1).unwrap_or_else(|| "target/examples-out".into()));
+    std::fs::create_dir_all(&out)?;
+    std::fs::write(out.join("hello.pdf"), build(BuildOptions::new())?)?;
+    Ok(())
+}
+
+/// The document's bytes. `options` can fix the file ID, the producer and the creation date, so
+/// that the same input gives the same bytes on every run.
+pub(crate) fn build(options: BuildOptions) -> Result<Vec<u8>, Box<dyn Error>> {
+    let mut b = Builder::new(options);
+    let helvetica = b.standard_font(Standard14::Helvetica)?;
+    let mut page = b.page(PageSize::A4);
+    // Page space: points from the top-left corner, y down; `y` is the text's baseline.
+    page.surface().text(
+        "Hello, world!",
+        &helvetica,
+        Pt::new(24.0),
+        PointPt::from_points(72.0, 96.0),
+    )?;
+    page.finish()?;
+    let mut doc = b.finish()?;
+    Ok(doc.save(&SaveOptions::new())?.bytes)
+}
+````</TabItem>
+
+The result is one page with the line near its top-left corner: [open the reference PDF](https://docs.laminapdf.com/examples/pdf/hello.pdf).
+
+## How it works
+
+- The builder makes an A4 page, and the page's surface is what you draw on.
+- `at` is in points from the top-left corner of the page, with y going down. Its second number is the text's baseline. See [Pages and coordinates](../../pages/concepts/pages-and-coordinates.md).
+- Helvetica is one of the [standard 14 fonts](../../pages/reference/glossary.md#standard-14-fonts), which every PDF viewer has, so the PDF embeds no font.
+- Finishing the builder gives a document, and saving the document gives its bytes. `using` in TypeScript frees both as soon as the function ends.
+
+## What to change
+
+- **The text and where it goes:** change the string, the size and `at`.
+- **The page size:** name another size, such as `"Letter"`, or pass `[width, height]` in points.
+- **The font:** for characters outside the standard 14 fonts' Latin set, embed a font. See [Text and fonts](../../pages/guides/fonts-and-text.md).
+- **A file ID or a date of your own:** pass them in the builder's options. Without them, the file ID is a hash of the content and the PDF has no creation date, so the same code writes the same bytes on every run.
+
+Next: [an invoice](../../pages/recipes/invoice.md), with an embedded font and a table of line items.

package/docs/pages/recipes/images-and-vectors.md

@@ -0,0 +1,209 @@
+---
+title: "Images and vectors"
+description: "Shapes, a dashed curve, gray, RGB, CMYK and hex colour, transparency, a blend mode, a clip, a rotation, a JPEG and an RGBA image on one page."
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/recipes/images-and-vectors/"
+---
+
+# Images and vectors
+
+Shapes, a dashed curve, gray, RGB, CMYK and hex colour, transparency, a blend mode, a clip, a rotation, a JPEG and an RGBA image on one page.
+
+You'll draw shapes and images on one A4 page: a rectangle, a circle, a dashed curve, two see-through discs, a photo cut to an ellipse and a rotated gradient that fades out. Start from it for a logo, a chart, the rules of a table or a page with photos.
+
+The function takes a JPEG's bytes, draws the page and returns the PDF's bytes. It draws no text, so in TypeScript it needs only the base module, `init()`. Both languages write the same bytes:
+
+<TabItem label="TypeScript">`packages/sdk/examples/images-and-vectors.ts`:
+
+```ts
+// Images and vector graphics on one A4 page. It draws shapes and a dashed Bézier curve in gray,
+// RGB, CMYK and hex colour, overlaps two translucent discs with a blend mode, clips a JPEG to an
+// ellipse and rotates an RGBA image with a soft mask. Needs only the base module.
+import { Builder, type BuilderOptions, Image, Matrix, type Surface } from "@laminapdf/sdk";
+
+/** The RGBA gradient's side, in pixels. */
+const GLOW_SIDE = 16;
+
+/**
+ * The document's bytes, with `photo` (a JPEG) on the page.
+ *
+ * @param options - can fix the file ID, the producer and the creation date.
+ */
+export function imagesAndVectors(photo: Uint8Array, options: BuilderOptions = {}): Uint8Array<ArrayBuffer> {
+  using b = new Builder(options);
+  const jpeg = Image.jpeg(photo);
+  const glow = Image.rgba(GLOW_SIDE, GLOW_SIDE, gradient());
+  const page = b.page("A4");
+  const s = page.surface();
+  shapes(s);
+  overlappingDiscs(s);
+  images(s, jpeg, glow);
+  page.finish();
+  using doc = b.finish();
+  return doc.save();
+}
+
+/** A square gradient whose alpha falls off towards the right. */
+function gradient(): Uint8Array {
+  const out = new Uint8Array(GLOW_SIDE * GLOW_SIDE * 4);
+  for (let y = 0; y < GLOW_SIDE; y++) {
+    for (let x = 0; x < GLOW_SIDE; x++) out.set([x * 16, y * 16, 200, 255 - x * 15], (y * GLOW_SIDE + x) * 4);
+  }
+  return out;
+}
+
+/** A rectangle, a circle and a dashed, round-capped Bézier curve. */
+function shapes(s: Surface): void {
+  s.fillColor([0.9, 0.3, 0.2])
+    .path((p) => p.rect([56, 56, 160, 100]))
+    .fill();
+  s.fillColor([0.8, 0.1, 0, 0])
+    .path((p) => p.circle([330, 106], 50))
+    .fill();
+  s.strokeColor("#2a9d8f")
+    .path((p) => p.moveTo(56, 220).cubicTo(180, 140, 300, 300, 539, 200))
+    .stroke({ width: 3, cap: "round", dash: [12, 8] });
+}
+
+/** Two translucent discs, the second multiplied onto the first. */
+function overlappingDiscs(s: Surface): void {
+  s.save().opacity(0.6, 1).fillColor([0.3]);
+  s.path((p) => p.circle([120, 330], 60)).fill();
+  s.blendMode("multiply").fillColor([1, 0.8, 0]);
+  s.path((p) => p.circle([190, 330], 60))
+    .fill()
+    .restore();
+}
+
+/** The photo clipped to an ellipse, and the gradient rotated by 30 degrees. */
+function images(s: Surface, photo: Image, glow: Image): void {
+  s.save()
+    .path((p) => p.ellipse([300, 270, 239, 120]))
+    .clip();
+  s.image(photo, [300, 250, 239, 160]).restore();
+  s.save().transform(Matrix.after(Matrix.translate(150, 520), Matrix.rotate(30)));
+  s.image(glow, [-60, -60, 120, 120]).restore();
+}
+```</TabItem>
+<TabItem label="Rust">`crates/laminapdf/examples/images_and_vectors.rs`:
+
+````rust
+//! Images and vector graphics on one A4 page.
+//!
+//! It draws shapes and a dashed Bézier curve in gray, RGB, CMYK and hex colour, overlaps two
+//! translucent discs with a blend mode, clips a JPEG to an ellipse and rotates an RGBA image
+//! with a soft mask.
+//!
+//! ```sh
+//! cargo run -p laminapdf --example images_and_vectors -- photo.jpg [out-dir]   # writes images_and_vectors.pdf
+//! ```
+
+use std::error::Error;
+use std::path::PathBuf;
+
+use laminapdf::{
+    BlendMode, BuildOptions, Builder, Color, Dash, FillRule, Image, LineCap, Matrix, PageSize, PathBuilder, PointPt,
+    Pt, RectPt, SaveOptions, StrokeStyle, Surface,
+};
+
+/// The RGBA gradient's side, in pixels.
+const GLOW_SIDE: u8 = 16;
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let mut args = std::env::args().skip(1);
+    let photo = std::fs::read(args.next().ok_or("usage: images_and_vectors <photo.jpg> [out-dir]")?)?;
+    let out = PathBuf::from(args.next().unwrap_or_else(|| "target/examples-out".into()));
+    std::fs::create_dir_all(&out)?;
+    std::fs::write(out.join("images_and_vectors.pdf"), build(BuildOptions::new(), photo)?)?;
+    Ok(())
+}
+
+/// The document's bytes, with `photo` (a JPEG) on the page. `options` can fix the file ID, the
+/// producer and the creation date.
+pub(crate) fn build(options: BuildOptions, photo: Vec<u8>) -> Result<Vec<u8>, Box<dyn Error>> {
+    let mut b = Builder::new(options);
+    let photo = Image::jpeg(photo)?;
+    let glow = Image::rgba(u32::from(GLOW_SIDE), u32::from(GLOW_SIDE), &gradient())?;
+    let mut page = b.page(PageSize::A4);
+    let s = page.surface();
+    shapes(s)?;
+    overlapping_discs(s);
+    images(s, &photo, &glow);
+    page.finish()?;
+    let mut doc = b.finish()?;
+    Ok(doc.save(&SaveOptions::new())?.bytes)
+}
+
+/// A square gradient whose alpha falls off towards the right.
+fn gradient() -> Vec<u8> {
+    (0..GLOW_SIDE)
+        .flat_map(|y| (0..GLOW_SIDE).flat_map(move |x| [x * 16, y * 16, 200, 255 - x * 15]))
+        .collect()
+}
+
+/// A rectangle, a circle and a dashed, round-capped Bézier curve.
+fn shapes(s: &mut Surface) -> Result<(), Box<dyn Error>> {
+    let at = PointPt::from_points;
+    s.fill_color(Color::rgb(0.9, 0.3, 0.2))
+        .path(|p| _ = p.rect(RectPt::from_points(56.0, 56.0, 160.0, 100.0)))
+        .fill(FillRule::NonZero);
+    s.fill_color(Color::cmyk(0.8, 0.1, 0.0, 0.0))
+        .path(|p| _ = p.circle(at(330.0, 106.0), Pt::new(50.0)))
+        .fill(FillRule::NonZero);
+    let dashed = StrokeStyle {
+        width: Pt::new(3.0),
+        cap: LineCap::Round,
+        dash: Some(Dash::new(vec![12.0, 8.0], 0.0)),
+        ..StrokeStyle::default()
+    };
+    s.stroke_color(Color::hex("#2a9d8f")?)
+        .path(|p| {
+            p.move_to(at(56.0, 220.0))
+                .cubic_to(at(180.0, 140.0), at(300.0, 300.0), at(539.0, 200.0));
+        })
+        .stroke(&dashed);
+    Ok(())
+}
+
+/// Two translucent discs, the second multiplied onto the first.
+fn overlapping_discs(s: &mut Surface) {
+    let disc = |x: f64| move |p: &mut PathBuilder| _ = p.circle(PointPt::from_points(x, 330.0), Pt::new(60.0));
+    s.save().opacity(0.6, 1.0).fill_color(Color::gray(0.3));
+    s.path(disc(120.0)).fill(FillRule::NonZero);
+    s.blend_mode(BlendMode::Multiply).fill_color(Color::rgb(1.0, 0.8, 0.0));
+    s.path(disc(190.0)).fill(FillRule::NonZero).restore();
+}
+
+/// The photo clipped to an ellipse, and the gradient rotated by 30 degrees.
+fn images(s: &mut Surface, photo: &Image, glow: &Image) {
+    s.save()
+        .path(|p| _ = p.ellipse(RectPt::from_points(300.0, 270.0, 239.0, 120.0)))
+        .clip(FillRule::NonZero);
+    s.image(photo, RectPt::from_points(300.0, 250.0, 239.0, 160.0))
+        .restore();
+    let placement = Matrix::translate(150.0, 520.0).after(&Matrix::rotate(30.0));
+    s.save().transform(placement);
+    s.image(glow, RectPt::from_points(-60.0, -60.0, 120.0, 120.0)).restore();
+}
+````</TabItem>
+
+The result is one A4 page with every shape and both images: [open the reference PDF](https://docs.laminapdf.com/examples/pdf/images_and_vectors.pdf).
+
+## How it works
+
+- `path(p => …)` builds a shape and returns it unpainted. `fill` and `stroke` paint it, and `clip` limits what's drawn next to its inside. See [Shapes, colour and images](../../pages/guides/images-and-vectors.md).
+- A colour of one, three or four numbers from 0 to 1 is gray, RGB or CMYK, and a string such as `"#2a9d8f"` is hex. Rust has `Color::gray`, `rgb`, `cmyk` and `hex`.
+- `save()` and `restore()` bracket each group of drawings, so the opacity, blend mode, clip and rotation set inside stop at `restore()`.
+- Both discs are 60% opaque, and `multiply` darkens the area where the second disc covers the first.
+- `Image.jpeg` embeds the photo as it is, without decoding it. `Image.rgba` takes raw pixels, and their alpha becomes a soft mask: a second image that holds the transparency.
+- The matrix turns the gradient 30 degrees clockwise, then moves it to (150, 520). The gradient is drawn centred on the origin, so it turns about its own centre. Like every position, the matrix works in [page space](../../pages/reference/glossary.md#page-space).
+
+## What to change
+
+- **A PNG instead of the JPEG:** `Image.png(bytes)` (`Image::png` in Rust) keeps the PNG's transparency.
+- **A shape with a hole:** draw both outlines in one path and fill it with `"evenOdd"` (`FillRule::EvenOdd`), so the inner shape stays empty.
+- **A filled shape with an outline:** `fillStroke(rule, style)` (`fill_stroke` in Rust) paints both at once.
+- **Another blend mode:** `"screen"` lightens where `"multiply"` darkens. `BlendMode` lists all sixteen.
+- **Alternate text:** pass a description as the third argument of `image` (`figure` in Rust), and a screen reader reads it out. See [Accessible PDFs](../../pages/guides/accessible-pdfs.md).
+
+Next: [links and outlines](../../pages/recipes/links-and-outlines.md), with four pages joined by links, an outline and page labels.