% Copyright 2006 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\section{Snake Library}

\label{section-library-snakes}

\begin{pgflibrary}{snakes}
  This library package defines basic
  snakes. Section~\ref{section-tikz-snakes} explains how snakes are
  used in \tikzname, Section~\ref{section-base-snakes} explains how
  new snakes can be defined.

  The snakes are influenced by the current values of parameters like
  |\pgfsnakesegmentamplitude|. Only this parameter and
  |\pgfsnakesegmentlength| are proper \TeX\ dimensions, all other
  parameters are \TeX\ macros.

  In \tikzname, each parameter can be set using an option having the
  parameters name minus the |\pgfsnake| part.
\end{pgflibrary}


\begin{snake}{bent}
  This snake adds a slightly bent line from the start to the
  target. The amplitude of the bent is given by the segement amplitude
  (and amplitude of zero gives a straight line). 
  \begin{itemize}
  \item |\pgfsnakesegmentamplitude|
    determines the amplitude of the bent.
  \item |\pgfsnakesegmentaspect|
    determines how tight the bent is. A good value is around |0.3|. 
  \end{itemize}
\begin{codeexample}[]
\begin{tikzpicture}[segment aspect=.3]
  \node[circle,draw] (A) at (.5,.5) {A};
  \node[circle,draw] (B) at (3,1.5) {B};
  \draw[->,snake=bent,raise snake=2pt] (A) -- (B);
  \draw[->,snake=bent,raise snake=2pt] (B) -- (A);

  \draw [snake=bent,mirror snake] (0,0) rectangle (3.5,2);
\end{tikzpicture}
\end{codeexample}
\end{snake}



\begin{snake}{border}
  This snake adds straight lines the path that are at a specific angle
  to the line toward the target. The idea is to add these little lines
  to indicate the ``border'' or an area. The following parameters
  influence the snake:  
  \begin{itemize}
  \item |\pgfsnakesegmentlength|
    determines the distance between consecutive ticks.
  \item |\pgfsnakesegmentamplitude|
    determines the length of the ticks.
  \item |\pgfsnakesegmentangle|
    determines the angle between the ticks and the line toward the
    target. 
  \end{itemize}
\begin{codeexample}[]
\tikz{\draw (0,0) rectangle (3,1)
            [snake=border,segment angle=-45] (0,0) rectangle (3,1);}
\end{codeexample}
\end{snake}


\begin{snake}{brace}
  This snake adds a long brace to the path. The left and right end of
  the brace will be exactly on the start and endpoint of the
  snake. The following parameters influence the snake:  
  \begin{itemize}
  \item |\pgfsnakesegmentamplitude|
    determines how much the brace rises above the path.
  \item |\pgfsnakesegmentaspect|
    determines the fraction of the total length where the ``middle
    part'' of the brace will be.  
  \end{itemize}
\begin{codeexample}[]
\tikz{\draw[snake=brace,segment aspect=0.25] (0,0) -- (3,0);}
\end{codeexample}
\end{snake}

\begin{snake}{bumps}
  This snake consists of little half ellipses. The following parameters
  influence the snake:
  \begin{itemize}
  \item |\pgfsnakesegmentamplitude|
    determines the height of the half ellipse.
  \item |\pgfsnakesegmentlength|
    determines the width of the half ellipse.
  \end{itemize}
\begin{codeexample}[]
\tikz{\draw[snake=bumps] (0,0) -- (3,0);}
\end{codeexample}
\end{snake}


\begin{snake}{coil}
  This snake adds a coil to the path. To understand how this works,
  imagine a three-dimensional spring. The spring's axis points along
  the line toward the target. Then, we ``view'' the spring from a
  certain angle. If we look ``straight from the side'' we will see a
  perfect sine curve, if we look ``more from the front'' we will see a
  coil. The following parameters influence the snake:  
  \begin{itemize}
  \item |\pgfsnakesegmentamplitude|
    determines how much the coil rises above the path and falls below
    it. Thus, this is the radius of the coil.
  \item |\pgfsnakesegmentlength|
    determines the distance between two consecutive ``curls.'' Thus,
    when the spring is see ``from the side'' this will be the wave
    length of the sine curve. 
  \item |\pgfsnakesegmentaspect|
    determines the ``viewing direction.'' A value of |0| means
    ``looking from the side'' and a value of |0.5|, which is the
    default, means ``look more from the front.'' 
  \end{itemize}
\begin{codeexample}[]
\begin{tikzpicture}[segment amplitude=10pt]
  \draw[snake=coil]                  (0,1) -- (3,1);
  \draw[snake=coil,segment aspect=0] (0,0) -- (3,0);
