\documentclass[11pt, a4paper]{article}
\IfFileExists{/home/daniel/.personal/models/new.sty}{%
  \def\pathToLaTeXMacros{/home/daniel/.personal/models}}{%
  \def\pathToLaTeXMacros{/users/200001077/.personal/modeles}}


\usepackage{tikz}
\usetikzlibrary{external}
\tikzexternalize[prefix=z_zExternalize/]

\usepackage{\pathToLaTeXMacros/Elanguage}
\usepackage{\pathToLaTeXMacros/new}
\usepackage{\pathToLaTeXMacros/boxedEnvironments}

\usepackage{hyperref}
\hypersetup{colorlinks=true, citecolor=M!80!V, linkcolor=BK}

\usepackage{caption}
% The caption package provides a width parameter than can be set for
% each figure individually.
% The width can be set with the option \captionsetup{width=<len>} globally.
\captionsetup{width=.926\textwidth}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% local commands

\usepackage{pgfplots}
\usepgfplotslibrary{colormaps}

\usetikzlibrary{patterns}
\usetikzlibrary{positioning}
\usetikzlibrary{decorations.markings}
\usetikzlibrary{decorations.pathmorphing}
\usetikzlibrary{decorations.pathreplacing} % for show control points
\usetikzlibrary{decorations.text}

\usetikzlibrary{shadings}
\usetikzlibrary{shadows.blur}
\usetikzlibrary{shapes.symbols} % for special shapes

%\usetikzlibrary{fadings}
\usepackage{rotunda}
\usepackage{pgothic}


\setcounter{tocdepth}{3}
\usepackage{fancyvrb}  % http://ctan.org/pkg/verbatim
\usepackage{newverbs}
\usepackage{longtable}

\DefineVerbatimEnvironment{code}{Verbatim}{%
  formatcom=\color{DarkB!90!BK},
  % fontfamily=\sfdefault,
  frame=single% bottomline, lines
}
\newverbcommand{\verbc}{\color{DarkB!90!BK}}{}

