Understanding the output of pdf.get_drawings() better

[qwertynik]

Hello,

Thanks for building this feature-rich and accessible PDF processing library.

To extract and locate drawings in the PDF had found that the get_drawings function will help in doing so.

While the output of the function is understandable, more clarity is required in some other parts of the output. Here are a couple of questions regarding the output:

1. For rectangles present in the PDF the following is accessible via items in a path.
   ('re', Rect(161.14181518554688, 1049.828857421875, 274.5833435058594, 1050.5782470703125), -1)
   What does the 3rd item, -1 mean here?

2. For circles, the output is
   ('c', (Point(84.67462921142578, 532.7891235351562), Point(84.67462158203125, 532.9878540039062), Point(84.6365966796875, 533.178955078125), Point(84.56056213378906, 533.3626098632812)))
   Unsure about why there are four points. What do they denote?

There are more questions. Any documentation to look at to understand the above with greater clarity?

Thanks!

[JorjMcKie]

Thanks for the compliments ...

This function tries to create output that can be used directly as input by methods of class Shape. So a deeper look in the docs there will help a lot.
This implies that you can recreate the drawings of some input page (not necessarily PDF!) on a new PDF page of your choice. For this there exists an example script.

For rectangles, I recently included an indicator (+1 / -1) for the area orientation. Background: you can draw it in a clockwise (-1) or anti-clockwise movement, which gives the enclosed are a "spin" or orientation.
Area orientation is important to determine if the fill color should be disregarded under the "non-zero winding rule".

Circles (ellipses) are generally drawn by 4 connected Bézier curves (a type of splines). The variant I am using consists of 4 points: start point, two control points, end point per each of the 4 curves.

BTW you will never see actual circles in documents (PDF or not) - it is always an approximation by Bézier splines (polynomial curves of 3rd degree). For mathematical reasons, it is theoretically impossible to precisely represent a circle by splines. But you can have good approximations if you restrict the spline to some part (hence quarter circle) of the circumference (and choose the control points well).

[qwertynik]

@JorjMcKie Thanks for your detailed response.

For those, like me, who do not know what non-zero winding rule is, check here

Area orientation is important to determine if the fill color should be disregarded under the "non-zero winding rule".

Will the fill key in the path (item from paths = page.get_drawings()) already have this derived? ie: whether to fill the area or not.

The primary goal behind understanding the output better is to identify shapes (in code). However, looks the way PDFs are designed it is not so straightforward.

Here's how a rectangle with rounded edges is represented.

('l', Point(129.63461303710938, 410.6478271484375), Point(129.63461303710938, 391.91448974609375))
('c', Point(129.63461303710938, 391.91448974609375), Point(129.63458251953125, 391.4176330566406), Point(129.7296600341797, 390.939697265625), Point(129.9197998046875, 390.48065185546875))
('c', Point(129.9197998046875, 390.48065185546875), Point(130.1099395751953, 390.0216064453125), Point(130.38064575195312, 389.6164855957031), Point(130.73196411132812, 389.2651672363281))
('c', Point(130.73196411132812, 389.2651672363281), Point(131.0832977294922, 388.913818359375), Point(131.4884490966797, 388.64312744140625), Point(131.9474639892578, 388.4529724121094))
('c', Point(131.9474639892578, 388.4529724121094), Point(132.40650939941406, 388.2629089355469), Point(132.88442993164062, 388.1678466796875), Point(133.3812713623047, 388.1678466796875))

('l', Point(133.3812713623047, 388.1678466796875), Point(428.6184997558594, 388.1678466796875))
('c', Point(428.6184997558594, 388.1678466796875), Point(429.1152648925781, 388.1678466796875), Point(429.59326171875, 388.2629089355469), Point(430.0522155761719, 388.4529724121094))
('c', Point(430.0522155761719, 388.4529724121094), Point(430.5111999511719, 388.64312744140625), Point(430.9163513183594, 388.913818359375), Point(431.26776123046875, 389.2651672363281))
('c', Point(431.26776123046875, 389.2651672363281), Point(431.61907958984375, 389.6164855957031), Point(431.8897705078125, 390.0216064453125), Point(432.0798645019531, 390.48065185546875))
('c', Point(432.0798645019531, 390.48065185546875), Point(432.27001953125, 390.939697265625), Point(432.3651428222656, 391.4176330566406), Point(432.3651428222656, 391.91448974609375))

