PDF Pattern
A PDF pattern is a colour definition that fills or strokes paths with repeating or gradient content, rather than a flat colour. Patterns are specified using the /Pattern colour space — to paint a path with a pattern, you set the colour space to /Pattern and the colour to the named pattern, then issue a fill or stroke command.
PDF defines two distinct pattern types: tiling patterns (Type 1) which repeat a user-defined graphic cell across a region, and shading patterns (Type 2) which apply a smooth gradient paint operation. Both types allow PDF to produce sophisticated visual effects that cannot be expressed with flat ink.
Tiling patterns (Type 1)
A tiling pattern defines a graphical cell — any sequence of PDF drawing operations — that repeats to fill the painted region:
<strong>Pattern dictionary structure</strong>: <code><< /Type /Pattern /PatternType 1</code> <code> /PaintType 1 % colored: pattern carries its own colour</code> <code> /TilingType 1 % constant spacing</code> <code> /BBox [0 0 10 10] % cell bounding box</code> <code> /XStep 10 /YStep 10 % cell repetition step</code> <code> /Resources <<>> % resources used in the pattern cell</code> <code> /Matrix [1 0 0 1 0 0] % pattern space to user space transform</code> <code>>></code>
The pattern stream (the content of the dictionary stream) contains normal PDF drawing operators that define the cell. On <code>/PaintType 1</code> (coloured tiling pattern), the cell carries its own colour information. On <code>/PaintType 2</code> (uncoloured tiling pattern), the cell is colourless — the pattern is applied with a tint colour specified at paint time, producing a coloured version of the template.
<strong>TilingType</strong> controls how cells are placed: - Type 1 (Constant Spacing): cells are placed at exact /XStep, /YStep intervals — fastest to render - Type 2 (No Distortion): cells may be placed at slightly different intervals to avoid distortion - Type 3 (Constant Spacing and Faster Tiling): approximation for fast rendering
<strong>Common uses</strong>: hatch fills for engineering drawings, textured backgrounds, repeating decorative borders, cross-hatching for area fills in charts, and technical diagram annotations.
Shading patterns (Type 2)
A shading pattern applies a smooth colour transition (gradient) as a paint operation. Instead of a pattern dictionary with a cell, a shading pattern dictionary contains a shading dictionary:
<code><< /Type /Pattern /PatternType 2</code> <code> /Shading shadingDict</code> <code> /Matrix [1 0 0 1 0 0]</code> <code>>></code>
The shading dictionary (or it can be defined separately and referenced by <code>sh</code> operator) defines the gradient type and parameters. PDF supports 7 shading types:
<strong>Type 1 (Function-Based)</strong>: A function maps (x, y) coordinates to colour values. Can produce any mathematical colour surface. <strong>Type 2 (Axial / Linear)</strong>: Colour transitions along a line between two endpoints. Standard linear gradient. <strong>Type 3 (Radial / Circular)</strong>: Colour transitions between two circles. Standard radial gradient. <strong>Type 4–7 (Mesh Shadings)</strong>: Complex free-form gradient meshes (Coons patch mesh, tensor-product patch mesh) for organic gradient shapes.
Shading patterns are vector-based — they are resolution-independent and scale without quality loss. This contrasts with rasterised gradients (images) which pixelate when enlarged. See <a href="/glossary/pdf-shading" target="_blank" rel="noopener">PDF Shading</a> for detailed shading type specifications.
<strong>Performance consideration</strong>: Shading patterns are computationally expensive to render, particularly mesh shadings. For screen display at typical zoom levels, modern PDF viewers handle them efficiently. For print production, RIPs may rasterise shading patterns to images at the output resolution — a process called "transparency flattening" also applies to shading patterns in transparency groups.
Patterns in the PDF resource model
Patterns are defined in the page (or Form XObject) resource dictionary under the /Pattern sub-dictionary. Each pattern has a unique name (e.g., /P1, /HatchFill) within the resource dictionary:
<code>/Resources << /Pattern << /P1 patternObject /P2 patternObject2 >> >></code>
To paint with a pattern in a content stream: <code>/Pattern cs % set non-stroking colour space to Pattern</code> <code>/P1 scn % set non-stroking colour to pattern P1</code> <code>rect fill % fill the path with the pattern</code>
Or for stroking: <code>/Pattern CS % stroking colour space (uppercase)</code> <code>/P1 SCN % stroking colour</code> <code>path S % stroke with the pattern</code>
<strong>Pattern inheritance</strong> — Like other resources, patterns can be defined at the page level and inherited by Form XObjects, or defined locally within a Form XObject. Patterns are not inherited across pages; each page that uses a pattern must reference it in its own resource dictionary (though the actual pattern object can be shared as an indirect object reference).
<strong>PDF/A and patterns</strong> — Tiling and shading patterns are allowed in PDF/A-2 and later. PDF/A-1 allows patterns but with restrictions aligned to its PDF 1.4 baseline. Colour-space requirements for patterns in PDF/A contexts are the same as for other page content: device-independent colour spaces or device-dependent with output intent.
Frequently asked questions
What is the difference between a PDF pattern and a PDF shading?
A shading (accessed via the sh operator) paints a gradient directly into the current clipping path — it is not a "colour" value, it is a painting operation. A shading pattern (PatternType 2) wraps a shading dictionary in a /Pattern colour space, allowing the gradient to be used as a "colour" — set as the fill or stroke colour for any path. The practical difference: sh paints the shading in the current user space regardless of path; a shading pattern paints the gradient only within the filled or stroked path. For filling a complex shape with a gradient, a shading pattern is the correct mechanism. For filling the entire current clipping region with a gradient, sh is simpler.
Can I use patterns in PDF/A documents?
Yes, with profile-specific restrictions. PDF/A-1 (based on PDF 1.4) allows tiling patterns and shading patterns but requires any colour spaces used within the pattern to comply with PDF/A-1 colour requirements (device-dependent colours must have an output intent). PDF/A-2 and later support patterns with the same colour space requirements as other content. Patterns that reference external content (Form XObjects with external references) are not allowed in PDF/A. Patterns that include transparency (blend modes, soft masks) are not allowed in PDF/A-1 but are allowed in PDF/A-2 and later (with colour management requirements for transparency groups).
How do I extract patterns from a PDF?
Patterns are stored as stream objects in the PDF's resource dictionary. To extract them: (1) In Adobe Acrobat, there is no direct export for patterns — they are embedded rendering instructions. (2) With PyMuPDF: use page.get_drawings() to extract vector drawing operations, which includes paths filled with patterns; the pattern itself is described as part of the drawing data. (3) With QPDF's object inspection: qpdf --json input.pdf shows all objects including pattern definitions. Tiling patterns are full content streams — they can be extracted and rendered as standalone graphics. Shading patterns contain mathematical gradient definitions that require a rendering engine to visualise.