\newcommand{\textttc}[1]{{\color{DarkB!90!BK}\texttt{#1}}}
\newcommand{\tikZ}{Ti{\color{R}\textbf{\textit{k}}}Z}



\makeatletter
  % transform a dimension (in pt) into a dimensionless number
  \newcommand{\strippt}{\strip@pt\dimexpr}
\makeatother



\begin{document}
\tikzexternaldisable
\equalheight  % side result: \mylength
\firstpage
\showdate

\title{\tikZ\ tutorial}
\author{\gsignature{.5}}



\begin{itemize}[noitemsep]
\item
  Manual: www.ctan.org/pkg/pgf
\item
  Example repository: www.texample.net/tikz/
\item
  Community for specific help: tex.stackexchange.com/
\end{itemize}

\tableofcontents


  % \tikzmath{%
  %   real \res, \n;
  %   function tmpF(\n) {
  %     \res = \n +1;
  %     return \res;
  %   };
  % }
  % \begin{tikzpicture}[scale=3]
  %   \draw[->, very thin] (-.2, 0) -- (1.3, 0);
  %   \draw[->, very thin] (0, -.2) -- (0, 1.05);

  %   \draw (-.2, .5) node[draw] {3}; %{\b};
  %   \draw (1, {sin(0.1 r)}) node[draw] {30}; %{\b};
  %   \draw (.4, {tmpF(0.1)}) node[draw] {3}; %{\b};
  % \end{tikzpicture}




\section{Introduction---drawings and canvas}

\tikZ\ is the frontend layer of PGF for drawing in \LaTeX.  Here
drawing means the use of points, curves, and shapes to convey a
message.  \tikZ\ commands for doing it parallel natural drawing
gestures: where to place the pencil, where to move the pencil, how to
move the pencil, how to enhance a drawn element, and so on.  The
syntax is the usual \LaTeX\ one.


Drawing commands have to be enclosed in an \emph{tikzpicture}
environment.  Among the global options, a useful one is
\verbc|baseline=d|, like in \tikz{\draw (0,0) rectangle (1em,2ex);}
\tikz[baseline=1ex]{\draw (0,0) rectangle (1em,2ex);} where
\verb|baseline=1ex| for the second rectangle (the baseline of the
drawing is modified with respect to the baseline of the surrounding
text).

\begin{code}
\begin{tikzpicture}[<options>] 
  <tikz commands>
\end{tikzpicture}
\end{code}


The basic elements of \tikZ\ are
\begin{itemize}[noitemsep]
\item
  points; \quad
  \verbc|\path (a,b) coordinate (P);| defines the point $P=(a,b)$
\item
  paths; \quad
  \verbc|\draw (P) -- (Q);| defines the line segment $[PQ]$ where $P$
  and $Q$ were previously defined
\item
  rectangles, circles, and ellipses (\ie basic shapes);\\
  \verbc|\draw (0,0) rectangle (1em,2ex);| draws
  \tikz{\draw (0,0) rectangle (1em,2ex);} as an in-text rectangle\\
  \verbc|\draw (0,0) circle (1ex);| draws
  \tikz{\draw (0,0) circle (1ex);} as an in-text circle of radius $2ex$\\
  \verbc|\draw (0,0) ellipse[x radius=2em, y radius=ex];| draws
  \tikz{\draw (0,0) ellipse[x radius=1em, y radius=1ex];}
\end{itemize}


In this introduction I briefly present the points and the coordinate
systems.  Then in the following sections, I continue the presentation of
the basic elements and of their main options.  For an element, the
presentation will be made in two steps: a simpler one first, and
later, being more at ease with \tikZ, a more detailed one. 




\subsection{Coordinates and points---placing the pencil}

The simplest way of defining a point is shown below.  The name of the
point is $A$ and can be used afterwards.  In the example, a circle is
drawn centered at $A$.
\begin{code}
  \coordinate (A) at (0, 0);
  \draw (A) circle (2pt);
\end{code}


\begin{noticeB}
  \verbc|\coordinate| is an abbreviation for \verbc|\path coordinate|.
\end{noticeB}


\pgfdeclarelayer{background}
\begin{tikzpicture}[remember picture, overlay]
  \pgfsetlayers{background, main}
  \coordinate (NE) at (current page.north east);
  \coordinate (C) at (current page.center);
  \path (NE) ++(-2, -1) node[R, scale=1.5] {\textbf{Test!}};
  \begin{pgfonlayer}{background}
    \draw[B, fill=AW, opacity=.5, transform canvas={shift={(-1, -1)}}]
    (NE) rectangle ($(C)!.35!(NE)$);    
  \end{pgfonlayer}
\end{tikzpicture}


It is worth noticing that on the current page there are points
associated to absolute positions.  The transparent antique white
rectangle in the upper right corner is drawn using them.  The elements
appearing in this definition will be explained in the next sections:
\begin{itemize}[noitemsep, label={--}]
\item 
  Apply the option \verbc|remember picture| to the tikzpicture
  environment; it enables \tikZ\ to save the picture size and various
  segments in the picture.
\item
  Specify the \verbc|overlay| option which puts the picture out
  of the text-segment.  It allows it to be placed on top of text
  without taking up any space (otherwise the drawing is a regular
  text-box which is placed next to the preceding TeX-box).
\item
  The two points defining the rectangle are
  \verbc|(current page.north east)| and an affine combination of it with
  \verbc|(current page.center)|.  The rectangle is shifted using the
  \emph{key=value operation}
  \verbc|transform canvas={shift={(-1,-1)}}|.
\item
  Note that the layer system (see the use of \verbc|pgfsetlayers| in the
  code) has no effect outside the picture
  environment.  The text already written on the page is under the
  antique white rectangle.
\end{itemize}


For other ways of defining points (calculated positions,
intersections, \ldots) see \S\,\ref{s:definingPoints}.



\subsection{Coordinate systems}

A coordinate is a position on the canvas---on which your picture is
drawn.  There are two ways of specifying which coordinate system
should be used: 
\begin{description}
\item[explicitly]
  the name of the coordinate system is given at the beginning,
  followed by \textttc{cs:}, which stands for ``coordinate system'',
  followed by a specification of the coordinate using the
  \textttc{key-value} syntax.
\item[implicitly]
  \tikZ\ notices when you use a coordinate specified in a special
  syntax and chooses the correct coordinate system.
\end{description}


\begin{examples*}
  In the first example, the red point is specified by
  \verbc|(canvas cs:x=2, y=0)|, \ie unitless coordinates, while the
  white one by $x=2pt$.

  \smallskip
  \renewcommand{\arraystretch}{1.5} % space between rows (default 1)
  \noindent
  \begin{tabular}{L{.2\linewidth} L{.3\linewidth} L{.4\linewidth}}
    explicitly
    & \begin{tikzpicture}
      \path[use as bounding box] (-.2,-.6) rectangle (3.2, 2.2);
      \draw[help lines] (0,0) grid (3,2);
      \fill (canvas cs:x=1cm, y=1.5cm) circle (2pt);
      \fill (canvas cs:x=2cm, y=-5mm+2pt) circle (2pt);
      \draw[fill=R] (canvas cs:x=2, y=0) circle (2pt);
      \draw[fill=white] (canvas cs:x=2pt, y=1cm) circle (2pt);
    \end{tikzpicture}
    & the lower left corner of the grid is the origin of the
      coordinate system \\
    implicitly
    & \begin{tikzpicture}
      \fill[B, opacity=.1, use as bounding box] (-.2,-.6) rectangle (3.2, 2.2);
      \draw[help lines] (0,0) grid (3,2);
      \fill (1, 1.5) circle (2pt);
      \fill[yshift=2pt] (2, -.5) circle (2pt);
      \draw[fill=R] (2, 0) circle (2pt);
      \draw[fill=white] (2pt, 1) circle (2pt);
    \end{tikzpicture}
    & note how the red point appears now at $(2,0)$, since everything
      is unitless \\
    implicitly (polar)
    & \begin{tikzpicture}[scale=.7]
      \draw[help lines] (-2, -2) grid (2,2);
      \foreach \i in {0, ...,7}{%
        \fill[R] ($(360*\i/7:1.5)$) circle (3pt);
      }
    \end{tikzpicture}
    & the vertices of a regular heptagon; the definition (see below)
      is \verbc|(360/7:1.5)| \\
    implicitly (3d)
    & \begin{tikzpicture}[->]
      \draw (0,0) -- (1,0);
      \draw (0,0) -- (0,1,0);
      \draw (0,0) -- (0,0,1);
    \end{tikzpicture}
  \end{tabular}
\end{examples*}


\begin{noticeB}
  \verbc|\draw[help lines] (0,0) grid (4,3);| creates and draws a
  coordinate system grid.  It is a version of the path operation
  \verbc|rectangle|. 
\end{noticeB}
  



\subsection{Loops}

\verbc|\foreach \i [options] in {<list>}{<commands>};| is a
\textbf{for \ldots do} command.  It can also be used as a \emph{path
action}, see \S\,\ref{ss:foreach}.  The \verbc|options| are introduced
using the keys \verbc|count|, \verbc|evaluate|, and \verbc|remember|
(see Figure \ref{fig:count}).  The former key is useful when the loop
is constructed on a list having no connection with the integers (see
Figure \ref{fig:colors}).

\begin{figure}[htb!]
  \centering
  \tikzexternalenable
  \begin{tikzpicture}[scale=.3, every node/.style={black, scale=.8}]
    \fill[R] (-2, 0) circle (2.1) node at +(0, -3) {$R$};
    \foreach \rC [count=\j from 0, remember=\rC as \lC (initially R)]
    in {O, Y, G, C, B, V, M}{%
      \fill[left color=\lC, right color=\rC] (5*\j, -.3) rectangle +(1, .6);
      \fill[\rC] (5*\j, 0) -- ++(3, 0) circle (2.1) node at ++(0, -3) {$\rC$};
    }
  \end{tikzpicture} \\
  \begin{tikzpicture}[scale=.3, every node/.style={black, scale=.8}]
    \fill[red] (-2, 0) circle (2.1) node at +(0, -3) {$red$};
    \foreach \rC [count=\j from 0, remember=\rC as \lC (initially R)]
    in {orange, yellow, green, cyan, blue, violet, magenta}{%
      \fill[left color=\lC, right color=\rC] (5*\j, -.3) rectangle +(1, .6);
      \fill[\rC] (5*\j, 0) -- ++(3, 0) circle (2.1) node at ++(0, -3) {$\rC$};
    }
  \end{tikzpicture}
  \tikzexternaldisable
  \caption{Name of the colors used in this presentation and the
    comparison with the predefined colors having the same ``name''.}
  \label{fig:colors}
\end{figure}

\begin{code}
  \fill[R] (-2, 0) circle (2.1) node at +(0, -3) {$R$};
  \foreach \rC [count=\j from 0, remember=\rC as \lC (initially R)]
  in {O, Y, G, C, B, V, M}{%
    \fill[left color=\lC, right color=\rC] (5*\j, -.3) rectangle +(1, .6);
    \fill[\rC] (5*\j, 0) -- ++(3, 0) circle (2.1) node at ++(0, -3) {$\rC$};
  }
  \end{tikzpicture}
\end{code}

In the following drawing the key \verbc|evaluate| is introduced.  

\begin{figure}[htb!]
  \centering
  \tikzmath{%
    integer \nb;
    real \r, \margin;
    \nb = 5;
    \r = 1.7;
    \margin = 15;
  }
  \begin{tikzpicture}
    \foreach \j
    [count=\i from 11, evaluate=\j as \a using {360/\nb*(\j -1)},
    evaluate=\j as \tmp using {50*\j/\nb}]
    in {1,...,\nb}{%
      \node[B, draw, circle, fill=B!\tmp!] at (\a: \r) {$\i$};
      \draw[arrows={-Latex[length=2ex, open]}]
      (\a +\margin: \r) arc (\a +\margin: {\a +360/\nb -\margin}: \r);
    }
  \end{tikzpicture}
  \qquad
  \begin{tikzpicture}
    \foreach \j [parse=true, remember=\j as \i (initially 0),
    evaluate=\j as \a using {360/\nb*(\j -1)}]
    in {1,...,\nb}{%
      \node[draw, circle] at (\a: \r) {$\i$};
      \draw[arrows={-Latex[length=2ex, open]}]
      (\a +\margin: \r) arc (\a +\margin: {\a +360/\nb -\margin}: \r);
    }
  \end{tikzpicture}
  \caption{Using the keys \textttc{count}, \textttc{evaluate}, 
    \textttc{remember}, and \textttc{parse}.}
  \label{fig:count}
\end{figure}

\begin{code}
  \foreach \j [count=\i from 11, evaluate=\j as \a using {360/\nb*(\j -1)},
  evaluate=\j as \tmp using {50*\j/\nb}]
  in {1,...,\nb}{%
    \node[B, draw, circle, fill=B!\tmp!] at (\a: \radius) {$\i$};
    \draw[arrows={-Latex[length=2ex, open]}]
    (\a +\margin: \radius) arc (\a +\margin: {\a +360/\nb -\margin}: \radius);
  }
\end{code}

\noindent
Expressions that might appear in \verbc|\foreach| loops:
\begin{itemize}[nolistsep]
\item
   \verbc|remember=\j as \i (initially 0)|
\end{itemize}


\noindent
\verbc|\margin| (=15) is an angle defined according to the node's
diameter; notice the difference between the two drawings in
Fig.\,\ref{fig:count} introduced by the slightly smaller nodes on the
right.

\begin{noticeB}
If mathematical expressions are used in the \verbc|\foreach| list,
then the option \verbc|parse=true| must be called:
\verbc|\foreach [parse=true] \x in {-\a, ..., 3*\a} {...|
\end{noticeB}




\section{Points and curves---drawing}

\subsection{Paths and their characteristics---moving the pencil}

A \emph{path} (or curve) is a series of straight and curved line
segments joining a series of points.  The command to create it is
\verbc|\path <specifications>|.  To make it visible as a curve, the
action \verbc|draw| must be invoked.  For example
\tikz{%
  \path[draw] (0, 0) -- (2em, 1ex) coordinate (A);
  \path[draw, LightGray] (0, 0) rectangle (1em, 1ex);
}
is the result of 
\begin{code}
  \path[draw] (0, 0) -- (2em, 1ex) coordinate (A);
  \path[draw, LightGray] (0, 0) rectangle (1em, 1ex);
\end{code}


The \verbc|<specifications>| is a sequence of \emph{path operations},
\emph{path actions}, and \emph{characteristics} (or
\emph{attributes}) telling \tikZ\ how the path is built and what it
does.  Some examples: 

\noindent
\renewcommand{\arraystretch}{1.2} % space between rows (default 1)
\begin{longtable}{L{.2\linewidth} C{.02\linewidth} L{.7\linewidth}}
  \verbc|-- (0,0)|
  & $=$
  & \emph{line-to operation} meaning ``continue the
    path from wherever you are to the origin'' \\
  \verbc|to (0,0)|
  & $=$
  & same as the previous \\
  \verbc|let ... in|
  & $=$
  & let operation which evaluates some coordinates and numbers and
  assign the results to special macros (\verbc|\x.|, \verbc|\y.|,
  \verbc|\p.|) (see \S\,\ref{ss:let}) \\
  \verbc|[draw]|
  & $=$
  & action making the path visible \\
  \verbc|[color=blue]|
  & $=$
  & attribute, the color used for drawing the path---all parts
    of the path--- \\ 
  \verbc|[line width=2pt]|
  & $=$
  & attribute, the width of the path---all parts of the path--- \\
  \verbc|coordinate|
  & $=$
  & operation defining a point \\
  \verbc|node|
  & $=$
  & special \emph{path operation} that can be used only when a
  normal path operation could follow

  The effect is to typeset the node's text
  and to place it at the ``current location'' on the path (see
  \S\,\ref{s:nodes}).  Note that \textbf{the nodes are not part of
    the path}.  After the curve has been drawn, the nodes are
  added in a post-processing step. \\
  \verbc|pic|
  & $=$
  & special \emph{path operation} that introduces a short picture and
  can be used where a node can (see \S\,\ref{s:pics})
\end{longtable}


\begin{noticeB}
  The attributes have the \verbc|[key=value]| syntax.  Some path
  actions also.
\end{noticeB}


The second path below is drawn with the attribute \textttc{line
width=2pt}, the third with \textttc{rounded corner}, and the fourth
with \textttc{color=B}, \textttc{line width=2pt}, and
\textttc{rounded corner=10pt}.
\begin{center}
  \tikz{\draw (0,0) -- (1,1) -- (2,0) -- (3,1) -- (3,0) -- (2,1);}
  \qquad
  \tikz{%
    \draw[line width=2pt]
    (0,0) -- (1,1) -- (2,0) -- (3,1) -- (3,0) -- (2,1);
  }
  \qquad
  \tikz{%
    \draw[rounded corners]
    (0,0) -- (1,1) -- (2,0) -- (3,1) -- (3,0) -- (2,1);
  } 
  \qquad
  \tikz{%
    \draw[B, line width=2pt, rounded corners=10pt]
    (0,0) -- (1,1) -- (2,0) -- (3,1) -- (3,0) -- (2,1);
  }  
\end{center}


The attribute \verbc|rounded corner| can be used \emph{in-line} during
the drawing process; the line width cannot!  The last value of rounded
corner is used for the whole curve, or the whole scope.  For example,
the command 
\begin{code}
  \draw[B] (0,0) -- (1,1) {[rounded corners=10pt] -- (2,0) -- (3,1)}
  -- (3,0) -- (2,1);
\end{code}
produces the next figure.
\begin{center}
  \begin{tikzpicture}[scale=1.3]   
    % the axis
    \draw[->] (-.5, 0) to (3.5, 0) node[below=2pt] {$x$};
    \draw[->] (0, -.5) -- (0, 1.5) node[left=2pt] {$y$};
    \draw[shift={(1, 0)}] (0, -1.5pt) -- (0, 1.5pt);
    \draw[shift={(0, 1)}] (-1.5pt, 0) -- (1.5pt, 0);
   
    \draw[B, line width=1.2pt] (0,0) -- (1,1)
    {[rounded corners=10pt] -- (2,0) -- (3,1)} -- (3,0) -- (2,1);
    \foreach \P in {(0,0), (1,1), (2,0), (3,1), (3,0), (2,1)}{%
      \draw[fill=white] \P circle (1.2pt);
    }
  \end{tikzpicture}
\end{center}  
The six points are drawn at the end, after the curve has been traced.


\begin{noticeB}
  \verbc|\draw| is an abbreviation for \verbc|\path[draw]|.
\end{noticeB}


\begin{figure}[htb!]
  \centering
  \begin{tikzpicture}
    \foreach \i/\width/\inpts in {0/ultra thin/.1, 2/very thin/.2,
      4/thin/.4, 6/semithick/.6, 8/thick/.8, 10/very thick/1.2,
      12/ultra thick/1.6%
    }{%
      \draw[B] (\i, .15) -- ++(1.5, 1);
      \draw[B, \width, postaction={draw, color=black,
        transform canvas={xshift=7pt, yshift=-3pt}
      }] (\i, 0) -- ++(1.5, 1) node[pos=.4, text=K, below=.5] {\width};
      \path (\i+.7, -.7) node {= \inpts pt};
    }
  \end{tikzpicture}
  \caption{Some ``natural'' predefined line widths, the default line
    width being $.5$ pt.  The top segment is drawn with the default
    line width.}
  \label{fig:linewidths}
\end{figure}

The key \verbc|line join| specifies how lines meet; the possible
values are \verbc|round|, \verbc|bevel|, and \verbc|miter|, with the
last one being the default value.  The result of using the second:
\tikz{
  \path[use as bounding box] (0, 0) rectangle (1, 1ex);
  \draw[B, line width=4pt, line join=bevel] (0, .2) -- +(1, 0) -- +(0, -.4);
}
There exists also the key \verbc|line cap| with three possible
values: \verbc|round|, \verbc|rect|, and (default)  \verbc|butt|.
\begin{figure}[htb!]
  \centering
  \begin{tikzpicture}
    \draw[Gold, line width=2ex, line join=bevel, line cap=rect]
    (0, .2cm+1ex) -- +(2, 0) -- +(0, -1);
    \draw[B, line width=2ex, line join=bevel, line cap=round]
    (0, .2) -- +(2, 0) -- +(0, -1);
    \draw[R, line width=2ex, line join=bevel, line cap=butt]
    (0, .2cm-1ex) -- +(2, 0) -- +(0, -1);
  \end{tikzpicture}
  \caption{The three possibilities for \textttc{line cap} distinguished
    by colors, \textc[Gold]{rect}, \textttc{round}, \textc[R]{butt}}
  \label{fig:linecaps}
\end{figure}




\subsection{Line-to and relative Cartesian coordinates---where to
  move the pencil}

In the line-to operation, the to-point can be given using absolute
coordinates relative to the canvas, relative coordinates relative to
the \textbf{first preceding absolute defined} point, or relative
coordinates relative to the previous point, the from-point.  The three
syntaxes are
\begin{center}
  \verbc|-- (B)|  \qquad  \verbc|-- +(B)|  \qquad
  \verbc|-- ++(B)|
\end{center}
respectively.  See the three closed curves below.

\begin{center}
  \begin{tikzpicture}[scale=.65, every node/.style={scale=.8}]
    % the grid
    \draw[step=1.0, LightGray, very thin] (-2.5, -1.5) grid (2.5, 3.5);  
    % the axis
    \draw[->] (-3, 0) -- (3, 0) node[below right] {$x$};
    \draw[->] (0, -1.5) -- (0, 4) node[left=.5ex] {$y$};
    % the curve
    \draw[B, very thick] (0, 1) circle (2pt)
    -- (2, 1) -- (-2, 1.5) -- (-1, -1) -- cycle;
    \node[text width=4cm, anchor=north] at (0, -2)
    {absolute position with respect to the initial point $(0, 1)$};
  \end{tikzpicture}
  \quad
  \begin{tikzpicture}[scale=.65, every node/.style={scale=.8}]
    % the grid
    \draw[step=1.0, LightGray, very thin] (-2.5, -1.5) grid (2.5, 3.5);  
    % the axis
    \draw[->] (-3, 0) -- (3, 0) node[below right] {$x$};
    \draw[->] (0, -1.5) -- (0, 4) node[left=.5ex] {$y$};
    % the elements
    \draw[DarkR, very thick] (0, 1) circle (2pt)
    -- +(2, 1) -- +(-2, 1.5) node[above right, text=black] {$(0, 1)+(-2, 1.5)$}
    -- +(-1, -1) -- cycle;
    \node[text width=4cm, anchor=north] at (0, -2)
    {relative position with respect to the initial point $(0, 1)$};
  \end{tikzpicture}
  \quad
  \begin{tikzpicture}[scale=.65, every node/.style={scale=.8}]
    % the grid
    \draw[step=1.0, LightGray, very thin] (-2.5, -1.5) grid (2.5, 3.5);  
    % the axis
    \draw[->] (-3, 0) -- (3, 0) node[below right] {$x$};
    \draw[->] (0, -1.5) -- (0, 4) node[left=.5ex] {$y$};
    % the elements
    \draw[G, very thick] (0,1)  circle (2pt)
    -- ++(2,1) -- ++(-2,1.5) node[above, anchor=west, text=black]
    {$(2, 2)+(-2, 1.5)$}
    -- ++(-1,-1) -- cycle;
    \node[text width=4cm, anchor=north] at (0, -2)
    {relative position with respect to the previous point};
  \end{tikzpicture}
\end{center}
The three path commands, in order, are written below.
\begin{code}
  \draw (0,1) -- (2,1) -- (-2,1.5) -- (-1,-1) -- cycle;
  \draw (0,1) -- +(2,1) -- +(-2,1.5) -- +(-1,-1) -- cycle;
  \draw (0,1) -- ++(2,1) -- ++(-2,1.5) -- ++(-1,-1) -- cycle;
\end{code}



\subsection{Line-to with controls---how to move the pencil. 
  Relative polar coordinates}

The controls (for the line-to operation) are tangent vectors
indicating how to move the pencil when drawing the current piece of
the path.  In the next examples, various type of controls are
given.  They are indicated on the right; the first drawing is the
reference obtained without any control, \ie the polygonal line.

\medskip\noindent
\begin{tikzpicture}[baseline=1cm, scale=.8]
  \draw[LightGray, very thin] (-.5,-.5) grid (3.5,3.2);
  \coordinate (A) at (.5, 0);
  \coordinate (B) at (1, 1);
  \coordinate (C) at (3, 2.5);
  \draw[B, very thick] (A) -- (B) -- (C); 
  \foreach \P in {A, B, C}{\draw[fill=white] (\P) circle (2pt);}
\end{tikzpicture}
\quad \label{page:useOfLet}
 \begin{tikzpicture}[baseline=1cm, scale=.8]
  \draw[LightGray, very thin] (-.5,-.5) grid (3.5,3.2);
  \coordinate (A) at (.5, 0);
  \coordinate (B) at (1, 1);
  \coordinate (C) at (3, 2.5);
  \draw[B, very thick] {%
    let \n1={atan(2)} 
    in (A) -- (B) to[out=\n1, in=270] (C)
  };
  \foreach \P in {A, B, C}{\draw[fill=white] (\P) circle (2pt);}
\end{tikzpicture}
\quad
\verbc|-- (1,1) to[out=\n1, in=270] (3,2.5)|\\
The tangent vector at $(1,1)$ makes an angle of \verbc|\n1| degrees
(which was previously computed as $\arctan(2)$).  It is the angle made
by the piece of curve leaving the from-point.  The tangent vector
at $(3,\frac{5}{2})$ is of $270$ degrees---the angle of the curve
entering the to-point.

\medskip\noindent
\begin{tikzpicture}[baseline=1cm, scale=.8]
  \draw[LightGray, very thin] (-.5,-.5) grid (3.5,3.2);
  \coordinate (A) at (0, 0);
  \coordinate (B) at (1, 2);
  \coordinate (C) at (3, 0);
  \draw[Gray, transform canvas={xshift=.3cm}] (A) -- (B) -- (C); 
  \draw[B, very thick, rounded corners=10pt] (A) -- (B) -- (C); 
  \foreach \P in {A, B, C}{\draw[fill=white] (\P) circle (2pt);}
\end{tikzpicture}
\quad\begin{tikzpicture}[baseline=1cm, scale=.8]
  \draw[LightGray, very thin] (-.5,-.5) grid (3.5,3.2);
  \coordinate (A) at (0, 0);
  \coordinate (B) at (1, 2);
  \coordinate (C) at (3, 0);
  \coordinate (P1) at (1.5, 3);  
  \draw[B, very thick]  (A) -- (B) .. controls (P1) .. (C);  
  \foreach \P in {A, B, C}{%
    \draw[fill=white] (\P) circle (2pt);
  }
  \draw[R, fill=R] (P1) circle (2pt);
\end{tikzpicture}
\quad
\verbc|-- (1,2) .. controls (1.5,3) .. (3.0)|\\
The tangent vector at $(1,2)$ is $(.5,1)=(1.5,3)-(1,2)$.

\medskip\noindent
\begin{tikzpicture}[baseline=1cm, scale=.8]
  \draw[LightGray, very thin] (-.5,-.5) grid (3.5,3.2);
  \coordinate (A) at (0, 0);
  \coordinate (B) at (1, 2);
  \coordinate (C) at (3, 0);
  \draw[B, very thick] (A) -- (B) -- (C); 
  \foreach \P in {A, B, C}{\draw[fill=white] (\P) circle (2pt);}
\end{tikzpicture}
\quad\begin{tikzpicture}[baseline=1cm, scale=.8]
  \draw[LightGray, very thin] (-.5,-.5) grid (3.5,4.2);
  \coordinate (A) at (0, 0);
  \coordinate (B) at (1, 2);
  \coordinate (C) at (3, 0);
  \path (A) -- (B) -- ([turn]0:2) coordinate (P1);  
  \draw[B, very thick]  (A) -- (B)
  .. controls ([turn]0:2) and (1.5, 0) .. (C);  
  \foreach \P in {A, B, C}{%
    \draw[fill=white] (\P) circle (2pt);
  }
  \draw[R, fill=R] (P1) circle (2pt);
\end{tikzpicture}
\quad
\verbc|-- (1,2) .. controls ([turn]0:2) and (1.5,0) .. (3,0)|\\
Now, the tangent vector at $(1,2)$ is the vector that supports the
line segment from $(0,0)$ to $(1,2)$ and is of length $2$.  The point
obtained by adding the vector to $(1,2)$ is indicated in red.


\begin{rem*}
The controls are best given either in a relative form
\verbc|+(vector)| through operations on coordinates, or using the
relative polar coordinates as above.  Explicitly, identical curves are
obtained with the following three line-to operations.
\begin{itemize}[nolistsep]
\item
  \verbc| -- (A) .. controls (P) and ($(B)+(w)$) .. (B)|

  Here $P$ is the point $A+v$ for a certain vector $v$; the curve
  leaves $A$ with speed vector $v$.  The second control point will be
  explained in \S\,\ref{s:definingPoints}---mathematically, it is
  $B+w$.
\item
  \verbc| -- (A) .. controls +(v) and +(w) .. (B)|

  Here, \verbc|+(v)| is the point $P=A+v$ and \verbc|+(w)| is the
  point $B+w$. 
\item
  \verbc| -- (A) .. controls ([turn]0: normOfv)|
  
  Here, the \emph{key} \verbc|turn| is used; inside a coordinate,
  it continues the curve in a direction that might not be controlled a
  priori. 
\end{itemize}
\end{rem*}


\tikzset{  % see manual page 583 
  show control points/.style={
    decoration={
      show path construction,
      curveto code={
        \draw[Gold, fill=DarkR, very thin]
        (\tikzinputsegmentfirst) -- (\tikzinputsegmentsupporta)
        coordinate (Co-1) circle (1.5pt);
        \draw [blue, dashed, fill=red]
        (\tikzinputsegmentsupportb) coordinate (Co-2) circle (1.5pt)
        -- (\tikzinputsegmentlast);
      }
    },
    postaction=decorate
  }
}
\begin{figure}[htb!]
  \centering
  \tikzmath{%
    real \a;
    coordinate \origin, \A, \B, \C, \Q, \v;
    \a = sqrt(2)/2;
    \origin = (0, 0);
    \A = (1, 1);
    \B = (2, 0);
    \C = (1+\a, 0);
    \v = (\a, \a);
    % \Q = (5, 2);
    \Q = ($(\A) + (\v)$);
  }
  \begin{tikzpicture}[scale=1.5]
    \draw[B,thin] (\origin) -- (\A) .. controls (\Q) .. (\B);
    \draw[B, line width=1pt] (\origin) -- (\A) .. controls +(\v) .. (\B);
    \draw[B, line width=1.5pt] (\origin) -- (\A) .. controls ([turn]0:1) .. (\B);    
    \foreach \P/\pos/\name in {%
      \origin/{below left}/O, \A/{above left}/A, \B/{below right}/B
    }{%
      \draw[fill=white] (\P) circle (1pt) node[\pos] {$\name$};
    }
    \filldraw[R] (\Q) circle (1pt) node[above left] {$Q$};
  \end{tikzpicture}
  \qquad
  \begin{tikzpicture}[scale=1.5]
    \draw[B] (\origin) -- (\A) .. controls +(\v) .. (\C);
    \draw[] (\origin) -- (\A) .. controls +(\v) and ($(\C)+(0, 1)$) .. (\C);
    \draw[R, thick] (\origin) -- (\A) to[out=45, in=90] (\C);
    
    \foreach \P/\pos/\name in {%
      \origin/{below left}/O, \A/{above left}/A, \C/{below right}/C
    }{%
      \draw[fill=white] (\P) circle (1pt) node[\pos] {$\name$};
    }
    \filldraw[R] (\Q) circle (1pt) node[above left] {$Q$};
  \end{tikzpicture}
  \qquad
  \begin{tikzpicture}[scale=3.5]
    \draw[B] (\origin) -- (\A) .. controls +(\v) .. (\C);
    \draw[show control points]
    (\A) .. controls +(\v) and ($(\C)+(0, 1)$) .. (\C);
    \draw[R, thick] (\origin) -- (\A) to[out=45, in=90] (\C);
    
    % \draw[G] (\origin)
    % let \p1 = (.4*\vx, .4*\vy) in
    % -- (\A) .. controls +(\p1) and ($(\C)+(0, .4)$) .. (\C);
    \draw[C] (\origin)
    let \p1 = (.5*\vx, .5*\vy) in
    -- (\A) .. controls +(\p1) and ($(\C)+(0, .5)$) .. (\C);
    
    \foreach \P/\pos/\name in {%
      \origin/{below left}/O, \A/{above left}/A, \C/{below right}/C
    }{%
      \draw[fill=white] (\P) circle (1pt) node[\pos] {$\name$};
    }
    \filldraw[R] (\Q) circle (1pt) node[above left] {$Q$};
  \end{tikzpicture}
  \caption{Different manners to define the same control (tangent
    vector).  On the left, the three ways described previously yield
    curves that are identical---superposed in the drawing.  On the
    right, the comparison with the command line-to
    \textttc{to[out=45, in=90]} (the red curve) is made.  For the
    middle black curve, the tangent vectors are of norm $1$ and both
    point towards $Q$.}
  \label{fig:controls}
\end{figure}


\textttc{([turn]<angle>:<norm>)} stands for either a point or a
tangent vector.  The current line-to operation for which the command
\verbc|([turn]<angle>:<norm>)| is either the to-point or the first
control, \textbf{must} follow a line-to operation; if its ending
tangent vector makes an angle $\alpha$, then the starting tangent
angle of the current line-to equals $\alpha + \textttc{<angle>}$.

For example in \verbc|-- (A) to[bend left] (B) -- ([turn]0:2)| the
curve is smoothly continued through $B$.  But if the last line-to
operation were \verbc|-- ([turn]90:2)|, then $B$ would be a singular
point and the two tangents (toward $B$ and away from $B$) would form a
$90^\circ$ direct angle.  See Fig.\,\ref{fig:turn}.

\begin{figure}[htb!]
  \centering
    \begin{tikzpicture}[scale=1]
    \draw[help lines,LightGray] (-.5, -3.5) grid (8.5, 1.5);
    \path (1,1) coordinate (A) node[below left]{$A$};
    \path (4,-1) coordinate (B)  node[below left]{$B$};
    \path (7,-1) coordinate (C)  node[right=3pt]{$C$};
    
    \draw[B, thick] (A) to [bend left] (B)
    -- ([turn]0:1) coordinate (Q) node[below left] {$Q$} 
    .. controls ([turn]0:1) .. (C);
    \draw[DarkG, thick, transform canvas={shift={(.07,.07)}}]
    (A) to [bend left] (B)
    -- ([turn]90:1) coordinate (Q') node[above left] {$Q'$}
    .. controls ([turn]0:1) .. (C);
    
    \foreach \P in {A, B, C, Q, Q'}{%
      \draw[B, fill=white] (\P) circle (2pt);
    }
    \draw[R, fill=R] ($(B)!2!(Q)$) circle (2pt);
  \end{tikzpicture}
  \caption{Using \textttc{[turn]}; for the blue curve, $Q$ is the end
    point of \textttc{-\/- ([turn]0:1)}.  For the green curve, $Q'$ is
    the end of \textttc{-\/- ([turn]90:1)}.}
  \label{fig:turn}
\end{figure}



\subsection{Path actions}

Once a path has been constructed, different things can be done with
it, such that: 
\begin{itemize}[noitemsep, label={--}]
\item
  be drawn (or stroked) with a ``pencil''
  \quad$\Longleftarrow$\quad \verbc|draw|
\item
  be filled with a color \quad$\Longleftarrow$\quad
  \verbc|fill|
\item
  be shaded (around some colors) \quad$\Longleftarrow$\quad
  \verbc|shade|

  (shading is a variation on filling that changes colors
  smoothly from one to another)
\item
  be used for clipping subsequent drawing \quad$\Longleftarrow$\quad
  \verbc|clip|

  (all subsequent drawings up to the end of the current scope are
  clipped against the current path and the size of subsequent paths
  \textbf{will not be important for the picture size})
\item
  be used to specify the extent of the picture \quad$\Longleftarrow$\quad
  \verbc|use as bounding box|
\item
  be geometrically (affine) transformed \quad$\Longleftarrow$\quad
  \verbc|rotate|, \verbc|scale|, \verbc|(xy)shift|
\item
  any combination of these actions at the same time.
\end{itemize}

\noindent
The actions appear as optional arguments along the \verbc|\path|
command.  Abbreviations exist; for example
\verbc|\filldraw| abbreviates \verbc|\path[fill, draw]|.
\begin{center}
  \begin{tikzpicture}[rounded corners, scale=0.9, every node/.style={scale=1}]
    \draw[M, line width=2pt] (0,0) rectangle +(2, 1)
    +(1, -.5) node[text=black] {draw};

    \fill[color=B] (3,0) rectangle +(2, 1)
    +(1, -.5) node[text=black] {fill};

    \draw[pattern=crosshatch] (6,0) rectangle +(2, 1)
    +(1, -.5) node[text=black] {pattern};

    \draw[R, shade, bottom color=C, top color=R]
    (9,0) rectangle +(2, 1)
    +(1, -.5) node[text=black] {shade};

    \draw[V, thin, shade, left color=white, right color=V!60]
    (12, 0) rectangle +(2, 1)
    +(1, -.5) node[text=black] {shade};

    \begin{scope}
      \draw[clip] (15, 0) rectangle +(2, 1);
      \fill[O] (16, -1) circle[radius=1.7];    
    \end{scope}
    \path (15, 0) -- +(1, -.5) node[text=black] {clip};
  \end{tikzpicture}
\end{center}
The first shade action is given by
\begin{code}
  \draw[R, shade, bottom color=C, top color=R] (9,0) rectangle +(2, 1);
\end{code}

Now, to understand the bounding box action, look at the following
in-text image representing a red disk.
\begin{tikzpicture}
  \draw[draw, use as bounding box] (0,0) rectangle (3ex, 4ex);
  \fill[DarkR, opacity=.3] (0, 0) circle (2.5ex);
\end{tikzpicture}
The rectangle's edges bound the image.  Note the vertical space that
is introduced only.  The code follows.
\begin{code}
  \draw[draw, use as bounding box] (0,0) rectangle (3ex, 4ex);
  \fill[R, opacity=.2] (0, 0) circle (2.5ex);
\end{code}





\section{Defining points through coordinate computations}
\label{s:definingPoints}

How can be obtained the coordinates of points issued from geometric
constructions such as the intersection of two curves, the orthogonal
projection of a point on a line segment, the center of the
circumcircle of a triangle, the point of tangency under certain
hypotheses \ldots? 



\subsection{Barycenters and points as images of direct similarities}

\verbc|($(p1)!c!(p2)$)|, where $c$ is a real number, is the barycenter
$(1-c)p_1+cp_2$.  Notice that this point can be obtained also through
the heavier command that copies the mathematical formula,
\verbc|($(1-c)*(p1)+c*(p2)$)|.  As a geometric transformation, it
represents the image of $p_2$ through a homothety of center $p_1$ and
ratio $c$.


\bigskip
\noindent
\verbc|($(p1)!c!angle:(p2)$)| is the image of $p_2$ through a direct
similarity of center $p_1$, ratio $c$, and angle $angle$.  This
similarity is the composition of the rotation of center $p_1$ and
angle $anlge$ with the previous homothety. 


\begin{minipage}[b]{.4\linewidth}
  \begin{tikzpicture}[baseline=1cm]
    \path (-2, 0) coordinate (A) node[below left] {$A$};
    \path (1, 1) coordinate (B) node[below right] {$B$};
    \path ($(A)!.5!(B)$) coordinate (M) node[below right] {$M$};
    \draw (A) -- (B);
    \draw[B, thick] ($(M)!1.5!90:(B)$) -- ($(M)!1.5!-90:(B)$);
    \foreach \P in {A, B, M}{%
      \draw[fill=white] (\P) circle (2pt);
    }
  \end{tikzpicture}
\end{minipage}%
\begin{minipage}[t]{.6\linewidth}
  The construction of the mediator of $[AB]$ is realized with the
  command below.
  \begin{code}
\draw (A) -- (B);
\draw ($(M)!2!90:(B)$) -- ($(M)!2!-90:(B)$);
  \end{code}
\end{minipage}

\bigskip

In Fig.\,\ref{fig:spiral}, the spiral is defined using the code
below.  Note that \verbc|tmp| is computed at each step of the loop
using the \verbc|evaluate| key and that the radius, \verbc|\r{\i}| was
computed initially using again the \verbc|evaluate| key.

\begin{code}
  \begin{tikzpicture}[evaluate={%
      int \i;
      for \i in {0, ..., 10}{\r{\i} = .1*(\i+1);};
    }]
    \foreach \i [evaluate=\i as \tmp using \i*10] in {0,...,10}{%
      \filldraw[white, fill=M!\tmp!C]
      ($(0, 0)!\i/12!\i*18:(5, -1)$) circle (\r{\i});
    }
  \end{tikzpicture}
\end{code}

\begin{figure}[htb!]
  \centering
  \begin{tikzpicture}[scale=.9,
    evaluate={%
      int \i;
      for \i in {0, ..., 10}{\r{\i} = .1*(\i+1);};
    }]
    \foreach \i [evaluate=\i as \tmp using \i*10] in {0, ..., 10}{%
      \filldraw[white, fill=M!\tmp!C]
      ($(0, 0)!\i/12!\i*18:(5, -1)$) circle (\r{\i});
    }
    \filldraw[G] (0, 0) circle (2pt);
    \filldraw[R] (5, -1) circle (2pt);
  \end{tikzpicture}
  \caption{Using direct similarities; the green point is the origin of
    the similarity and the red one is the helping point in the partway
    modifier.}
  \label{fig:spiral}
\end{figure}




\subsection{Points as images of orthogonal projections}

\verbc|($(p1)!(p)!(p2)$)| returns the projection of \textttc{(p)} on
the line \verbc|(p1) -- (p2)|.  It is a projection modifier.  There
exists a more general form, but I can not see a reasonable situation
to use it: \verbc|($(p1)!(p)!angle:(p2)$)| returns the rotation with
center \textttc{(p1)} of the given angle of the projected point.

As a first application, we consider in Fig.\,\ref{fig:heights} the
heights of a triangle.  To obtain the common point of the three
heights, we need to handle intersections.  We'll do it in the next
subsection.


\begin{figure}[htb!]
  \centering
  \begin{tikzpicture}
    \path (0, 0) coordinate (A) node[below left] {$A$};
    \path (7, -1) coordinate (B) node[below right] {$B$};
    \path (2.5, 4) coordinate (C) node[above=3pt] {$C$};
    \draw[thick] (A) -- (B) -- (C) -- cycle;
    \draw[B, thin]
    (A) -- ($(B)!(A)!(C)$) coordinate (A')
    (B) -- ($(A)!(B)!(C)$) coordinate (B')
    (C) -- ($(A)!(C)!(B)$) coordinate (C');

    \foreach \P in {A, B, C, A', B', C'}{%
      \draw[fill=white] (\P) circle (2pt);
    }
  \end{tikzpicture}  
  \caption{The heights of a triangle are meeting in a point.}
  \label{fig:heights}
\end{figure}


The triangle and the heights have been stroked with the code below.
Note the use of \verbc|-- cycle| for the triangle and of the
\emph{jump to} for the heights.
\begin{code}
  \draw[thick] (A) -- (B) -- (C) -- cycle;
  \draw[B, thin]
  (A) -- ($(B)!(A)!(C)$) coordinate (A')
  (B) -- ($(A)!(B)!(C)$) coordinate (B')
  (C) -- ($(A)!(C)!(B)$) coordinate (C');
\end{code}


As a second application, in Fig.\,\ref{fig:simson}, we
construct the Simson line associated to a point $P$ on the circumcircle
of the triangle $[ABC]$---it passes through the projections of $P$ on
the triangle's edges.


\begin{figure}[htb!]
  \centering
  \begin{tikzpicture}
    \path (-15: 2) coordinate (A) node[right=3pt] {$A$};
    \path (55: 2) coordinate (B) node[above right] {$B$};
    \path (180: 2) coordinate (C) node[left=3pt] {$C$};
    \path (282: 2) coordinate (P) node[below right] {$P$};
   
    \draw[thin] (0, 0) circle (2);
    \draw[thick] (A) -- (B) -- (C) -- cycle;
    \draw[B, very thin]
    (P) -- ($(B)!(P)!(C)$) coordinate (A') node[above=3pt] {$A'$}
    (P) -- ($(A)!(P)!(C)$) coordinate (B') node[above right] {$B'$}
    (P) -- ($(A)!(P)!(B)$) coordinate (C') node[above right] {$C'$};
    \draw[very thin, dashed] ($(A)!-.8!(B)$) -- (B);
    \draw[R, very thick] ($(A')!-.5!(C')$) -- ($(A')!1.3!(C')$);

    \foreach \P in {A, B, C, A', B', C', P}{%
      \draw[fill=white] (\P) circle (2pt);
    }
  \end{tikzpicture}  
  \caption{The Simson line associated to the point $P$ on the
    $[ABC]$'s circumcircle.  The points $A'$, $B'$, and $C'$ are
    obtained through projection modifiers.}
  \label{fig:simson}
\end{figure}




\subsection{Points through intersections}

The path action \verbc|name intersections|---with a \emph{key=value}
syntax and two arguments---returns, as names, the intersection points
of two curves, its arguments.  The intersecting curves must have been
enriched with the attribute \verbc|name path|.  I start by presenting
three ways of using the \verbc|name intersections| action.  For all
three of them, an intersection point must be a ``real'' intersection
of the two pieces of curve considered.  There is a fourth way that
will be seen in \S\,\ref{ss:let}---it can be used inside the path
action \verbc|let ... in|.\label{page:intersection4}


\begin{enumerate}[label={Form \arabic*)}]
\item
  \verbc|name intersections={of=<curve1> and <curve2>, name=<prefix>}|\\
  It defines the names' prefix of the intersection points of the two
  curves.  The code for the left drawing in
  Fig.\,\ref{fig:intersections} is
  \begin{code}
    \path [name intersections={of=circle and line, name=iP}];
    \foreach \j/\pos in {1/below, 2/below right}{%
      \filldraw[red] (iP-\j) circle (2pt) node[\pos, black] {$I_{\j}$};
    }
  \end{code}
  The prefix is \verbc|iP| and the two points are \verbc|(iP-1)|
  and \verbc|(iP-2)|.
\item
  \verbc|name intersections={of=<curve1> and <curve2>, by=<points>}|\\
  It defines the individual names of the intersection points through
  the use of \verbc|by=|.  The code for the middle drawing in
  Fig.\,\ref{fig:intersections} is
  \begin{code}
    \path[name intersections={of=circle and line, by={A, B}}];
    \foreach \P/\pos in {B/below left, A/above right}{%
      \filldraw[blue] (\P) circle (2pt) node[\pos] {$\P$};
    }
  \end{code}
\item
  \verbc|name intersections={of=<curve1> and <curve2>, name=<prefix>,|
    \verbc|total=\t}|\\
  It defines the names' prefix of the intersection points and their
  cardinal through the \emph{macro} \verbc|\t|.  The code for the
  right drawing in Fig.\,\ref{fig:intersections} is
  \begin{code}
    \fill[name intersections={of=circle and ellipse, name=I, total=\t}]
    [DarkB] \foreach \j in {1, ..., \t}{%
      (I-\j) circle (2pt) node[above right] {$I_\j$}
    };
  \end{code}
\end{enumerate}

\begin{figure}[htb!]
  \centering
  \begin{tikzpicture}[scale=.9]
    \draw [name path=circle] (0, 1) circle (2);
    \draw [name path=line] (-2, -1) -- +(5, 2);
    \path [name intersections={of=circle and line, name=iPoint}];
    \foreach \j/\pos in {1/below, 2/below right}{%
      \filldraw[R] (iPoint-\j) circle (2pt) node[\pos, black] {$I_{\j}$};
    }
  \end{tikzpicture}
  \quad
  \begin{tikzpicture}[scale=.9]
    \draw[name path=circle] (0, 1) circle (2);
    \draw[name path=line] (-2, -.5) to[out=0, in=180] +(5, 3);
    \path[name intersections={of=circle and line, by={A, B}}];
    \foreach \P/\pos in {B/below left, A/above right}{%
      \filldraw[B] (\P) circle (2pt) node[\pos] {$\P$};
    }
  \end{tikzpicture}
  \quad
  \begin{tikzpicture}[scale=.9]
    \draw[name path=circle] (0, 1) circle (2);
    \draw[name path=ellipse, rotate=-20]
    (.5, .5) ellipse[x radius=3, y radius=1];
    \fill[name intersections={of=circle and ellipse, name=I, total=\t}]
    [DarkB] \foreach \j in {1, ..., \t}{%
      (I-\j) circle (2pt) node[above right] {$I_\j$}
    };
  \end{tikzpicture}
  \caption{Using the three ways of dealing with the intersection
    points of two curves; note that the order of the two intersection
    points in the first two forms varies with the intersecting
    curves.  In the middle drawing, the open curve is the same
    line-to used in the left drawing, but with controls.}
  \label{fig:intersections}
\end{figure}

\begin{noticeB}
  The macro \verbc|\t| in the right drawing from
  Fig.\,\ref{fig:intersections} is a \textbf{local}  macro.  It does
  not survive outside the path command.  To be able to use it outside
  the path command, insert

  \verbc|\pgfextra{\xdef\total{\t}}| (to pass the value outside 
  the current scope).
\end{noticeB}


\begin{figure}[htb!]
  \centering
    \begin{tikzpicture}[scale=.9]
    \draw[name path=circle] (0, 1) circle (2);
    \draw[fill=B, fill opacity=.2, name path=ellipse, rotate=-22]
    (.5, .5) ellipse[x radius=3.5, y radius=1];
    \fill[name intersections={of=circle and ellipse, name=I, total=\t}]
    [DarkB] \foreach \j in {1, ..., \t}{%
      (I-\j) circle (2pt) node[above right] {$I_\j$}
    };
  \end{tikzpicture}
  \tikzmath{int \total;}
  \begin{tikzpicture}[spear/.style={
      ->, Gray, very thin, shorten <=3pt, shorten >=3pt
    }, scale=.9]
    \draw[name path=circle] (0, 1) circle (2);
    \draw[fill=O, fill opacity=.2, name path=ellipse, rotate=10]
    (.5, .5) ellipse[x radius=3.5, y radius=1];
    \path[name intersections={of=circle and ellipse, name=I, total=\t}]
    \pgfextra{\xdef\total{\t}};
    %\tikzmath{\total = \t;};  # doesn't work
    \foreach \j in {1, ..., \total}{%
      \draw[fill=white] (I-\j) circle (2pt);
    }
    \path (I-\total) node[label={%
      [fill=WBuff,
      rounded corners,
      label distance=5ex,
      name=last point label]-70:last point
    }] (last point) {};
    \path (last point label) edge[bend right, spear, right] (last point);
  \end{tikzpicture}
  \caption{Around the total number of points in
    \textttc{intersection}; in the second drawing, the label is
    inserted outside the intersection command (see above).
  }
  \label{fig:total}
\end{figure}


\begin{rem*}
Concerning the order of the intersection points: if one of the
curves is a line, then the points are ordered along the line (see
Fig.\,\ref{fig:alongALine}). 
\begin{figure}[htb!]
  \centering
    \begin{tikzpicture}[scale=.9]
    \draw[rounded corners, name path=curve]
    (0,0) to[out=70, in=180] (1,1)
    to[out=0, in=180] (3,-1) -- ([turn]0:2)
    to[out=0, in=-90] (3, 1) -- ++(2, .3) -- ++(.2, -1.5);
    \draw[B, name path=line] (-1, .5) -- ++(8, -.3);
    
    \fill[name intersections={of=line and curve, name=I, total=\t}]
    [R] \foreach \j in {1, ..., \t}{%
      (I-\j) circle (2pt) node[above right] {$I_\j$}
    };
  \end{tikzpicture}
  \caption{Intersection along a line}
  \label{fig:alongALine}
\end{figure}
\end{rem*}




\section{Geometric transformations---path actions}


The geometric path actions are
\begin{itemize}[noitemsep]
\item
  \textttc{rotate=<angle in degree>}
\item
  \textttc{xshift=<length>}, \textttc{yshift=<length>}
\item
  \verbc|shift=<{vector}>| \quad (the curly brackets are needed!)
\item
  \textttc{xscale=<factor>}, \textttc{yscale=<factor>}
\item
  \textttc{scale=<factor>}
\end{itemize}

The actions' order of appearance counts as can be noticed in the
following drawings.  It is as if composing functions in
mathematics: $(f\circ g)(x) = f(g(x))$.  Explicitly, in  
\begin{code}
  \draw[rotate=45, shift={(2,.5)}] ...
\end{code}
the translation is executed firstly, than the rotation. 


\begin{center}
  \begin{tikzpicture}[scale=1, every node/.style={scale=0.9}]   
    \draw[->] (-1,0) -- (3.5,0) node[below right] {$x$};
    \draw[->] (0,-1) -- (0,2.5) node[above left] {$y$};
    
    \draw[B, very thick]
    (-1,0) -- ++(1,0) -- ++(.5,1) to[bend left] ++(.5,-1) -- ++(1,0);
    \draw[R, very thick, rotate=45] 
    (-1,0) -- ++(1,0) -- ++(.5,1) to[bend left] ++(.5,-1) -- ++(1,0);

    \path (2.25, -1.15) node[R] {\texttt{rotate=45}};
  \end{tikzpicture}
  \hspace{4em}
  \begin{tikzpicture}[scale=1, every node/.style={scale=0.9}]   
    \draw[->] (-1,0) -- (3.5,0) node[below right] {$x$};
    \draw[->] (0,-1) -- (0,2.5) node[above left] {$y$};

    \draw[B, very thick]
    (-1,0) -- ++(1,0) -- ++(.5,1) to[bend left] ++(.5,-1) -- ++(1,0);
    
    \draw[B, very thick, opacity=.3, rotate=45] 
    (-1,0) -- ++(1,0) -- ++(.5,1) to[bend left] ++(.5,-1) -- ++(1,0);
    
    \draw[Gray, dashed] (0,0) -- (2,.5);
    \draw[R, very thick, shift={(2,.5)}, rotate=45] 
    (-1,0) -- ++(1,0) -- ++(.5,1) to[bend left] ++(.5,-1) -- ++(1,0);

    \path (2.25, -1.15) node[R] {\texttt{shift={(2,.5)}, rotate=45}};
  \end{tikzpicture}
\end{center}

\begin{center}
  \begin{tikzpicture}[scale=1, every node/.style={scale=0.8}]   
    \draw[->] (-1,0) -- (3.5,0) node[below right] {$x$};
    \draw[->] (0,-1) -- (0,2.5) node[above left] {$y$};
    
    \draw[B, very thick] 
    (-1,0) -- ++(1,0) -- ++(.5,1) to[bend left] ++(.5,-1) -- ++(1,0);
    
    \draw[R, very thick, shift={(2,.5)}] 
    (-1,0) -- ++(1,0) -- ++(.5,1) to[bend left] ++(.5,-1) -- ++(1,0);
    
    \draw[Gray, thin, dashed] (0, 0) -- (2, .5);    
    \path (2.25, -1.15) node[R] {\texttt{shift={(2,.5)}}};
  \end{tikzpicture}
  \hspace{4em}\label{pp:noncommuting}
  \begin{tikzpicture}[scale=1, every node/.style={scale=0.8}]   
    \draw[->] (-1,0) -- (3.5,0) node[below right] {$x$};
    \draw[->] (0,-1) -- (0,2.5) node[above left] {$y$};
    
    \draw[B, very thick]
    (-1,0) -- ++(1,0) -- ++(.5,1) to[bend left] ++(.5,-1) -- ++(1,0);
    
    \draw[Gray, dashed, thin] (0,0) -- (2,.5);
    \draw[B, very thick, opacity=.3, shift={(2,.5)}]
    (-1,0) -- ++(1,0) -- ++(.5,1) to[bend left] ++(.5,-1) -- ++(1,0);
    
    \draw[R, very thick, rotate=45, shift={(2,.5)}]
    (-1,0) -- ++(1,0) -- ++(.5,1) to[bend left] ++(.5,-1) -- ++(1,0);
    \path (2.25, -1.15) node[R] {\texttt{rotate=45, shift={(2,.5)}}};
  \end{tikzpicture}
\end{center}

\begin{noticeB}
  The global options are applied at the end, see
  Fig.\,\ref{fig:vertical2}.  It is as if they appear first in the
  local options.
\end{noticeB}


The same non commuting behavior may be observed with scale and shift.
They do not commute, the last one given being the first one executed;
see Fig.\,\ref{fig:notCommuting}.

\begin{figure}[htb!]
  \centering
  \begin{tikzpicture}
    \draw[LightGray, very thin] (-2.5, -1.15) grid (2.5, 3.5);
    \draw[->, thin] (-2.7, 0) -- (3, 0) node[below] {$x$}; \draw[->, thin]
    (0, -1.25) -- (0, 3.5) node[left] {$y$};
    
    \filldraw[V, opacity=.5] (0, 0) rectangle (2, 1);
    \filldraw[B, opacity=.5, shift={(.5, .5)}, scale=2]
    (0, 0) rectangle (2, 1);
    \filldraw[Y, opacity=.75, scale=2, shift={(.5, .5)}]
    (0, 0) rectangle (2, 1);
  \end{tikzpicture}
  \caption{The operations \textttc{scale} and \textttc{shift} do not
    commute.  The blue rectangle is obtained from the violet one
    through a scaling of factor $2$ followed by shifting with the
    vector $(0.5, 0.5)$.  The order is changed for the yellow one.
    Note that in this case, the scaling acts on the translation
    vector, since everything in the drawing instruction is expanded by
    $2$.}
  \label{fig:notCommuting}
\end{figure}






\section{Arrows---path attribute}

In order to add arrow tips to the lines which are drawn, the following
conditions must be met:
\begin{enumerate}[nolistsep]
\item 
  the \textttc{arrow}(s) key or its short form must be specified
\item
  the curve doesn't realize a clip action  
\item
  the curve is not closed.
\end{enumerate}


\begin{rem*}
  It is better to use the library \verbc|arrows.meta|. 
\end{rem*}


\verbc|arrows=<start arrow specification>-<end arrow specification>| \\
For example, as in
\verbc|\draw[->] (0, 0) -- (2, 0);| or 
\verbc#\draw[|-Stealth] (0, 0) -- (2, 0);#
that yield
\begin{center}
  \begin{tikzpicture}
    \draw[thick, ->] (0, 0) -- ++(2, 0);
    \draw[thick, |-Stealth] (3, 0) -- ++(2, 0);
    \draw[B, thick, |-Latex] (6, 0) -- ++(2, 0);
  \end{tikzpicture}
\end{center}
The blue arrow is obtained with \verbc#arrow=|-Latex#.  Note that the
tips properties can be defined independently of the curve's
properties:
\begin{center}
  \begin{tikzpicture}[scale=1.5]
    \draw[B, very thick, -{Latex}] (0, 0) -- ++(1, 0);
    \draw[B, very thick, -{Latex[C, length=5mm]}]
    (3, 0) -- ++(1, 0)
    node[pos=.5, below=3ex, text=BK] {Latex[C, length=5mm]};
    \draw[C, very thick, -{Latex[M, length=14pt, open]}]
    (7, 0) -- ++(1, 0)
    node[pos=.5, below=3ex, text=BK] {Latex[M, length=14pt, open]};
  \end{tikzpicture}
\end{center}

\verbc|slant=<factor>|\\
Slanting is used to create an italic effect for arrow tips; all arrow
tips get ``slanted'' a little bit relative to the axis of the arrow.
\begin{center}
    \begin{tikzpicture}[scale=1.5]
    \draw[B, very thick, arrows={->[slant=.3]}]
    (0, 0) -- ++(1, 0)
    node[pos=.5, below=3ex, text=BK] {\verb|arrows={->[slant=.3]}|};
    \draw[B, very thick, arrows={-Latex[B, length=5mm, open, slant=.3]}]
    (4, 0) -- ++(1, 0)
    node[pos=.5, below=3ex, text=BK]
    {\verb|arrows={-Latex[open, ..., slant=.3]}|};
  \end{tikzpicture}
\end{center}


\begin{noticeB}
  Like for \textttc{color=} attribute, since the arrow option is so
  often used, the \textttc{arrows=} syntax is optional.  But
  \textbf{it is no longer optional} if \textttc{slant} is one of the
  arrow's attributes.

  Now, \textbf{the use of the curly braces} is different depending on
  whether \textttc{arrows=} is explicit.
\end{noticeB}


\begin{rem*}
  The library \textttc{arrows.meta} is needed; the library
  \textttc{arrows} is deprecated.
\end{rem*}





\section{Nodes---path operation}
\label{s:nodes}

A node is typically a rectangle or circle or another simple shape with
some text on it.  Nodes are added to paths using the special path
operation \textttc{node}.  \emph{Nodes are not part of the path itself.}
Rather, they are added to the picture just before (with the attribute
\verbc|behind path|) or after the path has been drawn.


\begin{noticeB}
  Coordinate transformations do not apply to a node. Its anchor
  remains the same.  To achieve a translation for example, the shift
  command must be placed inside the node's name parentheses.  
\end{noticeB}


\subsection{Defining nodes}

The path operation
\verbc|...node[<options>] (nName) at (a,b) {content}...;|
creates a \textbf{node} for the current path, \ie writes down the
\emph{content} at the point $(a,b)$ with some \emph{node options} and
name \emph{nName}.  The node options or attributes have no effect
outside the node; they control its
\begin{itemize}[nolistsep, label={--}]
\item
  position with respect to the elements of the path
\item
  anchor
\item
 
  appearance
\item
  label.
\end{itemize}


\begin{noticeB}
  The end of the node path action is detected by the opening curly
  brace of the content.\\
  The name and the coordinates are optional.
\end{noticeB}


\begin{noticeB}
When a node is typeset, all the text given in the braces is put in one
long line---in an \verbc|\hbox|---and the node will become as wide as
necessary (p. 224).  The use of \verbc|\\| \textbf{must be
accompanied} by the option \verbc|align| which acts on the node's
content. 
\end{noticeB}

\noindent
\begin{tikzpicture}
  \draw[G, fill=G!40!Y, rounded corners=1pt]
  (0, 0) rectangle (\textwidth, 1.5)
  ++(-.5, -.7) node[G!50!Y, draw, fill=WBuff, rounded corners=1pt, very thin,
  anchor=north east, align=right, text=K]
  {\sffamily\bfseries
    this is a node with a line break inside its content \\
    and \verbc|align=right| as one of its options};
\end{tikzpicture}
The \textc{align} option must appear, otherwise the double backslash
has no effect.  But the same effect (almost) might be achieved through
the node's option \textc{text width=width}---a better choice since the
text properties, in the former solution, do not descend after the line
break; see the second solution in the drawing below.

\smallskip\noindent
\tikzmath{
  real \w;
  \w = .9;
}
\begin{tikzpicture}
  \draw[G, fill=G!40!Y, rounded corners=1pt]
  (0, 0) rectangle (\textwidth, 1.5) ++(-.5, -.7)
  node[G!50!Y, draw, fill=WBuff, rounded corners=1pt, very thin,
  anchor=north east, text=K,
  minimum width=\w\textwidth, text width=\w\textwidth,
  align=right, scale=.9]
  {\sffamily\bfseries this is a node without a line break inside its
    content and \textc{align=right} as one of its options ; note the
    balanced lengths for the two lines};
\end{tikzpicture}


\medskip
\paragraph{Absolute position of a node}
The path action introducing a node can appear either inside a path
operation or after a coordinate.  In the former case, the node
position is defined by the attribute \verbc|pos=t|, where $t\in[0,1]$.
In the latter case, the node is placed at the last position mentioned 
before the \verbc|node| path action.  Now, if \verbc|at (a,b)| is
added to the node specification, then the node is placed at $(a,b)$
instead. 

\begin{figure}[htb!]
  \centering
  \begin{tikzpicture}
    \path (0, 0) coordinate (A) node[below left] {$A$};
    \path (3, 2) coordinate (B) node[below right] {$B$};
    \draw (A) to[out=-30, in=180]
    node[draw, DarkR, pos=.5, above left] {content}
    node[draw, B, pos=.5] {content} (B);
    \draw[fill=white] (A) circle (2pt) (B) circle (2pt);
  \end{tikzpicture}
  \quad
  \begin{tikzpicture}
    \path (0, 0) coordinate (A) node[below left] {$A$};
    \path (3, 2) coordinate (B) node[below right] {$B$};
    \draw (A) to[out=-30, in=180] (B)
    node[draw, DarkR, above right] {content};
    \draw[fill=white] (A) circle (2pt) (B) circle (2pt);
  \end{tikzpicture}
  \caption{Nodes appearing either inside a path action (the left
    drawing) or after a coordinate (the right drawing).  In the left
    drawing, the position of the blue and red nodes is initially the
    same; the red one is eventually modified by the attribute
    \textttc{above left}.  In the right drawing, the red node is placed
    at $B$ and is modified by the same attribute.}
  \label{fig:nodes}
\end{figure}

The code of the left drawing in Fig.\,\ref{fig:nodes}.
\begin{code}
  \path (0, 0) coordinate (A) node[below left] {$A$};
  \path (3, 2) coordinate (B) node[below right] {$B$};
  \draw (A) to[out=-30, in=180]
    node[draw, red, pos=.5, above left] {content}
    node[draw, blue, pos=.5] {content} (B);
  \draw[fill=white] (A) circle (2pt) (B) circle (2pt);
\end{code}


\begin{rem*}
  The left drawing in Fig.\,\ref{fig:nodes} can be stroked in a
  single \verb|\path| command.  I present one possibility here for three
  reasons: it illustrates the general philosophy of \tikZ, it
  opens the discussion about the attributes and the labels of
  nodes, and finally, dealing with labels, it leads to the relative
  position of nodes.
  \begin{center}
    \begin{tikzpicture}[every label/.style={inner sep=1pt},
      point2d/.style={circle, draw, fill=white, inner sep=2pt}]
      \draw (0, 0) node[point2d, label={240:$A$}] (A) {}
      to[out=-30, in=180] node[draw, red, pos=.55, above left] {content}
      (3, 2) node[point2d, label={-60:$B$}] (B) {};
    \end{tikzpicture} 
  \end{center}
\begin{code}
  \begin{tikzpicture}[every label/.style={inner sep=1pt},
    point2d/.style={circle, draw, fill=white, inner sep=2pt}]
    \draw
      (0,0) node[point2d, label={240:$A$}] (A) {}
      to[out=-30, in=180] node[draw, red, pos=.55, above left] {content}
      (3,2) node[point2d, label={-60:$B$}] (B) {};
  \end{tikzpicture}
\end{code}
Note that the two white circles indicating the extremities of the
curve are nodes now---the \emph{shape} is circle having the radius
controlled by the attribute \verbc|inner sep|---with no content.
Their names are $A$ and $B$ as before, but this time, these names
refer to nodes and not to coordinates.  The $A$ and $B$ written down
in Fig.\,\ref{fig:nodes} are the \emph{labels} of the nodes.  The
labels are nodes also, hence the discussion about the relative
positioning of nodes below, in \S\,\ref{ss:relativePositioning}.
\end{rem*}


\paragraph{Anchor of a node}
We have already met the anchor of a node: in the left drawing of
Fig.\,\ref{fig:nodes} the blue and red nodes have initially the same
position, the red one being slightly moved through the attribute
\verbc|above left|.  The same characteristic can be obtained through
the equivalent attribute \verbc|anchor=south east|.


\begin{noticeB}
  \centering
  \verbc|above left| $\quad\Longleftrightarrow\quad$
  \verbc|anchor=south east|
  \flushleft
  These equivalent attributes correspond to different points of view
  on how the node is placed in the drawing: the coordinate system's
  for the former and the node's for the latter.
\end{noticeB}


The node occupies in the drawing a certain space corresponding to its
shape.  The attribute \verbc|draw| makes this shape visible.  The
shape has nine anchoring points; the anchor places one of them at
$(a,b)$.  See Fig.\,\ref{fig:anchors}.  I am referring to the path 
command\\ 
\indent\verbc|...(a,b) node[<options>] (nName) {content}...;|\\
By default, the anchor is set at the center of the shape.

\begin{figure}[htb!]
  \centering
  \begin{tikzpicture}[scale=1.2]
    \path (0, 0) coordinate (C);
    \path (0, -1) coordinate (S);
    \path (2, -1) coordinate (SE);
    \path (2, 0) coordinate (E);
    \path (2, 1) coordinate (NE);
    \path (0, 1) coordinate (N);
    \path (-2, 1) coordinate (NW);
    \path (-2, 0) coordinate (W);
    \path (-2, -1) coordinate (SW);
    \draw[fill=B!30] (SW) rectangle (NE)
    node[below right, R] {$(a,b)$};
    \path (2.8, .96) node[text width=4cm, below right]
    {the anchor for the blue node is \textttc{below left} with respect
      to $(a,b)$};

    \foreach \P/\pos in {%
      C/below left, S/below, SE/below right, E/right,
      NE/above right, N/above, NW/above left, W/left, SW/below left%
    }{\draw[fill=white] (\P) circle (2pt) node[circle, \pos] {$\P$};}
  \end{tikzpicture}
  \caption{The nine anchoring points of a node; if the point
    $NE=(a,b)$ is the node's position, then the anchor used is
    \textttc{below left} with respect to (from the point of view of)
    the coordinate $(a,b)$.}
  \label{fig:anchors}
\end{figure}


\paragraph{Appearance of a node}
There are many attributes that control the appearance of a node.  Some
of them are listed below.
\begin{itemize}[noitemsep]\color{DarkB}
\item
  draw, fill, fill color=$...$, opacity=$...$, fill opacity=$...$
\item
  shape=$...$, inner sep=$...$, outer sep=$...$
\item
  text color=$...$, text width=$...$, align=right/center/left
\item
  rotate=angle, anchor=$...$
\end{itemize}



\paragraph{Label of a node}
When the option \textttc{label} is given to a node operation, it causes
another node to be added to the path after the current node has been
finished.  This extra node will have the text defined by
\textttc{lText}
and is placed, in the direction \textttc{lAngle} relative to the main
node (on the border of it): \\
\indent \verbc|label=<lAngle>:<lText>|.

\smallskip\noindent
The distance between a node and its label is controlled through the
\verbc|[key=value]| syntax corresponding to the key \quad
\verbc|label={[label distance=...] angle:text}| \quad (see the ``white''
label and the violet one in Fig.\,\ref{fig:labels}).

\begin{figure}[htb!]
  \centering
  \begin{tikzpicture}[%
    every node/.style={text=white, draw, fill=B, rounded corners,
      inner sep=2ex},
    every label/.style={white, fill=Gold, rounded corners=0pt,
      inner sep=2.5ex, scale=.9, text=BK}]
    \draw[Gray, thin] (-9.5, -1.5) grid (4.5, 2.5);
    \node[label={[fill=Grape!40,
      label distance=3em, name={LM}] 60:something }]
    (Main) {Main node};
    \node[label={120:at $120^\circ$ for II},
    label={[fill=WBuff, text width=7em, align=center,
      label distance=5ex] 190:at $190^\circ$ for II}]
    (Second) [left=of Main] {Second node};

    \filldraw[R] (Main.60) circle (2pt) -- ++(60: 3em) circle (2pt);
    \draw[<->, very thick] (Main) -- (LM);

    \draw[C, fill=C] (2, 0) circle (3pt) coordinate[label={-70:a point}];
    
  \end{tikzpicture}  
  \caption{Labels and their position; in red are shown and connected
    the reference point on 
    the border of the main node and the anchoring position chosen on
    the border of the label--- \textttc{[label distance=3em] 
      60:something} was used.  The anchoring point is determined in
    such a way that the label node will “face away” from the border of
    the main node.  In black, the usual line-to is used, which points
    toward the center of both nodes (main node and its label).
  } 
  \label{fig:labels}
\end{figure}


\verbc|every label/.style|
defines the style used in every node created by the label option.  The
default values are \textttc{draw=none}, \textttc{fill=none}. 


\begin{rem*}
It would be natural to use the nodes' label when drawing points in
geometry.  The point would be represented in this case by the main
node.  The philosophy would be different though, since the points
would not be coordinates anymore, but nodes.

But coordinates support labels too!  See the cyan point in
Fig.\,\ref{fig:labels} with the label ``a point''. 
\end{rem*}




\subsection{Relative positioning of nodes}
\label{ss:relativePositioning}

With the library \verbc|\usetikzlibrary{positioning}|, relative
positioning can be used in placing the nodes.  For example, a part of
the code for the Fig.\,\ref{fig:labels} is
\begin{code}
  \node[label={[label distance=3em] 60:something}] (Main) {Main node};
  \node[label={120:something else},
  label={[fill=WBuff, text width=7em, align=center,
    label distance=5ex] 188:second label of Second node}]
  (Second) [left=of Main] {Second node};
\end{code}
Note the option \textttc{left=of Main} which controls the position of
the node \textttc{Second} with respect to the node \textttc{Main}.


\begin{figure}[htb!]
  \centering
  \begin{tikzpicture}[every node/.style={draw, rectangle,
      rounded corners, minimum height=1cm, inner sep=1ex},
    node distance=.3cm and .3cm]
    \node[minimum width=2cm, fill=Amber] (center) {center};
    \node[below=of center] (below) {below};
    \node[below right=of center] (belowright) {below right};
    \node[right=of center] (right) {right};
    \node[above right=of center] (aboveright) {above right};
    \node[above=of center] (above) {above};
    \node[above left=of center] (aboveleft) {above left};
    \node[left=of center] (left) {left};
    \node[below left=of center] (belowleft) {below left};
  \end{tikzpicture}
  \caption{Relative positioning; note how the relative positioning
    induces the anchoring of the exterior nodes with respect to the
    node \textttc{(center)}.} 
  \label{fig:relativePositioning}
\end{figure}



In what follows, the relative position is inspected from the point of
view of the vertical alignment---the height of each node equals $1 cm$.
\begin{itemize}[nolistsep]
\item 
  In Fig.\,\ref{fig:vertical1}, on the left, the position is defined
  using \textttc{below=of nodename}.  The vertical and horizontal 
  distances are the default ones between the borders of the nodes,
  $1\,cm$.  On the right, the position is defined
  using \textttc{below=of nodename1.west}.  The vertical and
  horizontal distances are the default ones between the border (here
  \textttc{nodename2.north}) and the \textttc{nodename1.west} of the
  previous node.
\item
  In Fig.\,\ref{fig:vertical2}, the positioning of the nodes is
  controlled through two instructions: the anchoring
  \textttc{anchor=west} and the vertical alignment, as in
  Fig.\,\ref{fig:vertical1}.  The result depends on the order of these
  instructions.  On the left, the vertical alignment appears first,
  and the anchoring second; on the right, it is the opposite.  Note
  that the result of the drawings on the right in both figures are the
  same, except for a translation to the right of the second.
\end{itemize}


\begin{figure}[htb!]
  \centering
  \begin{tikzpicture}[every node/.style={minimum height=1cm,
      BK, draw, rounded corners, inner sep=1.5ex}]
    \draw[Gray, very thin, help lines] (-2, 1) grid (2, -4.5);
    \node[fill=B, text=white] (base) at (0,0) {Base node}; 
    \node[fill=B!60, below=of base] (second) {Second node};
    \node[fill=B!30, below=of second] (third)
    {Node with long text};
    \filldraw[R] (0, 0) circle (2pt);
  \end{tikzpicture}
  \hspace{4em}
  \begin{tikzpicture}[every node/.style={minimum height=1cm,
      BK, draw, rounded corners, inner sep=1.5ex},
    node distance = 1cm and 7ex]
    \draw[Gray, very thin, help lines] (-2, 1) grid (2, -4.5);
    \node[fill=B, text=white] (base) at (0,0) {Base node}; 
    \node[fill=B!60, below=of base.west] (second) {Second node};
    \node[fill=B!30, below=of second.west] (third)
    {Node with long text};
    \filldraw[R] (0, 0) circle (2pt);
    \draw[Gold, ->, line width=2pt] (base.west) -- (second.north);
    \draw[Gold, ->, line width=2pt] (second.west) -- (third.north);
  \end{tikzpicture}  
  \caption{Vertical alignment using the library
    \textttc{positioning}.  The distance between the nodes depends on
    the reference point given, if explicit.  On the right, the
    reference point is set through \textttc{below=of nodename.west}.}
  \label{fig:vertical1}
\end{figure}

\begin{figure}[hbt!]
  \centering
  \begin{tikzpicture}[scale=1, every node/.style={minimum height=1cm,
      BK, draw, rounded corners, inner sep=1.5ex},]
    %node distance = 1cm and 7ex]
    \draw[Gray, very thin, help lines] (-2, 1) grid (2, -4);
    \node[fill=B, text=white, anchor=west] (base) at (0,0) {Base node}; 
    \node[fill=B!60, below=of base.west, anchor=west] (second) {Second node};
    \node[fill=B!30, below=of second.west, anchor=west] (third)
    {Node with long text};
    \filldraw[R] (0, 0) circle (2pt);
  \end{tikzpicture}
  \hspace{4em}
  \begin{tikzpicture}[scale=1,
    every node/.style={minimum height=1cm, BK, draw,
      rounded corners, inner sep=1.5ex}, node distance = 1cm and 7ex]
    \draw[Gray, very thin, help lines] (-2, 1) grid (2, -4);
    \node[fill=B, text=white, anchor=west] (base) at (0,0) {Base node}; 
    \node[fill=B!60, anchor=west, below=of base.west] (second) {Second node};
    \node[fill=B!30, anchor=west, below=of second.west] (third)
    {Node with long text};
    \filldraw[R] (0, 0) circle (2pt);
  \end{tikzpicture}
  \caption{Vertical alignment; the red dot is the origin.  On the left
    \textttc{below=of base.west} appears first and then
    \textttc{anchor=west}; on the the roles are exchanged.}
  \label{fig:vertical2}
\end{figure}

\noindent
\begin{minipage}[t]{.55\linewidth}
  In the next drawing \textttc{anchor=west} is given globally.  The
  result is identical with the right image in
  Fig.\,\ref{fig:vertical2}, so \emph{a global definition is equivalent to
    first position in a local definition} (see page
  \pageref{pp:noncommuting} also).

  Note that there are three actions in the placement of the second and
  third node.  Explicitly for \textttc{second}:
  \begin{enumerate}[nolistsep]
  \item
    \textttc{below=of base.west} $\leadsto$ vertical alignment using
    \textttc{second.north}
  \item
    the distance between \textttc{base.west} and
    \textttc{second.north} equals $1\,cm$
  \item
    anchoring point is set to \textttc{second.west}---used for the
    next positioning.
  \end{enumerate}
\end{minipage}
\begin{minipage}[t]{.4\linewidth}
  \centering
  \begin{tikzpicture}[scale=1, every node/.style={minimum height=1cm,
      BK, draw, rounded corners, inner sep=1.5ex, anchor=west},
    node distance = 1cm and 7ex, baseline={1.25cm}]
    \draw[Gray, very thin, help lines] (-2, 1) grid (2, -4);
    \node[fill=B, text=white] (base) at (0,0) {Base node}; 
    \node[fill=B!60, below=of base.west] (second) {Second node};
    \node[fill=B!30, below=of second.west] (third)
    {Node with long text};
    \filldraw[R] (0, 0) circle (2pt);
  \end{tikzpicture}
\end{minipage}

\begin{noticeB}
  Setting the anchor of the current node yields the reference point
  for its positioning (vertical and/or horizontal).
  The first instruction given is the last executed (see also
  Fig.\,\ref{fig:notCommuting}).
\end{noticeB}




\subsection{Connecting the nodes; the \textttc{edge} operation}

The \textttc{edge} operation has similar effect as the \textttc{node}
operation in that it adds something after the main path has been
drawn.  However, it works like the line-to operation, that is, it
adds a to-path to the picture after the main path has been drawn.

\begin{figure}[htb!]
  \centering
  \begin{tikzpicture}[%
    every node/.style={
      draw, rounded corners, text=black, text opacity=1,
      inner sep=2ex, fill opacity=.7
    },
    spear/.style={->, BK, thin, shorten <=3pt, shorten >=3pt}
    ]
    \node[fill=Y] at (0, 0) (Main) {Main node};
    \node[fill=Y!50!G] (Second) [right= 2cm of Main] {Second node};
    \node[fill=C, text=DarkR] (Third) [right= 2cm of Second] {Third node};

    \path
    (Main) edge[spear, right] (Second) (Second) edge[spear] (Third)
    (Main) edge[spear, right, out=-40, in=-140]
    node[white, fill=white, text=black, pos=.5, above=-2ex, scale=.9]
    {bending out and in options}
    (Third);
    \draw[R, very thick, ->] (Main) to[out=40, in=140] (Second.center);
  \end{tikzpicture}  
  \caption{Connecting curves or arrows between nodes.  The red arrow
    is a \textttc{to} operation; the others are \textttc{edge}
    operations.}
  \label{fig:edges}
\end{figure}

As the \textttc{node} operation, an \textttc{edge} temporarily
suspends the construction of the current path and a new path is
constructed. (This new path will be drawn after the main path has been
drawn.)


\begin{noticeB}
  The \textttc{edge} operation doesn't move the pencil!  If there are
several edge operations in a row, the start coordinate \textbf{is the
same for all of them}; their target coordinates are not, after all,
part of the main path. The start coordinate is the coordinate
preceding the first edge operation---similar to nodes insofar as the
edge operation does not modify the current path.
\end{noticeB}

\noindent
The code
\verbc|spear/.style={->, BK, thin, shorten <=3pt, shorten >=3pt}|
defines \textttc{spear}, the common style of the connecting arrows in
Fig.\,\ref{fig:edges}.  See also the \emph{TikZ-PGF} manual, \S\,16.3,
\emph{Arrow Keys: Configuring the Appearance of a Single Arrow Tip}.


\begin{rem*}
The \textttc{edge} operation creates a curve from the previous element
of the path, to the following one.  The \verb|\tikztostart| is the last
coordinate on the path just before the \textttc{edge} operation, just
as for the \textttc{node} or \textttc{path-to} operations.  However,
there is one exception to this rule: \textit{If the edge operation is
directly preceded by a node operation, then this just-declared node is
the start coordinate (and not, as would normally be the case, the
coordinate where this just-declared node is placed---a small, but
subtle difference).}  Below, on the first row \textttc{to} is used; on
the second \textttc{edge}.

\tikz{
  \path[use as bounding box] (-1,-.25) rectangle (5, .25);
  \draw[R, ->] (0, 0) to (4,0); 
}\quad
\tikz{
  \path[use as bounding box] (-1,-.25) rectangle (5, .25);
  \draw[R, ->] (0, 0) node {first} to (4,0); 
}


\tikz{
  \path[use as bounding box] (-1,-.25) rectangle (5, .25);
  \draw (0, 0) edge[->] (4,0); 
}\quad
\tikz{
  \path[use as bounding box] (-1,-.25) rectangle (5, .25);
  \draw (0, 0) node {first} edge[->] (4,0); 
}

\begin{code}
  \draw[R, ->] (0, 0) node {first} to (4,0);
  \draw (0, 0) node {first} edge[->] (4,0); 
\end{code}

\begin{noticeB}
  Note that were the nodes previously defined, then \textttc{to} and
\textttc{edge} would result in identical graphical behaviors; see below.
\end{noticeB}


\begin{tikzpicture}
  \path[use as bounding box] (-1,-.25) rectangle (5, .5);
  \path
  (0, 0) node[draw, R] (first) {first}
  (4, 0) node[draw] (second) {second};
  \draw[R, ->] (first) -- node[pos=.5, above] {to} (second); 
\end{tikzpicture}
\quad
\begin{tikzpicture}
  \path[use as bounding box] (-1,-.25) rectangle (5, .5);
  \path
  (0, 0) node[draw] (first) {first}
  (4, 0) node[draw] (second) {second};
  \path[->] (first) edge  node[pos=.5, above] {edge} (second); 
\end{tikzpicture}

\begin{code}
  \path
  (0, 0) node[draw] (first) {first}
  (4, 0) node[draw] (second) {second};
  \path[->] (first) edge  node[pos=.5, above] {edge} (second); 
\end{code}
\end{rem*}





\section{Plot---path operation}
\label{s:plot}

The \textttc{plot} path operation constructs a curve that passes
through a large number of points given
\begin{itemize}[nolistsep]
\item
  either given in a list of coordinates
  \verbc|plot[atributes] coordinates {A, B, ...}|
\item
  read from a file
  \verbc|plot[..] file {|\emph{filename}\verbc|}|
\item
  or computed through a formula (yielding a parametric curve; see
  below).
\end{itemize}

Among the attributes, one can use
\verbc|const plot mark right, mark=*|,
see the blue graph in Fig.\,\ref{fig:graphs}, which connects the
points on the path using piecewise constant---horizontal and
vertical---segments.  The \verbc|mark right, mark=*| adds marks on the
right ends of the horizontal segments.



\subsection{Reading points from an external file}

\begin{noticeB}
  In the file format that \tikZ\ allows each line either starts with two
  numbers separated by a space, or is empty (really empty or starting
  with \# or \% symbols).
\end{noticeB}

\begin{itemize}[nolistsep]
\item
  An empty line starts a \emph{new data set} resulting in a new curve
  being plotted.
\item
  A line starting with two numbers provides a new coordinate; they may
  be followed by arbitrary text, which is ignored (it might be a good
  habit to use \%).
\end{itemize}



\subsection{Drawing graphs of functions and parametric curves}

The \textttc{plot} path operation can be used to draw graphs of
functions, \ie the coordinates are computed through a mathematical
formula.  This is the most ``basic'' way of drawing a graph or
parametric curve; it leaves us with the construction of the environment
(axes, ticks, \ldots).

The computations of the coordinates are influenced by the following
options: \textttc{variable=}, \textttc{domain=}, \textttc{samples=}.


\begin{figure}[htb!]
  \centering

  \begin{tikzpicture}[every node/.style={scale=.9, text=K}, domain=-1.2:4]
    \draw[LightGray, very thin] (-1.5, -2.5) grid (5.5, 3.5);
    \draw[->] (-2, 0) -- (6, 0) node[above right] {$x$};
    \draw[->] (0,-2.5) -- (0, 4) node[left] {$y$};
    \draw[R, thick] plot (\x, .2*\x*\x) node[above] {$y=x^2/5$};
    % \x r converts \x from degrees to radians
    \draw[B, thick, domain=-1.4:5.2, const plot mark right, mark=*, samples=15]
    plot (\x, {-cos(2*(\x r)) -1}) node[below right] {$y=-\cos(2x)-1$};
    \draw[Eggplant, thick, variable=\t, domain=-1.6:1.6, samples=50]
    plot (\t*\t-1, {\t*(\t*\t-1)}) node[above] {$y^2=x^3+x^2$};
  \end{tikzpicture}
  \caption{Using \textttc{plot}; note that expressions containing
    powers of the variable (written as in a \LaTeX\ mathematical
    expression, \eg $t^2$) are badly handled---use \textc{pow(t, 2)}
    instead.}
  \label{fig:graphs}
\end{figure}

\noindent
The curve $y^2=x^3+x^2$ was drawn using the command 
\begin{code}
  \draw[variable=\t, domain=-1.6:1.6, samples=50]
  plot (\t*\t-1, {\t*(\t*\t-1)}) node[above] {$y^2=x^3+x^2$};
\end{code}




\subsection{\textttc{addplot} and \textttc{addplot3}}

These commands are provided by the \textttc{pgfplots} package.  Each
axis in \verbc|pgfplots| is written into a separate environment, for
example \verb|\begin{axis}...\end{axis}|---for a normal set of axes.
Note that the code contains two sets of keys: the first is provided
after \verbc|\begin{axis}[...]|; the second after
\verbc|\addplot[...]| or \verbc|\addplot3[...]|.


\begin{figure}[hbt!]
  \centering
  \tikzexternalenable
  \begin{tikzpicture}
    \begin{axis}[%
      view={35}{20},
      title={Graph of \textttc{$y\exp(-x^2-|y|)$}},
      title style={black, font=\normalsize},
      font=\scriptsize,
      blue!40!black, % axes color and text
      axis background style={fill=gray!10},
      grid=major,
      grid style={color=gray!50}, xlabel=$x$, ylabel=$y$,
      ytick={-2,-1,...,2},
      colormap/cold, colorbar,
      colorbar style={font=\scriptsize},
      scale=1.2]
      
      \addplot3[surf, domain=-3:3, domain y=-3:3, samples=40] 
      {exp(-x^2-abs(y))*y};
    \end{axis}
  \end{tikzpicture}
  \tikzexternalenable
  \caption{Using \textttc{\textbackslash addplot3} with the key
    \textttc{view$=\{35\}\{20\}$}. }
  \label{fig:addplot3}
\end{figure}

\noindent
The former and the latter, in Fig.\,\ref{fig:addplot3}, are given bellow.

\medskip\noindent
\begin{minipage}{.6\linewidth}
\begin{code}
  view={35}{20},
  title={Graph of \textttc{$y\exp(-x^2-|y|)$}},
  title style={black, font=\normalsize},
  font=\scriptsize,
  blue!40!black, % axes color and text
  axis background style={fill=gray!10},
  grid=major,
  grid style={color=gray!50},
  xlabel=$x$, ylabel=$y$,
  ytick={-2,-1,...,2},
  colormap/cold, colorbar,
  colorbar style={font=\scriptsize},
  scale=1.2
\end{code}
\end{minipage}\qquad % position, height, position in the minipage
\begin{minipage}[b][21.2ex][t]{.3\linewidth}
\begin{code}
  surf,
  domain=-3:3,
  domain y=-3:3,
  samples=40 
\end{code}
\end{minipage}


see \textttc{axis equal image} for axes' coherence




\section{Pics---path operation}
\label{s:pics}

The path operation \textttc{pic} adds some drawing to the current path 
where a node might also be inserted.  There are two main differences
between nodes and pics: 
\begin{enumerate}[nolistsep, label={{\small\scshape (\roman*)}}]
\item 
  Unlike nodes, pics cannot be referenced later on.  A node inside a
  pic can be referenced but not ``the pic itself''.
  In general, if some parts of the drawing must be connected to one
  another, it is better to use a node rather than a pic.
\item
  A pic used to emulate the full power of a node will be slower to
  construct and take up more memory than a node achieving the same
  effect. 
\end{enumerate}

\medskip

A first example of pic is given by the code bellow.  It might
produce
\tikzset{
  pics/seagull/.style={%
    code={%
      \filldraw[#1, very thin] (-2ex, .5ex)
      to[out=10, in=140] (0, 0) to[out=40, in=170] (2ex, .7ex)
      to[bend right] (0, -.3ex) to[bend right] (-2ex, .5ex) -- cycle;
    }
  }
}
\begin{tikzpicture}
  \path (-.1, .3) pic[rotate=30, scale=1.9] {seagull=C}  
  (0, 0) pic[rotate=-10, scale=2.4] {seagull=M};
\end{tikzpicture}.


\begin{code}
  pics/seagull/.style={%
    code={%
      \filldraw[#1, very thin] (-2ex, .5ex)
      to[out=10, in=140] (0, 0) to[out=40, in=170] (2ex, .7ex)
      to[bend right] (0, -.3ex) to[bend right] (-2ex, .5ex) -- cycle;
    }
  }
  [...]
  \path (-.1, .3) pic[rotate=30, scale=1.9] {seagull=C}  
  (0, 0) pic[rotate=-10, scale=2.4] {seagull=M};  
\end{code}

\noindent
As for nodes,
\begin{itemize}[nolistsep]
\item
  a pic is placed either at the path's last position or, when
  \verbc|at| is used, at the corresponding specified position; the
  coordinate system is translated at the position (inside the pic's
  code, any mentioning of the origin refers either to the last 
  position used on the path or to the specified \verbc|at|)
\item
  the current path is not modified by the pic command, all drawings
  produced by the pic's code being ``external'' to the path
\item
  a given option applies only to the pic and have no effect outside of
  it
\item
  most ``outside'' options apply to the pic, but not the path actions
  like \verbc|draw| or \verbc|fill| which must be given in the pic's
  code. 
\end{itemize}


\begin{exa}[The whole game] In Fig.\,\ref{fig:embeddedNode} a node is
  embedded in the pic named \verbc|young| (Young tableau); the name of
  the node, for further reference, is formed by concatenation from the
  name given to each calling of the pic and the initial name of the
  node.
  \begin{figure}[htb!]
    \centering
    \tikzset{%
      pics/young/.style args={#1|#2}{%
        code={%
          \tikzmath{%
            real = \csize, \xsize, \ysize, \tmpx;
            \csize = .8;
            \xsize = (#1+.5)*\csize;
            \ysize = 2.5*\csize;
            for \i in {1,...,#1}{%
              let \tmpx = \i*\csize-\csize-#1*\csize/2;
              {
                \draw[fill=WBuff] (\tmpx, 0) rectangle +(\csize, \csize);
              };
            };
            if #2>0 then {%
              for \i in {1,...,#2}{%
                let \tmpx = \i*\csize-\csize-#1*\csize/2;
                {
                  \draw[fill=WBuff] (\tmpx, -\csize)
                  rectangle +(\csize, \csize);
                };
              };
            } else {%
              {\draw (-#1*\csize/2, 0) -- +(0, -\csize);};
            };
          },
          \path (0, 0)
          node[minimum width=\xsize cm, minimum height=\ysize cm] (-y) {};
        }
      }
    }
    \tikzexternalenable
    \begin{tikzpicture}[node distance=2cm and 3cm] 
      \path
      (0, 0) pic (32) {young={3|2}}
      (-4, -3) pic (33) {young={3|3}}
      (4, -3) pic (42) {young={4|2}};
      \path (32-y) edge[->] (33-y) edge[->] (42-y);
    \end{tikzpicture}
    \tikzexternaldisable
    \caption{The pic \textttc{young} contains an embedded node and
      behaves as such for further reference.  Note that \textc[R]{the
        relative positioning does not work well in this context}.}
    \label{fig:embeddedNode}
  \end{figure}
\end{exa}




\section{Decorations, \ie markings on paths}

A marking on a path is a \emph{path operation} that places at a
specific position a certain ``small drawing''.  For example, an arrow
tip can be placed at the middle of a path to indicate a flowing
direction, or information can be placed at certain
positions of a path, or the path can be suggested by the ``small
drawings''.


\subsection{Markings}

\begin{rem*}
  \verbc|\usetikzlibrary{decorations.markings}| needs to be called for
  arbitrary markings.
\end{rem*}

The blue Frenet-Serret frames in Fig.\,\ref{fig:frenet} are introduced
through the code below.  The command \verbc|use frenet| allows us to
draw using the Frenet coordinate system.
\begin{code}
  show frenet/.style 2 args={  % position and opacity
    decoration={
      markings,  % switch on markings
      mark = at position #1 with {
        \path (0, 0) coordinate
        (origin-\pgfkeysvalueof{/pgf/decoration/mark info/sequence number});
        \path (1, 0) coordinate (tangent unit vector-%
        \pgfkeysvalueof{/pgf/decoration/mark info/sequence number});
        \path (0, 1) coordinate (normal unit vector-%
        \pgfkeysvalueof{/pgf/decoration/mark info/sequence number});
        \filldraw[B] (0, 0) circle (1.5pt) ++(0, -1.5ex);
        \draw[thick, arrows={-Latex[width=7pt, open]}, opacity=#2]
        (0, 0) -- (1, 0);
        \draw[thick, arrows={-Latex[width=7pt, open]}, opacity=#2]
        (0, 0) -- (0, 1);
      }
    }, postaction=decorate
  }
\end{code}
\tikzset{
  % frenet/.style={
  %   decoration={
  %     markings,  % switch on markings
  %     mark = at position #1 with {
  %       \path (0, 0) coordinate
  %       (origin-\pgfkeysvalueof{/pgf/decoration/mark info/sequence number});
  %       \path (1, 0) coordinate (tangent unit vector-%
  %       \pgfkeysvalueof{/pgf/decoration/mark info/sequence number});
  %       \path (0, 1) coordinate (normal unit vector-%
  %       \pgfkeysvalueof{/pgf/decoration/mark info/sequence number});
  %       \filldraw[B] (0, 0) circle (1.5pt) ++(0, -1.5ex)
  %       node {\pgfkeysvalueof{/pgf/decoration/mark info/sequence number}};
  %     }
  %   }, postaction=decorate
  % },
  show frenet/.style 2 args={  % position and opacity
    decoration={
      markings,  % switch on markings
      mark = at position #1 with {
        \path (0, 0) coordinate
        (origin-\pgfkeysvalueof{/pgf/decoration/mark info/sequence number});
        \path (1, 0) coordinate (tangent unit vector-%
        \pgfkeysvalueof{/pgf/decoration/mark info/sequence number});
        \path (0, 1) coordinate (normal unit vector-%
        \pgfkeysvalueof{/pgf/decoration/mark info/sequence number});
        \filldraw[B] (0, 0) circle (1.5pt) ++(0, -1.5ex);
        \draw[thick, arrows={-Latex[width=7pt, open]}, opacity=#2]
        (0, 0) -- (1, 0);
        \draw[thick, arrows={-Latex[width=7pt, open]}, opacity=#2]
        (0, 0) -- (0, 1);
      }
    }, postaction=decorate
  },
  use frenet/.style={% uses the points defined before by the
                     % decoration <show frenet>
    shift=(origin-#1),
    x=(tangent unit vector-#1),
    y=(normal unit vector-#1)
  },
  use frenet/.default=1
}
\begin{figure}[htb!]
  \centering
  \begin{tikzpicture}[scale=1.3]
    \draw[WBuff, very thin] grid (5, 3);
    \draw[DarkB, show frenet={.4}{1}, show frenet={.62}{.3}]
    (0, 1) .. controls +(2, 2.3) and (6, 3) .. (4.5, 0);
    \begin{scope}[use frenet, thick, arrows={-Latex[width=7pt, open]}]
      \draw[R] (0, 0) -- ($(tangent unit vector-2)-(origin-2)$)
      coordinate (tmp);
      \draw[R] (0, 0) -- ($(normal unit vector-2)-(origin-2)$);
      \draw[very thin, ->] (1, 0) -- (tmp) node[pos=.6, right, scale=.8]
      {$\delta T$};
    \end{scope}
  \end{tikzpicture}  
  \caption{The Frenet-Serret frame, \ie the $T$ and $N$ vectors, is
    represented at two points on a plane curve.  A translated version
    of the second frame (in red) is indicated yielding the change in
    $T$ denoted $\delta T$.  Accordingly, $\delta s$ is the distance
    between the points.  When $\delta s$ goes to $0$, the vector
    $\frac{dT}{ds}$ is proportional to $N$.  The curvature describes
    the speed of rotation of the frame.}  
  \label{fig:frenet}
\end{figure}

\noindent
\verbc|mark=at position ... with {<drawing commands>}| induces the
followings:
\begin{itemize}[nolistsep]
\item
  \verbc|pgf| determines the corresponding position on the path
\item
  the coordinate system is translated to this position and is rotated
  such that the positive $x$-axis is tangent to the path
\item
  a temporary \verbc|scope| is created, inside which the code is
  executed. 
\end{itemize}


\begin{noticeB}
  The \emph{markings} decoration allows us to place one or more
  markings on a path.  The decoration destroys the input path.  To
  keep the path intact, the markings must be added through the use of
  either a pre or a postaction.
\end{noticeB}


A second way to use the \verbc|mark| key is to place multiple marks
from a starting position till an ending one and being spaced apart by
a given step.  These positions and step may be given in the same way
as for the \verbc|at position| version---using units or no units and
also using positive or negative values.

\begin{figure}[htb!]
  \centering
\tikzset{%
  counting/.style={%
    decorate,
    decoration={markings,
      mark=between positions 0 and 1 step{#1} with {%
        \draw (Omega) -- (0, 0) coordinate[
        name=mark-\pgfkeysvalueof{/pgf/decoration/mark info/sequence number}
        ] node[circle, draw, fill=Sand, transform shape]
        {\pgfkeysvalueof{/pgf/decoration/mark info/sequence number}};
      }
    }
  }
}
\begin{tikzpicture}[scale=.8]
  \path (0, 0) coordinate (Omega);
  \draw[WBuff] (-3, -3) grid (3, 3);
  \path[Grape, text=K, postaction={counting={.0909}}]
  (60: 3) arc (60: -270: 3);
  \draw[Gold, arrows={-Latex[fill=white, length=15pt]}, line width=2pt]
  (0, 0) -- ($.8*(mark-4)$);
\end{tikzpicture}
\begin{tikzpicture}[scale=.8]
  \begin{scope}[x={(-1, 0)}]
    \path (0, 0) coordinate (Omega);
    \draw[WBuff] (-3, -3) grid (3, 3);
    \path[Grape, text=K, postaction={counting={.08334}}, rotate=-120]
    (0, 0) circle (3);
    \draw[Gold, arrows={-Latex[fill=white, length=15pt]}, line width=2pt]
    (0, 0) -- ($.8*(mark-4)$);
  \end{scope}
\end{tikzpicture}
  \caption{The final image is the same, but the construction is
    different. On the left an arc negatively parameterized is used; on
    the right a full circle but the image is reflected in the $Oy$
    axis.  So the difference for the markings come from the open vs
    closed character of the curves.}
  \label{fig:clock}
\end{figure}
The decoration is defined as follows (\verbc|Omega| being the origin
defined in the drawing):
\begin{code}
    counting/.style={%
    decorate,
    decoration={markings,
      mark=between positions 0 and 1 step{#1} with {%
        \draw (Omega) -- (0, 0) coordinate[
        name=mark-\pgfkeysvalueof{/pgf/decoration/mark info/sequence number}
        ] node[circle, draw, fill=Sand, transform shape]
        {\pgfkeysvalueof{/pgf/decoration/mark info/sequence number}};
      }...
\end{code}


\begin{rem}
For arrow tip markings, two special commands are available when the
\emph{code of a mark option} is executed:
\begin{itemize}[nolistsep]
\item
  \verbc|\arrow[..., options]{arrow end tip}|
\item
  \verbc|\arrowreversed[..., options]{arrow end tip}|
\end{itemize}
These commands draw the arrow end tip at the origin (of the marking),
pointing right and left, respectively.

\medskip\noindent
\begin{minipage}[t]{.7\linewidth}
  For example, in the drawing on the right, the red and green tips are
  obtained through
  \begin{itemize}[nolistsep, label={}]
  \item
    \verbc|\arrow[R, very thick]{stealth}|
  \item
    \verbc|\arrow[G, thick]{Latex[width=2ex, open]}|
  \end{itemize}
  respectively.  Note that the origin of the marking coincides with
  the summit of the arrow tip.  The blue and green markings both occur
  at position $0.75$.
\end{minipage}
\begin{minipage}[t]{.3\linewidth}
  \centering
  \begin{tikzpicture}[baseline=2.3cm, 
    decoration={
      markings,% switch on markings
      mark=at position .5 with {\arrow[R, very thick]{stealth}},
      mark=at position .75 with {\arrow[VB, thick]{>}},
      mark=at position .75 with {
        \arrow[G, thick]{Latex[width=2ex, length=2em, open]}
      }
    }]
    \fill[LightGray!10] (-.3, -.3) rectangle (3.3, 2.3);
    \draw[LightGray] (0, 0) grid (3, 2);
    \draw[Gold, very thick, postaction={decorate}]
    (.7, 0) -- (3, .5) arc (0: 180: 1.5 and 1);
  \end{tikzpicture}
\end{minipage}
\end{rem}



\subsection{Random edge}

The following example needs the library
\verbc|decorations.pathmorphing|.  The name of the decoration is
\verbc|random steps|.
\begin{figure}[htb!]
  \centering
  \begin{tikzpicture}
    \draw[Gray, help lines, ultra thin] (-.5, -.5) grid ++(4, 3);
    \draw[B, very thin]
    (-.2, 0) -- (3, 1) arc (0: 180: 1.5 and 1) -- cycle;
  \end{tikzpicture}
  \quad
  \begin{tikzpicture}[decoration={random steps, segment length=2mm}]
    \draw[Gray, help lines, ultra thin] (-.5, -.5) grid ++(4, 3);
    \draw[decorate, fill=Gold]
    (-.2, 0) -- (3, 1) arc (0: 180: 1.5 and 1) -- cycle;
  \end{tikzpicture}
  \quad
  \begin{tikzpicture}[decoration={%
      random steps, segment length=1ex, amplitude=1ex%
    }]
    \draw[Gray, help lines, ultra thin] (-.5, -.5) grid ++(4, 3);
    \draw[decorate, fill=Gold]
    (-.2, 0) -- (3, 1) arc (0: 180: 1.5 and 1) -- cycle;
  \end{tikzpicture}
  \caption{Random steps decoration; the last drawing uses
    \textttc{segment length=1ex} and \textttc{amplitude=1ex}.}
  \label{fig:randomSteps}
\end{figure}
It has two arguments:
\begin{itemize}[nolistsep]
\item 
  \textttc{segment length} that determines the length of each step in
  the drawn process of the path
\item
  \textttc{amplitude} that determines the interval from which the
  perturbation values in the $x$ and $y$ directions are both drawn.
\end{itemize}


\begin{code}
\draw[decoration={random steps, segment length=1ex, amplitude=1ex},
decorate] (-.2, 0) -- (3, 1) arc (0: 180: 1.5 and 1) -- cycle;
\end{code}




\subsection{Text effects}

The examples in Fig.\,\ref{fig:textEffects} use the library
\verbc|decorations.text|.  The philosophy is different for the ``red''
effect and for the other two .

First, \verbc|text along path| decorates the path with text; the
drawing of the text is a ``side effect'' of the decoration.
\begin{itemize}[nolistsep]
\item
  Each character is positioned using the center of its baseline. To
  move the text vertically (relative to the path), the additional
  key \verbc|raise| should be used.
\item
  It is only possible to typeset text in math mode under considerable
  restrictions, say simple math expressions.  Math subscripts and
  superscripts need to be contained within braces (\eg \verb|{y_i^2}|)
  as do commands like \verb|\times| or \verb|\cdot|.
\item
  The text's options can be given in a concatenation style; for
  example
  \begin{code}
text={It is a |\color{R}|ground breaking |+\bf|experience||, isn't it.}
  \end{code}
\end{itemize}

Second, \verbc|text effects along path| is similar to
\verbc|text along path| except that each character is inserted
into the picture as a \tikZ\ node.  Thus, node options (such as
\verbc|text|, \verbc|scale|, \verbc|opacity|) may be used to
create \emph{text effects}.  Note the following differences with
respect to \verbc|text along path|:
\begin{itemize}[nolistsep]
\item
  Formatting (\eg font, color) cannot be specified in the decoration
  text, but only through the node's options.
\item
  Due to the number of computations involved, this is quite a slow
  decoration. 
\end{itemize}

\begin{figure}[htb!]
  \centering
\tikzset{%
  simple/.style={%
    postaction={%
      decorate,
      decoration={%
        text along path,
        text={#1},
        text align=center,
        raise=1ex,
        reverse path
      }
    }
  },
  fancy/.style={%
    postaction={%
      decorate, decoration={%
        text effects along path,
        text={#1},
        text align=center,
        text effects/.cd, 
        text along path, 
        every character/.style={%
          fill=white, yshift=-0.5ex, font=\large, text=DarkG%
        }
      }
    }
  },
  fancy plus/.style 2 args={%
    postaction={%
      decorate, decoration={%
        text effects along path,
        text={#1},
        text align=center,
        text effects/.cd, 
        text along path,
        character count=\i,
        character total=\n,
        characters={evaluate={\c=\i/\n*(1-\i/\n)*400;},
          text=V!\c!O, font=\Large, fill=W, yshift=.4ex
        },
        character #2/.style={text=C, font=\Large\bf\itshape},
      }
    }
  },
  reflections/.style={%
    decorate, decoration={%
      text effects along path,
      text={#1},
      text align=center,
      text effects/.cd, 
      text along path,
      character count=\i,
      character total=\n,
      characters={evaluate={\c=\i/\n*(1-\i/\n)*3+.4;},
        font=\Large, opacity=\c, text=Gray, yscale=-1, yshift=.4ex,
        xslant=(\i/\n-0.5)*2,
      },
      character widths={font=\Large, text along path, xslant=0}
    }
  }
}
\begin{tikzpicture}
  \path[clip] (-7, 5.2) rectangle (7.3, -1.7);
  
  \draw[DarkB, -Latex,
  fancy={~Some text following a path that we don't see~}]
  (-5, 0) to[out=-40, in=170] ++(4, 3) to[out=-10, in=240] ++(4, 2);

  \draw[B, arrows={Latex-Latex},
  simple={It is a |\color{R}|ground breaking |+\bf|experience||, isn't it.}]
  (0, 1) arc[start angle=10, end angle=130, radius=4];

  \path[fancy plus={~Some text following a path that we don't see but
    can guess~}{3},
  postaction={reflections={~Some text following a path that we don't
      see but can guess~}}]
  (-5, -1) to[out=-40, in=170] ++(6, 3) to[out=-10, in=240] ++(6, 2);
\end{tikzpicture}
  \caption{Using \textc{text along path} and
  \textc{text effects along path}.}
  \label{fig:textEffects}
\end{figure}




\section{Shapes}

For the shapes below, we need
\verbc|\usetikzlibrary{shapes.symbols}|.
\begin{center}
  \begin{tikzpicture}
    \path (0, 0) 
    node [correct forbidden sign, draw=red, fill=white, line width=1ex]
    (forbidden) {\sffamily Thinking}
    ++(0, -1.5) node[BK] {correct forbidden sign};
    \path (4.5, 0)
    node[draw, fill=DarkB, text=W, signal, signal to=west, inner sep=2ex]
    (to) {\sffamily\bfseries To West}
    ++(0, -1.3) node[BK] {signal,}
    ++(0, -.5) node[BK] {signal to=west};
    \path (9, 0)
    node[draw, fill=Gold, text=BK,
    signal, signal to=nowhere, signal from=west, inner sep=2ex]
    (from) {\sffamily\bfseries From West}
    ++(0, -1.3) node[BK] {signal, signal to=nowhere,}
    ++(0, -.5) node[BK] {signal to=west};
  \end{tikzpicture}
\end{center}

\noindent
The code for the second and third nodes are below; note the need to
invoke \verbc|signal to=nowhere| to achieve the third one.

\begin{code}
  \path (0, 0) node[draw, fill=DarkB, text=W,
  signal, signal to=west, inner sep=2ex] {To West};
  \path (5, 0)
  node[draw, fill=Gold, text=BK,
  signal, signal to=nowhere, signal from=west, inner sep=2ex] {From West};
\end{code}

Next, we consider closely the shape \verbc|signal to|; we increase the
\verbc|inner sep| dimension---an additional (invisible) separation
space of added inside the shape, between the text and the shape's
background path---to better see the point.  See Fig.\,\ref{fig:signal}.

\begin{figure}[htb!]
  \centering
  \begin{tikzpicture}[node distance=0pt and 0pt]
    \path (0, 0)
    node[draw, fill=DarkB, text=W,
    signal, signal to=nowhere, signal from=west, inner sep=3ex]
    (from) {\sffamily\bfseries From West}
    node[draw, fill=Y, above left=of from] {Testing the position};    
    \filldraw[O] (0, 0) circle (2pt);
  \end{tikzpicture}  
  \caption{In the case of \textc{signal} shapes, the center is
    considered with respect to the initial form (the orange circle),
    not to the border; by comparison, note the position of the node
    ``Testing the position'' set as \textc{above left} with respect to
    the shape node.}
  \label{fig:signal}
\end{figure}




\section{Other path actions}
\subsection{Pre and post actions}

\begin{figure}[htb!]
  \centering
  \begin{tikzpicture}[scale=1.2]
    \draw[help lines] (0, 0) grid (3, 2);
    \fill[preaction={%
      fill=BK, opacity=.4, transform canvas={xshift=10pt, yshift=-5pt}
    }, fill=O, even odd rule] (0, -.25) rectangle (1, 2) (1, 2) circle (.5);
  \end{tikzpicture}
  \qquad
  \begin{tikzpicture}[scale=1.2]
    \draw[help lines] (0, 0) grid (3, 2);
    \fill[preaction={%
      fill=BK, opacity=.3, transform canvas={xshift=6pt, yshift=-3pt}
    }, fill=G!30!Y] (-.5, .2) rectangle ++(3, 1);    
    \fill[preaction={%
      fill=BK, opacity=.3, transform canvas={xshift=10pt, yshift=-5pt}
    }, fill=M, even odd rule] (0, -.25) rectangle (1, 2) (1, 2) circle (.5);
    
    % correctiong the drop shadow
    \fill[G!30!Y, xshift={4pt}] (1, .2) rectangle ++(7pt, 1);
  \end{tikzpicture}
  \caption{Using \textttc{preaction} and \textttc{even odd rule} for
    graphical effects.}
  \label{fig:preaction}
\end{figure}
\begin{code}
  \fill[preaction={%
    fill=BK, opacity=.4, transform canvas={xshift=10pt, yshift=-5pt}
  }, fill=O, even odd rule] (0, -.25) rectangle (1, 2) (1, 2) circle (.5);
\end{code}

\noindent
\begin{minipage}[t]{.6\linewidth}
  We consider the same figure but construct the cast shadow differently.
  More precisely, we use the library \textttc{shadows.blur}.  The
  preaction is not needed; it is contained in \textttc{blur shadow={...}}.
\end{minipage}
\begin{minipage}[t]{.4\linewidth}
  \centering
    \begin{tikzpicture}[baseline=1cm, scale=1.2]
    \draw[help lines] (0, 0) grid (3, 2);
    \fill[blur shadow={%
      shadow xshift=10pt,
      shadow yshift=-4.5pt,
      shadow blur steps=9,
      shadow blur extra rounding=1.5pt%
    }, fill=O, even odd rule] (0, -.25) rectangle (1, 2) (1, 2) circle (.5);
  \end{tikzpicture}
\end{minipage}


\bigskip
\paragraph{A different example---multiple postactions}
In the figure below, the construction uses multiple postactions which
create the horizontal lines as well as the vertical ones; the latter
are the outcome of the last postaction,

\verbc|postaction={draw=BK, line width=4.98ex, dash pattern=on .5 off 4.5}|.

\begin{center}
  \colorlet{tmp}{WBuff}
  \tikzexternalenable
  \begin{tikzpicture}
    \draw[BK, line width=5.1ex,
    postaction={draw=tmp, line width=5ex},
    postaction={draw=BK, line width=3.09ex},
    postaction={draw=tmp, line width=3ex},  
    postaction={draw=BK, line width=1.1ex},
    postaction={draw=tmp, line width=1ex},  
    postaction={draw=BK, line width=4.98ex, dash pattern=on .5 off 4.5}]
    (0, 0) -- ++(1, 0) to[out=0, in=180] ++(3, -1)
    -- ++(3, 0) to[out=0, in=180] ++(3, 3) -- ++(2, 0);
  \end{tikzpicture}
  \tikzexternaldisable
\end{center}



\paragraph{Example---approaching the color variations of a parchment}
Starting with the left image in Fig.\,\ref{fig:parchment}, we try to
reproduce the color variations, margin, and texture as the background
and border of a node.
\begin{itemize}[nolistsep]
\item
  We use the library \textttc{shadings}; there are two shadings (a
  vertical---horizontal stripes---and a radial one) that are created.
  The former with opacity $0.9$, the latter $0.7$.  See below the
  definition of the radial one.  They are applied through two
  \textttc{postaction} commands.
\item
  The drop shadow is created with the \textttc{blur shadow=...}
  command as in the first example of this subsection.
\item
  The border is obtained through the random step decoration, see
  Fig.\,~\ref{fig:randomSteps}.
\item
  I don't know how to handle the texture.  One of the main reasons is
  the fact that this is the background of a node.
\end{itemize}


\begin{code}
  \pgfdeclareradialshading{rparchment}{\pgfpoint{0cm}{0cm}}{%
    color(0bp)=(pylight);
    color(13bp)=(pylight);
    color(20bp)=(py);
    color(40bp)=(pydark);
    color(60bp)=(pydark!50!DarkR);
    color(100bp)=(RK)%
  }
\end{code}

\definecolor{parchment_yellow}{RGB}{245, 233, 175}
\definecolor{pylight}{RGB}{247, 235, 205}
\definecolor{py}{RGB}{243, 224, 181}
\definecolor{pydark}{RGB}{221, 182, 110}
\definecolor{pyhighlight}{RGB}{254, 235, 204}

\pgfdeclareverticalshading{parchment}{100bp}{%
  color(0bp)=(pydark);
  color(25bp)=(pydark);
  color(30bp)=(py);
  color(50bp)=(pylight);
  color(70bp)=(py);
  color(75bp)=(pydark);
  color(100bp)=(pydark)%
}
\pgfdeclareradialshading{rparchment}{\pgfpoint{0cm}{0cm}}{%
  color(0bp)=(pylight);
  color(13bp)=(pylight);
  color(20bp)=(py);
  color(40bp)=(pydark);
  color(60bp)=(pydark!50!DarkR);
  color(100bp)=(RK)%
}
\tikzset{
  ragged border/.style={%
    decorate,  decoration={%
      random steps, segment length=1.1ex, amplitude=.5ex%
    }
  },
  drop shadow/.style={
    blur shadow={%
      shadow xshift=.5pt,
      shadow yshift=-.5pt,
      shadow blur steps=9,
      shadow blur extra rounding=1.5pt%
    },
  },
  parchment fill/.style={
    ragged border, fill=pyhighlight,
    postaction={shading=parchment, opacity=.9},
    postaction={shading=rparchment, opacity=.7}
  }
}
\begin{figure}[htb!]
  \begin{tikzpicture}[scale=.6]
    \path node[label={270:original}, scale=.65] (original)
    {\includegraphics[width=11cm]{z_zExternalize/fig_parchment.png}};
  \end{tikzpicture}
  \quad
  \tikzexternalenable
  \begin{tikzpicture}[scale=.6]
    \shade node[rounded corners, parchment fill,
    drop shadow, text width=10cm, text height=6.5cm,
    inner sep=3ex, align=justify,
    label={[label distance=2ex] 270:test}, scale=.65]
    (test) {};
  \end{tikzpicture}
  \tikzexternaldisable
  \caption{Reproducing an old parchment.  Well, not really, since it
    resembles more to a biscuit.  Some irregularities would be most needed.}
  \label{fig:parchment}
\end{figure}


\noindent
Below are some examples of using the ``parchment node''.  The fonts in
the second example are \emph{rotunda}.

\medskip
\tikzexternalenable
\begin{tikzpicture}
  \shade node[rounded corners, parchment fill,
  drop shadow, text width=11cm, % text height=7.3cm,
  inner sep=4ex, align=justify, color=DarkR]
  (I) {\fontfamily{qhv}\selectfont\Large  % TEX Gyre Heros (tgheros)
    The brown fox jumps over the lazy dog
    following the joyful rabbit.  ``Rabbit wait!'' };
\end{tikzpicture}

\medskip
\begin{tikzpicture}
  \shade node[rounded corners, parchment fill,
  drop shadow, text width=11cm, % text height=7.3cm,
  inner sep=4ex, align=justify, color=DarkR!70!BK]
  (II) {\rtndfamily\Large  % rotunda
    The brown fox jumps over the lazy dog
    following the joyful rabbit.};
\end{tikzpicture}

\medskip
\begin{tikzpicture}
\shade node[rounded corners, parchment fill,
  drop shadow, text width=11cm, % text height=7.3cm,
  inner sep=4ex, align=justify, color=DarkR!71!BK]
  (II) {\pgothfamily\LARGE
    The brown fox jumps over the lazy dog
    following the joyful rabbit.};
\end{tikzpicture}
\tikzexternaldisable



\subsection{let \ldots\, in}
\label{ss:let}

We give two examples; this action was already used on page
\pageref{page:useOfLet} to construct the angle \verb|\n1|..


\paragraph{Example (Euclid)}
How to construct an equilateral triangle on a given finite straight
line, \ie a segment.

\smallskip
If the segment is determined by the points $A$ and $B$, the idea is to
construct the two circles centered at $A$ and $B$ and of radius $AB$.
Each point of intersection of the circles gives rise to an equilateral
triangle together with $A$ and $B$.  The only remaining problem is to
access the $x$- and $y$-coordinate of the vector $\vector{AB}$.  For
this, we need a new concept: the \textttc{let ... in} operation.  A let
operation can be given anywhere on a path where a normal path
operation like a line-to or a move-to is expected.  The effect of a
let operation is to evaluate some coordinates and numbers and to
assign the results to special macros.  These macros make it easy to
access the $x$- and $y$-coordinates of the points and/or vectors (\ie
coordinates):
\begin{itemize}[nolistsep]
\item
  \verbc|\p<digit> = (a, b)| creates the point $(a,b)$.  Note that,
  say \verbc|\p1|, is the string formed with the coordinates of the
  point $(a,b)$.
\item
  \verbc|(\p<digit>)| yields the resulting point
\item
  \verbc|\x<digit>| or \verbc|\y<digit>| yields the $x$- or $y$-coordinate
  of the resulting point
\item
  \verbc|\n<digit> = ...| or \verbc|\n{symbols} = ...| creates a
  number.
\end{itemize}

\begin{noticeB}
  Given $a, b\in\RR$, \verbc|veclen(a,b)| inside a mathematical
  expression, \ie \textbf{curly brackets}, yields $\sqrt{a^2+b^2}$.
\end{noticeB}

The result of the code below is used in 
Fig.\,\ref{fig:equilateralTriangle} to obtain the vertex $C$ of the
equilateral triangle.
\begin{code}
  \path ($(B)-(A)$) coordinate (v);
  \draw let
  \p1 = (v),
  \n1 = {veclen(\x1, \y1)}
  in [name path=circleA] (A) circle (\n1);
  \draw let
  \p1 = (v),
  \n1 = {veclen(\x1, \y1)}
  in [name path=circleB] (B) circle (\n1);
  \path[name intersections={of=circleA and circleB, by={C, D}}];
  \draw[thick, fill=O] (A) -- (B) -- (C) -- cycle;
\end{code}

\begin{figure}[htb!]
  \centering
  \begin{tikzpicture}
    \path (0, 0) coordinate (A)  (1.7, .7) coordinate (B);
    \path ($(B)-(A)$) coordinate (v);
    \draw
    let \p1 = (v), \n1 = {veclen(\x1, \y1)}
    in [name path=circleA] (A) circle (\n1);
    \draw
    let \p1 = (v), \n1 = {veclen(\x1, \y1)}
    in [name path=circleB] (B) circle (\n1);
    \path[name intersections={of=circleA and circleB, by={C, D}}];
    \draw[thick, fill=O] (A) -- (B) -- (C) -- cycle;
    \foreach \P/\pos in {A/below left, B/right, C/above left}{%
      \draw[fill=white] (\P) circle (1.5pt) node[\pos] {$\P$};
    }
  \end{tikzpicture}
  \caption{An equilateral triangle constructed on the segment $[AB]$}
  \label{fig:equilateralTriangle}
\end{figure}


\begin{rem*}
  A different way of solving the problem is to compute the radius only
  once in a \textttc{tikzmath} declaration.
  \begin{code}
  \begin{tikzpicture}
    \path (0, 0) coordinate (A)  (1.7, .7) coordinate (B);
    \tikzmath{%
      coordinate \v;
      real \r;
      \v = ($(B)-(A)$);
      \r = veclen(\vx, \vy);
    }
    \draw[name path=circleA] (A) circle (\r pt);
    \draw[name path=circleB] (B) circle (\r pt);
    \path[name intersections={of=circleA and circleB, by={C, D}}];
    \draw[thick, fill=O] (A) -- (B) -- (C) -- cycle;
    \foreach \P/\pos in {A/below left, B/right, C/above left}{%
      \draw[fill=white] (\P) circle (1.5pt) node[\pos] {$\P$};
    }
  \end{tikzpicture}
  \end{code}
\end{rem*}


\begin{noticeB}
  Note the need of specifying the units in
  \verbc|\draw (A) circle (\r pt);| since, even if the macros
  \verbc|\vx| and \verbc|\vy| return coordinates converted in points,
  the use of \verbc|real \r| yields a dimensionless number which is
  big!
\end{noticeB}

\noindent
For example,
\begin{itemize}
\item 
  \begin{tikzpicture}
    \tikzmath{
      coordinate \v;
      \v=(1, 0);
    }
    \path node[fill=O, text=W, scale=.9] {\textbf\vx};
  \end{tikzpicture}
  is the result of
  \begin{code}
    \tikzmath{
      coordinate \v;
      \v=(1, 0);
    }
    \path node[fill=O, text=W, scale=.9] {\vx};
  \end{code}
\item
  \begin{tikzpicture}
    \tikzmath{
      coordinate \v;
      real \tmp;
      \v=(1, 0);
      \tmp = \vx;
    }
    \path node[fill=O, text=W, scale=.9] {\textbf\tmp};
  \end{tikzpicture}
  is the result of
  \begin{code}
    \tikzmath{
      coordinate \v;
      real \tmp;
      \v=(1, 0);
      \tmp = \vx;
    }
    \path node[fill=O, text=W, scale=.9] {\tmp};
  \end{code}  
\end{itemize}


\paragraph{Bisecting an angle}
Suppose that $A$, $B$ and $C$ are known and that we want to construct
the bisector of the angle $\widehat{BAC}$.  Some solutions are given
by the use of \textttc{let \ldots\, in} action.

For example, it is possible to construct the measure of the angle and
then to draw the bisector based on this measure.  Of course, a
decision must be taken concerning the sign of the angle of rotation in
the direct similitude considered; see the blue (B) ray.

The red elements in the figure below are constructed as follows: the
point $B'$ is constructed on the ray $[AB)$ such that $AB'=AC$, and
then the bisector is drawn using the middle point of $[B'C]$.
\begin{figure}[htb!]
  \centering
  \begin{tikzpicture}
    \path 
    (-.5, 0) coordinate (B)
    (.2, 3) coordinate (A)
    (5, -1) coordinate (C);
    \clip (-5, -4) rectangle (6, 4);
    \draw (B) -- (A) -- (C);
    \draw[LightGray] (A)
    let \p2 = ($(C)-(A)$), \n2 = {veclen(\x2, \y2)}
    in circle (\n2);

    \draw[Gold, line width=2pt] let
    \p1 = ($(B)-(A)$),
    \p2 = ($(C)-(A)$),
    \n1 = {veclen(\x1, \y1)},
    \n2 = {veclen(\x2, \y2)},
    \n{angle} = {acos((\x1*\x2+\y1*\y2)/(\n1*\n2))/2}
    in (A) -- ($(A)!1.2!\n{angle}:(B)$);
    \draw[B, fill=B] let
    \p1 = ($(B)-(A)$),  \p2 = ($(C)-(A)$),
    \n1 = {veclen(\x1, \y1)},  \n2 = {veclen(\x2, \y2)},
    \n3 = {\n2/\n1},
    \p3 = ($(A)!\strippt(\n3)!(B)$)
    in
    (C) -- (\p3)
    (A) -- ($(\p3)!.5!(C)$) circle (1.5pt) node[below right] {$M$}
    (B) -- (\p3) circle (1.5pt) node[below left] {$B'$};

    \foreach \P/\pos in {A/above, B/left, C/right}{%
      \draw[fill=white] (\P) circle (1.5pt) node[circle, \pos] {$\P$};
    }
  \end{tikzpicture}
  \caption{Bisecting the angle $\widehat{BAC}$.}
  \label{fig:bisector}
\end{figure}


\begin{itemize}[noitemsep]
\item[(B)]
\begin{code}
  \draw[B, thick] let
    \p1 = ($(B)-(A)$),  \p2 = ($(C)-(A)$),
    \n1 = {veclen(\x1, \y1)},  \n2 = {veclen(\x2, \y2)},
    \n{angle} = {acos((\x1*\x2+\y1*\y2)/(\n1*\n2))/2}
  in (A) -- ($(A)!1.2!\n{angle}:(B)$);
\end{code}
\item[(R)]
\begin{code}
  \draw[R, thick] let
    \p1 = ($(B)-(A)$),  \p2 = ($(C)-(A)$),
    \n1 = {veclen(\x1, \y1)},  \n2 = {veclen(\x2, \y2)},
    \n3 = {\n2/\n1},
    \p3 = ($(A)!\strippt(\n3)!(B)$)
  in (A) -- ($(\p3)!.5!(C)$);
\end{code}
\end{itemize}

\begin{noticeB}
  In the preceding code, the length \verbc|\n3| (expressed in pt) is
  transformed into a dimensionless number through the command
  \verbc|\strippt| which is defined in the preamble.
\end{noticeB}



\paragraph{Intersection point of two lines}

outside let

\verb|\coordinate (D) at (intersection of leftD--rightD and C--c);| ?

This is the fourth way an intersection point can be found.  We were
referring to it on page \pageref{page:intersection4}.  One
advantage is that the lines are defined mathematically, \ie as drawn
elements on the canvas they may not have a point in common.

\begin{tikzpicture}[every node/.style={scale=.8}]
  % points and directions
  \path
  (0, 0) coordinate (A) (80:1) coordinate (v)
  (4, 1) coordinate (B) (150:1) coordinate (w);

  % intersection point
  \path let
  \p1 = (A),
  \p2 = ($(A)+(v)$),
  \p3 = (B),
  \p4 = ($(B)+(w)$),
  \p5 = (intersection of \p1--\p2 and \p3--\p4)
  in
  (\p5) coordinate (C);
  
  \draw (A) -- (C)  (B) -- (C);

  \draw[blue, very thick, ->] (A) -- +(v) node[above left] {$\vv$};
  \draw[blue, very thick, ->] (B) -- +(w) node[above right] {$\ww$};
  
  \foreach \P/\pos in {A/below left, B/below right, C/above left}{%
    \draw[fill=white] (\P) circle (1.2pt) node[\pos] {$\P$};
  }

  \path[B] (6, 1.1) node[draw, right, scale=1.1, text width=22.5em]
  {\verbc|\p5 = (intersection of \p1--\p2 and \p3--\p4)|};
  \path (6, .2) node[right, scale=1.1, text width=22.5em]
  {is used inside the \verbc|let ... in| action to produce the
  intersection point.};
\end{tikzpicture}




\subsection{\textbackslash foreach}
\label{ss:foreach}

A pattern created by rotating and scaling a rectangle multiple times.
Note the use of color fading obtained by superposition only.
Moreover, the whole construction---\tikZ\ commands included---are
embedded in a \verbc|\tikzmath| environment.

\begin{figure}[htb!]
  \centering
  \begin{tikzpicture}[scale=.8]
    \tikzmath{
      integer \nbPoints, \j;
      real \oIndex;
      \nbPoints = 20;
      \oIndex = 1/(2*sqrt(\nbPoints));
      coordinate \A, \B, \C, \D, \M, \N, \P, \Q;
      \A = (0, 0); \B = (10, 0); \C = (10, 10); \D = (0, 10);
      {
        \fill[M, opacity=\oIndex] (\A) -- (\B) -- (\C) -- (\D) -- cycle;
      };
      for \i in {1, 2, ..., \nbPoints}{%
        \j = 5*\i;
        \M = (\A)!\oIndex!(\B);
        \N = (\B)!\oIndex!(\C);
        \P = (\C)!\oIndex!(\D);
        \Q = (\D)!\oIndex!(\A);
        \A = (\M); \B = (\N); \C = (\P); \D = (\Q);
        {
          \filldraw[B!\j!VB, opacity=\oIndex] (\A) -- (\B) -- (\C) -- (\D) -- cycle;
        };
      };
    }
  \end{tikzpicture}
  \caption{Fading rectangle with with 20 steps---it uses tikzmath}
  \label{fig:rectangle}
\end{figure}

\begin{code}
    \tikzmath{
      coordinate \A, \B, \C, \D, \M, \N, \P, \Q;
      \A = (0, 0); \B = (10, 0); \C = (10, 10); \D = (0, 10);
      {
        \fill[VB, opacity=\oIndex] (\A) -- (\B) -- (\C) -- (\D) -- cycle;
      };
      for \i in {1,2,...,\nbPoints}{% 
        \M = (\A)!\oIndex!(\B);
        \N = (\B)!\oIndex!(\C);
        \P = (\C)!\oIndex!(\D);
        \Q = (\D)!\oIndex!(\A);
        \A = (\M); \B = (\N); \C = (\P); \D = (\Q);
        {
          \fill[fill=B, opacity=\oIndex]
          (\A) -- (\B) -- (\C) -- (\D) -- cycle;
        };
      };
    }
\end{code}




\section{Using mathematics and functions}


\paragraph{The Ford circles}
Given an irreducible fraction $\frac{p}{q}$, the circle at
$(\frac{p}{q},\frac{1}{2q^{2}})$ with radius $r=\frac{1}{2q^{2}}$ is
tangent to  $(Ox)$.  If all such circles are drawn, they do not
intersect but are at most tangent.


\begin{figure}[htb!]
  \centering
  \tikzmath{%
    real \b;
    integer \n, \p, \q, \pend;
    let \n=6;
    let \b=3.3;
  }
  \begin{tikzpicture}[scale=3]
    \draw[Gray, very thin] (-.5, 0) -- ++(\b+1, 0);
    \foreach \q [evaluate=\q as \pend using {\b*\q}] in {1, ..., \n}{%
      \foreach \p in {0, ..., \pend}{% a<p/q<b
        \tikzmath{%
          if gcd(\p,\q)==1 then {%
            \f = \p/\q;  % evaluate the first coordinate of the tuch point
            \r = 1/(2*\q*\q);  % evaluate the radius r=1/2q^2
            {
              \draw[B] (\f, \r) circle (\r); 
            };
          };
        }
      }
    }
  \end{tikzpicture}
  \caption{Giving the interval $[0, b]$ and the integer $n$, the Ford
    circles corresponding to $\frac{p}{q}\in[a, b]$ such that
    $0<q\leq n$ are drawn.  We have $b=3.3$ and $n=6$.}
  \label{fig:foirdCircles}
\end{figure}


\begin{noticeB}
  The outer loop introduces the upper bound of the inner loop through
  \verbc|evaluate|: \\
  \verbc|\foreach \q [evaluate=\q as \pend using {\b*\q}] in {1, ..., \n}{%|\\
  \verbc|  \foreach \p in {0, ..., \pend}{%|
\end{noticeB}



\paragraph{A not so random path}
The construction is based on a loop and the use of the function
\textttc{rand} which produces a random number in $[0, 1]$.

\pgfmathsetseed{117}
\begin{figure}[htb!]
  \centering
  \tikzexternalenable
  \begin{tikzpicture}[line width=2pt, line cap=round]
    \path
    (0, 0) coordinate (current point)
    (1, .6) coordinate (old velocity);
    \path let
    \p1 = (old velocity),
    \p2 = (-\y1, \x1)
    in (\p2) coordinate (new velocity);
    \path ($(rand, rand)!.4!(new velocity)$) coordinate (new point);
    \path (current point) node[fill=O, inner sep =3pt] {};
    \foreach \i in {50, 52, ..., 100}{%
      \draw[B!\i!WBuff]
      (current point) .. controls ++([scale=-.7]old velocity) and
      ++(new velocity) .. ++($1.6*(new point)$) coordinate (current point);
      \path (new velocity) coordinate (old velocity);      
      \path let
      \p1 = (old velocity),
      \p2 = ($(rand, rand)!.3!(-\y1, \x1)$) 
      in (\p2) coordinate (new velocity);
      \path ($(rand, rand)!.4!(new velocity)$) coordinate (new point);
    }
  \end{tikzpicture}
  \tikzexternaldisable
  \caption{A random path with control points chosen not so randomly
    composed of $45$ steps.  It uses the modifier of a coordinate
    (a vector here) \textttc{([scale=-.7]old velocity)}.}
  \label{fig:random}
\end{figure}


\begin{rem*}
  See page 928 of \emph{\tikZ\&\,PGF manual for version 3.0} fot the
  list of existing functions, section {\bfseries \emph{89.3 Syntax for
    Mathematical Expressions: Functions}}.
\end{rem*}




\section{Defining keys}

See Fig.\,\ref{fig:controls} where the key \textttc{show control point}
has been defined.  Below, we introduce some other user defined keys.



\subsection{Path modifiers}

\begin{noticeB}
  Introduced, mainly, by the syntax \verbc|insert path={...}| inside a
  style declaration.
\end{noticeB}


\begin{exa*}[variant for drawing an arc]
This is not really a key, but rather a \TeX\ command.
  
% \def\arc at#1(#2)#3(#4:#5:#6){%(center) (initial angle:final angle:radius)
%   ($(#2) +({#6*cos(#4)} ,{#6*sin(#4)})$) arc (#4:#5:#6)
% }
\def\arc at#1(#2)#3(#4:#5:#6){%(center) (initial angle:final angle:radius)
  ($(#2) +(#4: #6)$) arc (#4: #5: #6)
}
\begin{center}
  \begin{tikzpicture}
    \draw[thin, ->] (0, 0) -- (4, 0);
    \draw[thin, ->] (0, 0) -- (0, 2.5);
    \draw[B, thick, fill=B!20] (
    1, 0) -- \arc at (1, 0) (20: 80: 2) -- cycle;
    \draw[thin] (-2, 1) ellipse (2.5 and .7);
    \draw[O, ultra thick] \arc at (-2, 1) (-20: 80: 2.5 and .7); 
  \end{tikzpicture}
\end{center}
\end{exa*}

\begin{code}
  \def\arc at#1(#2)#3(#4:#5:#6){%(center) (initial angle:final angle:radius)
    ($(#2) +(#4: #6)$) arc (#4: #5: #6)
  }
\end{code}

\noindent
Note the use of \verbc|($(A)+(B)$)| instead of \verbc|(A)+(B)|, say;
there is no unintentional jump to the point \verbc|(B)| in the drawing
process.

\medskip
The same effect is obtained with the following two keys---more \tikZ\ oriented:
\begin{itemize}[nolistsep]
\item
  \verbc|c arc/.style args={#1:#2:#3}{insert path={++(#1:#3) arc (#1:#2:#3)}}|
\item
  \verbc|c-arc/.style args={#1:#2:#3}{insert path={--++(#1:#3) arc (#1:#2:#3)}}|
\end{itemize}
Note that the \verbc|-- cycle| command will not work.  The path
is broken where the arc starts for the \verbc|c arc| command, as the
notation indicates.  

\tikzset{
  c arc/.style args={#1:#2:#3}{insert path={++(#1:#3) arc (#1:#2:#3)}},
  c-arc/.style args={#1:#2:#3}{insert path={--++(#1:#3) arc (#1:#2:#3)}}
}
\begin{center}
\begin{tikzpicture}[scale=.6]
  \draw[Gold, line width=3pt] (0, 0) -- (2, 0) ++(-3, 4) [c arc=-53:30:5];
  \draw[DarkB, thin] (-2, 0) -- (2, 0) -- ++(-3, 4) [c-arc=-40:30:5];

  \draw[Gold, line width=3pt] (6, 0) -- ++(2, 0)
  ++(-3, 4) [c arc=-53:30:5] -- cycle;  
  \draw[DarkB, thin] (12, 0) -- ++(2, 0)
  -- ++(-3, 4) [c-arc=-40:30:5] -- cycle;
\end{tikzpicture}  
\end{center}


  
\begin{exa*}[streched segment]
  The key \textttc{longer} which takes two arguments, allows to draw a
  segment whose extremities are prolonged with lengths corresponding
  to the two arguments and measured in centimeters. 

\tikzset{
  longer/.style 2 args={
    shorten <= {-#1 cm}, shorten >= {-#2 cm}
  },
  point2d/.style args={#1:#2}{%
    circle, draw=K, fill=W, inner sep=1.5pt, outer sep=1.5pt, text=K,
    label={[inner sep=0pt, outer sep=1.5pt, text=K, text opacity=1,
      fill=W, fill opacity=.5]#1:#2}
  }
}
\begin{figure}[htb!]
  \centering
  \begin{tikzpicture}[show/.style={draw, circle, inner sep=2pt}]
    \draw[Gray, very thin] (-5, -3) grid (6, 2);
    
    \draw[B, thick, longer={.5}{1.5}] (-3, -1) node[show] {}
    -- ++(6, 2) node[show] {}
    node[pos=1.26, right] {\verbc|longer={.5}{1.5}|};
    
    \draw[DarkR, thick, longer={-.5}{.8}] (-3, -2) node[fill=R, show] {}
    -- ++(6, 2)  node[DarkR, pos=1.15, right] {\verb|longer={-.5}{.8}|};
    \path (-3, -2) ++(6, 2) node[point2d={-40:$E$ (added as point2d)}] {};
  \end{tikzpicture}
  \caption{Using the key \textttc{longer}.  Note that for the second
    segment, the first argument is negative..}
  \label{fig:longer}
\end{figure}

\noindent
The definition of the key uses the key \textttc{shorten <} and
\textttc{shorten <}.
\begin{code}
  longer/.style 2 args={
    shorten <= {-#1 cm}, shorten >= {-#2 cm}
  } 
\end{code}
\end{exa*}


\begin{exa*}[longitude and latitude]
The key \textttc{view} sets the longitude and latitude corresponding to the
observer's point of view and defines the unitary vector pointing
towards the point of view.

\begin{enumerate}
\item 
  The point of view is defined by the unitary vector $\wvec$ that
points towards the observer.  Its components are \verb|\tox|,
\verb|\toy|, and \verb|\toz| equal to
\begin{align*}
  \backslash\text{tox} &= x_\wvec = \sin\mu\,\cos\lambda \\
  \backslash\text{toy} &= y_\wvec = \sin\lambda \\
  \backslash\text{toz} &= z_\wvec = \cos\mu\,\cos\lambda.
\end{align*}
The angles $\mu$ and $\lambda$ represent the longitude and the
latitude, respectively---the arguments of \textttc{view}.
\item
  The screen---plane on which the image is drawn or plane of the
paper---is the plane passing through the origin and orthogonal to
$\wvec$.  The orthonormal basis that induces the coordinate system of
the screen is $(\uvec, \vvec, \wvec)$, where
\[
  \uvec = (\cos\mu, 0 , -\sin\mu),
  \qquad
  \vvec
  = (-\sin\mu\,\sin\lambda, \cos\lambda, -\cos\mu\,\sin\lambda).
\]
Note that the initial coordinate system is $Oxyz$, such that, when
$\mu=\lambda=0$, $Oz$ is horizontal and points towards the observer
and $Ox$ is horizontal and points to the right (seen by the observer).
Consequently, $\uvec$ is parallel to $Oxz$ and so,
$\lambda\neq90^\circ\mod 180^\circ$ for a 3D image---otherwise we
arrive at a 2D image representing the $Oxz$ plane.

The points $(1,0,0)$, $(0,1,0)$, and $(0,0,1)$ projects onto points
described in the global options of the drawing by
\begin{align*}
  x
  &= \big(
    \langle (1, 0, 0), \uvec \rangle, \langle (1, 0, 0), \vvec \rangle
    \big) \\
  y
  &= \big(
    \langle (0, 1, 0), \uvec \rangle, \langle (0, 1, 0), \vvec \rangle
    \big) \\
  z
  &= \big(
    \langle (0, 0, 1), \uvec \rangle, \langle (0, 0, 1), \vvec \rangle
    \big)
\end{align*}
\end{enumerate}

\begin{noticeB}
  Due to the way the \textttc{pgf}-coordinate system function, $z$
  \textbf{must be modified first}. 
\end{noticeB}
\begin{code}
\tikzset{%
  view/.style 2 args={%
    z={({-sin(#1)}, {-cos(#1)*sin(#2)})},
    x={({cos(#1)}, {-sin(#1)*sin(#2)})},
    y={(0, {cos(#2)})},
    evaluate={%
      \tox={sin(#1)*cos(#2)};
      \toy={sin(#2)};
      \toz={cos(#1)*cos(#2)};
    }
  }
}
\end{code}
We apply it to draw the cubes below.
\begin{figure}[htb!]
  \centering
  \tikzset{%
    view/.style 2 args={%
      z={({-sin(#1)}, {-cos(#1)*sin(#2)})},
      x={({cos(#1)}, {-sin(#1)*sin(#2)})},
      y={(0, {cos(#2)})},
      evaluate={%
        \tox={sin(#1)*cos(#2)};
        \toy={sin(#2)};
        \toz={cos(#1)*cos(#2)};
      }
    }
  }
  \tikzmath{
    real \a;
    \a = 1;
  }
  \begin{tikzpicture}[view={15}{21}]
    \draw[Gold, very thin, ->] (0, 0, 0) -- (3*\a, 0, 0);
    \draw[B, very thin, ->] (0, 0, 0) -- (0, 0, 3*\a);
    \draw[Gold, very thin, ->] (0, 0, 0) -- (0, 3*\a, 0);
    
    \draw[C!40, very thin] (-\a, -\a, -\a)
    -- (-\a, \a, -\a) -- (\a, \a, -\a) -- (\a, -\a, -\a) -- cycle; % z=-1
    \draw[C!40, very thin] (-\a, -\a, -\a)
    -- (-\a, \a, -\a) -- (-\a, \a, \a) -- (-\a, -\a, \a) -- cycle; % x=-1
    \fill[C, thick, opacity=.5] (-\a, -\a, \a)
    -- (-\a, \a, \a) -- (\a, \a, \a) -- (\a, -\a, \a) -- cycle; % z=1
    \fill[C, thick, opacity=.7] (\a, -\a, -\a)
    -- (\a, \a, -\a) -- (\a, \a, \a) -- (\a, -\a, \a) -- cycle; % x=1
    \fill[C, thick, opacity=.3] (-\a, \a, -\a)
    -- (\a, \a, -\a) -- (\a, \a, \a) -- (-\a, \a, \a) -- cycle; % y=1

    \draw[Gold, thin, ->] (\a, 0, 0) circle (1pt) -- (3*\a, 0, 0);
    \draw[B, thin, ->] (0, 0, \a) circle (1pt) -- (0, 0, 3*\a);
    \draw[Gold, thin, ->] (0, \a, 0) circle (1pt) -- (0, 3*\a, 0);
  \end{tikzpicture}
  \quad
  \begin{tikzpicture}[view={35}{21}]
    \draw[Gold, very thin, ->] (0, 0, 0) -- (3*\a, 0, 0);
    \draw[B, very thin, ->] (0, 0, 0) -- (0, 0, 3*\a);
    \draw[Gold, very thin, ->] (0, 0, 0) -- (0, 3*\a, 0);
    
    \draw[C!40, very thin] (-\a, -\a, -\a)
    -- (-\a, \a, -\a) -- (\a, \a, -\a) -- (\a, -\a, -\a) -- cycle; % z=-1
    \draw[C!40, very thin] (-\a, -\a, -\a)
    -- (-\a, \a, -\a) -- (-\a, \a, \a) -- (-\a, -\a, \a) -- cycle; % x=-1
    \fill[C, thick, opacity=.45] (-\a, -\a, \a)
    -- (-\a, \a, \a) -- (\a, \a, \a) -- (\a, -\a, \a) -- cycle; % z=1
    \fill[C, thick, opacity=.65] (\a, -\a, -\a)
    -- (\a, \a, -\a) -- (\a, \a, \a) -- (\a, -\a, \a) -- cycle; % x=1
    \fill[C, thick, opacity=.3] (-\a, \a, -\a)
    -- (\a, \a, -\a) -- (\a, \a, \a) -- (-\a, \a, \a) -- cycle; % y=1

    \draw[Gold, thin, ->] (\a, 0, 0) circle (1pt) -- (3*\a, 0, 0);
    \draw[B, thin, ->] (0, 0, \a) circle (1pt) -- (0, 0, 3*\a);
    \draw[Gold, thin, ->] (0, \a, 0) circle (1pt) -- (0, 3*\a, 0);
  \end{tikzpicture}
  \quad
    \begin{tikzpicture}[view={55}{21}]
    \draw[Gold, very thin, ->] (0, 0, 0) -- (3*\a, 0, 0);
    \draw[B, very thin, ->] (0, 0, 0) -- (0, 0, 3*\a);
    \draw[Gold, very thin, ->] (0, 0, 0) -- (0, 3*\a, 0);
    
    \draw[C!40, very thin] (-\a, -\a, -\a)
    -- (-\a, \a, -\a) -- (\a, \a, -\a) -- (\a, -\a, -\a) -- cycle; % z=-1
    \draw[C!40, very thin] (-\a, -\a, -\a)
    -- (-\a, \a, -\a) -- (-\a, \a, \a) -- (-\a, -\a, \a) -- cycle; % x=-1
    \fill[C, thick, opacity=.4] (-\a, -\a, \a)
    -- (-\a, \a, \a) -- (\a, \a, \a) -- (\a, -\a, \a) -- cycle; % z=1
    \fill[C, thick, opacity=.6] (\a, -\a, -\a)
    -- (\a, \a, -\a) -- (\a, \a, \a) -- (\a, -\a, \a) -- cycle; % x=1
    \fill[C, thick, opacity=.3] (-\a, \a, -\a)
    -- (\a, \a, -\a) -- (\a, \a, \a) -- (-\a, \a, \a) -- cycle; % y=1

    \draw[Gold, thin, ->] (\a, 0, 0) circle (1pt) -- (3*\a, 0, 0);
    \draw[B, thin, ->] (0, 0, \a) circle (1pt) -- (0, 0, 3*\a);
    \draw[Gold, thin, ->] (0, \a, 0) circle (1pt) -- (0, 3*\a, 0);
  \end{tikzpicture}
  \caption{Using the key \textttc{view}.  The latitude equals 21 and the
    longitude equals 15, 35, and 55, respectively.  The axis $Oz$ is
    represented in blue.}
  \label{fig:cube}
\end{figure}
\end{exa*}


\begin{exa*}[circle through three points]
This key draws the circumscribed circle to a given triangle, \ie the
unique circle through three non aligned points.  As a side effect, it
stores the center as (the point) \verbc|ccenter|.

\tikzset{%
  circle through/.style args={#1,#2,#3}{%
    insert path={let 
      \p1 = ($(#1)!0.5!(#2)$),
      \p2 = ($(#1)!0.5!(#3)$),
      \p3 = ($(#1)!0.5!(#2)!1!90:(#2)$),
      \p4 = ($(#1)!0.5!(#3)!1!-90:(#3)$),
      \p5 = (intersection of \p1--\p3 and \p2--\p4),
      \p6 = (#1),
      \n5 = {veclen(\x5-\x6, \y5-\y6)}
      in
      (\p5) coordinate (ccenter) circle ({veclen(\x5-\x6, \y5-\y6)})
    }
  }
}
\begin{tikzpicture}
  \coordinate (A) at (-1, 1);
  \coordinate (B) at (0, 2);
  \coordinate (C) at (3, 1.5);
  \draw[B, thin] (A) -- (B) -- (C) -- cycle;
  \draw[R, thick, circle through={A, B, C}] {};
  \foreach \i/\position in {A/left, B/above, C/above right}{%
    \filldraw[B] (\i) circle (2pt) node[\position] {$\i$};
  }
  \filldraw[R] (ccenter) circle (2pt) node[below] {$\Omega$};

  \path (5, 1) node[below right, text width=7cm]
  {The circle is firstly drawn, the center being placed
    afterward.  The construction is based on the fact that the center
    is the intersection of two edge bisectors.};
\end{tikzpicture}
\end{exa*}



\subsection{Path modifiers II}

The path operation \verbc|to| inserts the path via the \verbc|to path|
option at the current position.  Options can be used to modify
(perhaps implicitly) the \verbc|to path| and to set up how the path
will be rendered.

Before the \verbc|to path| is inserted, a number of macros are set up
that can be used to modify or ``decorate'' the \verbc|to path|.  These
are \verbc|\tikztostart|, \verbc|\tikztotarget|, and
\verbc|\tikztonodes|.

\begin{figure}[htb!]
  \centering
  \tikzset{%
    what length/.style={%
      to path={%
        -- (\tikztotarget)
        let
        \p1 = ($(\tikztostart) -(\tikztotarget)$),
        \n1 = {veclen(\x1, \y1)*1pt/1cm},
        \n2 = {\strippt(\n1)}
        in node[pos=.5, above, sloped] {\n2}
        \tikztonodes
      }
    },
    windy/.style={%
      to path={%
        let
        \p1 = (\tikztostart),
        \p2 = (\tikztotarget),
        \p{12} = ($(\p2) -(\p1)$),
        \n1 = {veclen(\x{12}, \y{12})},      
        \n{12} = {atan2(\y{12}, \x{12})},
        \p3 = (\n{12} -20: \n1/3),
        \p4 = (\n{12} +220: \n1/3),      
        in .. controls +(\p3)  and +(\p4) .. (\tikztotarget)
        \tikztonodes
      }
    }  
  }
  \begin{tikzpicture}[scale=.8, every node/.style={scale=.8}]
    \draw[Gray] (-1, -2) grid ++(10, 5);
    \draw[B, thick]
    (0, 0) to[what length] ++(3, 2) to[what length]
    ++(2.4, 0) to[what length] ++(3, -3);
    
    \foreach \a [evaluate=\a as \b using \a/5]
    in {0, 40, ..., 320}{%
      \draw[M!\b!B] (14, .5) to[windy] ++(\a: 3);
    }
  \end{tikzpicture}
  \caption{The use of {\color{B}\textbackslash tikztostart} and of
  {\color{B}\textbackslash tikztotarget} to ``modify'' the default
  \textc{line-to} command.  In the left drawing, the modified
  \textc{line-to} command computes the length of the segment.  Now, 
  the right drawing might have been easier
  obtained directly, without passing though the modification of the
  \textc{line-to} command.}
  \label{fig:tikztostart}
\end{figure}


\begin{exa*}[Multiple edges between nodes]
  We define the style \verbc|LR translation| which create an edge
  parallel to the default one at a certain distance (given as an
  argument in \emph{ex} units of length.
  
\centering
\tikzset{%
  LR translation/.style={%  Left or Right in ex units
    auto=right, arrows={-Latex[width=1.5ex]},
    to path={%
      let
      \p1 = (\tikztostart),
      \p2 = (\tikztotarget),
      \n1 = {atan2(\y2-\y1, \x2-\x1)},
      \n2 = {\n1+180}
      in ($(\tikztostart.{\n1})!{#1 ex}!270:(\tikztotarget.{\n2})$)
      -- ($(\tikztotarget.{\n2})!{#1 ex}!90:(\tikztostart.{\n1})$)
      \tikztonodes
    }
  }
}
\begin{tikzpicture}[tmp/.style={
    circle, draw, outer sep=1ex, inner sep=2ex},
  node distance=1cm and 2cm]
  \node[tmp](a) {$a$};
  \node[tmp, right=of a] (b) {$b$};  
  \node[tmp, above=of b] (c) {$c$};
  \path
  (a) edge[LR translation=1] node {$\alpha$} (b)  
  (b) edge[LR translation=1] node {$\beta$} (a);  
  \draw
  (b) edge[LR translation=1] node {$\lambda$} (c)  
  (b) edge[LR translation=-1] node[left] {$\mu$} (c);
\end{tikzpicture}
\end{exa*}

\begin{code}
  LR translation/.style={%  Left or Right in ex units
    auto=right, arrows={-Latex[width=1.5ex]},
    to path={%
      let
      \p1 = (\tikztostart),
      \p2 = (\tikztotarget),
      \n1 = {atan2(\y2-\y1, \x2-\x1)},
      \n2 = {\n1+180}
      in ($(\tikztostart.{\n1})!{#1 ex}!270:(\tikztotarget.{\n2})$)
      -- ($(\tikztotarget.{\n2})!{#1 ex}!90:(\tikztostart.{\n1})$)
      \tikztonodes
    }...
\end{code}




\appendix
\section{Various examples}

\subsection{The construction of an equilateral triangle when the
  circumcircle and a vertex are given}

  \begin{figure}[htb!]
    \centering
    \tikzmath{%
      real \R, \r;
      \R = 2.4;
      \r = \R*.5;
    }
    \begin{tikzpicture}[rotate=-10]
      \path
      (0, 0) coordinate (O)
      (\R, 0) coordinate (A);

      \draw[name path=given circle] (O) circle (\R);
      \draw[B, name path=first] (A) circle (\r);
      \path[name intersections={of=given circle and first, by={I, J}}];
      \draw[B, name path=second] (I) circle (\r);
      \path[name intersections={of=first and second, by={E, F}}];
      \path ($(J)!.5!(F)$) coordinate (M);
      \draw[R, thin] (J) -- (F);
      \draw[B, name path=line] (A) -- ($(A)!6!(M)$);
      \path[name intersections={of=given circle and line, by={B, A'}}];
      \draw[Gold, very thick] (A) -- (B) -- (120: \R) -- cycle;
      
      \foreach \P in {I, J, E, F, M, B}{%
        \draw[B, fill=white] (\P) circle (1.5pt);
      }
      \draw[fill=black] (A) circle (1.5pt) node[below right] {$A$};
    \end{tikzpicture}
    \caption{The construction of an equilateral triangle when the
  circumcircle and a vertex are given (drawn in black).  It is based
  on the geometrical property described in Fig.\,\ref{fig:60}.}
\label{fig:euclidea}
  \end{figure}


The construction is based on the following fact.  Consider the
configuration in Fig.\,\ref{fig:60}.  The two circles centered in at
$A$ and $J$ have the same radius and intersect at $E$ and $F$---the
triangles $[AJE]$ and $[AJF]$ are equilateral.  The arbitrary point
$I$ belongs to the circle of center $A$.  If the points $M$ and $N$
bisects the segments $[EI]$ and $[FI]$ respectively, then the
measure of the angle $MAN$ is either $60^\circ$ or
$120^\circ$---since the points $A$, $M$, $N$, and $I$ determine an
inscribed quadrilateral.
\begin{figure}[htb!]
  \centering
  \tikzmath{%
    real \a, \r;
    \a = -65; 
    \r = 2.5;
  }
  \begin{tikzpicture}[every node/.style={scale=.9}]
    \clip (-2*\r, 1.3*\r) rectangle (2*\r, -1.2*\r);
    \path (0, 0) coordinate (A);
    \path (\a: \r) coordinate (I);
    \path (90: \r) coordinate (J);
    \draw[B, name path=circle_A] (A) circle (\r);
    \draw[B, name path=circle_J] (J) circle (\r);
    \path[name intersections={of=circle_A and circle_J, by={E, F}}];
    \draw[Gray!70, very thin] (A) -- (J) -- (E) -- cycle;
    \draw[Gray!70, very thin] (A) -- (J) -- (F) -- cycle;

    \draw[R, thin] (I) -- (E) ($(E)!.5!(I)$) coordinate (M);
    \draw[Gold, very thick] (A) -- ($(A)!1.8!(M)$);
    \draw[R, thin] (I) -- (F) ($(F)!.5!(I)$) coordinate (N);
    \draw[Gold, very thick] (A) -- ($(A)!4!(N)$);
    \draw[Gold, very thick, dashed] (A) -- ($(A)!-4!(N)$);

    \foreach \P/\pos in {A/above left, I/below, J/above left, E/right,
      F/left, M/below right, N/left%
    }{%
      \draw[fill=white] (\P) circle (1.5pt) node[circle, \pos] {$\P$};
    }
  \end{tikzpicture}
  \caption{The golden lines are perpendicular on
    $(EI)$ and $(FI)$ respectively; they subtend an angle of
    $60^\circ$ or $120^\circ$. 
  }
  \label{fig:60}
\end{figure}




\subsection{Dandelin's spheres for a hyperbola defined as a conic
  section}


The point of view is given by the unitary vector pointing toward the
observer defined by the angles $\phi$ (longitude) and $\theta$
(latitude) in the coordinate system $Ozxy$.  Almost all computations
are performed in the coordinate plane $z=0$.
\begin{itemize}
\item
  The cone is defined by the equation $y^2=b^2(x^2+z^2)$, $b>0$.
\item
  The plane of the hyperbola is defined by $ax+y=c$ with $a>b$ and
  $c>0$.  The vertices of the hyperbola are defined in the plane $z=0$
  by the intersections
  \[
    ax+y=c \textq{and} y = bx,
    \textq{\ie} V_+ = \bigg(\frac{c}{a+b}, \frac{bc}{a+b}\bigg)
  \]
  and
  \[
    ax+y=c \textq{and} y = -bx,
    \textq{\ie} V_- = \bigg(\frac{c}{a-b}, \frac{bc}{a-b}\bigg).
  \]
\item
  The Dandelin spheres are centered at $\Omega_\pm$ and have radii
  $r_\pm$.  Solving a distance problem, we obtain
  \[
    \Omega_\pm
    = \bigg( 0,
    \pm\frac{c\sqrt{b^2+1}}{\sqrt{a^2+1}\pm\sqrt{b^2+1}}
    \bigg) 
    \textq{and}
    r_\pm = \frac{c}{\sqrt{a^2+1}\pm\sqrt{b^2+1}}.
  \]
\item
  In the plane $ax+y=c$, the hyperbola is defined by the equation
  \[
    \frac{
      \bigg(y+\dfrac{b^2c}{a^2-b^2}\bigg)^2
    }{
      \bigg(\dfrac{abc}{a^2-b^2}\bigg)^2
    }
    - \frac{z^2}{
      \bigg(\dfrac{c}{\sqrt{a^2-b^2}}\bigg)^2
    }
    = 1.
  \]
  (So we can use parametrizations in $\cosh$ and $\sinh$ to represent
  it graphically.)
\item
  To determine the tangency circles of the spheres and the cone, two
  points are sufficient.  They are granted by the distance problem
  solved previously.  The same raisonning gives the hyperbola's foci.
  Setting
  \[
    h_\pm = \frac{c\sqrt{b^2+1}}{\sqrt{a^2+1}\pm\sqrt{b^2+1}} > 0,
  \]
  we have
  \[
    Q_\pm = \bigg(
    \frac{bh_\pm}{b^2+1}, \pm\frac{b^2h_\pm}{b^2+1}
    \bigg)
    \textqq{and}
    F_\pm = \bigg(
    \frac{a(c\mp h_\pm)}{a^2+1}, \frac{c\pm a^2h_\pm}{a^2+1}
    \bigg).
  \]
\end{itemize}


\begin{figure}[htb!]
  \centering
  % \includegraphics[height=9cm]{fig_dandelin.pdf}
\tikzmath{
  real \longit, \latit, \tox, \toy, \toz;
  real \newxx, \newxy, \newyx, \newyy, \newzx, \newzy;  
  \longit = 19;
  \latit = 17;
  \tox = sin(\longit)*cos(\latit);
  \toy = sin(\latit);
  \toz = cos(\longit)*cos(\latit);
  \newxx = cos(\longit); \newxy = -sin(\longit)*sin(\latit);
  \newyy = cos(\latit);
  \newzx = -sin(\longit); \newzy = -cos(\longit)*sin(\latit);
  integer \Sy, \Sz, \prevj, \prevk;  % for a sphere
  real \a, \b, \c, \h{+}, \r{+}, \h{-}, \r{-};
  real \Qx{+}, \Qy{+}, \Qx{-}, \Qy{-}, \Fx{+}, \Fy{+}, \Fx{-}, \Fy{-};
  real \Ha, \Hb;
  \a = 5.;
  \b = 1.4;
  \c = 7.;
  \r{+} = \c/(sqrt(\a^2+1)+sqrt(\b^2+1));
  \h{+} = \r{+}*sqrt(\b^2+1);
  \r{-} = \c/(sqrt(\a^2+1)-sqrt(\b^2+1));
  \h{-} = \r{-}*sqrt(\b^2+1);
  \Qx{+} = \b*\h{+}/(\b^2+1);
  \Qy{+} = \b*\Qx{+};
  \Qx{-} = \b*\h{-}/(\b^2+1);
  \Qy{-} = -\b*\Qx{-};
  \Fx{+} = \a*(\c-\h{+})/(\a^2+1);
  \Fy{+} = (\c+\a^2*\h{+})/(\a^2+1);
  \Fx{-} = \a*(\c+\h{-})/(\a^2+1);
  \Fy{-} = (\c-\a^2*\h{-})/(\a^2+1);
  \Ha = \a/(\a^2-\b^2)*\b*\c;
  \Hb = \c/sqrt(\a^2-\b^2);
  \y0 = \b^2*\c/(\a^2-\b^2);
  \Sy = 20;  % 36;
  \Sz = 20;  % 36;
  function Sx(\j, \k) {
    return cos(360*(\k/\Sz))*cos(360*(\j/\Sy));
  };
  function Sy(\j, \k) {
    return sin(360*(\k/\Sz));
  };
  function Sz(\j, \k) {
    return cos(360*(\k/\Sz))*sin(360*(\j/\Sy));
  };
  function isSeen(\j, \k) {
    let \res = Sx(\j,\k)*\tox + Sy(\j,\k)*\toy + Sz(\j,\k)*\toz;
    if \res>0 then {return .9;} else {return .4;};
  };
  function Hycrd(\ha, \t, \y0) {
    return \ha*cosh(\t) + \y0;
  };
  function Hzcrd(\ha, \t) {
    return \ha*sinh(\t);
  };
  function Hxcrd(\ha, \t, \y0) {
    return (\c-\ha*cosh(\t)-\y0)/\a;
  };
}
\tikzexternalenable
\begin{tikzpicture}[every node/.style={scale=.8},
  z={(\newzx cm, \newzy cm)},
  x={(\newxx cm, \newxy cm)},
  y={(0 cm, \newyy cm)}
  ]

  % \draw[O, -{Latex[length=5pt, width=5pt]}]
  % (0, 0, 0) -- (5, 0, 0) node[right] {$x$};
  % \draw[O, -{Latex[length=5pt, width=5pt]}]
  % (0, -6, 0) -- (0, 5, 0) node[above] {$y$}; 
  % \draw[O, -{Latex[length=5pt, width=5pt]}]
  % (0, 0, 0) -- (0, 0, 5) node[below left] {$z$};

  %%% upper sphere
  % longitude circles
  \foreach \j in {4, 8, ..., \Sy}{%
    \foreach \k [remember=\k as \prevk (initially 0)] in {1, ..., \Sz}{
      \draw[BK!70, opacity={isSeen(\j, \k)},
      shift={(0, \h{+}, 0)}, scale=\r{+}]
      ({Sx(\j,\prevk)}, {Sy(\j,\prevk)}, {Sz(\j,\prevk)})
      -- ({Sx(\j,\k)}, {Sy(\j,\k)}, {Sz(\j,\k)});
    }
  }
  % latitude circles
  \foreach \k in {4, 8, ..., \Sz}{%
    \foreach \j [remember=\j as \prevj (initially 0)] in {1, ..., \Sy}{%
      \draw[BK!70, opacity={isSeen(\j, \k)},
      shift={(0, \h{+}, 0)}, scale=\r{+}]
      ({Sx(\prevj,\k)}, {Sy(\prevj,\k)}, {Sz(\prevj,\k)})
      -- ({Sx(\j,\k)}, {Sy(\j,\k)}, {Sz(\j,\k)});
    }
  }
  % tangency circle
  \foreach \j [remember=\j as \prevj (initially 0)] in {1, ..., \Sy}{%
    \draw[R, thick, shift={(0, \Qy{+}, 0)}, scale=\Qx{+}]
    ($({cos(360/\Sy*\prevj)}, 0, {sin(360/\Sy*\prevj)})$)
    -- ($({cos(360/\Sy*\j)}, 0, {sin(360/\Sy*\j)})$);
  }

  %%% lower sphere
  % longitude circles
  \foreach \j in {4, 8, ..., \Sy}{%
    \foreach \k [remember=\k as \prevk (initially 0)] in {1, ..., \Sz}{
      \draw[BK!70, opacity={isSeen(\j, \k)},
      shift={(0, -\h{-}, 0)}, scale=\r{-}]
      ({Sx(\j,\prevk)}, {Sy(\j,\prevk)}, {Sz(\j,\prevk)})
      -- ({Sx(\j,\k)}, {Sy(\j,\k)}, {Sz(\j,\k)});
    }
  }
  % latitude circles
  \foreach \k in {4, 8, ..., \Sz}{%
    \foreach \j [remember=\j as \prevj (initially 0)] in {1, ..., \Sy}{%
      \draw[BK!70, opacity={isSeen(\j, \k)},
      shift={(0, -\h{-}, 0)}, scale=\r{-}]
      ({Sx(\prevj,\k)}, {Sy(\prevj,\k)}, {Sz(\prevj,\k)})
      -- ({Sx(\j,\k)}, {Sy(\j,\k)}, {Sz(\j,\k)});
    }
  }
  % tangency circle
  \foreach \j [remember=\j as \prevj (initially 0)] in {1, ..., \Sy}{%
    \draw[R, thick, shift={(0, \Qy{-}, 0)}, scale=\Qx{-}]
    ($({cos(360/\Sy*\prevj)}, 0, {sin(360/\Sy*\prevj)})$)
    -- ($({cos(360/\Sy*\j)}, 0, {sin(360/\Sy*\j)})$);
  }
  
  % points... foci 
  \draw[fill=white] (\Qx{+}, \Qy{+}, 0) circle (1pt);
  \draw[fill=white] (\Qx{-}, \Qy{-}, 0) circle (1pt);
  \filldraw[R] (\Fx{+}, \Fy{+}, 0) circle (1pt);
  \filldraw[R] (\Fx{-}, \Fy{-}, 0) circle (1pt) node[right] {$F_-$};

  \filldraw[G] ($({\c/(\a+\b)}, {\b*\c/(\a+\b)}, 0)$) circle (1pt)
  node[right] {vertex} ; 

  %%% hyperbola
  % upper branch
  \tikzmath{ real \ct;  \ct = .9; }
  \fill[B!80, opacity=.3]
  ({Hxcrd(\Ha,-2*\ct,-\y0)}, {Hycrd(\Ha,-2*\ct,-\y0)}, {Hzcrd(\Hb,-2*\ct)})
  \foreach \t [evaluate=\t as \mt using \ct*\t] in {-1.9, -1.8, ..., 2}{%
    -- ({Hxcrd(\Ha,\mt,-\y0)}, {Hycrd(\Ha,\mt,-\y0)}, {Hzcrd(\Hb,\mt)})
  } -- cycle;
  \foreach \t [remember=\t as \prevt (initially -2)]
  in {-1.9, -1.8, ..., 2}{%
    \draw[DarkB, rounded corners]
    ({Hxcrd(\Ha,\ct*\t,-\y0)}, {Hycrd(\Ha,\ct*\t,-\y0)}, {Hzcrd(\Hb,\ct*\t)})
    -- ({Hxcrd(\Ha,\ct*\prevt,-\y0)}, {Hycrd(\Ha,\ct*\prevt,-\y0)},
    {Hzcrd(\Hb,\ct*\prevt)});
  }
  % lower branch
  \tikzmath{ real \ct;  \ct = .8; }  
  \fill[B!80, opacity=.3]
  ({Hxcrd(-\Ha,-2*\ct,-\y0)}, {Hycrd(-\Ha,-2*\ct,-\y0)}, {Hzcrd(\Hb,-2*\ct)})
  \foreach \t [evaluate=\t as \mt using \ct*\t] in {-1.9, -1.8, ..., 2}{%
    -- ({Hxcrd(-\Ha,\mt,-\y0)}, {Hycrd(-\Ha,\mt,-\y0)}, {Hzcrd(\Hb,\mt)})
  } -- cycle;  
  \foreach \t [remember=\t as \prevt (initially -2)]
  in {-1.9, -1.8, ..., 2}{%
    \draw[DarkB, rounded corners]
    ({Hxcrd(-\Ha,\ct*\t,-\y0)}, {Hycrd(-\Ha,\ct*\t,-\y0)}, {Hzcrd(\Hb,\ct*\t)})
    -- ({Hxcrd(-\Ha,\ct*\prevt,-\y0)}, {Hycrd(-\Ha,\ct*\prevt,-\y0)},
    {Hzcrd(\Hb,\ct*\prevt)});
  }

  % upper and lower bases of the cone
  \foreach \j [remember=\j as \prevj (initially 0)] in {1, ..., \Sy}{%
    \draw[BK, thick, shift={(0, 6., 0)}, scale=6.]
    ($({cos(360/\Sy*\prevj)/\b}, 0, {sin(360/\Sy*\prevj)/\b})$)
    -- ($({cos(360/\Sy*\j)/\b}, 0, {sin(360/\Sy*\j)/\b})$);
    \draw[BK, thick,
    opacity={isSeen(\j, 0)}, shift={(0, -6., 0)}, scale=6.]
    ($({cos(360/\Sy*\prevj)/\b}, 0, {sin(360/\Sy*\prevj)/\b})$)
    -- ($({cos(360/\Sy*\j)/\b}, 0, {sin(360/\Sy*\j)/\b})$);
  }

  % the cone
  \tikzmath{ real \tmp;  \tmp=7; }  % final tuning of cone's generatrices 
  \draw[BK, very thin] % upper left to lower right
  ($({-6*cos(\longit+\tmp)/\b}, 6, {6*sin(\longit+\tmp)/\b})$)
  -- ($({6*cos(\longit+\tmp)/\b}, -6, {-6*sin(\longit+\tmp)/\b})$);
  \draw[BK, very thin]
  ($({6*cos(\longit-\tmp)/\b}, 6, {-6*sin(\longit-\tmp)/\b})$)
  -- ($({-6*cos(\longit-\tmp)/\b}, -6, {6*sin(\longit-\tmp)/\b})$);
\end{tikzpicture}
\tikzexternaldisable
  \caption{Dandelin's spheres of a hyperbola}
  \label{fig:dandelin}
\end{figure}


\begin{rem*}
  The code is commented (see below in the file); it uses constants and
  functions defined in a \textttc{tikzmath} environment, and the 3D view
  given by latitude and longitude angles introduced with respect to
  the $Ozxy$ coordinate system.
  The image in Fig.\,\ref{fig:dandelin} is included form a
  \textttc{standalone} file. 
\end{rem*}




\subsection{Torus in the light}

Using the same elements introduced to draw Dandelin's spheres, and
adding the shade (computed by projection), we get the torus below, see
Fig.\,\ref{fig:torus}.  Note that the coordinate axes are shadowless.

\begin{code}
   function isSeen(\j, \k) {
    let \px = cos(360*(\k/\Nz))*cos(360*(\j/\Ny));
    let \py = -sin(360*(\k/\Nz));
    let \pz = cos(360*(\k/\Nz))*sin(360*(\j/\Ny));
    let \res = \px*\tox + \py*\toy + \pz*\toz;
    if \res>0 then {return 1;} else {return 0;};
  };
\end{code}

\begin{code}
  function inLight(\j, \k) {%  dot product of the normal vector with
                            %  the sun vector
    let \px = cos(360*(\k/\Nz))*cos(360*(\j/\Ny));
    let \py = -sin(360*(\k/\Nz));
    let \pz = cos(360*(\k/\Nz))*sin(360*(\j/\Ny));
    return {\px*\sunx + \py*\suny + \pz*\sunz};
  };  
\end{code}
% \begin{center}
%   \includegraphics[width=.7\textwidth]{fig_torusLight.pdf}
% \end{center}
\begin{figure}[htb!]
\tikzmath{%
  real \slongit, \slatit, \sunx, \suny, \sunz;  % towards the light source 
  real \longit, \latit, \tox, \toy, \toz;
  real \newxx, \newxy, \newyx, \newyy, \newzx, \newzy;  
  \slongit = 100; \slatit = 45;
  \sunx = sin(\slongit)*cos(\slatit);
  \suny = sin(\slatit);
  \sunz = cos(\slongit)*cos(\slatit);
  \longit = 25;  \latit = 36;  % 35;
  \tox = sin(\longit)*cos(\latit);
  \toy = sin(\latit);
  \toz = cos(\longit)*cos(\latit);
  \newxx = cos(\longit); \newxy = -sin(\longit)*sin(\latit);
  \newyy = cos(\latit);
  \newzx = -sin(\longit); \newzy = -cos(\longit)*sin(\latit);
  real \ry, \rz;
  \ry = 4;
  \rz = 1.5;  
  integer \Ny, \Nz, \j, \k, \prevj, \prevk, \aj, \ak;
  % j moves around Oy and k moves around Oz.
  % They describe full circles of radii \ry and \rz respectively.
  \Nz = 48;  % 24;  % 60;
  \Ny = 80;  % 36;  % 120;
  \ktmp = \Nz-1; 
  \jtmp = \Ny-1;
  \aj = 10;
  \ak = 0;
  function isSeen(\j, \k) {
    let \px = cos(360*(\k/\Nz))*cos(360*(\j/\Ny));
    let \py = -sin(360*(\k/\Nz));
    let \pz = cos(360*(\k/\Nz))*sin(360*(\j/\Ny));
    let \res = \px*\tox + \py*\toy + \pz*\toz;
    if \res>0 then {return 1;} else {return 0;};
  };
  function inLight(\j, \k) {%  dot product of the normal vector with
                            %  the sun vector
    let \px = cos(360*(\k/\Nz))*cos(360*(\j/\Ny));
    let \py = -sin(360*(\k/\Nz));
    let \pz = cos(360*(\k/\Nz))*sin(360*(\j/\Ny));
    return {\px*\sunx + \py*\suny + \pz*\sunz};
  };
  function T(\j, \k) {%
    let \py = -\rz*sin(360*(\k/\Nz));
    let \pz = \ry+\rz*cos(360*(\k/\Nz))*sin(360*(\j/\Ny));
    return {\rz*(-1+sin(360*(\k/\Nz)))/\suny};
  };
}
\tikzexternalenable
\begin{tikzpicture}[every node/.style={scale=.8},
  z={(\newzx cm, \newzy cm)},
  x={(\newxx cm, \newxy cm)},
  y={(0 cm, \newyy cm)},
  evaluate={% highlights and darkest darks; note that the highlights
            % depend on the observer's position (\tox, \toy, \toz)
    real \tmp;
    for \j in {0, 1, ..., \Ny}{%
      for \k in {0, 1, ..., \Nz}{%
        \test{\j,\k} = isSeen(\j, \k);
        if \test{\j,\k}>0 then {%
          \tmp{\j,\k} = int(100*inLight(\j,\k)));
          if \tmp{\j,\k}>0 then {%
            \tmpW{\j,\k}=int(100*inLight(\j,\k)^2);
          }
          else {%
            \tmpK{\j,\k}=-int(100*inLight(\j,\k));
          };
        } else {};
      };
    };
  }]

  % points (P-\j-\k)
  \foreach \j in {0, ..., \Ny}{%
    \foreach \k in {0, ..., \Nz}{%
      \path
      ( {( \ry+\rz*cos(360*(\k/\Nz)) )*cos(360*(\j/\Ny))},
      {-\rz*sin(360*(\k/\Nz))},
      {( \ry+\rz*cos(360*(\k/\Nz)) )*sin(360*(\j/\Ny))} )
      coordinate (P-\j-\k);
    }
  }

  % shadow
  \foreach \k [remember=\k as \prevk (initially 0)] in {1, ..., \Nz}{%
    \foreach \j [remember=\j as \prevj (initially 0)] in {1, ..., \Ny}{%
      \fill[gray!70!black, opacity={.4*abs(inLight(\j,\k))}]
      ($(P-\j-\prevk)+T(\j,\prevk)*(\sunx, \suny, \sunz)$)
      -- ($(P-\prevj-\prevk)+T(\prevj,\prevk)*(\sunx, \suny, \sunz)$)
      -- ($(P-\prevj-\k)+T(\prevj,\k)*(\sunx, \suny, \sunz)$)
      -- ($(P-\j-\k)+T(\j,\k)*(\sunx, \suny, \sunz)$) -- cycle;
    }
  }
  
  % coordinate system $Oxyz$; first layer
  \draw[green!50!black]
  (0, 0, 0) -- (\ry, 0, 0)
  (0, 0, 0) -- (0, 0, \ry);

  % "squares"---the mesh
  \foreach \k [remember=\k as \prevk (initially 0)] in {1, ..., \Nz}{%
    \foreach \j [remember=\j as \prevj (initially 0)] in {1, ..., \Ny}{%
      \ifthenelse{\test{\j,\k}=1}{
        \ifthenelse{\tmp{\j,\k}>0}{
          \filldraw[white!\tmpW{\j,\k}!B]
          (P-\j-\prevk) -- (P-\prevj-\prevk)
          -- (P-\prevj-\k) --(P-\j-\k) -- cycle;
        }{%
          \filldraw[black!\tmpK{\j,\k}!B]
          (P-\j-\prevk) -- (P-\prevj-\prevk)
          -- (P-\prevj-\k) --(P-\j-\k) -- cycle;
        }
      }{}
    }
  }

  % longitude cycle
  \foreach \k [remember=\k as \prevk (initially 0)] in {1, ..., \Nz}{%
    \ifthenelse{\test{\aj,\k}=1}{
      \draw[red, thick] (P-\aj-\k) -- (P-\aj-\prevk);
    }{
      \draw[red, very thin, opacity=.4] (P-\aj-\k) -- (P-\aj-\prevk);
    }
  }

  % latitude cycle
  \foreach \j [remember=\j as \prevj (initially 0)] in {1, ..., \Ny}{%
    \ifthenelse{\test{\j,\ak}=1}{
      \draw[red, thick] (P-\j-\ak) -- (P-\prevj-\ak);
    }{
      \draw[red, very thin, opacity=.3] (P-\j-\ak) -- (P-\prevj-\ak);
    }
  }
  
  % coordinate system $Oxyz$; second layer
  \draw[green!50!black, -{Latex[length=5pt, width=5pt]}]
  (\ry+\rz, 0, 0) -- (8, 0, 0) node[right] {$x$};
  \draw[green!50!black, -{Latex[length=5pt, width=5pt]}]
  (0, 0, 0) -- (0, 6, 0) node[above] {$y$};
  \draw[green!50!black, -{Latex[length=5pt, width=5pt]}]
  (0, 0, \ry+\rz) -- (0, 0, 8) node[below left] {$z$};
\end{tikzpicture}
\tikzexternaldisable
  \caption{Torus in the light}
  \label{fig:torus}
\end{figure}




\subsection{Penrose triangle}

The Penrose triangle is an \emph{optical illusion} consisting of an
object which can be depicted in a perspective drawing, but cannot
exist as a solid object.  It was first created by the Swedish artist
Oscar Reutersv\"ard in 1934.

There also exist three-dimensional solid shapes each of which, when
viewed from a certain angle, appears the same as the $2$-dimensional
depiction of the Penrose triangle (see Fig.\,\ref{fig:penrose}).  The
term \emph{Penrose triangle} can refer to the $2$-dimensional
depiction or the impossible object itself.


\begin{rem*}
  If a line is traced ``around'' the Penrose triangle, a $4$-loop
M\"obius strip is formed.  I don't really understand this claim.  I
would say that the exterior surface that is seen forms a M\"obius
strip.  
\end{rem*}
 

\begin{figure}[htb!]
  \centering
  \tikzmath{
    real \mainL, \d, \edge;
    \mainL = 5;
    \d = 1.;
    \edge = \mainL*sqrt(3)-2*\d;
  }
  \tikzset{
    penroseB/.pic={
      \draw[color=#1, fill=#1] ($(-30:\mainL)+(120:\d)$)
      -- ++(120:\edge) -- ++(-\d,0)
      -- ++(-60:\edge-\d) -- ++(-\edge+3*\d,0)
      -- ++(240:\d) -- cycle;
    }
  }
  \begin{tikzpicture}
    \path (0,0) pic[rotate=0] {penroseB={BG!90!Gray}};
    \path (0,0) pic[rotate=120] {penroseB={BG!70}};
    \path (0,0) pic[rotate=240] {penroseB={BG!70!black}};
  \end{tikzpicture}
  \qquad
  \begin{tikzpicture}[scale=.8]
    \draw[Gray, thin] (-30:\mainL) coordinate (A)
    -- (0,\mainL) coordinate (B)
    -- (210:\mainL) coordinate (C) -- cycle;
    \draw[Gray, thin] ($(A)+(120:\d)$) -- ($(C)+(60:\d)$);
    \draw[Gray, thin] ($(A)+(120:2*\d)$) -- ($(C)+(60:2*\d)$);

    \draw[Gray, thin] ($(B)+(240:\d)$) -- ($(A)+(0:-\d)$);
    \draw[Gray, thin] ($(B)+(240:2*\d)$) -- ($(A)+(0:-2*\d)$);
    
    \draw[Gray, thin] ($(C)+(0:\d)$) -- ($(B)+(-60:\d)$);
    \draw[Gray, thin] ($(C)+(0:2*\d)$) -- ($(B)+(-60:2*\d)$);

    \draw[R] ($(C)+(1pt,-1pt)$) -- ++(0:\edge) -- ++(120:\edge) -- cycle;

    \fill[fill=BG!90!Gray, opacity=.7] ($(-30:\mainL)+(120:\d)$)
    -- ++(120:\edge) -- ++(-\d,0)
    -- ++(-60:\edge-\d) -- ++(-\edge+3*\d,0)
    -- ++(240:\d) -- cycle;

    \draw[R, fill=R] (0,0) circle (2pt) node[above left] {$O$};
\end{tikzpicture}
  
  \caption{The construction of the Penrose triangle: the triangle is
    constructed by performing on the turquoise element (the right
    drawing),
    two rotations of $60$ and $120$ degrees respectively, centered at
    $O$.  The red triangle can be seen as the building brick of the
    whole figure.} 
  \label{fig:penrose}
\end{figure}




\section{Drawing a path of varying width}

This is based on Alain Matthes's idea; see his answer at\\
\url{https://tex.stackexchange.com/questions/14283/stroke-with-variable-thickness}
\begin{code}
\pgfkeys{/pgf/decoration/.cd,
  width factor/.store in =\wfactor,
  start color/.store in =\startcolor,
  end color/.store in =\endcolor
}
\end{code}
\begin{code}
\pgfdeclaredecoration{width and color change}{initial}{%
  \state{initial}[width=0pt, next state=line, persistent precomputation={%
    \pgfmathdivide{50}{\pgfdecoratedpathlength}%
    \let\increment=\pgfmathresult%
    \def\x{0}%
  }]{}
  \state{line}[width=.5pt, persistent postcomputation={%
    \pgfmathadd@{\x}{\increment}%
    \let\x=\pgfmathresult%
  }]{%
    \pgfsetlinewidth{\wfactor*\x/50*0.075pt+\pgflinewidth}%
    \pgfsetarrows{-}%
    \pgfpathmoveto{\pgfpointorigin}%
    \pgfpathlineto{\pgfqpoint{.75pt}{0pt}}%
    \pgfsetstrokecolor{\endcolor!\x!\startcolor}%
    \pgfusepath{stroke}%
  }
  \state{final}{%
    \pgfsetlinewidth{\pgflinewidth}%
    \pgfpathmoveto{\pgfpointorigin}%
    \color{\endcolor!\x!\startcolor}%
    \pgfusepath{stroke}% 
  }
}
\end{code}

\pgfkeys{/pgf/decoration/.cd,
  width factor/.store in =\wfactor,
  start color/.store in =\startcolor,
  end color/.store in =\endcolor
}
\makeatletter
\pgfdeclaredecoration{width and color change}{initial}{%
  \state{initial}[width=0pt, next state=line, persistent precomputation={%
    \pgfmathdivide{50}{\pgfdecoratedpathlength}%
    \let\increment=\pgfmathresult%
    \def\x{0}%
  }]{}
  \state{line}[width=.5pt, persistent postcomputation={%
    \pgfmathadd@{\x}{\increment}%
    \let\x=\pgfmathresult%
  }]{%
    \pgfsetlinewidth{\wfactor*\x/50*0.075pt+\pgflinewidth}%
    \pgfsetarrows{-}%
    \pgfpathmoveto{\pgfpointorigin}%
    \pgfpathlineto{\pgfqpoint{.75pt}{0pt}}%
    \pgfsetstrokecolor{\endcolor!\x!\startcolor}%
    \pgfusepath{stroke}%
  }
  \state{final}{%
    \pgfsetlinewidth{\pgflinewidth}%
    \pgfpathmoveto{\pgfpointorigin}%
    \color{\endcolor!\x!\startcolor}%
    \pgfusepath{stroke}% 
  }
}
\makeatother
\tikzexternalenable
\begin{tikzpicture}
  \draw[%line width=.4pt, 
  decoration={
    width and color change,   
    width factor=1.5,
    start color=Y,
    end color=R
  }, decorate] (0, 0) to[out=20, in=170] ++(5, 2);
  \draw[%line width=.4pt,
  decoration={
    width and color change,   
    width factor=.8,
    start color=G!50,
    end color=V
  }, decorate] (1, 2) to[out=20, in=170] ++(7, -2);
\end{tikzpicture}
\tikzexternaldisable

\tikzexternalenable
\begin{tikzpicture}
  \draw[%line width=.4pt,
  decoration={
    width and color change,   
    width factor=.5,
    start color=C,
    end color=O
  }, decorate] (0, 0) to[out=-20, in=180] ++(8, -2)
  to[out=0, in=120] ++(2, -.5);
\end{tikzpicture}
\tikzexternaldisable




\section{Around colors}

We construct below two gradients; the first is based on color mixing,
yellow, red, cyan, and dark red.  The second on the wave length of
different additive colors.


\begin{figure}[htb!]
  \centering
  \newcommand{\tmpT}{white}
  \newcommand{\tmpB}{white}
  \newcommand{\tmpC}{white}
  \tikzset{
    evaluate={
      int \i, \N;
      real \dx, \dy;
      \N = 50;
      \dx = 10/\N;
      \dy = 10/\N; 
      for \i in {0,...,\N}{
        \a{\i} = \i*100/\N;
      };
    }
  }
  \tikzexternalenable
  \begin{tikzpicture}[x=.65cm,y=.65cm]
    \foreach \i in {0,...,\N}{
      \renewcommand{\tmpT}{R!\a{\i}!Y}
      \renewcommand{\tmpB}{DarkR!\a{\i}!C}
      \pgfshadecolortorgb{\tmpT}{\rgbT}
      \pgfshadecolortorgb{\tmpB}{\rgbB}
      \fill[\tmpT] ($(\i*10/\N,11.1)$) rectangle ++(\dx, \dy);      
      \fill[\tmpB] ($(\i*10/\N,-1.1)$) rectangle ++(\dx, \dy);

      \foreach \j in {0,...,\N}{
        \pgfmathsetmacro{\newr}{(1-\j/\N)*\rgbBred+\j/\N*\rgbTred}
        \pgfmathsetmacro{\newg}{(1-\j/\N)*\rgbBgreen+\j/\N*\rgbTgreen}
        \pgfmathsetmacro{\newb}{(1-\j/\N)*\rgbBblue+\j/\N*\rgbTblue}
        \xdefinecolor{tmpC}{rgb}{\newr, \newg, \newb}
        \draw[tmpC, fill=tmpC] ($(\i*10/\N,\j*10/\N)$) rectangle ++(\dx, \dy);
      }
    }
  \end{tikzpicture}
  \tikzexternaldisable
  \caption{A planar gradient based on four colors}
  \label{fig:gradient}
\end{figure}


\begin{figure}[h]
  \centering
  \tikzmath{%
    real \extR;
    \extR = 6;
    function rightPos(\x){
      if \x>90 then{
        if \x<269 then{
          \x = 180+\x;
        };
      };
      return \x;
    };
  }
  \tikzfading[%
  name=fade out,
  inner color=transparent!0,
  outer color=transparent!100]
  \tikzexternalenable
  \begin{tikzpicture}[scale=.7]
    \draw[color=Gray,thin] (0,0) circle (\extR);
    \foreach \t in {0,1,2,...,359}{%
      \pgfmathsetmacro{\h}{\t/360}
      \definecolor{tmp}{hsb}{\h,1,1}
      \fill[tmp, rotate=\t] (0,0)
      -- +(-.5:\extR-.1) -- +(.5:\extR-.1) -- cycle;
    }
    \foreach \t in {0,10,20,...,350}{%
      \node[rotate={rightPos(\t)}, scale=.7] at (\t:\extR+.5) {$\t$};
    }
    \fill[white, path fading=fade out] (0,0) circle[radius=\extR-1];
  \end{tikzpicture}
  \tikzexternaldisable
  \caption{The colors are created with a \textttc{foreach} command,
    one color for each degree.  The fading is applied afterwards based
    on opacity only.}
  \label{fig:shadings}
\end{figure}



\end{document}
