summaryrefslogtreecommitdiff
path: root/graphics/pgf/contrib/tikz-3dtools/3DToolsManual.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/contrib/tikz-3dtools/3DToolsManual.tex')
-rw-r--r--graphics/pgf/contrib/tikz-3dtools/3DToolsManual.tex387
1 files changed, 387 insertions, 0 deletions
diff --git a/graphics/pgf/contrib/tikz-3dtools/3DToolsManual.tex b/graphics/pgf/contrib/tikz-3dtools/3DToolsManual.tex
new file mode 100644
index 0000000000..4463f79613
--- /dev/null
+++ b/graphics/pgf/contrib/tikz-3dtools/3DToolsManual.tex
@@ -0,0 +1,387 @@
+\documentclass[a4paper]{ltxdoc}
+%\input{pgfmanual-dvipdfm.cfg}
+%\input{../../text-en/pgfmanual-en-main-preamble}
+\usepackage[version=latest]{pgf}
+\usepackage{xkeyval,calc,listings,tikz,fp}
+\usepackage[T1]{fontenc}% big thanks to samcarter!
+\usepackage{makeidx}
+\makeindex
+\usepackage{hyperref}
+\hypersetup{%
+ colorlinks=true,
+ linkcolor=blue,
+ filecolor=blue,
+ urlcolor=blue,
+ citecolor=blue,
+ pdfborder=0 0 0,
+}
+\makeatletter % see https://tex.stackexchange.com/q/33946
+\input{pgfmanual.code} %
+\makeatother %
+\input{pgfmanual-en-macros.tex} % link from
+% /usr/local/texlive/2019/texmf-dist/doc/generic/pgf/macros/pgfmanual-en-macros.tex
+% or the equivalent on your installation
+\newenvironment{ltxtikzlibrary}[1]{
+ \begin{pgfmanualentry}
+ \pgfmanualentryheadline{%
+ \pgfmanualpdflabel{#1}{}%
+ \textbf{\tikzname\ Library} \texttt{\declare{#1}}}
+ \index{#1@\protect\texttt{#1} library}%
+ \index{Libraries!#1@\protect\texttt{#1}}%
+ \vskip.25em%
+ {{\ttfamily\char`\\usetikzlibrary\char`\{\declare{#1}\char`\}\space\space \char`\%\space\space \LaTeX\space only}}\\[.5em]
+ \pgfmanualbody
+}
+{
+ \end{pgfmanualentry}
+}
+\def\pgfautoxrefs{1}
+\usetikzlibrary{3dtools}
+\begin{document}
+\title{\tikzname\ 3D Tools}
+\author{tallmarmot}
+\date{v1.0}
+\maketitle
+\section{Manual}
+\begin{ltxtikzlibrary}{3dtools}
+ This library provides additional tools to create 3d--like pictures.
+\end{ltxtikzlibrary}
+
+TikZ has the |3d| and |tpp| libraries which deal with the projections of
+three--dimensional drawings. This library provides some means to manipulate
+the coordinates. It supports linear combinations of vectors, vector and scalar
+products.
+
+\noindent\textbf{Note:} Hopefully this library is only temporary and its
+contents will be absorbed in slightly extended versions of the |3d| and |calc|
+libraries.
+
+\subsection{Coordinate computations}
+\label{sec:3DCoordinateComputations}
+
+
+The |3dtools| library has some options and styles for coordinate computations.
+\begin{key}{/tikz/3d parse}
+ Parses and expression and inserts the result in form of a coordinate.
+\end{key}
+\begin{key}{/tikz/3d coordinate}
+ Allow one to define a 3d coordinate from other coordinates.
+\end{key}
+Both keys support both symbolic and explicit coordinates.
+
+\begin{codeexample}[width=6cm]
+\begin{tikzpicture}
+ \path (1,2,3) coordinate (A)
+ (2,3,-1) coordinate (B)
+ (-1,-2,1) coordinate (C)
+ [3d parse={0.25*(1,2,3)x(B)}]
+ coordinate(D)
+ [3d parse={0.25*(C)x(B)}]
+ coordinate(E);
+ \path foreach \X in {A,...,E}
+ {(\X) node[fill,inner sep=1pt,
+ label=above:$\X$]{}};
+\end{tikzpicture}
+\end{codeexample}
+
+Notice that, as of now, only the syntax |\path (1,2,3) coordinate (A);| works,
+i.e.\ |\coordinate (A) at (1,2,3);| does \emph{not} work, but leads to error
+messages.
+
+\begin{codeexample}[width=6cm]
+\begin{tikzpicture}
+ \path (1,2,3) coordinate (A)
+ (2,3,-1) coordinate (B)
+ (-1,-2,1) coordinate (C)
+ [3d coordinate={(D)=0.25*(1,2,3)x(B)},
+ 3d coordinate={(E)=0.25*(C)x(B)},
+ 3d coordinate={(F)=(A)-(B)},];
+ \path foreach \X in {A,...,E}
+ {(\X) node[fill,inner sep=1pt,
+ label=above:$\X$]{}};
+\end{tikzpicture}
+\end{codeexample}
+
+The actual parsings are done by the function |\pgfmathtdparse| that allows one
+to parse 3d expressions. The supported vector operations are |+| (addition $+$),
+|-| (subtraction $-$), |*| (multiplication of the vector by a scalar), |x|
+(vector product $\times$) and |o| (scalar product).
+
+\begin{command}{\pgfmathtdparse{\marg{x}}}
+ Parses 3d expressions.
+\end{command}
+
+In order to pretty-print the result one may want to use |\pgfmathprintvector|,
+and use the math function |TD| for parsing.
+
+\begin{command}{\pgfmathprintvector\marg{x}}
+ Pretty-prints vectors.
+\end{command}
+
+
+\begin{codeexample}[width=6.5cm]
+\pgfmathparse{TD("0.2*(A)
+-0.3*(B)+0.6*(C)")}%
+$0.2\,\vec A-0.3\,\vec B+0.6\,\vec C
+=(\pgfmathprintvector\pgfmathresult)$
+\end{codeexample}
+
+The alert reader may wonder why this works, i.e.\ how would \tikzname\ ``know''
+what the coordinates $A$, $B$ and $C$ are. It works because the coordinates in
+\tikzname\ are global, so they get remembered from the above example.
+
+\paragraph{Warning.} The expressions that are used in the coordinates will only
+be evaluated when they are retrieved. So, if you use, say, random numbers, you
+will get each time a \emph{different} result.
+
+\begin{codeexample}[width=4cm]
+\begin{tikzpicture}
+ \path[overlay] (rnd,rnd,rnd)
+ coordinate (R);
+ \node at (0,1)
+ {\pgfmathparse{TD("(R)")}%
+ $\vec R=(\pgfmathprintvector\pgfmathresult)$};
+ \node at (0,0)
+ {\pgfmathparse{TD("(R)")}%
+ $\vec R=(\pgfmathprintvector\pgfmathresult)$};
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{codeexample}[width=5.2cm]
+\pgfmathparse{TD("(1,0,0)x(0,1,0)")}%
+$(1,0,0)^T\times(0,1,0)^T=
+(\pgfmathprintvector\pgfmathresult)^T$
+\end{codeexample}
+
+
+\begin{codeexample}[width=5.2cm]
+\pgfmathparse{TD("(A)o(B)")}%
+$\vec A\cdot \vec B=
+\pgfmathprintnumber\pgfmathresult$
+\end{codeexample}
+
+
+Notice that, as of now, the only purpose of brackets |(...)| is to delimit
+vectors. Further, the addition |+| and subtraction |-| have a \emph{higher}
+precedence than vector products |x| and scalar products |o|. That is,
+|(A)+(B)o(C)| gets interpreted as $(\vec A+\vec B)\cdot\vec C$, and
+|(A)+(B)x(C)| as $(\vec A+\vec B)\times\vec C$.
+
+
+\begin{codeexample}[width=5.2cm]
+\pgfmathparse{TD("(A)+(B)o(C)")}%
+$(\vec A+\vec B)\cdot\vec C=
+\pgfmathprintnumber\pgfmathresult$
+\end{codeexample}
+
+\begin{codeexample}[width=5.2cm]
+\pgfmathparse{TD("(A)+(B)x(C)")}%
+$(\vec A+\vec B)\times\vec C=
+(\pgfmathprintvector\pgfmathresult)$
+\end{codeexample}
+
+Moreover, any expression can only have either one |o| or one |x|, or none of
+these. Expressions with more of these can be accidentally right.
+
+\subsection{Orthonormal projections}
+\label{sec:3DOrthonormalProjections}
+
+This library can be used together with the |tikz-3dplot| package. It also has
+its own means to install orthonormal projections. Orthonormal projections emerge
+from subjecting 3-dimensional vectors to orthogonal transformations and
+projecting them to 2 dimensions. They are not to be confused with the
+perspective projections, which are more realistic and supported by the |tpp|
+library. Orthonormal projections may be thought of a limit of perspective
+projections at large distances, where large means that the distance of the
+observer is much larger than the dimensions of the objects that get depicted.
+
+\begin{key}{/tikz/3d/install view}
+ Installs a 3d orthonormal projection.
+\end{key}
+
+The initial projection is such that $x$ is right an $y$ is up, as if we had no
+third direction.
+
+\begin{codeexample}[width=2cm]
+\begin{tikzpicture}[3d/install view]
+ \draw[-stealth] (0,0,0) -- (1,0,0)
+ node[pos=1.2] {$x$};
+ \draw[-stealth] (0,0,0) -- (0,1,0)
+ node[pos=1.2] {$y$};
+ \draw[-stealth] (0,0,0) -- (0,0,1)
+ node[pos=1.2] {$z$};
+\end{tikzpicture}
+\end{codeexample}
+
+The 3d-like picture emerge by rotating the view. The conventions for the
+parametrization of the orthogonal rotations in terms of three rotation angles
+$\phi$, $\psi$ and $\theta$ are
+\[ O(\phi,\psi,\theta)=\left(\begin{array}{ccc}
+ s_{\phi}\,c_{\psi}
+& s_{\psi}
+& -s_{\phi}\,c_{\theta}-c_{\phi}\,s_{\psi}\,s_{\theta} \\
+ c_{\phi}\,c_{\theta}-s_{\phi}\,s_{\psi}\,s_{\theta}
+& c_{\psi}\,s_ {\theta}
+& s_{\phi}\,s_{\theta}-c_{\phi}\,c_{\theta}\,s_{\psi} \\
+ -s_{\phi}\,s_{\psi}\,c_{\theta}-c_{\phi}\,s_{\theta}
+& c_{\psi}\,c_{\theta}
+& c_{\psi}\,c_{\theta}\end{array}\right)\;.
+\]
+Here, $c_\phi:=\cos\phi$, $s_\phi:=\sin\phi$ and so on.
+\begin{key}{/tikz/3d/phi (initially 0)}
+ 3d rotation angle.
+\end{key}
+\begin{key}{/tikz/3d/psi (initially 0)}
+ 3d rotation angle.
+\end{key}
+\begin{key}{/tikz/3d/theta (initially 0)}
+ 3d rotation angle.
+\end{key}
+The rotation angles can be used to define the view. The conventions are chosen
+in such a way that they resemble those of the |tikz-3dplot| package, which gets
+widely used.
+
+\begin{codeexample}[width=2.5cm]
+\begin{tikzpicture}[3d/install view={phi=110,psi=0,theta=70}]
+ \draw[-stealth] (0,0,0) -- (1,0,0)
+ node[pos=1.2] {$x$};
+ \draw[-stealth] (0,0,0) -- (0,1,0)
+ node[pos=1.2] {$y$};
+ \draw[-stealth] (0,0,0) -- (0,0,1)
+ node[pos=1.2] {$z$};
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{codeexample}[width=2.5cm]
+\begin{tikzpicture}[3d/install view={phi=110,psi=0,theta=70}]
+ \draw[-stealth] (0,0,0) -- (1,0,0)
+ node[pos=1.2] {$x$};
+ \draw[-stealth] (0,0,0) -- (0,1,0)
+ node[pos=1.2] {$y$};
+ \draw[-stealth] (0,0,0) -- (0,0,1)
+ node[pos=1.2] {$z$};
+\end{tikzpicture}
+\end{codeexample}
+
+\subsection{Predefined pics}
+
+\begin{key}{/tikz/pics/3d circle through 3 points=\meta{options} (initially empty)}
+ Draws a circle through 3 points in 3 dimensions. If the three
+ coordinates are close to linearly dependent, the circle will not be
+ drawn.
+\end{key}
+\begin{key}{/tikz/3d circle through 3 points/A (initially {(1,0,0)})}
+ First coordinate. Can be either symbolic or explicit. Symbolic
+ coordinates need to be defined via
+ |\path (x,y,z) coordinate (name);|.
+\end{key}
+\begin{key}{/tikz/3d circle through 3 points/B (initially {(0,1,0)})}
+ Second coordinate, like above.
+\end{key}
+\begin{key}{/tikz/3d circle through 3 points/C (initially {(0,0,1)})}
+ Third coordinate, like above.
+\end{key}
+\begin{key}{/tikz/3d circle through 3 points/center name (initially {M})}
+ Name of the center coordinate that will be derived.
+\end{key}
+\begin{key}{/tikz/3d circle through 3 points/auxiliary coordinate prefix (initially {tmp})}
+ In \tikzname the coordinates are global. The code for the circle is more
+ comprehensible if named coordinates are introduced. Their names will begin with
+ this prefix. Changing the prefix will allow users to avoid overwritin
+ existing coordinates.
+\end{key}
+
+\begin{codeexample}[width=2.5cm]
+\begin{tikzpicture}[3d/install view={phi=30,psi=0,theta=70}]
+ \foreach \X in {A,B,C}
+ {\pgfmathsetmacro{\myx}{3*(rnd-1/2)}
+ \pgfmathsetmacro{\myy}{3*(rnd-1/2)}
+ \pgfmathsetmacro{\myz}{3*(rnd-1/2)}
+ \path (\myx,\myy,\myz) coordinate (\X);}
+ \path pic{3d circle through 3 points={%
+ A={(A)},B={(B)},C={(C)}}};
+ \foreach \X in {A,B,C,M}
+ {\fill (\X) circle[radius=1.5pt]
+ node[above]{$\X$};}
+\end{tikzpicture}
+\end{codeexample}
+
+To do:
+\begin{itemize}
+ \item transform to plane given by three non-degenerate coordinates
+ \item transform to plane given by normal and one point
+ \item maybe layering/visibility
+\end{itemize}
+
+\subsection{3D--like decorations}
+
+\begin{key}{/tikz/decorations/3d complete coil}
+ 3d--like coil where the front is thicker than the back.
+\end{key}
+
+\begin{key}{/tikz/decorations/3d coil closed}
+ Indicates that the coil is closed.
+\end{key}
+
+
+\begin{codeexample}[width=8cm]
+\begin{tikzpicture}
+\draw[decoration={3d coil color=red,aspect=0.35, segment length=3.1mm,
+amplitude=3mm,3d complete coil},
+decorate] (0,1) -- (0,6);
+\draw[decoration={3d coil color=blue,3d coil opacity=0.9,aspect=0.5,
+segment length={2*pi*3cm/50}, amplitude=5mm,3d complete coil,
+3d coil closed},
+decorate] (5,3.5) circle[radius=3cm];
+\end{tikzpicture}
+\end{codeexample}
+
+
+\end{document}
+
+
+\tdplotsetmaincoords{70}{110}
+\begin{tikzpicture}
+ \begin{scope}[local bounding box=tests,tdplot_main_coords]
+ % to work with this library, you need to define the cordinate
+ % with \path (<x>,<y>,<z>) coordinate (<name>);
+ \path (0,0,0) coordinate (O)
+ (1,2,3) coordinate (A)
+ (2,3,-1) coordinate (B)
+ (-1,-2,1) coordinate (C)
+ % you can use 3d parse (clumsy)
+ [3d parse={0.25*(A)x(B)}] coordinate(D)
+ % you can use 3d coordinate to define a new coordinate from existing ones
+ [3d coordinate={(E)=0.2*(A)-0.3*(B)+0.6*(C)}]
+ [3d coordinate={(H)=0.2*(A)-0.3*(B)+0.6*(C)}];
+ \draw (A) -- (B) -- (C) -- (D) -- (E) -- cycle;
+ \end{scope}
+ %\RawCoord yields the components
+ \edef\tempD{\RawCoord(D)}
+ \edef\tempE{\RawCoord(E)}
+ \edef\tempH{\RawCoord(H)}
+ \node[below right,align=left] at (tests.south west)
+ {$(D)=\tempD$,\\ $(E)=\tempE$,\\ $(H)=\tempH$};
+\end{tikzpicture}
+
+\noindent% clumsy parser
+$\tdparse{(A)+0.3*(B)>(A)+0.3(B)}=(\pgfmathresult)$
+
+\noindent% parsing inside \pgfmathparse. You need to wrap the argument in "..."
+\pgfmathparse{TD("0.2*(A)-0.3*(B)+0.6*(C)")}%
+$0.2\,\vec A-0.3\,\vec B+0.6\vec C=(\pgfmathresult)$
+
+%one can parse with the same parser vector products
+\noindent\pgfmathparse{TD("0.5*(A)x(B)")}%
+$0.5\,\vec A\times\vec B=(\pgfmathresult)$
+%(note, however, that something like (A)x(B)x(C) does NOT work)
+
+%as well as scalar products
+\noindent\pgfmathparse{TD("(A)+(C)o(B)")}%
+$\left(\begin{array}{@{}c@{}}1\\ 0\\ 0\end{array}\right)$
+%(note, however, that + and - have higher precedence than o)\end{document}
+
+
+\end{document}
+
+\endinput