Tikz: What is the use of coordinate system xyz polar?

Question

I am learning TikZ from the manual—Till Tantau makes a great explanation job. However, I got stucked in the Coordinate system xyz polar. (See page 138 of the tikz manual). The canvas polar coordinates make full sense to me, you define points in the plane through distance to coordinates origin and angle (see picture)

But for the xyz polar I do not understand the explanation in the manual and the examples make no sense to me.

Please, could I get some example that shows me what is the advantage of using them?

Note added:

This comment on page 139 makes it even more weird "[xy polar is] an alias for xyz polar, which some people might prefer as there is no z-coordinate involved in the xyz polar coordinates".

It seems quite an intricate coordinates system.

Answer 1

The difference is in the units. Let's have a look at the pgfmanual v3.1.5 on p. 138

The perhaps most important statement is the sentence

Finally, multiply the resulting vector by the given radius factor.

Let's look at an example.

\documentclass[tikz,border=3mm]{standalone}
\begin{document}
\begin{tikzpicture}
 \draw circle[x radius=2.5,y radius=1];
 \path (xyz polar cs:angle=50,x radius=2.5,y radius=1) 
    node[circle,fill=blue,inner sep=1.5pt]{}
 (canvas polar cs:angle=50,x radius=2.5,y radius=1) 
    node[circle,fill=red,inner sep=1.5pt]{}
 (canvas polar cs:angle=50,x radius=2.5cm,y radius=1cm) 
    node[circle,draw=red,inner sep=1.75pt]{};
\end{tikzpicture}
\end{document} 

We did not specify the units in xyz polar cs: and the point is in on the ellipse as the coordinates here are factors that multiply the basis vectors. If we leave out the units in canvas polar cs:, they will be interpreted as dimensionful distances in pt, which is why the red dot is very close to the origin. If we add the units, we are back at the blue point.

The pgfmanual sort of admits that the name xyz polar may be confusing on p 139.

So just imagine we had talked about xy polar all time (but the question was specifically about xyz polar).

The same output as above is obtained with

\documentclass[tikz,border=3mm]{standalone}
\begin{document}
\begin{tikzpicture}[x=2.5cm,y=1cm];
 \draw circle[radius=1];
 \path (xy polar cs:angle=50,radius=1) 
    node[circle,fill=blue,inner sep=1.5pt]{}
 (canvas polar cs:angle=50,radius=1)    
    node[circle,fill=red,inner sep=1.5pt]{}
 (canvas polar cs:angle=50,x radius=2.5cm,y radius=1cm) 
    node[circle,draw=red,inner sep=1.75pt]{};
\end{tikzpicture}
\end{document}

where you see that the advantage is that we only need to say radius=1 in xy polar cs. The main reason why this is not really appreciated that much is that

\path (50:1) node[circle,fill=blue,inner sep=1.5pt]{};

yields the same blue point, and virtually everyone uses the last syntax. The parser checks whether the radius has dimensions via \ifpgfmathunitsdeclared, and if not it interprets it as a factor. (I recommend reading this very nice answer for a very pedagogical and clear discussion of radii with or without explicit units.)

The upshot is that probably most of us have at a given point used polar coordinates of the type (<angle>:<radius factor>), where the term radius factor is used to indicate that we did not add dimensions to the radius. At this point we were using xyz polar cs, perhaps without explicitly noticing it. So xyz polar cs is in fact a very useful coordinate system which gets used a lot, perhaps without us users noticing that too much.

Finally, let us mention that canvas polar and xyz polar really are just wrappers for \pgfpointpolar and \pgfpointpolarxy, respectively.

\tikzdeclarecoordinatesystem{canvas polar}
{%
  \tikzset{cs/.cd,angle=0,radius=0cm,#1}%
  \pgfpointpolar{\tikz@cs@angle}{\tikz@cs@xradius and \tikz@cs@yradius}%
}%

\tikzdeclarecoordinatesystem{xyz polar}
{%
  \tikzset{cs/.cd,angle=0,radius=0,#1}%
  \pgfpointpolarxy{\tikz@cs@angle}{\tikz@cs@xradius and \tikz@cs@yradius}%
}%

where the latter can be looked up on p. 1084 and 1085, respectively

So, again, the difference is a radius vs. a radius factor.