simplify_vectors

Reduce vector path complexity

Usage

pdftl <input> simplify_vectors [<pages>] [key=val ...] output <output>

Details

The simplify_vectors operation reduces the complexity of vector paths in PDF content streams, lowering file size and rendering time while attempting to preserve visual appearance.

How It Works

The operation processes content streams in four stages:

  1. Parse PDF content streams into drawing instructions.

  2. Segment instructions into individual paths and subpaths.

  3. Simplify geometry:

    • Curved paths are fitted with cubic Bézier curves using Schneider’s Graphics Gems algorithm.

    • Linear paths are simplified using the Ramer-Douglas-Peucker (RDP) algorithm.

  4. Serialize the simplified paths back into PDF content streams.

The current transformation matrix (CTM) is tracked throughout processing so that tolerances are applied consistently in device space, even under nested graphics-state transforms.

Form XObjects and Tiling Patterns are processed recursively.

If simplification would increase operator count, exceed error limits, or cannot be performed safely, the original path is preserved unchanged. |

Configuration Parameters

tolerance (float, default: 0.15)

  • Maximum permitted geometric deviation in device-space points.

  • Larger values produce more aggressive simplification.

  • Must be greater than zero.

curves (bool, default: true)

  • Enable Schneider cubic Bézier fitting for curved paths.

lines (bool, default: true)

  • Enable Ramer-Douglas-Peucker simplification for linear paths.

clip_paths (bool, default: false)

  • Allow simplification of clipping paths (W / W*).

  • Use with care because clipping paths affect subsequent rendering.

min_points (int, default: 4)

  • Minimum number of sampled points required before simplification is attempted on a subpath.

max_error_scale (float, default: 4.0)

  • Error multiplier used by curve-fitting heuristics when attempting iterative refinement before subdivision.

Notes

  • Tolerances are specified in device-space points, not PDF user-space units.

  • Graphics-state transforms (cm, q, Q) are tracked automatically.

  • Form XObjects and Tiling Patterns are processed recursively.

  • When simplification is not beneficial, the original path is emitted unchanged.

Examples

Simplify all pages with default tolerance

pdftl in.pdf simplify_vectors output out.pdf

Aggressive simplification of curved paths on pages 2-3

pdftl in.pdf simplify_vectors 2-3 tolerance=0.5 curves=true lines=false output out.pdf

Simplify clipping paths (use with care)

pdftl in.pdf simplify_vectors clip_paths=true tolerance=0.1 output out.pdf

Tags: in_place, content_stream, custom

Source: pdftl.operations.simplify_vectors

Read online: https://pdftl.readthedocs.io/en/latest/operations/simplify_vectors.html

Type: Operation