Return the vector graphics of the page. These are instructions which draw lines, rectangles, quadruples or curves, including properties like colors, transparency, line width and dashing, etc. Alternative terms are “line art” and “drawings”.
Returns:a list of dictionaries. Each dictionary item contains one or more single draw commands belonging together: they have the same properties (colors, dashing, etc.). This is called a “path” in PDF, so we adopted that name here, but the method works for all document types.
The path dictionary for fill, stroke and fill-stroke paths has been designed to be compatible with class Shape. There are the following keys:
Key
Value
closePath
Same as the parameter in Shape.
color
Stroke color (see Shape).
dashes
Dashed line specification (see Shape).
even_odd
Fill colors of area overlaps – same as the parameter in Shape.
fill
Fill color (see Shape).
items
List of draw commands: lines, rectangles, quads or curves.
lineCap
Number 3-tuple, use its max value on output with Shape.
lineJoin
Same as the parameter in Shape.
fill_opacity
fill color transparency (see Shape). (New in v1.18.17)
stroke_opacity
stroke color transparency (see Shape). (New in v1.18.17)
rect
Page area covered by this path. Information only.
layer
name of applicable Optional Content Group. (New in v1.22.0)
level
the hierarchy level if extended=True. (New in v1.22.0)
seqno
command number when building page appearance. (New in v1.19.0)
type
type of this path. (New in v1.18.17)
width
Stroke line width. (see Shape).
Key "opacity" has been replaced by the new keys "fill_opacity" and "stroke_opacity". This is now compatible with the corresponding parameters of Shape.finish(). (Changed in v1.18.17)
For paths other than groups or clips, key "type" takes one of the following values:
“f” – this is a fill-only path. Only key-values relevant for this operation have a meaning, not applicable ones are present with a value of None: "color", "lineCap", "lineJoin", "width", "closePath", "dashes" and should be ignored.
“s” – this is a stroke-only path. Similar to previous, key "fill" is present with value None.
“fs” – this is a path performing combined fill and stroke operations.
Each item in path["items"] is one of the following:
("l", p1, p2) - a line from p1 to p2 (Point objects).
("c", p1, p2, p3, p4) - cubic Bézier curve from p1 to p4 (p2 and p3 are the control points). All objects are of type Point.
("re", rect, orientation) - a Rect. Multiple rectangles within the same path are now detected (changed in v1.18.17). Integer orientation is 1 resp. -1 indicating whether the enclosed area is rotated left (1 = anti-clockwise), or resp. right [7] (changed in v1.19.2).
("qu", quad) - a Quad. 3 or 4 consecutive lines are detected to actually represent a Quad (changed in v1.19.2:). (New in v1.18.17)
Using class Shape, you should be able to recreate the original drawings on a separate (PDF) page with high fidelity under normal, not too sophisticated circumstances. Please see the following comments on restrictions. A coding draft can be found in section “Extractings Drawings” of chapter FAQ.
Specifying extended=True significantly alters the output. Most importantly, new dictionary types are present: “clip” and “group”. All paths will now be organized in a hierarchic structure which is encoded by the new integer key “level”, the hierarchy level. Each group or clip establishes a new hierarchy, which applies to all subsequent paths having a larger level value. (New in v1.22.0)
Any path with a smaller level value than its predecessor will end the scope of (at least) the preceding hierarchy level. A “clip” path with the same level as the preceding clip will end the scope of that clip. Same is true for groups. This is best explained by an example:
+------+------+--------+------+--------+| line | lvl0 | lvl1| lvl2 | lvl3 |+------+------+--------+------+--------+| 0| clip || ||| 1| | fill| ||| 2| | group | ||| 3| || clip ||| 4| || | stroke || 5| || fill || ends scope of clip in line 3| 6| | stroke | || ends scope of group in line 2| 7| | clip| ||| 8| fill || || ends scope of line 0+------+------+--------+------+--------+The clip in line 0 applies to line including line 7. Group in line 2 applies to lines 3 to 5, clip in line 3 only applies to line 4.
“stroke” in line 4 is under control of “group” in line 2 and “clip” in line 3 (which in turn is a subset of line 0 clip).
“clip” dictionary. Its values (most importantly “scissor”) remain valid / apply as long as following dictionaries have a larger “level” value.
Key
Value
closePath
Same as in “stroke” or “fill” dictionaries
even_odd
Same as in “stroke” or “fill” dictionaries
items
Same as in “stroke” or “fill” dictionaries
rect
Same as in “stroke” or “fill” dictionaries
layer
Same as in “stroke” or “fill” dictionaries
level
Same as in “stroke” or “fill” dictionaries
scissor
the clip rectangle
type
“clip”
“group” dictionary. Its values remain valid (apply) as long as following dictionaries have a larger “level” value. Any dictionary with an equal or lower level end this group.
Key
Value
rect
Same as in “stroke” or “fill” dictionaries
layer
Same as in “stroke” or “fill” dictionaries
level
Same as in “stroke” or “fill” dictionaries
isolated
(bool) Whether this group is isolated
knockout
(bool) Whether this is a “Knockout Group”
blendmode
Name of the BlendMode, default is “Normal”
opacity
Float value in range [0, 1].
type
“group”
Note
The method is based on the output of Page.get_cdrawings() – which is much faster, but requires somewhat more attention processing its output.
Show/hide history
New in v1.18.0
Changed in v1.18.17
Changed in v1.19.0: add “seqno” key, remove “clippings” key
Changed in v1.19.1: “color” / “fill” keys now always are either are RGB tuples or None. This resolves issues caused by exotic colorspaces.
Changed in v1.19.2: add an indicator for the “orientation” of the area covered by an “re” item.
Changed in v1.22.0: add new key "layer" which contains the name of the Optional Content Group of the path (or None).
Changed in v1.22.0: add parameter extended to also return clipping and group paths.