vec-io 0.1.0__tar.gz

vec_io-0.1.0/API.md

@@ -0,0 +1,1413 @@
+# vec_io API
+
+Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
+
+1. [Conventions](#1-conventions)
+2. [Converting SVG](#2-converting-svg)
+3. [Command line](#3-command-line)
+4. [Document and Page](#4-document-and-page)
+5. [Canvas](#5-canvas)
+6. [Text layout](#6-text-layout)
+7. [Paints and recorded content](#7-paints-and-recorded-content)
+8. [Markers](#8-markers)
+9. [Lines, segments and areas](#9-lines-segments-and-areas)
+10. [Cells](#10-cells)
+11. [Drawings: `vec_io.draw`](#11-drawings-vec_iodraw)
+12. [Rasterization](#12-rasterization)
+13. [Simplification](#13-simplification)
+14. [Filters](#14-filters)
+15. [SVG support](#15-svg-support)
+16. [Fonts](#16-fonts)
+17. [Geometry: `Matrix`, `Path`](#17-geometry-matrix-path)
+18. [Output](#18-output)
+19. [Errors](#19-errors)
+20. [Modules](#20-modules)
+21. [Array arguments](#21-array-arguments)
+
+## 1. Conventions
+
+* **Coordinates.** Origin at the top-left corner, y pointing down, in every API. Angles are
+  in degrees, clockwise on screen.
+* **Unit.** A document has one unit, `Document(unit=…)`: `pt` (default), `px` (CSS pixels,
+  1/96 in), `mm`, `cm`, `in`, `pc` or `q`. Page sizes, coordinates, line widths, font sizes,
+  `vec_io.draw` drawings drawn on its pages: all are in it. SVG input is in CSS pixels by
+  its own definition and is scaled into the page. `vec_io.units` parses CSS dimensions:
+  `split_length(value, units=None)` gives `(number, unit)` or raises `ValueError`;
+  `to_px(number, unit)` converts absolute units; `parse_angle(value, strict=False)` gives
+  degrees; `parse_length` is the lenient SVG form. Tables: `PX_PER_UNIT`, `ANGLE_UNITS`.
+* **Colors.** A color is a CSS string (`"red"`, `"#rgb[a]"`, `"#rrggbb[aa]"`,
+  `"transparent"`, and the CSS Color 4 functions in modern or comma syntax: `rgb[a]()`,
+  `hsl[a]()`, `hwb()`, `lab()`, `lch()`, `oklab()`, `oklch()`, `color(<space> r g b)` with
+  `srgb`, `srgb-linear`, `display-p3`, `a98-rgb`, `prophoto-rgb`, `rec2020`, `xyz`,
+  `xyz-d50`, `xyz-d65`, and `device-cmyk(c m y k)`; each takes `/ alpha` and `none`); a
+  tuple `(r, g, b)` or `(r, g, b, a)` of numbers in [0, 1]; or a print color below.
+  Components outside [0, 1] raise `ValueError`: values on the 0–255 scale go through
+  `rgb255(r, g, b, alpha=1)` or a CSS string. Colors outside sRGB are gamut mapped as
+  CSS Color 4 specifies (chroma reduced in OKLCh).
+* **Print colors.** `CMYK(c, m, y, k, alpha=1)` is a device CMYK color, components in
+  [0, 1]. `Spot(name, cmyk, tint=1, alpha=1)` is a spot ink: `cmyk` (a `CMYK` or 4-tuple)
+  is its appearance at full tint, used by devices without the ink. Both are written exactly
+  (`k`/`K` operators, a `Separation` color space) in every color mode. They are values of
+  their own, equal only to print colors of the same components; `rgb` and `rgba` are their
+  approximation, used where RGB is needed (rasterized pixels, image and SVG output).
+  Methods: `with_alpha(alpha)`, `css()`.
+* **Color spaces.** `vec_io.paint.srgb_to_oklab(r, g, b)` and `oklab_to_srgb(L, a, b)`
+  convert between sRGB (gamma-encoded, 0–1; clipped on the way back) and Oklab;
+  `oklch_to_oklab(L, C, H)` takes the hue in degrees; `lchuv_to_srgb(L, C, H)` converts CIE
+  LCh(uv) (D65, lightness 0–100) to sRGB as R's `hcl()` does.
+* **Sources.** Files are given as paths; images and SVGs may also be bytes or `data:` URIs.
+  Relative references resolve against `base_dir`; without it only `data:` URIs are loaded.
+  With it, any local file the process can read may be embedded (`../` paths, absolute
+  paths, `file:` URLs on this machine), so pass `base_dir=None` for untrusted SVG. Remote
+  URLs and `file:` URLs naming another host are never fetched.
+* **Types.** The package is typed (`py.typed`). Aliases: `vec_io.Color` (a color argument),
+  `vec_io.Paint` (a color, gradient, pattern or `None`), `vec_io.Content` (text layout
+  content). Chainable methods return the object's own type.
+* **Arrays.** Coordinates, sizes, per-item values and cell grids are sequences (`None`
+  for a missing value) or any object with the buffer protocol: `array.array`,
+  `memoryview`, numpy arrays (read without importing numpy).
+* **C library.** Bulk work (writing content streams, rasterization, culling, PNG and JPEG
+  coding, filters) runs in a bundled C library, prebuilt for Linux x86_64/aarch64, Windows
+  x86_64/arm64 and macOS arm64. It releases the GIL. Elsewhere, features that need it
+  raise `vec_io.native.NativeLibraryError` (build it with `tools/build_native.py` and set
+  `VEC_IO_NATIVE_LIB`).
+
+## 2. Converting SVG
+
+```python
+convert(source, output=None, *, format=None, base_dir=None, font_db=None, font_dirs=None,
+        system_fonts=True, filters=False, pdf_a=None, compress=True, compression="balanced",
+        simplify=None, images=None, dpi=96, background=None, png=None, jpeg=None, jxl=None,
+        avif=None) -> bytes
+```
+
+Converts an SVG document to PDF, PNG, JPEG, JPEG XL or AVIF, returns the bytes and writes
+them to `output` (a path or a binary file object) when given. It is a `Document` in CSS
+pixels with the SVG on its page, saved or rendered with the options below.
+
+| Parameter | Meaning |
+|---|---|
+| `source` | SVG text or bytes (gzip-compressed SVGZ too), a path, a binary file object, or an `SVGDocument`. A string not starting with `<` is a path. |
+| `format` | `"pdf"`, `"png"`, `"jpeg"`, `"jxl"` or `"avif"`; default: the extension of an `output` path, else `"pdf"`. |
+| `base_dir` | Directory of relative `<image>` and `@font-face` URLs; default: a source path's directory. |
+| `font_db`, `font_dirs`, `system_fonts` | Fonts: a `FontDB`, or extra directories searched first and whether to use installed fonts ([Fonts](#16-fonts)). |
+| `filters` | Apply SVG filters (rasterizes filtered elements; [Filters](#14-filters)). |
+| `pdf_a` | PDF: `"2b"`, `"2u"` or `"3b"` ([PDF/A](#pdfa)). |
+| `compress`, `compression`, `simplify`, `images` | PDF: the options of `Document.to_bytes` ([4](#4-document-and-page)). |
+| `dpi`, `simplify`, `background` | Images: resolution (96: one pixel per CSS pixel), decimation, a color under the page (`None`: transparent, white for JPEG). |
+| `png`, `jpeg`, `jxl`, `avif` | Images: the options of the format (`PNG(…)`, `JPEG(…)`, …; [5.9](#59-rendering-and-image-output)). |
+
+`SVGDocument(source)` parses SVG once (`vec_io.svg.parse`); `SVGParseError` (a
+`ValueError`) reports input that is not usable SVG.
+
+```python
+vec_io.convert("drawing.svg", "drawing.pdf")
+png = vec_io.convert(text, format="png", dpi=192, png=vec_io.PNG(quality=90))
+```
+
+## 3. Command line
+
+```
+vec_io INPUT [OUTPUT]          (or: python -m vec_io …)
+```
+
+| Argument | Meaning |
+|---|---|
+| `INPUT` | SVG file, or `-` for stdin. |
+| `OUTPUT` | Output file, or `-` for stdout. Default: `INPUT` with the extension of `--format` (`.pdf`, `.png`, `.jpg`, `.jxl`, `.avif`). |
+| `--format FORMAT` | `pdf` (default), `png`, `jpeg`, `jxl` or `avif`. |
+| `--no-compress` | Uncompressed content streams. |
+| `--compression LEVEL` | `fast`, `balanced` (default) or `best`: the encoder's effort. |
+| `--font-dir DIR` | Extra font directory (repeatable). |
+| `--no-system-fonts` | Ignore installed fonts. |
+| `--filters` | Apply SVG filters. |
+| `--quality N` | PDF: store rasterized content as JPEG (JPEG XL with `--jxl`) of quality N (1–100); images: the quality of the image (JPEG default 90, JPEG XL and AVIF default lossless, PNG a lossy palette). |
+| `--jxl` | Write the PDF's images as JPEG XL ([JPEG XL](#jpeg-xl)). |
+| `--pdf-a LEVEL` | Write PDF/A: `2b`, `2u` or `3b`. |
+| `--simplify [DPI]` | Leave out what later content hides at DPI (default 600); `--simplify auto`: only where it pays off. |
+| `--dpi N` | Image resolution (default 96). |
+| `--version` | Print the version. |
+
+Exit status 1 on unreadable input, invalid SVG, malformed fonts or write errors (including
+a closed standard output); status 2 on invalid arguments: `--dpi` or `--simplify` not
+positive, `--quality` outside 1–100, or an image `--format` with `--pdf-a`, `--jxl` or
+`--no-compress`.
+
+## 4. Document and Page
+
+```python
+Document(unit="pt", title=None, author=None, subject=None, keywords=None, creator=None,
+         font_dirs=None, system_fonts=True, base_dir=None, font_db=None, filters=False,
+         color_mode="rgb", ink_limit=None, icc_profile=None, pdf_a=None, creation_date=None)
+```
+
+A document records what is drawn on its pages: commands, the images and fonts as they were
+given, and what content asks of simplification. Outputs are made from that record when
+asked for, with their own options: `save`/`to_bytes` write the PDF, `Page.render` renders a
+page ([5.9](#59-rendering-and-image-output)). Both can be called any number of times, in
+any order, and drawing may go on after either; the same record written with the same
+options gives the same bytes.
+
+The constructor takes document-level choices. `unit` is the document's unit
+([Conventions](#1-conventions)). The metadata arguments fill the PDF document information.
+`base_dir` resolves relative paths given to `draw_image`, `draw_svg`, `add_font`, `attach`
+and `icc_profile` (default: the working directory), and the references of SVGs placed from
+text or bytes. `filters` applies to SVGs placed with `draw_svg`. `font_db` shares a
+`FontDB` between documents. `creation_date` (a `datetime`; naive means local time) is
+written as the creation and modification date; PDF/A files default to the current time,
+other files have no date unless one is given.
+
+| Print parameter | Meaning |
+|---|---|
+| `color_mode` | `"rgb"` (default) or `"cmyk"`. In CMYK mode every RGB color, gradient, PNG image and rasterized group is converted to DeviceCMYK; only JPEG files keep their own color space. `CMYK` and `Spot` colors are written as given in both modes. |
+| `ink_limit` | Maximum total ink in percent (e.g. `300`) for RGB colors converted in CMYK mode. |
+| `icc_profile` | ICC profile (path or bytes) of the printing condition, written as the output intent (`GTS_PDFX`). |
+
+The RGB to CMYK conversion is naive, not color-managed: K = 1 − max(R, G, B), with full gray
+component replacement. Convert with a color-managed tool when exact print colors matter,
+and pass `CMYK` values. The content of luminance masks is written in DeviceGray in CMYK
+mode: only its luminosity matters, and viewers disagree on the luminosity of inks.
+
+| Method | Description |
+|---|---|
+| `add_page(width=None, height=None, size="A4", landscape=False)` | New `Page`: `width` and `height` in the document's unit, or a named `size`. |
+| `add_bookmark(title, page, y=None, parent=None)` | Outline entry for `page` (a `Page` or index), optionally at `y`. Returns a `Bookmark`, usable as `parent`. |
+| `add_font(data_or_path, family=None, weight=None, italic=None)` | Register a font file (path or bytes) under `family` (default: its own name). |
+| `attach(name, data, mime=None, description=None, relationship="Unspecified")` | Embed a file (bytes or a path). `relationship` is the PDF/A-3 `AFRelationship`: `Source`, `Data`, `Alternative`, `Supplement` or `Unspecified`. Not allowed in PDF/A-2. |
+| `to_bytes(*, compress=True, compression="balanced", simplify=None, images=None, font_hinting=False)` | The PDF as `bytes` (a document without pages gets an empty A4 page), with this output's options. |
+| `save(file, **options)` | Write the PDF to a path or binary file object; `options` as `to_bytes`. |
+| `pages` | The pages, in order. |
+
+| PDF option | Meaning |
+|---|---|
+| `compress` | Compressed PDF 1.5 (default); `False` writes a readable PDF 1.4 layout ([Output](#18-output)). |
+| `compression` | `"fast"`, `"balanced"` (default) or `"best"`: the effort of every compressed stream, of image samples and of JPEG and JPEG XL encoding. |
+| `simplify` | `None` (default): only what the content asks for; `True` (600 dpi) or a resolution: leave out what later content hides, and decimate lines; `"auto"`: per bulk call, where it pays off ([Simplification](#13-simplification)). |
+| `images` | An `ImagePolicy`: how images are stored ([Image encoding](#image-encoding)). |
+| `font_hinting` | Keep the TrueType hinting in embedded subsets (default: left out, [Fonts](#16-fonts)). |
+
+```python
+ImagePolicy(quality=None, jxl=False)
+```
+
+`quality` (1–100): rasterized content (rasterized groups, filtered elements) is stored lossy
+at this quality, as JPEG, or as JPEG XL with `jxl`; `None`: lossless. A group's own
+`quality` overrides it. `jxl`: write images as JPEG XL ([JPEG XL](#jpeg-xl)). Other images
+keep their encoding.
+
+```python
+doc = vec_io.Document(unit="mm")
+page = doc.add_page(size="A4")                        # 210 x 297, in mm
+doc.save("a.pdf", compression="best", simplify=True,
+         images=vec_io.ImagePolicy(quality=85))
+page.render(dpi=192).save("a.png")                   # the same record, as an image
+```
+
+`Page` is the `Canvas` of a page ([5](#5-canvas)) with `render` ([5.9](#59-rendering-and-image-output)),
+`document` and `index`. Named sizes (portrait): `A0`–`A6`, `B4`, `B5`, `Letter`, `Legal`,
+`Tabloid`, `Ledger`, `Executive`. `landscape=True` swaps width and height.
+
+### PDF/A
+
+`pdf_a="2b"`, `"2u"` or `"3b"` writes an archival PDF/A file (ISO 19005-2 and -3; output
+checked with veraPDF). Compared with a normal file:
+
+* Every font is embedded; `embed=False` is ignored (a standard 14 name resolves to its
+  metric alias, see [Fonts](#16-fonts)). A character that no available font covers raises
+  `ValueError`, since PDF/A forbids showing `.notdef`.
+* An XMP metadata stream repeats the document information and the `pdfaid` level;
+  creation and modification dates are written.
+* The output intent is an sRGB profile generated by vec_io in RGB mode. CMYK mode requires
+  `icc_profile` (a CMYK profile). The `icc_profile` of a PDF/A file must be an output
+  (`prtr`) or display (`mntr`) profile, version 2 or 4.
+* Colors that do not match the output intent are converted: `CMYK` colors become RGB in RGB
+  mode, and a `Spot` color gets an RGB alternate. In CMYK mode, RGB JPEG files are tagged
+  with an sRGB ICC color space. A CMYK JPEG file in RGB mode raises `ValueError`.
+* Link annotations are printable; images are never interpolated.
+* `"3b"` allows `attach()`; the files are associated with the document (`/AF`).
+
+`"2u"` also guarantees that text extraction gives Unicode; vec_io maps every glyph, so
+`"2u"` costs nothing over `"2b"`.
+
+## 5. Canvas
+
+A `Canvas` draws on one page (a `Page` is one), in the document's unit. It follows the HTML
+canvas model: set state attributes, build a path, then paint it. Paint arguments (`fill`,
+`stroke`) default to the state (`fill_style`, `stroke_style`) and take any paint; `None`
+paints nothing.
+
+### 5.1 State
+
+`push()` saves the drawing attributes, the transform and the clip on a stack, `pop()`
+restores them; `with page.state():` does both around a body. Inside a group, mask or
+pattern every `push()` needs its `pop()` in the same body; an unbalanced one raises
+`RuntimeError`. `reset_state()` restores the defaults (not the transform).
+
+| Attribute | Default | Values |
+|---|---|---|
+| `fill_style` | `"black"` | a paint: color, `LinearGradient`, `RadialGradient`, `Pattern` or `None` |
+| `stroke_style` | `None` | a paint; `stroke()` strokes in black when it is `None` |
+| `line_width` | `1.0` | the document's unit |
+| `line_cap` | `"butt"` | `butt`, `round`, `square` |
+| `line_join` | `"miter"` | `miter`, `round`, `bevel` |
+| `miter_limit` | `4.0` | |
+| `line_dash` | `None` | sequence of lengths |
+| `line_dash_offset` | `0.0` | |
+| `global_alpha` | `1.0` | multiplies every paint |
+| `font_family` | `"sans-serif"` | CSS family list |
+| `font_size` | `12.0` | the document's unit |
+| `font_weight` | `"normal"` | `normal`, `bold`, `1`–`1000` |
+| `font_style` | `"normal"` | `normal`, `italic`, `oblique`, `oblique 10deg` |
+| `font_stretch` | `"normal"` | CSS keywords (`condensed`, …) or a percentage, `50%`–`200%` |
+| `font_variation_settings` | `""` | `'"wght" 650, "GRAD" -50'` or `{"wght": 650}` ([variable fonts](#variable-fonts)) |
+| `font_optical_sizing` | `"auto"` | `auto` (the `opsz` axis follows the font size) or `none` |
+| `font_kerning` | `"auto"` | `auto`/`normal`: pair kerning; `none` |
+| `font_embed` | `True` | `False`: a standard 14 font, not embedded, when the family names one ([Fonts](#16-fonts)) |
+| `text_align` | `"start"` | `start`/`left`, `center`/`middle`, `end`/`right` |
+| `letter_spacing` | `0.0` | |
+| `word_spacing` | `0.0` | |
+| `fill_rule` | `"nonzero"` | `nonzero`, `evenodd` |
+
+Properties: `width`, `height` (page size in the document's unit); `font`, the
+[`Font`](#61-shaping-without-a-page-vec_iotext) of the font attributes (setting it sets
+them).
+
+### 5.2 Transform
+
+| Method | |
+|---|---|
+| `translate(tx, ty)` | |
+| `scale(sx, sy=None)` | |
+| `rotate(degrees, cx=0, cy=0)` | Clockwise around `(cx, cy)`. |
+| `skew(x_degrees=0, y_degrees=0)` | |
+| `transform(a, b, c, d, e, f)` or `transform(matrix)` | Concatenate a matrix. |
+
+### 5.3 Paths and painting
+
+The current path persists until `begin_path()`.
+
+| Method | |
+|---|---|
+| `begin_path()` | Start a new path. |
+| `move_to(x, y)`, `line_to(x, y)` | |
+| `curve_to(x1, y1, x2, y2, x, y)` | Cubic Bézier. |
+| `quad_to(qx, qy, x, y)` | Quadratic Bézier. |
+| `arc(cx, cy, r, start_angle, end_angle, counterclockwise=False)` | A sweep of a full turn or more draws a full circle; angles must be finite. |
+| `close_path()` | |
+| `rect(x, y, width, height)`, `rounded_rect(x, y, width, height, rx, ry=None)` | |
+| `circle(cx, cy, r)`, `ellipse(cx, cy, rx, ry)` | |
+| `add_path(path)` | Append a `Path` or SVG path data. |
+| `fill(paint=<fill_style>, rule=None)` | Fill the path. |
+| `stroke(paint=<stroke_style>)` | Stroke the path (black when `stroke_style` is `None`). |
+| `fill_stroke(fill=<state>, stroke=<state>)` | Fill then stroke. |
+| `clip(path=None, rule=None)` | Intersect the clip with `path` (a `Path` or path data; default the current path), until the enclosing `pop()`; `with page.clip(path):` clips the body only. |
+| `fill_rect(x, y, width, height, fill=<state>)`, `stroke_rect(x, y, width, height, stroke=<state>)` | Independent of the current path. |
+| `draw_path(path, fill=<state>, stroke=<state>, fill_rule=None, markers=None)` | Paint a `Path` or path data with the state's line settings, then its `markers`. |
+| `draw_path_markers(path, markers, stroke_width=None)` | `PathMarker`s at the vertices of a path: one for every vertex, or `(start, mid, end)` (each may be `None`). |
+
+The path-building methods return the canvas, so calls chain.
+
+A `PathMarker` is SVG's `<marker>`:
+
+```python
+PathMarker(draw, width=3, height=3, ref=(0, 0), orient=0, units="stroke_width",
+           view_box=None, preserve_aspect_ratio=None, clip=True)
+```
+
+`draw(canvas)` draws the marker at each vertex, in its own coordinates and from the default
+drawing state (or `draw` is a recorded `Marker`, [7](#7-paints-and-recorded-content),
+placed as a form). The marker box is `width` × `height`; its point `ref` sits on the vertex;
+`view_box` maps the marker's coordinates into the box. `orient` is an angle in degrees,
+`"auto"` (halfway between the directions in and out) or `"auto-start-reverse"` (the
+same, turned around at the first vertex); `units="stroke_width"` scales the marker by
+`stroke_width` (default `line_width`), `"user"` does not; `clip` clips to the box.
+
+```python
+arrow = vec_io.PathMarker(lambda c: c.draw_path("M0 0 L10 5 L0 10 Z"), 10, 10, ref=(10, 5),
+                          orient="auto")
+page.draw_path("M10 10 L80 20", fill=None, stroke="black", markers=(None, None, arrow))
+```
+
+### 5.4 Text
+
+| Method | |
+|---|---|
+| `fill_text(text, x, y, fill=<state>)` | Baseline at `y`, aligned by `text_align`. |
+| `stroke_text(text, x, y, stroke=<state>)` | The outlines. |
+| `draw_text(text, x, y, fill=<state>, stroke=<state>)` | Fill and/or stroke. |
+| `measure_text(text)` | Advance width. |
+| `text_extent(text)` | `(width, ascent, descent)`: the advance width and the largest ascent and descent (positive) of the fonts used; for `""`, those of the current font. |
+| `shape_text(text)` | The `GlyphRun` the calls above draw or measure ([`vec_io.text.shape`](#61-shaping-without-a-page-vec_iotext) with the state's font, spacing and kerning). |
+| `layout_text(content, width, …)`, `text_box(content, x, y, width, …, fill=<state>)` | Paragraphs in a box: see [Text layout](#6-text-layout). |
+| `fill_text_on_path(text, path, offset=0, side="left", method="align", fill=<state>)`, `draw_text_on_path(…, fill=<state>, stroke=<state>)` | Text along a `Path` or path data, as SVG's `<textPath>` (below). |
+
+`text` is a string, rich content (a list of strings and `Span` objects,
+[Text layout](#6-text-layout)) or a `GlyphRun`, drawn on one line (newlines become spaces).
+Spans without a color use the fill. One line is shaped as a paragraph is: fonts chosen per
+character, pairs kerned (`font_kerning`), words shaped one by one, so `measure_text(s)` is
+the width of `s` laid out on one line. Fonts are embedded as needed ([Fonts](#16-fonts)).
+
+Text on a path is shaped the same way and starts at `offset` along the path (a length, or
+a percentage of its length: `"50%"`), aligned there by `text_align`. Each glyph is drawn
+where the path is under its middle, rotated with the path there (a kerned glyph's middle
+counts its kerning, as in SVG); glyphs whose middle is past either end are left out.
+`side="right"` runs the path the other way, `method="stretch"` bends the glyph outlines
+along it (drawn as paths, not text). A span's `baseline_shift` moves its glyphs off the
+path; underlines and links of spans are not drawn.
+
+### 5.5 Images and SVG
+
+| Method | |
+|---|---|
+| `draw_image(source, x, y, width=None, height=None, preserve_aspect_ratio="xMidYMid meet", opacity=1.0, smooth=None)` | PNG, JPEG or JPEG XL from a path, bytes or `data:` URI. Without a size, one pixel per unit; with one dimension the aspect ratio is kept. `smooth=False` keeps pixels sharp when scaled. Returns `False` if the image cannot be loaded. |
+| `draw_svg(svg, x=0, y=0, width=None, height=None, base_dir=None, clip=True)` | Place SVG text, bytes, a path or an `SVGDocument`. Default size: its CSS pixel size. `clip` clips to its viewport. |
+
+A `vec_io.draw` drawing draws itself: `drawing.draw(page, x, y, width=None, height=None)`
+([11](#11-drawings-vec_iodraw)).
+
+### 5.6 Plots
+
+`draw_markers(...)`: see [Markers](#8-markers). `draw_lines(...)`, `draw_segments(...)`,
+`fill_between(...)`, `draw_rects(...)`, `fill_polygons(...)`: see
+[Lines, segments and areas](#9-lines-segments-and-areas). `draw_cells(...)`: see
+[Cells](#10-cells). The bulk calls share one vocabulary: `fill`,
+`stroke`, `stroke_width` (default `line_width`) and `opacity`, each one value or a column of
+one per item.
+
+### 5.7 Compositing
+
+Context managers; everything drawn in the body is affected.
+
+| Method | |
+|---|---|
+| `group(opacity=1.0, rasterize=False, dpi=None, quality=None, simplify=None, filter=None)` | Transparency group. `filter`: a `Filter` run on the body's pixels at `dpi` ([Filters](#14-filters)). `rasterize=True` makes the PDF hold the body as an image at `dpi` (default 300; [Rasterization](#12-rasterization)). `quality`: 1–100 for JPEG (JPEG XL with `ImagePolicy(jxl=True)`), `False` for lossless, `None` for the output's `ImagePolicy`. `simplify`: see [Simplification](#13-simplification); with it and no opacity or `rasterize`, the body is drawn directly, not as a group. Drawing attributes are restored afterwards; if the body raises, nothing is drawn. |
+| `rasterized(dpi=None, opacity=1.0, post_process=None, region=None, quality=None, simplify=None)` | Lower-level rasterization. `post_process(surface)` edits the pixels (premultiplied float32 RGBA in `surface.pixels`); the body is then rasterized while it is drawn, and both outputs show that image. `region` `(x0, y0, x1, y1)` fixes the rasterized area. |
+| `clip(path, rule=None)` | The body clipped to `path` ([5.3](#53-paths-and-painting)). |
+| `masked(mask)` | The body seen through a `Mask` ([7](#7-paints-and-recorded-content)): white shows it, black hides it. Drawing attributes are restored afterwards. |
+
+`mask()`, `pattern()` and `marker()` record content to be used elsewhere
+([7](#7-paints-and-recorded-content)).
+
+```python
+with page.mask() as fade:                 # recorded, not drawn
+    page.fill_rect(0, 0, 100, 50, fill=vec_io.LinearGradient(0, 0, 100, 0,
+                                                                [(0, "white"), (1, "black")]))
+with page.masked(fade):
+    page.fill_rect(0, 0, 100, 50, fill="red")
+```
+
+### 5.8 Links
+
+`link(x, y, width, height, url=None, page=None, page_y=None)`: a clickable rectangle that
+opens `url` or goes to `page` (a `Page` of this document, or a page index, which may name a
+page added later), optionally at `page_y`.
+
+### 5.9 Rendering and image output
+
+```python
+page.render(dpi=96, simplify=None, background=None) -> Image
+```
+
+Renders the page from what it records: images from their samples (nothing is encoded to be
+decoded again), rasterized groups as vectors, at `dpi` (96: one pixel per CSS pixel).
+`background` is a color put under the page, or `None` (transparent). `simplify` decimates
+lines for this resolution; nothing is left out, since rasterizing hidden content costs less
+than finding it ([Simplification](#13-simplification)). `dpi` must be positive.
+
+`Image`: `width`, `height`, `dpi`, `samples` (8-bit RGB, not premultiplied), `alpha` (one
+byte per pixel, `None` when every pixel is opaque), `opaque`; `rgba()` (4 bytes per pixel),
+`flattened(background="white")` (opaque, on that color),
+`encode(format="png", *, png=None, jpeg=None, jxl=None, avif=None)` (bytes of `"png"`,
+`"jpeg"`, `"jxl"` or `"avif"`) and `save(file, format=None, **options)` (a path, whose
+extension gives the format, or a binary file object with `format`). Each format takes its
+own options:
+
+| Options | |
+|---|---|
+| `PNG(compression="balanced", quality=None)` | lossless, or a lossy palette at `quality` (1–100) |
+| `JPEG(quality=90, compression="balanced", progressive=True)` | transparent pixels on white |
+| `JXL(quality=None, compression="balanced")` | lossless, or lossy at `quality`; needs libjxl |
+| `AVIF(quality=None, compression="balanced")` | lossless, or lossy at `quality` (alpha lossless); needs libavif ([AVIF](#avif)) |
+
+`compression` is the encoder's effort: zlib level 1 or 6 or vec_io's Deflate for PNG,
+trellis quantization for JPEG, the JPEG XL effort (5, 7, 9) and the AVIF speed (8, 6, 4).
+
+```python
+image = page.render(dpi=192, background="white")
+image.save("plot.png", png=vec_io.PNG(quality=90))
+data = image.encode("jpeg", jpeg=vec_io.JPEG(quality=85))
+```
+
+PNG: lossless by default, in the smallest layout that keeps every pixel (gray, palette of
+1–8 bits, color key or alpha dropped when they apply), with the row filters that compress
+best; `compression="fast"` keeps the samples' layout, `"best"` adds a wider filter search
+and vec_io's Deflate. `quality` (1–100) writes a palette of at most 256 colors chosen in
+Oklab: colors covering at least 0.1% of the pixels stay exact, smooth areas are dithered,
+flat areas and edges are not, and an image that needs more colors for the quality, or that
+is smaller lossless, is written lossless. On plots, `quality=90` halves the file
+(SSIM ≥ 0.999).
+
+JPEG: Robidoux's quantization tables, the quality scale calibrated so that each value looks
+at least as good (SSIM) as the IJG scale of the specification's tables; `"balanced"` adds
+trellis quantization, deringing of dark edges on white and sharp 4:2:0 color, `"best"` tries
+four progressive scan orders, `"fast"` quantizes plainly. Progressive files are about 5%
+smaller than baseline ones. On plots and photographs, balanced JPEGs are 9–14% smaller than
+with the specification's tables at the same quality, and 20–36% smaller at the same SSIM.
+
+## 6. Text layout
+
+Paragraphs broken into lines inside a box.
+
+```python
+layout = page.layout_text(content, width, height=None, align="start", line_height=1.2,
+                          overflow="visible", breaking="greedy", kerning=True,
+                          ligatures=False, paragraph_spacing=0.0, first_indent=0.0)
+layout.draw(x, y)                                     # top-left corner of the box
+layout = page.text_box(content, x, y, width, height=None, fill=<state>, **options)
+```
+
+`content` is a string or a list of strings and `Span` objects. A blank line separates
+paragraphs, `\n` forces a line break, runs of spaces collapse. Lines break at spaces; after a
+hyphen between letters; at a soft hyphen (U+00AD, shown as `-` only where the line breaks);
+at U+200B; between CJK characters, except before closing punctuation and small kana and
+after opening brackets. A word wider than the line is split between glyphs.
+
+| Option | |
+|---|---|
+| `align` | `start`, `center`, `end` or `justify` (aliases `left`, `middle`, `right`). `justify` stretches or shrinks the spaces of every line except the last of a paragraph and lines ending at `\n`. |
+| `line_height` | Line height as a multiple of the largest font size on the line. |
+| `breaking` | `greedy`: fill each line in turn. `optimal`: Knuth–Plass, minimal total looseness over the paragraph. |
+| `height`, `overflow` | `visible` (default): place every line. `clip`: place the lines that fit in `height` (`text_box` also clips to the box). `ellipsis`: same, and end the last placed line with `…`. |
+| `kerning` | Pair kerning: GPOS `kern` feature, else the `kern` table. |
+| `ligatures` | Standard ligatures (GSUB `liga`); off with letter spacing. A ligature extracts as its characters. |
+| `paragraph_spacing` | Extra space between paragraphs. |
+| `first_indent` | Indent of the first line of each paragraph. |
+
+The text style comes from the canvas state: `font`, `fill_style` (or `text_box`'s `fill`),
+`letter_spacing`, `word_spacing`, `global_alpha`; `font_kerning="none"` turns kerning off.
+[`vec_io.text.layout`](#61-shaping-without-a-page-vec_iotext) does the same without a page.
+
+```python
+Span(text, font_family=None, font_size=None, font_weight=None, font_style=None,
+     color=None, url=None, letter_spacing=None, word_spacing=None, underline=False,
+     baseline_shift=None, font_scale=None)
+```
+
+A run of text with its own style; `None` inherits the canvas state. `url` makes the run a
+link; `underline` draws a line under it. `font_scale` multiplies the size. `baseline_shift`
+raises the run: `"super"` (0.33 em of the canvas font size), `"sub"` (−0.2 em) or a number
+of em (positive up). Exponents: `["10", Span("5", baseline_shift="super", font_scale=0.7)]`.
+
+| `TextLayout` member | |
+|---|---|
+| `draw(x, y)` | Draw with the box's top-left corner at `(x, y)`. Can be called several times. |
+| `width`, `height` | Widest line; height of the placed lines. |
+| `lines`, `baselines` | Number of lines; baseline of each, from the top of the box. |
+| `overflow`, `remainder` | Whether text did not fit in `height`; that text as a list of `Span`, to lay out in the next column or page. |
+| `line_text(k)` | Text of line `k`. |
+
+Kerning and justification are written as `TJ` adjustments, so the text stays selectable and
+searchable. Speed: 1,800 words in about 0.02 s (greedy) or 0.035 s (optimal), fonts already
+loaded. Not supported: bidirectional text, complex-script shaping, hyphenation
+dictionaries.
+
+### 6.1 Shaping without a page: `vec_io.text`
+
+The text of every path (Canvas, SVG text, paragraphs) is shaped by `vec_io.text`, whose
+functions need only a font database and a font description, so text can be measured before
+any page exists.
+
+```python
+from vec_io import text
+
+font = text.Font("Inter, sans-serif", size=10, weight="bold")
+run = text.shape("AVATAR", font)                 # GlyphRun; db=None: the default FontDB
+width, ascent, descent = text.measure("AVATAR", font)
+para = text.layout(content, font, width=200, align="justify")   # Paragraphs
+page.draw_text(run, x, y)                        # any canvas, any document
+para.draw(page, x, y, fill="black")
+```
+
+| Name | |
+|---|---|
+| `Font(family="sans-serif", size=12, weight=400, style="normal", stretch="normal", variations=None, optical_sizing="auto", embed=True, unit=1)` | A font description: CSS values as for the canvas attributes; `embed=False` uses a standard 14 font when the family names one; `unit`: CSS px per unit of `size` (a number or a unit name, for `opsz`). Immutable and hashable; `replace(**changes)`. |
+| `shape(content, font, db=None, *, kerning=True, ligatures=False, letter_spacing=0, word_spacing=0)` | `GlyphRun` of a string or rich content on one line. |
+| `measure(content, font, db=None, **options)` | `Extent(width, ascent, descent)` of that run. |
+| `layout(content, font, width, height=None, db=None, *, align, line_height, overflow, breaking, kerning, ligatures, paragraph_spacing, first_indent, letter_spacing, word_spacing)` | `Paragraphs`: the [layout](#6-text-layout) options; `draw(canvas, x, y, fill=None)`, `width`, `height`, `lines`, `baselines`, `overflow`, `remainder`, `line_text(k)`, `line_cells()` (placed `Line`s). |
+| `GlyphRun` | `text`, `width`, `ascent`, `descent`, `extent`; `segments` (`Segment`: one face and style, with `gids`, `texts`, `chars`, `advances`, `adjusts`); `glyphs` (`Glyph`: `face`, `gid`, `advance`, `adjust`, `text`, `char`, `style`, `synth`). |
+| `default_db()` | The process-wide `FontDB` (installed fonts and `VEC_IO_FONT_DIRS`). |
+| `NoFontError` | `ValueError`: no outline font at all for the text. |
+
+Lengths are in the unit of `size` (on a page: `page.font` carries the document's unit).
+Runs of plain strings are memoized in the `FontDB`, per text, description and options (up to
+20,000; adding fonts empties the memo): measure a label many times and draw it once for the
+price of one shaping. Words are shaped one by one and spaces apart (no kerning around a
+space). Speed: shaping a new 5-character label about 7 µs, a memoized one under 1 µs.
+
+## 7. Paints and recorded content
+
+```python
+LinearGradient(x1, y1, x2, y2, stops=(), spread="pad", transform=None)
+RadialGradient(cx, cy, r, stops=(), fx=None, fy=None, fr=0.0, spread="pad", transform=None)
+```
+
+* `stops`: `(offset, color)` or `(offset, color, opacity)`; `offset` in [0, 1].
+  `add_stop(offset, color, opacity=1.0)` appends one and returns the gradient.
+* `spread`: `pad`, `reflect` or `repeat`.
+* `transform`: a `Matrix` applied to the paint geometry.
+* `RadialGradient`: `(fx, fy)` is the focal point, `fr` its radius.
+
+Gradients with transparent stops are drawn with soft masks.
+
+Content recorded on a canvas, in its current user space, to be used elsewhere; nothing is
+drawn on the page while it is recorded, and its body starts from the default drawing state:
+
+| With | Records | Used as |
+|---|---|---|
+| `with page.pattern(width, height, x=0, y=0, transform=None) as pattern:` | a `Pattern`: a `width` × `height` tile, its origin at the top-left corner; `x`, `y` offset the tiling, `transform` transforms it | a paint: `fill_style = pattern`, `fill=pattern` |
+| `with page.mask() as mask:` | a `Mask`: what the body draws is the luminance (white keeps, black hides) | `with page.masked(mask):` |
+| `with page.marker() as marker:` | a `Marker`: one marker centered on the origin | `draw_markers(xs, ys, marker)`; `PathMarker(marker, …)` ([5.3](#53-paths-and-painting)) |
+
+## 8. Markers
+
+```python
+Canvas.draw_markers(xs, ys, marker=None, size=6.0, fill=<state>, stroke=<state>,
+                    stroke_width=None, opacity=1.0, simplify=None, keep=False)
+draw.Markers(xs, ys, shape=None, size=6.0, **style)
+```
+
+Draws a marker at every `(xs[i], ys[i])`. `xs`, `ys` are sequences or buffers.
+
+| Parameter | One value or one per point | Meaning |
+|---|---|---|
+| `marker` / `shape` | yes | A `Path` or SVG path data in a unit box centered on the origin; `None` (default) is the unit circle. Shapes are not named here (plot_io names them): a square is `"M-0.5 -0.5 H0.5 V0.5 H-0.5 Z"`. Equal paths are stored once. One `Marker` ([7](#7-paints-and-recorded-content)) is drawn as recorded (uniform markers only). |
+| `size` | yes | Marker width: the unit box is scaled by it. |
+| `fill`, `stroke` | yes | Colors. Per point: a list of colors or an `(n, 3)`/`(n, 4)` buffer of numbers in [0, 1]; `None` paints nothing. One paint for all may be a gradient or pattern, when nothing else varies. |
+| `stroke_width` | yes | Stroke width; default `line_width`. |
+| `opacity` | yes | Multiplies the fill and stroke alpha. |
+| `simplify`, `keep` | — | `True` (600 dpi) or a resolution: leave out the markers that later ones hide; `"auto"`: only where it pays off; `keep=True` never ([Simplification](#13-simplification)). |
+
+Output:
+
+* PDF: each shape is stored once (per paint kind) and placed at every point.
+* Rasterized: each marker is drawn as its vector version, in order, placed to 1/32 pixel. A
+  shape is rendered once per size, line style and offset and reused with any colors and
+  opacities. Timings in [Rasterization](#12-rasterization).
+
+## 9. Lines, segments and areas
+
+```python
+Canvas.draw_lines(xs, ys, stroke=<stroke_style>, stroke_width=None, dash=None, opacity=1.0,
+                  cap=None, join=None, simplify=None, interpolation="linear", missing="break",
+                  keep=False)
+Canvas.draw_segments(x0, y0, x1, y1, stroke=<stroke_style>, stroke_width=None, opacity=1.0,
+                     cap=None, simplify=None, keep=False)
+Canvas.fill_between(xs, y1, y2=0.0, fill=<fill_style>, stroke=None, stroke_width=None,
+                    opacity=1.0, simplify=None, interpolation="linear", missing="break",
+                    keep=False)
+
+draw.Lines(xs, ys, interpolation="linear", missing="break", **style)
+draw.Segments(x0, y0, x1, y1, **style)
+draw.Area(xs, y1, y2=0.0, interpolation="linear", missing="break", **style)
+```
+
+| Function | Draws | One value or one per… |
+|---|---|---|
+| `draw_lines` | One polyline, or one per row of `ys` (a list of sequences or a 2-D buffer); `xs` is shared or one per series. | series: `stroke`, `stroke_width`, `dash`, `opacity`, `interpolation` |
+| `draw_segments` | Independent segments `(x0[i], y0[i]) → (x1[i], y1[i])`. | segment: `stroke`, `stroke_width`, `opacity` |
+| `fill_between` | The area between `y1` and `y2` (a sequence or a constant), optionally outlined with `stroke`. | — |
+
+`stroke` defaults to `stroke_style`, black when it is `None`; `stroke_width` to
+`line_width`.
+
+* NaN or `None` coordinates break a line or split an area (`missing="break"`): each run of
+  finite points is drawn on its own. With `missing="skip"`, they are left out and the other
+  points joined. Segments and markers with one are skipped. For an area, a point is missing
+  when x, y1 or y2 is.
+* `interpolation` between the points:
+
+  | Value | Drawn as |
+  |---|---|
+  | `"linear"` | straight segments |
+  | `"step-pre"`, `"step-post"`, `"step-mid"` | horizontal and vertical segments; y changes at the start, end or middle of each interval |
+  | `"monotone"` | Fritsch–Carlson curve: never overshoots between two points; where x is not strictly monotonic within a run, the spline |
+  | `"spline"` | centripetal Catmull–Rom curve (α = 0.5): no cusps or loops |
+
+  Curves pass through every point, one Bézier per interval, with one-sided tangents at the
+  ends of each run, computed in C. An area interpolates both edges alike; a constant `y2`
+  stays straight. Only linear series are decimated by `simplify`. A coordinate of
+  `draw_segments` given as a number applies to every segment.
+* `cap`, `join` and `dash` (with `line_dash_offset`) default to the canvas state.
+* `simplify=True` (600 dpi) or a dpi: lines and areas whose x values increase keep only the
+  first, last, lowest and highest point of each device-pixel column at that resolution (M4
+  decimation), made by each output for its own resolution. Lines, areas and segments that
+  later content hides are left out ([Simplification](#13-simplification)). `keep=True` keeps
+  every point.
+
+Output: PDF coordinates are written in bulk by the C library, to 1/1000 pt
+([Output](#18-output)). A 1M-point line takes 0.10 s and 4.7 MB; with `simplify=True`,
+0.05 s and 0.1 MB. Rasterized: drawn by the general rasterizer, with the line's own joins,
+caps and dashes.
+
+| 300 dpi, 400 × 300 pt (including the vector output) | Time |
+|---|---|
+| `draw_lines`, 1M points | 0.21 s |
+| `fill_between`, 1M points | 0.14 s |
+| `draw_segments`, 100k segments with their own colors | 0.23 s |
+
+### Rectangles and polygons
+
+```python
+Canvas.draw_rects(x, y, width, height, fill=<fill_style>, stroke=<stroke_style>,
+                  stroke_width=None, opacity=1.0, simplify=None, keep=False)
+Canvas.fill_polygons(paths, fill=<fill_style>, stroke=None, stroke_width=None,
+                     opacity=1.0, fill_rule="nonzero", simplify=None, keep=False)
+
+draw.Rects(x, y, width, height, **style)
+draw.Polygons(paths, **style)
+```
+
+Many bars, cells, violins, filled contours or wedges in one call.
+
+* **Rectangles:** `x`, `y`, `width` and `height` are sequences or numbers (a number applies
+  to every rectangle). A rectangle with a NaN or `None` value is skipped.
+* **Polygons:** `paths` is a list of `Path` objects or SVG path data (curves allowed), or
+  `(xs, ys, ring_starts[, path_starts])` arrays for large inputs: ring k has the points
+  `ring_starts[k]` to `ring_starts[k + 1] - 1` (`ring_starts` ends with the total), path p
+  the rings `path_starts[p]` to `path_starts[p + 1] - 1` (default: all rings in one path).
+  The rings of a path are filled together with `fill_rule`, so holes work.
+* **Paints:** `fill`, `stroke`, `stroke_width` and `opacity` take one value or one per item.
+  One paint for all items may be a gradient or a pattern; values per item need flat colors.
+* **PDF:** with one paint, the geometry is written in bulk and painted once. With values per
+  item, one block sets only what changes from item to item.
+* **`simplify`:** culling only ([Simplification](#13-simplification)).
+
+10,000 rectangles take 0.001 s with one fill and 0.017 s with a fill each.
+
+## 10. Cells
+
+```python
+Canvas.draw_cells(x_edges, y_edges, fill, palette=None, *, bounds=None, bad=None,
+                  mode="image", opacity=1.0)
+draw.Cells(x_edges, y_edges, fill, palette=None, bounds=None, bad=None, mode="image",
+           **keywords)
+```
+
+A grid of rectangles, each with its own color: heatmaps, 2-D histograms. vec_io has no
+color maps: the caller turns values into colors, palette indices or positions (plot_io does
+it in its own C library).
+
+| Parameter | Meaning |
+|---|---|
+| `x_edges`, `y_edges` | Cell edges: columns + 1 and rows + 1 values, finite, strictly increasing or decreasing. Uneven edges need `cells` or `smooth` mode. |
+| `fill` | The cells row by row, row 0 between `y_edges[0]` and `y_edges[1]`. Without `palette`: colors, an `(n, 3)` or `(n, 4)` buffer (or `(rows, columns, 3 or 4)`) of floats in [0, 1], or a sequence of n colors. With `palette`: palette indices, or in `smooth` mode positions in [0, 1] along the palette. Any shape with n values in all. |
+| `palette` | A list of colors, or an `(m, 3)` or `(m, 4)` buffer. As indices: at most 256 colors (255 when some cells are bad). In `smooth` mode: a color table sampled evenly over [0, 1], interpolated linearly between entries. |
+| `bounds` | `smooth` mode: `len(palette) - 1` increasing positions in [0, 1] between the palette's colors; each color is then constant over its interval, so steps stay sharp. |
+| `bad` | Color of bad cells: a `None` color or a NaN component, a NaN or negative index, a NaN position. Default: none (the cell stays empty). |
+| `mode` | `image` (one sharp image pixel per cell, `/Interpolate false`; even edges only), `cells` (rectangles, one per run of equal cells, grouped by color) or `smooth` (a type 5 mesh shading over the cell centres, constant to the outer edges). |
+| `opacity` | Opacity of the whole grid. |
+
+* **Colors.** Cells are drawn as 8-bit RGB with alpha. CMYK and spot colors keep their space
+  as palette entries in `cells` mode and as `bad` with a palette in `cells` and `smooth`
+  modes; elsewhere they are drawn as their RGB approximation.
+* **Smooth mode.** With a palette, positions are interpolated between cell centres and then
+  colored: the palette is a PDF function (type 0, sampled; with `bounds`, type 3 stitching
+  constant pieces), so a step table stays sharp. Palette alpha is not used. Bad cells are
+  clipped out, their neighbours' mean filling the mesh, and painted with `bad`. Without a
+  palette the colors themselves are interpolated; they must be opaque (bad cells too).
+* **Cells mode.** Opaque cells reach 2 % of their size into their right and lower
+  neighbours, so viewers show no seams.
+* **PDF.** `image` mode writes one Indexed image (palette indices) or an RGB image with a
+  soft mask for translucent cells. A 500 × 500 grid takes 0.01 s and 73 KB as an image,
+  0.05 s and 631 KB as cells, 0.06 s and 1.3 MB smooth (`tools/bench.py cells`).
+
+## 11. Drawings: `vec_io.draw`
+
+A drawing is a tree of elements (drawsvg-style names) that draws itself onto a canvas: a
+page of its own document (`Drawing.document`), any page or canvas (`Drawing.draw`), or SVG
+written from what it draws (`Drawing.to_svg`, through the scene's SVG writer,
+[18](#18-output)).
+
+```python
+import vec_io.draw as draw
+
+d = draw.Drawing(400, 200, font_family="Helvetica, Arial, sans-serif")
+d.append(draw.Rect(10, 10, 380, 180, rx=16,
+                   fill=vec_io.LinearGradient(0, 0, 400, 0, [(0, "orange"), (1, "purple")])))
+d.append(draw.Text("Hello", 48, 200, 120, text_anchor="middle", fill="white"))
+d.save("hello.pdf"); d.save("hello.svg"); d.save("hello.png", dpi=192)
+```
+
+### 11.1 Keywords
+
+Style keywords are inherited by the children of a `Group`, as in SVG:
+
+| Keyword | Canvas state |
+|---|---|
+| `fill`, `stroke` | `fill_style`, `stroke_style`: a paint, a `draw.Pattern`, or `None` (no paint); defaults: black fill, no stroke |
+| `fill_opacity`, `stroke_opacity` | multiply the alpha of a fill or stroke color |
+| `stroke_width`, `stroke_linecap`, `stroke_linejoin`, `stroke_miterlimit`, `stroke_dasharray`, `stroke_dashoffset` | `line_width`, `line_cap`, `line_join`, `miter_limit`, `line_dash`, `line_dash_offset` |
+| `fill_rule` | `fill_rule` |
+| `font_family`, `font_size`, `font_weight`, `font_style`, `font_stretch`, `letter_spacing`, `word_spacing`, `text_anchor` | the font attributes; `text_anchor` (`start`, `middle`, `end`) is `text_align` |
+
+Element keywords (not inherited): `transform` (a `Matrix` or SVG transform text), `opacity`
+(the element as one transparency group, folded into the paint when it has one), `clip_path`
+(a shape element, `ClipPath`, `Path` or path data), `mask` (an element or `Mask` drawing the
+luminance), `filter` (a `Filter`, run at `rasterize`'s dpi or 300), `rasterize` (`True`
+or a dpi), `quality` (of a rasterized element), `simplify`. `Path`, `Line`, `Polyline` and
+`Polygon` also take `marker_start`, `marker_mid`, `marker_end` and `markers` (all three):
+`Marker` elements. Other keywords raise `TypeError`. `set(**keywords)` changes them (`None` inherits again,
+except for `fill` and `stroke`, where it paints nothing).
+
+### 11.2 Drawing
+
+```python
+Drawing(width, height, *children, view_box=None, unit="px", **style)
+```
+
+`width` × `height` in `unit`; `view_box=(x, y, w, h)` maps that box into it (aspect kept,
+centered).
+
+| Method | |
+|---|---|
+| `append(*elements)`, `extend(elements)`, `group(**keywords)` | Children; `group` is a context manager appending and yielding a `Group` (also on `Group`). |
+| `draw(canvas, x=0, y=0, width=None, height=None, clip=True)` | Draw onto a canvas at `(x, y)`, scaled to `width` × `height` (default its own size, in the canvas's unit), clipped to its box. |
+| `document(**options)` | A new `Document` in the drawing's unit with one page holding the drawing; `options`: of the `Document`. |
+| `render(dpi=96, simplify=None, background=None, **options)` | The drawing as an `Image` ([5.9](#59-rendering-and-image-output)). |
+| `to_svg(**options)` | SVG source of what the drawing draws. |
+| `save(file, format=None, **options)` | PDF, SVG, PNG, JPEG, JPEG XL or AVIF by `format` or the extension; `options`: of the `Document`, and of the output (`compress`, `compression`, `simplify`, `images`, `font_hinting` for PDF; `dpi`, `simplify`, `background`, `png`, `jpeg`, `jxl`, `avif` for images). |
+
+### 11.3 Elements
+
+| Element | Signature |
+|---|---|
+| `Group` | `Group(*children, **keywords)` |
+| `Rect` | `Rect(x, y, width, height, rx=None, ry=None, **keywords)` |
+| `Circle`, `Ellipse` | `Circle(cx, cy, r, …)`, `Ellipse(cx, cy, rx, ry, …)` |
+| `Line` | `Line(x1, y1, x2, y2, …)` (stroked only) |
+| `Polyline`, `Polygon` | `Polyline(points, …)`; `points` as `[(x, y), …]` or flat numbers |
+| `Path` | `Path(d="", …)`: SVG path data or a `vec_io.Path`, with the builder methods `M m L l H h V v C c S s Q q T t A a Z` (SVG semantics); `d` is the path data, `outline()` the `vec_io.Path` |
+| `Text` | `Text(text, font_size, x=0, y=0, line_height=1.2, path=None, offset=0, side="left", method="align", …)`: a string (`\n` stacks lines `line_height` em apart) or rich content (strings, `TSpan`, `Span`) on one line; with `path` (a shape element, `Path` or path data), along it ([5.4](#54-text)) |
+| `TSpan` | `TSpan(text, font_family=…, font_size=…, font_weight=…, font_style=…, fill=…, underline=…, baseline_shift=…, url=…)`: a styled run (a `Span`) |
+| `TextBox` | `TextBox(content, x, y, width, height=None, …)`: wrapped text, box top-left at `(x, y)`; the [layout](#6-text-layout) options as keywords |
+| `Image` | `Image(x, y, width, height, path=None, data=None, preserve_aspect_ratio="xMidYMid meet", smooth=None, …)`: PNG, JPEG or JPEG XL |
+| `SVG` | `SVG(source, x=0, y=0, width=None, height=None, base_dir=None, …)`: an SVG document drawn in the box, with everything SVG has, CSS style sheets included (filters when enabled) |
+| `Use` | `Use(element, x=0, y=0, …)`: the element drawn again, moved; its keywords apply where the element sets none |
+| `Markers`, `Lines`, `Segments`, `Area`, `Rects`, `Polygons` | the bulk calls ([8](#8-markers), [9](#9-lines-segments-and-areas)); `fill`, `stroke`, `stroke_width` and `opacity` may be columns |
+| `Cells` | `Cells(x_edges, y_edges, fill, palette=None, bounds=None, bad=None, mode="image", …)`: [cells](#10-cells) |
+| `Pattern` | `Pattern(width, height, *children, x=0, y=0, transform=None)`: a tile drawn by its children, as `fill=` or `stroke=` |
+| `ClipPath` | `ClipPath(*shapes)`: the union of their outlines, as `clip_path=` |
+| `Mask` | `Mask(*children)`: a luminance mask, as `mask=` |
+| `Marker` | `Marker(*children, width=3, height=3, ref=(0, 0), orient=0, units="stroke_width", view_box=None, preserve_aspect_ratio=None, clip=True, **style)`: a marker drawn by its children (with its own style keywords, not the path's) at the vertices of paths, as `marker_start=` … ([`PathMarker`](#53-paths-and-painting)) |
+
+Gradients are vec_io's (`vec_io.LinearGradient`, `RadialGradient`, also importable from
+`vec_io.draw`), as are `CMYK` and `Spot`.
+
+## 12. Rasterization
+
+Rasterizes a group into an image aligned with the page's pixel grid,
+trimmed to its visible extent and clipped to the page. In CMYK documents the
+group is rendered in CMYK.
+
+| API | |
+|---|---|
+| `Canvas.group(rasterize=True, dpi=300)` | Canvas |
+| `Group(..., rasterize=True)` or `rasterize=150` | `vec_io.draw` |
+| `<g data-rasterize="true">` or `data-rasterize="150"` | SVG |
+
+The group is recorded as it is drawn; each output makes what it needs. A PDF rasterizes
+the body when it is written (once per `simplify` of the output, kept for later saves) and
+holds the image; a group that paints nothing writes nothing. Image output
+([`render`](#59-rendering-and-image-output)) draws the body as vectors, clipped to
+`region`: the page is rasterized anyway, at its own resolution, so the result is sharper
+and faster than an image rasterized first. Filtered elements (`post_process`) are
+rasterized while they are drawn, and both outputs show that image.
+
+### Image encoding
+
+Images are kept as they were given (PNG rows a PDF can hold as they are, JPEG files,
+samples) and encoded when a PDF is written, with that output's `compression` and
+`ImagePolicy`; each image keeps its last encoding, so saving again with the same options
+encodes nothing. Image output uses the samples.
+
+| Setting | Stored as |
+|---|---|
+| default | lossless (`/FlateDecode`): the smallest of 8-bit RGB (or CMYK), gray and `/Indexed` with 1–8 bits, with the PNG row filters that compress best; an alpha of only 0 and 255 is a 1-bit soft mask (`compression="fast"`: 8-bit RGB, filtered when it helps) |
+| `quality=1…100` | baseline JPEG (`/DCTDecode`) as [JPEG output](#59-rendering-and-image-output) at the output's `compression`; 4:4:4 chroma from quality 90, 4:2:0 below |
+| `ImagePolicy(jxl=True)` | JPEG XL (`/JXLDecode`), lossless, or lossy at `quality`, with the alpha inside |
+
+Transparency is always stored losslessly, as a separate soft mask; under
+transparent pixels the JPEG holds neighboring colors, so edges do not ring.
+JPEG suits photographic or smooth content (blurs, gradients, dense point
+clouds); lossless suits flat colors and sharp edges.
+
+`quality` is set per group (`Canvas.group`, `draw` keyword, SVG
+`data-quality` on the element or an ancestor; `"false"` forces
+lossless) or per output (`ImagePolicy(quality=…)`, `--quality`). It
+also applies to filtered elements.
+
+100,000 markers with per-point colors, rasterized at 300 dpi on a
+400 × 300 pt area:
+
+| Encoding | Time | PDF size |
+|---|---|---|
+| lossless | 0.28 s | 4.9 MB |
+| JPEG 95 | 0.45 s | 3.4 MB |
+| JPEG 85 | 0.31 s | 1.5 MB |
+| JPEG 70 | 0.28 s | 1.3 MB |
+
+The codecs are public in `vec_io.image.codecs`: `jpeg_encode(samples, width,
+height, components, quality=90, progressive=True, compression="balanced")`,
+`jpeg_decode(data)`, `png_encode(samples, width, height, components, dpi=None,
+compression="balanced", quality=None, colors=None)` (`colors`: the most palette
+entries), `png_decode(data)`,
+`jxl_encode(samples, width, height, components, quality=None)`,
+`jxl_decode(data)` and `avif_encode(samples, width, height, components,
+quality=None)`, on 8-bit interleaved samples. An A4 page at 300 dpi encodes as JPEG 85 in 0.21 s
+(balanced).
+
+### JPEG XL
+
+JPEG XL goes through the system's libjxl, 0.9 or later, loaded on first use
+(`VEC_IO_LIBJXL` gives its path when it is not found by name);
+`vec_io.image.codecs.jxl_available()` tells whether it was found.
+
+**Reading.** JPEG XL images (`draw_image`, `<image>`, `feImage`,
+`draw.Image`) are decoded with libjxl; without it they are skipped like any
+unreadable image (`draw_image` returns `False`). In a document without
+`jxl`, a recompressed JPEG (`cjxl photo.jpg`) is rebuilt and embedded as
+that JPEG; other images are embedded as 8-bit samples (Flate) with alpha as
+an SMask. The first frame of an animation is used. Lossy images are decoded
+to sRGB; lossless ones keep their color space, written as `ICCBased` when it
+is not sRGB.
+
+**Writing.** With `ImagePolicy(jxl=True)` (`save`/`to_bytes`, `convert`, `--jxl`) every image is written as JPEG XL, as PDFium's JPEG XL support reads it: the
+JPEG XL file as the stream, `/Filter /JXLDecode`, `/ColorSpace /DeviceGray`
+or `/DeviceRGB` (`ICCBased` for other color spaces), `/BitsPerComponent 8`,
+alpha inside the JPEG XL rather than in an SMask:
+
+* rasterized content: lossless, or lossy at `quality`;
+* PNG images, cells drawn as images and other samples: lossless;
+* JPEG files: recompressed without loss (CMYK JPEGs stay JPEG);
+* JPEG XL files: as they are.
+
+ISO 32000 has no JPEG XL filter yet; `/JXLDecode` is the name PDFium's
+implementation uses, and viewers without it show nothing for these images.
+`jxl` cannot be combined with `pdf_a` or `color_mode="cmyk"`, and raises
+`ValueError` when the PDF is written without libjxl. The encoder effort follows `compression`: 5
+(`fast`), 7 (`balanced`) or 9 (`best`).
+
+JPEG XL pays off most on photographs and flat graphics: a recompressed
+JPEG file is about 25% smaller, and a 960 × 450 heatmap is 51 KB lossless
+against 80 KB with Flate. On noise-like content it gains little and lossless
+encoding is slow: 100,000 translucent markers of random colors and sizes
+on 400 × 300 pt at 300 dpi take 4.4 s for 4.9 MB lossless
+(Flate: 0.3 s, 5.8 MB) and 1.0 s for 2.1 MB at quality 85 (JPEG: 0.25 s,
+2.2 MB).
+
+### AVIF
+
+AVIF is an export format only (`Image.encode("avif")`, `Image.save("….avif")`,
+`convert(…, format="avif")`, `--format avif`, `vec_io.image.codecs.avif_encode`): PDF
+has no AVIF filter. It goes through the system's libavif 1.x
+(`libavif.so.16`, `libavif.16.dylib`, `avif.dll`; `VEC_IO_LIBAVIF` gives its
+path) with whichever AV1 encoder libavif was built with; without it the
+calls raise `vec_io.image.codecs.AVIFError`, and `avif_available()` tells.
+libavif's options are fields of its structures, so vec_io checks their
+layout against libavif 1.x's defaults before use and treats any other
+layout as missing.
+
+Images are 8-bit sRGB. Without `quality` they are lossless (4:4:4, identity
+matrix); with it, lossy (BT.601, 4:4:4 from quality 90, 4:2:0 below).
+Alpha is always lossless. Encoder speed follows `compression`: 8 (`fast`),
+6 (`balanced`) or 4 (`best`). AVIF suits lossy output: a 960 × 450 heatmap
+is 26 KB at quality 90 and 12 KB at 70, but 115 KB lossless, more than its
+81 KB PNG.
+
+### Rendering
+
+The rasterizer runs what a page records, the scene its PDF content is written
+from, number for number, so a rasterized group matches its vector version.
+Coverage is exact (the area of each pixel covered, computed in fixed point);
+fills, strokes (caps, joins, dashes), gradients, tiling patterns, images,
+clipping, transparency groups and soft masks are supported, and every platform
+computes identical pixels.
+As in PDF viewers, strokes are at least one device pixel wide; images are
+smoothed unless `smooth=False` (`/Interpolate false`) or magnified 4 times or
+more, and minified images are averaged. A dash pattern with more than
+5,000,000 visible dashes in one subpath raises `RasterizationError`.
+
+The scene is compiled once into a display list: shapes scan converted, plain
+forms (markers) rendered once per 1/32-pixel phase, gradients, patterns and
+images prepared, transparency groups and soft masks as lists of their own.
+Surfaces of 250,000 pixels or more, or with 64 KB of recorded content or more,
+then replay the list in horizontal bands on worker threads, one per thread, cut
+so that each holds about the same work. The markers of one `draw_markers` call
+(one shape and size, one fill or a fill per point) are runs of 16-byte
+instances grouped by rows; the pixels are those of the markers drawn one by
+one.
+`VEC_IO_THREADS` sets the number of threads: default the usable CPUs, at
+most 8; `1` disables them. Pixels and bytes do not depend on it.
+
+Text is drawn from the outlines of its fonts (TrueType or CFF), the ones the PDF
+embeds (scenes hold glyph ids; their codes in each subset are written with the PDF),
+wherever it is: groups, masks, patterns, markers, clipping paths, images. A
+standard 14 font (`embed=False`) is drawn with the outlines of the installed font its name
+resolves to as a family (metric aliases first, [Fonts](#16-fonts)) at the standard advance
+widths; with no installed font at all that raises `RasterizationError`.
+
+Marker timings, 100,000 points on a 400 × 300 pt area:
+
+| Output | One colour | Per-point fill, size and a stroke | Per-point fill, one size |
+|---|---|---|---|
+| Vector PDF | 0.02 s (0.8 MB) | 0.08 s (2.6 MB) | 0.06 s (1.8 MB) |
+| Rasterized, 150 dpi | 0.04 s | 0.21 s | 0.12 s |
+| Rasterized, 300 dpi | 0.10 s | 0.35 s | 0.21 s |
+
+Timings: 8 worker threads (see above); on one thread the 300 dpi row is
+0.17 s, 1.12 s and 0.40 s. A page of 1,000,000 one-colour markers renders to
+PNG at 150 dpi in 0.09 s (0.12 s with a fill per point); its display list
+takes about 21 bytes per marker.
+
+JPEG images are decoded when rasterized (baseline, extended and progressive;
+arithmetic-coded and 12-bit JPEGs raise `RasterizationError`), once per image; a
+1500 × 1000 JPEG decodes in about 0.01 s. PNG files are decoded when drawn.
+
+## 13. Simplification
+
+`simplify=True` (600 dpi) or a resolution leaves out what cannot be seen at
+that resolution:
+
+* Content that later content in the same scope hides is deleted whole:
+  painting operators with their path, marker placements, and single subpaths
+  of strokes (each segment of `draw_segments`). Deleted content changes no
+  pixel by more than half an 8-bit level in all, translucent covers
+  included. Content that paints nothing on the page (outside it, or clipped
+  away) goes too.
+* Lines and areas whose x values increase are decimated (M4, see
+  [Lines, segments and areas](#9-lines-segments-and-areas)).
+
+It is a choice of the output. Drawing records everything, with what each piece
+of content asks for; writing the PDF decides what to leave out (culling runs
+on the recorded commands, before anything is written), and image output only
+decimates. The same page can be written with different settings.
+
+| API | Scope |
+|---|---|
+| `Document.save(…, simplify=…)`, `to_bytes(simplify=…)` | every page, group, mask and pattern |
+| `Page.render(…, simplify=…)` | decimation of the page's lines |
+| `draw_markers`, `draw_segments`, `draw_lines`, `fill_between`, `draw_rects`, `fill_polygons` (`simplify=`) | the call |
+| `Canvas.group(simplify=…)` | the body, across calls |
+| `simplify=` on any `vec_io.draw` element | the element |
+| `data-simplify="true"`, `"600"` or `"auto"` on any SVG element | the element |
+| `convert(…, simplify=…)`, `--simplify [DPI\|auto]` | the document |
+
+* `None` (default) follows the enclosing scope, and outside any the output's
+  setting. A resolution given inside a culled scope merges into it (it still
+  sets the call's decimation).
+* `False`, or `keep=True` on the bulk calls, keeps content whole: nothing in
+  it is deleted or decimated (it can still hide earlier content).
+  `group(simplify=False)` draws its body directly, not as a group.
+* Groups, masks and patterns are culled on their own when the PDF is written, with
+  the output's setting and the scope they were drawn in, and kept whole in the page.
+* Image output (`render`, rasterized groups, `convert` to an image format,
+  `--format png|jpeg|jxl|avif`) is not culled:
+  rasterizing hidden content is faster than culling it, and the image is the
+  same. Lines are still decimated: with the output's setting, in a rasterized
+  group at its dpi when `simplify=True`.
+* Never deleted: text, paths that also clip, images, shadings, groups and
+  inlined content. Content under a soft mask or painted with a pattern is
+  deleted when hidden but hides nothing; images, shadings and groups hide
+  nothing either. Under a soft mask, a scope opened by a call or an inline
+  group does nothing.
+* SVG output ([18](#18-output)) writes content whole.
+
+What changes: in a renderer that composites shapes one by one with partial
+coverage (vec_io and PDF viewers), the deleted content changes no pixel by
+more than 0.5/255 at the given resolution, except two kinds of pixels:
+
+* Edges of stacked copies: a point drawn many times shows the copies' colors
+  in its anti-aliased edge; culled, it shows its own edge.
+* Seams between covering shapes, through which a hidden shape leaked.
+
+At other resolutions the same holds up to slivers smaller than a pixel.
+`tools/simplify_check.py` measures it on the scenes below (300 × 200 pt,
+600 dpi; time to draw and write, without and with `simplify`):
+
+| Scene | PDF | Time | Max change | Pixels changed ≥ 1 / ≥ 8 levels |
+|---|---|---|---|---|
+| Gaussian 60k, sizes 1–4, 3 colors, opaque | 790 → 188 KB | 0.10 → 0.16 s | 47 | 0.013 / 0.003 % |
+| same, alpha 0.5 | 802 → 586 KB | 0.09 → 0.26 s | 1 | 0.37 / 0 % |
+| Binned 60k (duplicates), one color, opaque | 119 → 4 KB | 0.29 → 0.34 s | 212 | 1.0 / 0.94 % |
+| Binned 60k, 3 colors, alpha 0.3 | 159 → 56 KB | 0.32 → 0.42 s | 114 | 1.3 / 0.12 % |
+| Gaussian 60k, one color, white outline | 437 → 84 KB | 0.05 → 0.10 s | 1 | 0 / 0 % |
+| Segments 40k, one color | 528 → 313 KB | 0.08 → 0.12 s | 0 | 0 / 0 % |
+| Segments 40k, 3 colors | 582 → 365 KB | 0.08 → 0.13 s | 1 | 0.003 / 0 % |
+| Area, 60 lines, markers, clip, opacity group, text | 380 → 243 KB | 0.06 → 0.12 s | 1 | 0 / 0 % |
+| SVG: 20k `<use>` markers in a clipped group | 173 → 75 KB | 1.87 → 1.95 s | 1 | 0 / 0 % |
+
+Culling 100,000 markers at 600 dpi on a 500 × 360 pt page takes 0.21 s
+with one size and 0.29 s with a size per point; 1,000,000 opaque markers of
+one size take about 0.6 s, at opacity 0.5 about 2.1 s. Culling runs on the
+recorded scene and gives the writer a keep map: per command whether it is
+written, and per marker, segment or subpath of a stroke whether it stays, so the
+content is written once. What each translucent marker covers is computed on the
+worker threads (see `VEC_IO_THREADS` in [Rendering](#rendering)); opaque ones
+are read from their cached sprite when needed. The decisions, which depend on
+each other, are made in order on one thread. A unit whose pixels later content
+already covers fully is deleted without its pixels being visited. The result
+does not depend on the number of threads.
+
+### `simplify="auto"`
+
+`"auto"` simplifies each bulk call only where it pays off. Culling costs about
+0.1–0.2 s per 100,000 markers, and its gain depends on how deeply markers stack;
+decimation is cheap but only removes points where there are many per pixel column.
+Every decision depends on the data alone, so the output stays deterministic.
+
+| Call | `"auto"` does |
+|---|---|
+| `draw_markers` | Culls as `True` when there are at least 20,000 markers and an estimate finds at least 30 % of them hidden; otherwise draws them all. |
+| `draw_lines`, `fill_between` | Decimates as `True` a series with more than 2 points per device-pixel column over its x extent. |
+| `draw_segments`, `draw_rects`, `fill_polygons` | Nothing. |
+| In rasterized groups and image output | As `True`: decimation at the group's resolution, no culling. |
+
+The estimate (one pass in C, about 2 ms per million markers) bins the marker
+centers into square cells of half the median marker size and, in each cell,
+counts all but the last k markers as hidden, where k is the number of layers
+of the median fill opacity α that hide what is under them within 0.5/255
+(k = 1 when opaque, 8 at α 0.5, 15 at α 0.3). Markers without a plain fill
+color (stroke only, gradients, patterns) are never culled by `"auto"`.
+
+As a scope (`Document.save`, `Canvas.group`, `vec_io.draw` elements,
+`data-simplify`, `convert`, `--simplify auto`), `"auto"` is inherited by the
+bulk calls inside, each deciding for itself (when the output needs it); other content is not culled across calls,
+which only `True` or a resolution does. Inside a `True` scope, `"auto"` means
+that scope. Each decision is logged at debug level by the `vec_io` logger.
+
+`tools/simplify_check.py --auto` compares the decisions with the rule they are
+calibrated to, cull exactly where culling saves at least 30 % of the bytes
+(600 dpi, sizes without simplify → with `True`; estimated hidden fraction):
+
+| Scene | PDF | Estimate | `"auto"` |
+|---|---|---|---|
+| Gaussian 60k, sizes 1–4, 3 colors, opaque | 790 → 188 KB (−76 %) | 0.79 | culls |
+| same, alpha 0.5 | 802 → 586 KB (−27 %) | 0.14 | keeps |
+| Binned 60k (duplicates), one color, opaque | 119 → 4 KB (−97 %) | 0.99 | culls |
+| Binned 60k, 3 colors, alpha 0.3 | 159 → 56 KB (−65 %) | 0.89 | culls |
+| Gaussian 60k, one color, white outline | 437 → 84 KB (−81 %) | 0.84 | culls |
+| Uniform 2k, one color, opaque | 17 → 16 KB (−1 %) | 0.00 | keeps |
+| Uniform 200k, one color, alpha 0.3 | 1,490 → 1,432 KB (−4 %) | 0.00 | keeps |
+| Binned 1M, one color, opaque | 1,957 → 6 KB (−100 %) | 1.00 | culls |
+
+On a million markers that it does not cull, `"auto"` adds 2 ms.
+
+## 14. Filters
+
+PDF has no filters: a filtered group is drawn into an image (at the group's `dpi`, 300 by
+default) and the filter runs on its pixels. PDF, image and SVG output show that image (the
+scene keeps the pixels, not the filter).
+
+```python
+from vec_io import Filter
+from vec_io.filter import GaussianBlur, Merge, Offset
+
+shadow = Filter(GaussianBlur(3, input="SourceAlpha"), Offset(4, 4, result="s"),
+                Merge("s", "SourceGraphic"))
+with page.group(filter=shadow, dpi=300):
+    page.fill_rect(20, 20, 100, 60, fill="tomato")
+d.append(draw.Rect(20, 20, 100, 60, fill="tomato", filter=shadow))      # vec_io.draw
+```
+
+`Filter(*primitives, region=None)`: the primitives run in order; `region` `(x, y, width,
+height)` in user space is what the filter may paint, by default the bounds of what the group
+draws, 10 % wider and higher on each side. The primitives (`vec_io.filter`) are those of
+SVG's Filter Effects 1, with the same semantics:
+
+| Primitive | Parameters |
+|---|---|
+| `GaussianBlur` | `std_deviation` (one value, or x and y) |
+| `Offset` | `dx`, `dy` (sub-pixel) |
+| `Flood` | `color`, `opacity` |
+| `DropShadow` | `dx=2`, `dy=2`, `std_deviation=2`, `color`, `opacity` |
+| `Composite` | `operator` (`over`, `in`, `out`, `atop`, `xor`, `lighter`, `arithmetic`), `input2`, `k1`…`k4` |
+| `Merge` | `*inputs`, the first at the bottom (`None`: the previous result) |
+| `Blend` | `mode` (the 16 CSS blend modes), `input2` |
+| `ColorMatrix` | `type` (`matrix` with 20 `values`, `saturate`, `hueRotate`, `luminanceToAlpha`), `values` |
+| `ComponentTransfer` | `r`, `g`, `b`, `a`: `Transfer(type, table, slope, intercept, amplitude, exponent, offset)` |
+| `Morphology` | `operator` (`erode`, `dilate`), `radius` |
+| `Tile` | — |
+| `ConvolveMatrix` | `kernel`, `order=3`, `divisor`, `bias`, `target_x`, `target_y`, `edge_mode`, `preserve_alpha` |
+| `Turbulence` | `base_frequency`, `octaves`, `seed`, `type` (`turbulence`, `fractalNoise`), `stitch`, `transform` |
+| `DiffuseLighting`, `SpecularLighting` | `light` (`DistantLight(azimuth, elevation)`, `PointLight(x, y, z)`, `SpotLight(x, y, z, points_at, specular_exponent, limiting_cone_angle)`), `surface_scale`, `constant`, (`exponent`), `color` |
+| `Image` | `source` (PNG, JPEG or JPEG XL bytes or a path), `preserve_aspect_ratio`, `smooth` |
+| `DisplacementMap` | `scale`, `x_channel`, `y_channel` (`R`, `G`, `B`, `A`), `input2` |
+
+Every primitive also takes `input` (`"SourceGraphic"`, `"SourceAlpha"` or an earlier
+`result`; default the previous result; the other standard inputs are transparent),
+`result`, its subregion `x`, `y`, `width`, `height` (default: the union of its inputs'
+subregions, or the filter region) and `space` (`"linearRGB"`, the default, or `"sRGB"`).
+Lengths and positions are in the group's user space; one kernel pixel is one device pixel.
+The pixel work is C (`src/filters.c`).
+
+SVG `filter` properties are read into the same `Filter` (`primitiveUnits`, `filterUnits`,
+`color-interpolation-filters`, `flood-color`, `lighting-color`; `feImage` references to
+elements are transparent; `kernelUnitLength` is ignored) and drawn through
+`group(filter=…)`. In SVG they are off by default, since they rasterize:
+
+| Scope | Enable |
+|---|---|
+| Conversion | `convert(…, filters=True)`; CLI `--filters` |
+| Document | `Document(filters=True)` (SVGs placed with `draw_svg` and `draw.SVG`) |
+| Element and descendants | SVG `data-filters="true"` / `"false"`. Overrides the scope above. |
+
+## 15. SVG support
+
+| Area | Support |
+|---|---|
+| Shapes | `rect` (rounded), `circle`, `ellipse`, `line`, `polyline`, `polygon`, `path` (all commands, arcs) |
+| Structure | `g`, nested `svg`, `use`, `symbol`, `defs`, `a`, `switch`, `viewBox`, `preserveAspectRatio`, `transform`; a zero-size `viewBox` disables rendering; at most 300,000 elements are instantiated through `<use>` per document (further instances are skipped) |
+| Styling | presentation attributes, `style`, `<style>` (type, class, id, attribute selectors; descendant, child, sibling combinators; `:first-child`, `:not()` (selector lists); specificity; `!important`), `font` and `marker` shorthands, inheritance, `inherit`, `currentColor` |
+| CSS | `@media` evaluated for print; `<style media="…">` |
+| Painting | `fill`, `stroke` (CSS Color 4 colors, `device-cmyk()`), `fill-rule`, `stroke-width`/`-linecap`/`-linejoin`/`-miterlimit`/`-dasharray`/`-dashoffset`, `paint-order`, `opacity`, `fill-opacity`, `stroke-opacity` |
+| Paint servers | `linearGradient`, `radialGradient` (focal point, `href` inheritance, `gradientTransform`, `spreadMethod`, `stop-opacity`), `pattern` |
+| Compositing | group opacity, `clipPath` (any shapes and text, `objectBoundingBox`, nested), luminance `mask` |
+| Markers | `marker-start`/`-mid`/`-end`, `orient` (`auto`, `auto-start-reverse`, angles), `viewBox`, `markerUnits`, `overflow`; drawn through `PathMarker` |
+| Text | `text`, `tspan`, `tref`, `textPath` (`startOffset`, `side`, `path`, `method="stretch"`); `x`/`y`/`dx`/`dy`/`rotate` lists; `textLength`, `lengthAdjust`; `text-anchor`; `inline-size` (SVG 2 wrapping: lines aligned by `text-anchor`, the first baseline at `y`); `font` and `font-*` (`font-kerning` included); `letter-spacing`, `word-spacing`, `text-decoration` (applies to descendants, painted with the declaring element's fill and stroke), `dominant-baseline`, `baseline-shift` (`sub`, `super`, lengths, percentages; nested shifts add up), `xml:space` (inherited) |
+| Images | PNG (all color types and depths, interlacing, transparency), JPEG (embedded unchanged), [JPEG XL](#jpeg-xl) (with libjxl), SVG; `data:` URIs or local files; `image-rendering: pixelated`/`crisp-edges` |
+| Filters | see [Filters](#14-filters) |
+| vec_io attributes | `data-rasterize`, `data-simplify`, `data-quality`, `data-filters` |
+| Input | UTF-8 or declared encodings, SVGZ, common HTML entities |
+
+Document size: `width`/`height` in any CSS unit, else `viewBox`, else
+300 × 150. `rem` refers to the font size of the root `<svg>`.
+
+## 16. Fonts
+
+Fonts are embedded as subsets, always. For each character, the font is the first of:
+
+1. The listed families of `font-family`, in order: an `@font-face` font, a font added with
+   `Document.add_font`, or an installed font (`font_dirs`, then `VEC_IO_FONT_DIRS`, then the
+   system directories), weight, width and style matched as in CSS Fonts 4 (missing bold
+   and italic faces are synthesized). A family that is not installed resolves to its
+   first installed metric alias: Helvetica and Arial to Liberation Sans, Arimo, Nimbus
+   Sans, TeX Gyre Heros…; Times and Times New Roman to Liberation Serif, Tinos, Nimbus
+   Roman…; Courier and Courier New to Liberation Mono, Cousine, Nimbus Mono…; else the
+   next family. Generic families resolve to the first installed family of their list
+   (`serif`: Times New Roman, Liberation Serif, DejaVu Serif, …; `sans-serif`: Arial,
+   Helvetica, Liberation Sans, DejaVu Sans, …; `monospace`: Courier New, Liberation Mono,
+   DejaVu Sans Mono, …), else to the best installed face of all.
+2. The generic family the list implies (`serif` for Times-like names, `monospace` for
+   Courier-like ones, else `sans-serif`).
+3. Any installed font that has the character (Greek, Cyrillic, CJK, …).
+4. The first font's `.notdef` glyph (a character no font has).
+
+The standard 14 PDF fonts are used only when asked for: a family naming one (`Helvetica`,
+`Times-Roman`, `Courier-Bold`, `Symbol`, `ZapfDingbats`…, the variant chosen by weight and
+style) with `font_embed=False` (or `Font(embed=False)`): it is not embedded, covers
+WinAnsi (Symbol and ZapfDingbats theirs) with the Adobe metrics, and is not kerned; other
+characters take steps 1–4. SVG text is always embedded.
+
+Text needs an outline font. With none available at all (no installed font, or
+`system_fonts=False` without `font_dirs`, `VEC_IO_FONT_DIRS`, `@font-face` or `add_font`),
+drawing or measuring text raises `NoFontError` (`vec_io.fonts.fontdb`, a `ValueError`) naming
+these remedies; documents without text need no font. A silent fallback to the standard 14
+fonts would make the PDF depend on the viewer's fonts, differ from vec_io's own images,
+and fail anyway in image output and PDF/A, which need outlines.
+
+Font files: TrueType, OpenType (CFF), collections (`.ttc`), WOFF 1.0 and WOFF 2.0
+(`.woff2`, collections included; Brotli is decoded by the bundled C library),
+variable fonts included (TrueType `gvar` and CFF2).
+All fonts are subset to the glyphs used, renumbered in order of first use; the codes
+are given when the PDF is written, so a document drawn on after a save writes a larger
+subset next time. TrueType outlines are embedded as TrueType (`FontFile2`), without their
+hinting unless the output asks for it (`font_hinting=True`, [Document](#4-document-and-page));
+CFF outlines,
+name-keyed or CID-keyed, as a CID-keyed CFF (`FontFile3/CIDFontType0C`) with
+unused subroutines emptied. A 5 MB CJK OpenType font typically adds a few
+kilobytes.
+Text remains selectable and searchable (ToUnicode maps).
+Pair kerning (GPOS `kern`, else the `kern` table) applies to every text: one-line text,
+paragraphs and SVG text (`font-kerning: none` and `font_kerning="none"` turn it off).
+Standard ligatures (GSUB `liga`) apply to paragraphs and to `vec_io.text.shape` with
+`ligatures=True`; one-line Canvas text and SVG text show one glyph per character.
+A subset costs a few KB: a plot page's labels and bold title in Arial (two faces) add
+about 4 KB, compressed (20 KB with the hinting).
+
+### Variable fonts
+
+A variable font is embedded as a static instance at each position used: outlines
+(`gvar` with IUP, or CFF2 blends), advances (`HVAR`, else phantom points), metrics
+(`MVAR`), hinting (`cvt` with `cvar`) and kerning (`GPOS` device deltas) are
+varied; `GSUB`/`GPOS` feature variations (such as `rvrn`) apply. CFF2
+instances are written as CID-keyed CFF. The axes follow CSS:
+
+| Axis | From |
+|---|---|
+| `wght` | `font_weight` / `font-weight` |
+| `wdth` | `font_stretch` / `font-stretch` (percent) |
+| `ital` | 1 for `italic` |
+| `slnt` | minus the `oblique` angle (14° when none is given) |
+| `opsz` | the font size in px, with `font_optical_sizing="auto"` |
+| any | `font_variation_settings` / `font-variation-settings`, applied last |
+
+Values are clamped to the axes' ranges. Face matching treats a variable face as
+covering its whole `wght` and `wdth` ranges, and as italic when an `ital` or `slnt`
+axis allows it, so a variable font is preferred to synthetic bold or oblique. A
+position that matches a named instance uses its PostScript name (`NotoSans-Bold`);
+others are named after Adobe TN 5902 (`RobotoFlex_26.667opsz_650wght_85wdth`). An
+`@font-face` with a `font-weight` range (`100 900`) takes the font's own axis.
+Malformed variation data raises `FontError` when the font is used.
+
+### Installed fonts
+
+For machine-independent output, pass `system_fonts=False` and provide fonts
+with `font_dirs`, `@font-face` or `add_font`. `VEC_IO_FONT_DIRS` (directories separated by
+`os.pathsep`) adds font directories to every `FontDB`, also with `system_fonts=False`; the
+tests point it at their own font.
+
+Font directories are scanned once per process. The name, weight and style of
+every font file are kept in a persistent index (`fonts.json` in
+`$XDG_CACHE_HOME/vec_io`, `~/Library/Caches/vec_io` or
+`%LOCALAPPDATA%\vec_io\Cache`), so later processes re-read only new or
+changed files (by size and modification time). `VEC_IO_FONT_CACHE=0` disables
+the index; another value is the path of the index file.
+
+PDF/A documents embed every font: `embed=False` is ignored, and a character no font
+covers raises `ValueError`.
+
+## 17. Geometry: `Matrix`, `Path`
+
+```python
+Matrix(a=1, b=0, c=0, d=1, e=0, f=0)     # x' = a x + c y + e,  y' = b x + d y + f
+```
+
+Class methods `translate(tx, ty=0)`, `scale(sx, sy=None)`,
+`rotate(degrees, cx=0, cy=0)`, `skew_x(degrees)`, `skew_y(degrees)`.
+Methods: `multiply(other)` (applies `other` first), `apply(x, y)`,
+`inverse()` (`None` if singular), `determinant()`, `is_identity()`,
+`values()` → `(a, b, c, d, e, f)`.
+
+```python
+Path(d=None)        # SVG path data (made absolute cubic), another Path, or segments
+```
+
+A packed path: `verbs` (a `bytearray` of `Path.MOVE`, `LINE`, `CURVE`, `CLOSE`) and
+`coords` (an `array('d')`: 2 per move or line, 6 per curve), recorded into scenes as they
+are. Segments are tuples `("M", x, y)`, `("L", x, y)`, `("C", x1, y1, x2, y2, x, y)`,
+`("Z",)`; iterating a path gives them, `segments` lists them. Methods (chainable):
+`move_to`, `line_to`, `curve_to`, `close`, `extend(other)`; `transformed(m)` (new path),
+`current_point()`, `to_svg(decimals=6)` (path data), `bbox()` → `(x0, y0, x1, y1)` or
+`None`, `is_empty()`, `area()`: the area filled with the nonzero rule (subpaths closed as for
+filling; holes, overlaps and self-intersections counted as filled), with curves flattened
+to 1/10,000 of the path's size; 0 for paths that fill nothing.
+
+## 18. Output
+
+* Compressed (default): PDF 1.5. Streams are zlib-compressed, small objects
+  are packed into compressed object streams and the cross-reference table is
+  a compressed xref stream; identical streams are written once. Tiny
+  documents use whichever layout is smaller. On SVG files this halves the
+  output size compared with a classic layout (median ratio 0.53).
+* `compression` of every compressed stream: `"fast"` (zlib level 1),
+  `"balanced"` (zlib 6, default) or `"best"`: vec_io's Deflate (binary-tree match
+  finder, near-optimal parsing iterated over the Huffman costs, block splitting),
+  as small as libdeflate's best level and 3–6 % smaller than zlib's best (PNG rows,
+  PDF streams). On a 17 MB content stream (a 1M-point line) `fast` is 6.5× faster
+  than `balanced` and 16 % larger; on SVG conversions `best` writes 9 % less Flate
+  data than `balanced`, in 1.6× the time of zlib's best. PNG data embedded as is is
+  recompressed at `best`.
+* Streams of 1 MB or more are compressed in 1 MB chunks on worker threads
+  (`VEC_IO_THREADS`, see [Rendering](#rendering)): each chunk is primed with
+  the previous 32 KB, so the result is one zlib stream within 0.01 % of the
+  serial size, and the same bytes for any number of threads.
+* `compress=False`: classic, human-readable PDF 1.4 layout, for debugging.
+* Every file carries a document `/ID` derived from its content.
+* Object numbers and resource names are given when a file is written: names per
+  category in the order the resources were first used (`F1`, `GS1`, `Fm1`, `Im2`…),
+  objects in the order they are reached; identical streams are written once.
+* Fonts are embedded as subsets of the glyphs drawn, in the order they were first drawn
+  (scenes hold glyph ids; the subset codes are written with the PDF). TrueType subsets
+  leave out the hinting by default (`fpgm`, `prep`, `cvt` and the glyph instructions):
+  viewers rarely use it at screen resolutions, and vec_io's rasterizer never does.
+  A plot page with Arial labels and a bold title is 5.4 KB without it, 21.8 KB with it
+  (`font_hinting=True`); CFF subsets keep their hints (they are part of the
+  charstrings).
+* SVG conversion: one page of the SVG's size, 1 px = 0.75 pt.
+* SVG output: `vec_io.svg.writer.page_svg(page)` (and `Drawing.to_svg`) writes what a page
+  draws, read from its scene command by command by the C library, as the PDF writer reads
+  it: paths with their fills and strokes, `<text>` with every glyph placed (`<tspan>` where
+  kerning or adjustments move one; the faces named by family, weight and style), `<image>`
+  (PNG and JPEG files as given, other images as PNG), gradients and tiling patterns, clips
+  and soft masks (`<clipPath>`, `<mask>`), forms (marker shapes, groups) as `<defs>` reused
+  by `<use>`, links as `<a>`; smooth cells' mesh becomes an image of about two samples per
+  unit, and a filtered group the image it is drawn as. Colors are RGB (CMYK and spot colors
+  as their approximation); content asking for simplification is written whole. Read back
+  by vec_io, a page renders as it did (tests: mean difference under half an 8-bit level;
+  marker sprites and meshes differ at edges). 200,000 markers take 20 ms (12 MB), a
+  1M-point line 42 ms, 1.5–2.6× the PDF content writer.
+* Shapes and text stay vectors; only rasterized groups, filters and PNG
+  output produce pixels.
+* Numbers: coordinates (paths, rectangles, marker positions, lines, areas,
+  segments, cells) are written to 1/1000 pt or finer on the page:
+  the decimals follow the largest scale of the transform, from 0 to 6 (3 for
+  user units in points, 5 for inches). Transform matrices, line widths and
+  dashes have 6 decimals, colors 4. Drawing records a scene (`scene.py`) whose numbers
+  are rounded to these decimals when they are captured; the C library writes the content
+  streams from it.
+* Identical inputs give identical bytes, and a document written again with the same
+  options gives the same bytes. PDF/A files carry the current date (taken when the
+  document is made) unless `creation_date` is given.
+* PDF/A-2b, 2u and 3b: see [PDF/A](#pdfa).
+* CMYK (`Document(color_mode="cmyk")`): see [Document](#4-document-and-page).
+  Limits: the conversion is naive (not ICC-managed); JPEG files are kept
+  in their own color space; a spot color in a gradient uses its CMYK
+  alternate; inside masks, images (including heatmaps in `image` mode)
+  stay in CMYK.
+
+## 19. Errors
+
+| Exception | Raised for |
+|---|---|
+| `vec_io.SVGParseError` (`ValueError`) | Input that is not a usable SVG document. |
+| `vec_io.fonts.sfnt.FontError` (`ValueError`) | Malformed or unsupported font data: from `Document.add_font`, and when writing or rasterizing a font whose glyph data is malformed. `@font-face` fonts that cannot be read are ignored. |
+| `vec_io.fonts.fontdb.NoFontError` (`ValueError`) | Text with no outline font available at all ([Fonts](#16-fonts)). |
+| `vec_io.raster.RasterizationError` | Content the rasterizer cannot draw (a standard 14 font with no installed font to draw it, too many dashes, unsupported shadings or JPEGs). |
+| `vec_io.native.NativeLibraryError` | The C library is not built for this platform or failed to load. |
+| `vec_io.image.codecs.JPEGError`, `JXLError`, `AVIFError`, `vec_io.image.resource.ImageError` (all `ValueError`) | Malformed or unsupported image data given to `vec_io.image.codecs`. |
+| `ValueError` | Invalid arguments: mismatched per-point lengths, marker names (markers are paths), invalid colors (components outside [0, 1] included), an unknown unit, cells whose `fill` does not match their edges, palette indices outside the palette, `quality` outside 1–100, `color_mode` other than `"rgb"`/`"cmyk"`, an unknown `pdf_a` level, PDF/A requirements that cannot be met (no font for a character, a missing or mismatched `icc_profile`, a CMYK JPEG in RGB mode, two spot colors with one name and different alternates, `attach` in PDF/A-2), `ink_limit` outside (0, 400], an `icc_profile` that is not a gray, RGB or CMYK ICC profile, a `Spot` alternate without 4 components, a link or bookmark to a page of another document or an out-of-range page index, non-finite page sizes or `arc` angles. |
+
+## 20. Modules
+
+| Module | Role |
+|---|---|
+| `document.py` | `Document`, `Page`: pages, metadata, outline, attachments, PDF/A, color settings; resources and writing |
+| `canvas.py` | `Canvas`: the recording API |
+| `scene.py` | what a page, form or pattern draws: binary commands, columns, resource handles; written by the C library |
+| `simplify.py` | what content asks of simplification, and each output's plan |
+| `items.py` | per-item arguments of bulk calls |
+| `paint.py`, `units.py` | colors (CSS, CMYK, spot, Oklab), gradients, patterns, masks, markers, path markers; length units |
+| `filter.py` | `Filter` and its primitives: the filter graph, run on a group's pixels |
+| `geometry.py` | `Matrix`, the packed `Path`, path data, arcs |
+| `lines.py`, `shapes.py`, `cells.py` | lines, segments and areas; rectangles and polygons; cells |
+| `text/` | shaping, measuring and layout from a font database (`Font`, `GlyphRun`, `Span`, `shape`, `measure`, `layout`); `text/breaking.py`: line breaking of paragraphs; `text/path.py`: glyphs along a path |
+| `fonts/` | standard and embedded fonts; `fontdb` (discovery and matching), `sfnt`, `cff`, `cff2`, `variations`, `opentype`, `woff2` |
+| `svg/` | `convert`; `parse` (XML, CSS cascade, `SVGDocument`), `css`, `render` (SVG semantics drawn through a `Canvas`), `filters` (`<filter>` as a `Filter`), `writer` (SVG output of scenes, written by the C library) |
+| `image/` | `Image` and the output options (`PNG`, `JPEG`, `JXL`, `AVIF`, `ImagePolicy`); `codecs`, `jxl`, `avif`, `resource` (loading, `ImageResource`) |
+| `pdf/` | `objects` (PDF values, numbered when written), `writer`, `images` (image XObjects), `pdfa` |
+| `raster/` | rasterizer bindings, resource tables, rasterized groups |
+| `draw.py` | drawings of elements |
+| `arrays.py`, `flate.py`, `threads.py` | array arguments ([§21](#21-array-arguments)); parallel zlib; worker threads (`VEC_IO_THREADS`) |
+| `native/` | the bundled C library: sources, binaries, generated bindings |
+
+## 21. Array arguments
+
+`vec_io.arrays` reads array arguments: sequences (`None` for missing values) or buffers, as
+everywhere ([Conventions](#1-conventions)). Buffers are converted in C, whatever their item
+type and byte order.
+
+| Function | Returns |
+|---|---|
+| `doubles(values)` | a 1-D sequence or buffer as `array('d')`, `None` as NaN; an `array('d')` is returned as it is |
+
+Statistics (binning, densities, contours, quantiles, scaling) and color maps are plot_io's.