\end{tikzpicture}
\end{codeexample}
\end{snake}


\begin{snake}{expanding waves}
  This snake adds arcs to the path that get bigger along the line
  towards the target. The following parameters influence the snake:
  \begin{itemize}
  \item |\pgfsnakesegmentlength|
    determines the distance between consecutive arcs.
  \item |\pgfsnakesegmentangle|
    determines the opening angle below and above the path. Thus, the
    total opening angle is twice this angle.
  \end{itemize}
\begin{codeexample}[]
\tikz{\draw[snake=expanding waves] (0,0) -- (3,0);}
\end{codeexample}
\end{snake}


\begin{snake}{saw}
  This snake looks like the blade of a saw. The following parameters
  influence the snake:
  \begin{itemize}
  \item |\pgfsnakesegmentamplitude|
    determines how much each spike raises above the straight line.
  \item |\pgfsnakesegmentlength|
    determines the length each spike.
  \end{itemize}
\begin{codeexample}[]
\tikz{\draw[snake=saw] (0,0) -- (3,0);}
\end{codeexample}
\end{snake}


\begin{snake}{snake}
  This snake is the ``architypical'' snake: It looks like a snake seen
  from above. More precisely, the snake is a sine wave with a
  ``softened'' start and ending. The following parameters influence
  the snake: 
  \begin{itemize}
  \item |\pgfsnakesegmentamplitude|
    determines the sine wave's amplitude.
  \item |\pgfsnakesegmentlength|
    determines the sine wave's wave length.
  \end{itemize}
\begin{codeexample}[]
\tikz{\draw[snake=snake] (0,0) -- (3,0);}
\end{codeexample}
\end{snake}


\begin{snake}{ticks}
  This snake adds straight lines  the path that are orthogonal to the
  line toward the target. The following parameters influence the snake: 
  \begin{itemize}
  \item |\pgfsnakesegmentlength|
    determines the distance between consecutive ticks.
  \item |\pgfsnakesegmentamplitude|
    determines half the length of the ticks.
  \end{itemize}
\begin{codeexample}[]
\tikz{\draw[snake=ticks] (0,0) -- (3,0);}
\end{codeexample}
\end{snake}

\begin{snake}{triangles}
  This snake adds triangles to the path that point toward the
  target. The following parameters influence the snake: 
  \begin{itemize}
  \item |\pgfsnakesegmentlength|
    determines the distance between consecutive triangles.
  \item |\pgfsnakesegmentamplitude|
    determines half the length of the triangle side that is orthogonal
    to the path.
  \item |\pgfsnakesegmentobjectlength|
    determines the height of the triangle.
  \end{itemize}
\begin{codeexample}[]
\tikz{\draw[snake=triangles] (0,0) -- (3,0);}
\end{codeexample}
\end{snake}

\begin{snake}{crosses}
  This snake adds (diagonal) crosses to the path. The following
  parameters influence the snake:  
  \begin{itemize}
  \item |\pgfsnakesegmentlength|
    determines the distance between consecutive crosses.
  \item |\pgfsnakesegmentamplitude|
    determines half the hieght of each cross.
  \item |\pgfsnakesegmentobjectlength|
    determines width of each cross.
  \end{itemize}
\begin{codeexample}[]
\tikz{\draw[snake=crosses] (0,0) -- (3,0);}
\end{codeexample}
\end{snake}


\begin{snake}{waves}
  This snake adds arcs to the path that have a constant size. The
  following parameters influence the snake: 
  \begin{itemize}
  \item |\pgfsnakesegmentlength|
    determines the distance between consecutive arcs.
  \item |\pgfsnakesegmentangle|
    determines the opening angle below and above the path. Thus, the
    total opening angle is twice this angle.
  \item |\pgfsnakesegmentamplitude|
    determines the radius of each arc.
  \end{itemize}
\begin{codeexample}[]
\tikz{\draw[snake=waves] (0,0) -- (3,0);}
\end{codeexample}
\end{snake}


\begin{snake}{zigzag}
  This snake looks like a zig-zag line. The following parameters
  influence the snake:
  \begin{itemize}
  \item |\pgfsnakesegmentamplitude|
    determines how much the zig-zag lines raises above and falls below
    a straight line to the target point.
  \item |\pgfsnakesegmentlength|
    determines the length of a complete ``up-down'' cycle.
  \end{itemize}
\begin{codeexample}[]
\tikz{\draw[snake=zigzag] (0,0) -- (3,0);}
\end{codeexample}
\end{snake}



%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "pgfmanual-pdftex-version"
%%% End: 
