#438 [manual] The order of transformations in the description of the \pgfshadepath algorithm

[Evan Aad]

The shading algorithm given in the description of the \pgfshadepath command in subsection 109.3 ('Using Shadings') of chapter 109 ('Shadings') of the TikZ & PGF manual for version 3.0.1a reads (pp. 1085-1086):

... the center of the shading is translated (moved) such that it lies on the center of the bounding box of the path. The low-level coordinate system is also scaled such that the shading “covers” the path (the details are a bit more complex, see below). Then, the coordinate system is rotated by 〈angle〉.

Thus, according to the manual the order of transformations is: 1. shift, 2. scale, 3. rotate. However, in the source code (tex/generic/pgf/basiclayer/pgfcoreshade.code.tex) a different order is specified in the comment attached to the implementation of the \pgfshadepath command:

The shading will be rotated by #2 and then rescaled so that it completely covers the path.

Thus, according to the documentation inside the source code, the order of transfromations is: 1. rotate, 2. scale.

Since matrices in general, and transformation matrices in particular, are generally not commutative, the order of application matters!

A perusal of the source code reveals that the system-layer transformations are applied in the order 1. shift, 2. scale, 3. rotate. However since system-layer transformations affect the coordinate-system rather than the graphical objects, the effect on the coordinates that his sequence have is the opposite, so that a user who is not familiar with system-layer transformations (and someone reading chapter 109 should not be expected to be familiar with these details), will perceive the effects of this algorithm as though the order of transformations were as described in the source-code comment, namely: 1. rotation, 2. scale, 3. shift, and will therefore be confused by the algorithm described in the manual.

In my opinion, the manual should be corrected to state the order of transfromations as 1. rotate, 2. scale, 3. shift. I personally was very confused when I read this algorithm in the manual and tried to compare it to the actual results of shading a path, and it wasn't until I delved into the source-code and read about PDF canvas transfromations that I realized what was really going on.

[Stefan Pinnow]

Because I don't know how to test this, could you add an MWE to prove right order of transformations and best also a suggestion on what the text should be changed to (as you did for a lot of your other manual bug reports)?

[Evan Aad]

I'd love to add a minimal working example, however I haven't used TikZ/PGF
since, roughly, the time I made this bug report, and I've grown very rusty.
I wouldn't be able to produce a working example now without a lot of
effort, which I'd rather not put into it. Thanks for going over all my bug
reports.