('l', Point(432.3651428222656, 391.91448974609375), Point(432.3651428222656, 410.6478271484375))
('c', Point(432.3651428222656, 410.6478271484375), Point(432.3651428222656, 411.1446228027344), Point(432.27001953125, 411.62249755859375), Point(432.0798645019531, 412.08160400390625))
('c', Point(432.0798645019531, 412.08160400390625), Point(431.8897705078125, 412.5406494140625), Point(431.61907958984375, 412.9457702636719), Point(431.26776123046875, 413.297119140625))
('c', Point(431.26776123046875, 413.297119140625), Point(430.9163513183594, 413.6484069824219), Point(430.5111999511719, 413.91912841796875), Point(430.0522155761719, 414.10919189453125))
('c', Point(430.0522155761719, 414.10919189453125), Point(429.59326171875, 414.29937744140625), Point(429.1152648925781, 414.3945007324219), Point(428.6184997558594, 414.3945007324219))

('l', Point(428.6184997558594, 414.3945007324219), Point(133.3812713623047, 414.3945007324219))
('c', Point(133.3812713623047, 414.3945007324219), Point(132.88442993164062, 414.3945007324219), Point(132.40650939941406, 414.29937744140625), Point(131.9474639892578, 414.10919189453125))
('c', Point(131.9474639892578, 414.10919189453125), Point(131.4884490966797, 413.91912841796875), Point(131.0832977294922, 413.6484069824219), Point(130.73196411132812, 413.297119140625))
('c', Point(130.73196411132812, 413.297119140625), Point(130.38064575195312, 412.9457702636719), Point(130.1099395751953, 412.5406494140625), Point(129.9197998046875, 412.08160400390625))
('c', Point(129.9197998046875, 412.08160400390625), Point(129.7296600341797, 411.62249755859375), Point(129.63458251953125, 411.1446228027344), Point(129.63461303710938, 410.6478271484375))

Any helper methods in the library that would discern that it is a rectangle with rounded corners? By looking at the Points one can infer that it is a rounded rectangle: the first Bezier curve's point is similar to the line's last point, and the last Bezier curve's point is similar to the first point of the line following.

It's simpler for this case. However, for different paths, inferring how they will appear to the human eye becomes complex. A relatively simpler approach could be to just export the path as an image and use OpenCV to detect the shape.

Any other simpler approaches to adopt here?

Thanks!

[JorjMcKie]

Will the fill key in the path (item from paths = page.get_drawings()) already have this derived? ie: whether to fill the area or not.

No, because it cannot.
There may be multiple rectangles, circles, ... in the same path. Only their mutual overlap applies for that NZW rule, which obviously could be quite arbitrary looking figures.

I have no intention to add more higher level interpretations of the drawings output - like rectangles with rounded corners etc.
As per now I am detecting rectangles and quads - not even whether something is a circle. And that will be it, presumably. I am not underway building a new PDF viewer ... 😎.
So the rest will remain the "atomic" draw commands, lines and curves.

If you find something that can dig its way through the page's pixmap image and detect more complex things - please do not hesitate to share it here.

[qwertynik]

Sure @JorjMcKie.

Is Bezier curve used in MuPDF's output, or is this unique to this library - perhaps for better representation.

[JorjMcKie]

Bézier curves are used all over the place: PDF, XPS, EPUB, fonts, postscript and what not.
Nothing specific to PDF nor MuPDF at all.
As mentioned, this is a class of curves collectively called splines. Used in mathematics as well to piecewise approximate other curves, where the precise point coordinates are represented by infinite power series.
E.g. the correct parametric function for a circle is f(t) = (cos(t), sin(t)). But if this were used instead of an approximating 3rd degree spline, then each point on the perimeter would require computing the power series for sine / cosine - which may mean adding up 5-8 numbers each of the form x**n/n! where n is in range(8) for the x and the y component - plus a check for x**n/n! < 1e-8 or similar ...
Whereas a spline only requires adding 3 numbers, each of which are extremely easy to compute ... and no checking required.