On the meaning of \the and \pgf@xx in \edef#1{\the\pgf@xx}

Question

Let us assume that we have a JPEG file of mushrooms given in the following link: mushroom Regarding how to put a rounded node at a certain position I appreciate the complete answer of frougon in the link, frougon. frougon also used simple \getxlength and \getylength macros to allow easy storing of the current lengths of the /tikz/x and /tikz/y vectors, expressed in points. On the meaning of \the and \pgf@xx in \edef#1{\the\pgf@xx}, I searched in Tikz manual and could not find anything. My Question:

1. What is the meaning of \the and \pgf@xx in \edef#1{\the\pgf@xx}
2. In which CTAN package we can find the explanation of \the and \pgf@xx in \edef#1{\the\pgf@xx}?

Below is the code:

\documentclass{article}
\usepackage{tikz}
\usetikzlibrary{calc, shapes.misc}

\newcommand{\midfont}{\fontsize{15}{18}\usefont{T1}{lmss}{m}{n}}

\makeatletter
% These assume that the /tikz/x vector is “horizontal” and /tikz/y “vertical”.
\newcommand*{\getxlength}[1]{\edef#1{\the\pgf@xx}}
\newcommand*{\getylength}[1]{\edef#1{\the\pgf@yy}}
\makeatother

\begin{document}

\centering
\begin{tikzpicture}
\node[anchor=south west, inner sep=0] (image) at (0,0)
{\includegraphics[width=0.9\textwidth]{mushrooms.jpg}};

\begin{scope}[x={(image.south east)}, y={(image.north west)}]
\draw[help lines, xstep=.1, ystep=.1] (0,0) grid (1,1);
\foreach \x in {0,1,...,9} { \node [anchor=north] at (\x/10, 0) {0.\x}; }
\foreach \y in {0,1,...,9} { \node [anchor=east] at (0, \y/10) {0.\y}; }

% Get the unit vector lengths in points
\getxlength{\xLen} \getylength{\yLen}
\node[draw, red, line width=1pt, shape=rounded rectangle, inner sep=0,
    minimum width=0.2*\xLen, minimum height=0.2*\yLen]
 at (.5,.5) (rect) {};
\node[red, font=\midfont] at (0.5-0.2, 0.5+0.2) (text) {Center is here};
\draw[line width=1pt, red, ->] (text) -- (rect);
\end{scope}
\end{tikzpicture}

\end{document}

Answer 1

In TikZ, when you say \draw(0, 0)--(1, 0), the "pen" moves to (0, 0) (the origin) and then draw a straight to (1, 0) (one centimeter east of the origin).

You can modify this behavior by saying \begin{tikzpicture}[x = 1in]. That way, the unit length in the x-direction becomes one inch. So (1, 0) is now one inch east of the origin.

Similarly, \begin{tikzpicture}[y = 1pt] will change the unit length in the y-direction to one TeX point (not PostScript point, the latter is what bp is for). So now (0, 1) is one TeX point north of the origin.

Things become complicated when there is a third dimension. When you have

\draw [->] (0, 0, 0) -- (1, 0, 0) node {$x$};
\draw [->] (0, 0, 0) -- (0, 1, 0) node {$y$};
\draw [->] (0, 0, 0) -- (0, 0, 1) node {$z$};

You don't always want the x-axis to point to the east. You want the three axes forming some 120-ish degree angles. So TikZ allows you to say

\begin{tikzpicture}[
    x = {(-2cm, -1cm)},
    y = {(2cm, -1cm)},
    z = {(0cm, 3cm)}
]

So now the x-unit vector is two centimeters west and one centimeter south of the origin, and so on. That way, the whole graph will look like it's using orthogonal projection.

\pgf@xx and its five friends (that's a group of six friends!) are just registers that store your setting.

x = («\pgf@xx», «\pgf@xy»),
y = («\pgf@yx», «\pgf@yy»),
z = («\pgf@zx», «\pgf@zy»),

They together store a transformation matrix.

Additional remark

tikz-3dplot has the follwoing

\tikzset{tdplot_main_coords/.style={
    x={(\raarot cm, \rbarot cm)},
    y={(\rabrot cm, \rbbrot cm)},
    z={(\racrot cm, \rbcrot cm)}}}
}

it also has \rcarot, \rcbrot, and \rccrot Those are the depths into the screen of the three unit vectors. They are not visible, but they are important when you accumulate transformations. Eventually, you are just storing the 3x3 transformation matrix.

So that's the meaning of \pgf@xx family.

\the

Let's just say \the is a magic word that turns a length to a string. After \xdef\mystring{\the\pgf@xx}, \mystring is now a literal representation of \pgf@xx. If \pgf@xx is one hundred TeX points, then \mystring will be "100.0pt", a string consisting of seven characters. This is useful because you may want to reuse that length else where (for instance, outside the TikZ picture).

It looks unnecessarily difficult because that's just how length registers in TeX work. In TeX, there is a limited number of length registers but you can store as many strings as you want. So by converting useful lengths into strings, we can store them under some unique macro names. And when we need them later, we just convert them back to lengths. The entire node system works like that.

Answer 2

I am no tikz expert, but if you play around a little, one can glean the meaning as the paper-length associated with the distance 1.0 in the x and y directions of the particular tikzpicture.

The leading \the merely means to typeset the subsequent (internal) length.

In the MWE, I print the values of \xLen and \yLen. Then I typeset a rule of width \xLen. In the first image, it spans the whole width of the active portion of the graph, from (not surprisingly) 0 to 1.

In the second image, I have used a scale=2 on the outer tikzpicture, which apparently does not apply to the scoped inner commands. Thus, the scoped portion appears at 1/2 size, and the values of \xLen and \yLen are correspondingly halved, as well.

\documentclass{article}
\usepackage{tikz}
\usetikzlibrary{calc, shapes.misc}

\newcommand{\midfont}{\fontsize{15}{18}\usefont{T1}{lmss}{m}{n}}

\makeatletter
% These assume that the /tikz/x vector is “horizontal” and /tikz/y “vertical”.
\newcommand*{\getxlength}[1]{\edef#1{\the\pgf@xx}}
\newcommand*{\getylength}[1]{\edef#1{\the\pgf@yy}}
\makeatother

\begin{document}

\centering
\begin{tikzpicture}
\node[anchor=south west, inner sep=0] (image) at (0,0)
{\includegraphics[width=0.9\textwidth]{example-image}};

\begin{scope}[x={(image.south east)}, y={(image.north west)}]
\draw[help lines, xstep=.1, ystep=.1] (0,0) grid (1,1);
\foreach \x in {0,1,...,9} { \node [anchor=north] at (\x/10, 0) {0.\x}; }
\foreach \y in {0,1,...,9} { \node [anchor=east] at (0, \y/10) {0.\y}; }

% Get the unit vector lengths in points
\getxlength{\xLen} \getylength{\yLen}
\node at (.2,.2) {\xLen, \yLen.};
\node at (.5,.32) {\rule{310pt}{1pt}};
\node[draw, red, line width=1pt, shape=rounded rectangle, inner sep=0,
    minimum width=0.2*\xLen, minimum height=0.2*\yLen]
 at (.5,.5) (rect) {};
\node[red, font=\midfont] at (0.5-0.2, 0.5+0.2) (text) {Center is here};
\draw[line width=1pt, red, ->] (text) -- (rect);
\end{scope}
\end{tikzpicture}

\begin{tikzpicture}[scale=2]
\node[anchor=south west, inner sep=0] (image) at (0,0)
{\includegraphics[width=0.9\textwidth]{example-image}};

\begin{scope}[x={(image.south east)}, y={(image.north west)}]
\draw[help lines, xstep=.1, ystep=.1] (0,0) grid (1,1);
\foreach \x in {0,1,...,9} { \node [anchor=north] at (\x/10, 0) {0.\x}; }
\foreach \y in {0,1,...,9} { \node [anchor=east] at (0, \y/10) {0.\y}; }

% Get the unit vector lengths in points
\getxlength{\xLen} \getylength{\yLen}
\node at (.2,.2) {\xLen, \yLen.};
\node at (.5,.32) {\rule{155pt}{1pt}};
\node[draw, red, line width=1pt, shape=rounded rectangle, inner sep=0,
    minimum width=0.2*\xLen, minimum height=0.2*\yLen]
 at (.5,.5) (rect) {};
\node[red, font=\midfont] at (0.5-0.2, 0.5+0.2) (text) {Center is here};
\draw[line width=1pt, red, ->] (text) -- (rect);
\end{scope}
\end{tikzpicture}

\end{document}

Answer 3

I appreciate the answers and comments done by great authors, Steven B. Segletes, and David Carlisle, and Symbol 1. I combine their hints to answer my original question.

Q1:What is the meaning of \the and \pgf@xx in \edef#1{\the\pgf@xx}? A1:

• Per Steven B. Segletes: The leading \the merely means to typeset the subsequent (internal) length.
• Per David Carlisle if say \textwidth is a length register set to 10cm then \the\textwidth produces the characters 10cm and similarly any other register. \pgf@xx is just an internal length from the pgf package.
• Per Symbol 1 Let's just say \the is a magic word that turns a length to a string. After \edef\mystring{\the\pgf@xx}, \mystring is now a literal representation of \pgf@xx. If \pgf@xx is one hundred TeX points, then \mystring will be "100.0pt", a string consisting of seven characters.

Q2: In which CTAN package we can find the explanation of \the and \pgf@xx in \edef#1{\the\pgf@xx}?

A2: Per David Carlisle:

• \the is a tex primitive so look in the TeXbook or tex by topic, it returns the value of a register
• a simple file seach will show where it is defined, it is a length register allocated in the core pgf code. /usr/local/texlive/2021/texmf-dist/tex/generic/pgf/basiclayer/pgfcorepoints.code.tex:\newdimen\pgf@xx
• commands with @ in them are by design internal commands that you should not expect to find in a manual.