line["dir"] seems to actually be (cosine, -sine) instead (cosine, sine)

[indigoviolet]

https://pymupdf.readthedocs.io/en/latest/textpage.html#line-dictionary

cos 30 = 0.87
sin 30 = 0.5

and so on.

[JorjMcKie]

Hm, true - in a way. The problem here is again the difference between the coordinate systems of PDF vs. MuPDF:

• PDF has (0,0) at the page's bottom-left. So the positive y-direction points upwards and the text in top-left quadrant is rotated anti-clockwise via matrix Matrix(30). In fact, the text in the picture has been written using page.insert_text(point, "PyMuPDF", morph=(point, fitz.Matrix(30))). Where Matrix(30) = Matrix(0.87, 0.5, -0.5, 0.87, 0.0, 0.0).

• MuPDF has (0,0) at the page's top-left, and positive y-direction points downwards. In that system, this text coordinates (and the writing direction) are multiplied with the page transformation matrix, which for an A4 page is ctm = Matrix(1.0, 0.0, 0.0, -1.0, 0.0, 842.0). So in MuPDF's coordinate system the text indeed appears as being transformed with Matrix(30) * ctm = Matrix(0.87, -0.5, -0.5, -0.87, 0.0, 842.0). This explains the value of "dir" in the picture (matrix.a, matrix.b).

Maybe you have a suggestion, how this could best be explained in the documentation?

[indigoviolet]

A few initial thoughts:

1. Add a page explaining the different coordinate systems, pointers to the rotation machinery, and lay out the functions that produce rotated or unrotated coordinates. I see this information distributed across many issues/discussions in this repo.

2. dir as (cosine, sine) is just incorrect in the context of the counterclockwise angle to x-axis. I would present this as (cosine, -sine), so that people know how to go from "dir" to the angle.

3. To write text at an angle, it seems that the PyMuPDF API already handles this as you show.

[indigoviolet]

Also to explain the context in which I'm encountering this:

I'm trying to use the extractDICT spans to create a text representation that follows the layout. This is similar to how pdfplumber does it (and based on that code, I'd be happy to contribute it back to this repo if you are interested) -- it is optimized for left->right horizontal top->bottom text).

While doing this I encountered pages whose page.rotation = 0, but the text is written with dir (0, -1), and I'm correcting for it by picking the majority "dir", selecting a rotation based on it, and then I apply the same algorithm on that rotated page (making sure to correct bboxes with rotation_matrix).

If you have suggestions or pointers for how to do this better/more robustly, I'd be grateful.

[JorjMcKie]

Thank you very much for your feedback!
I think we will start by correcting the documentation of the line dictionary.
An adequate synopsis of the different coordinate systems and how to deal with them is indeed necessary, but does require upfront thought how to best structure it.