diff options
author | Karl Berry <karl@freefriends.org> | 2019-11-15 21:38:02 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2019-11-15 21:38:02 +0000 |
commit | 114f0dcb24f1aea5407bfa676ef0dcfb2a60b28d (patch) | |
tree | cdefc1ffacbe8f68f47541d10dd5ad6481b0e6b1 /Master/texmf-dist/doc | |
parent | ad0cc2635a7a6ba53d891f339d362a41da71cacb (diff) |
tikz-3dtools (15nov19)
git-svn-id: svn://tug.org/texlive/trunk@52805 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r-- | Master/texmf-dist/doc/latex/tikz-3dtools/3DToolsManual.pdf | bin | 0 -> 282508 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/tikz-3dtools/3DToolsManual.tex | 387 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/tikz-3dtools/README.md | 23 |
3 files changed, 410 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/tikz-3dtools/3DToolsManual.pdf b/Master/texmf-dist/doc/latex/tikz-3dtools/3DToolsManual.pdf Binary files differnew file mode 100644 index 00000000000..471194ae312 --- /dev/null +++ b/Master/texmf-dist/doc/latex/tikz-3dtools/3DToolsManual.pdf diff --git a/Master/texmf-dist/doc/latex/tikz-3dtools/3DToolsManual.tex b/Master/texmf-dist/doc/latex/tikz-3dtools/3DToolsManual.tex new file mode 100644 index 00000000000..4463f79613f --- /dev/null +++ b/Master/texmf-dist/doc/latex/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 diff --git a/Master/texmf-dist/doc/latex/tikz-3dtools/README.md b/Master/texmf-dist/doc/latex/tikz-3dtools/README.md new file mode 100644 index 00000000000..15e54b235cf --- /dev/null +++ b/Master/texmf-dist/doc/latex/tikz-3dtools/README.md @@ -0,0 +1,23 @@ +# tikz-3dtools – additional tools to create 3d–like pictures + +[![Travis Build Status][travis-svg]][travis-link] + +*by [tallmarmot](https://github.com/tallmarmot)* + +Ti*k*Z 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. + +The library is currently maintained by the PGF/Ti*k*Z development team +at https://github.com/pgf-tikz/tikz-3dtools. Please report bugs on +the issue tracker at https://github.com/pgf-tikz/tikz-3dtools/issues +or on the mailing list https://tug.org/mailman/listinfo/pgf-tikz. + +This library may be distributed and/or modified + +1. under the LaTeX Project Public License 1.3c or later and/or +2. under the GNU General Public License v2. + +[travis-svg]: https://travis-ci.com/pgf-tikz/tikz-3dtools.svg?branch=master +[travis-link]: https://travis-ci.com/pgf-tikz/tikz-3dtools
\ No newline at end of file |