Debian Codegraph @

texmf-dist/doc/latex/tikz-3dplot/tikz-3dplot_documentation.tex

raw
1 %% tikz-3dplot_documentation.tex
2 %% Copyright 2010-2012 Jeffrey D. Hein
3 %
4 % This work may be distributed and/or modified under the
5 % conditions of the LaTeX Project Public License, either version 1.3
6 % of this license or (at your option) any later version.
7 % The latest version of this license is in
8 % http://www.latex-project.org/lppl.txt
9 % and version 1.3 or later is part of all distributions of LaTeX
10 % version 2005/12/01 or later.
11 %
12 % This work has the LPPL maintenance status `maintained'.
13 %
14 % The Current Maintainer of this work is Jeffrey D. Hein.
15 %
16 % This work consists of the files tikz-3dplot.sty and tikz-3dplot_documentation.tex
17
18 %Description
19 %-----------
20
21 %tikz-3dplot_documentation.tex - documentation for tikz-3dplot.sty: package for plotting three dimensional axes and coordinates in TikZ. The user can specify orientation of the display, and also define rotated coordinate systems within the 3d display coordinate system.
22
23 %Created 2009-11-07 by Jeff Hein. Last updated: 2010-07-30
24 %----------------------------------------------------------
25
26 %Requirements
27 %------------
28 %This requires the tikz package.
29
30 %Update Notes
31 %------------
32
33 %As of Jan 17, 2010, this package has been renamed from ``3dplot'' to ``tikz-3dplot''.
34
35
36 \documentclass[10pt,letterpaper,oneside]{memoir}
37
38 \usepackage{tikz} %for TikZ graphics
39 \usepackage{tikz-3dplot} %for tikz-3dplot functionality
40 \usepackage{amsmath} %for align equation environment
41 \usepackage{url}
42
43 \pgfrealjobname{tikz-3dplot_documentation}
44
45 \usepackage[pdftex]{hyperref}
46 \hypersetup{pdftitle={The tikz-3dplot Package}}
47 \hypersetup{pdfauthor={Jeff Hein}}
48 \hypersetup{pdfsubject={LaTeX}}
49 \hypersetup{pdfcreator={Jeff Hein}}
50 \hypersetup{colorlinks=true}
51 \hypersetup{citecolor=darkgreen}
52
53
54
55 \input{tikz-3dplot_documentation_figures.tex}
56
57
58 \newcommand{\tikzname}{Ti\emph{k}Z}
59 \newcommand{\tdplot}{\texttt{tikz-3dplot}}
60
61
62 \title{The \texttt{\tdplot} Package}
63
64 \author{Jeff Hein\\ \url{http://tikz3dplot.wordpress.com}}
65
66
67
68
69 \newcommand{\tdplotlocation}{\url{http://www.ctan.org}}
70
71 \settocdepth{subsection}
72
73 \setsecnumdepth{subsection}
74 \maxsecnumdepth{subsection}
75 \settocdepth{subsection}
76 \maxtocdepth{subsection}
77
78
79 \newif\ifscratch %for doing scratchpad work, this cuts out the rest of the document
80
81
82 %**************** Example Box *********************
83
84 \definecolor{shadecolor}{rgb}{0.90,0.90,0.90}
85 %this defines an environment for presenting code in an indented, shaded, verbatim, multipage region. Requires framed, alltt, and color environments, and \definecolor{shadecolor}{rgb}{0.90,0.90,0.90}
86
87 %this sets the verbatim font and size, based on the memoir class usage
88 \setverbatimfont{\normalfont\ttfamily\footnotesize}
89 %this turns tabs on in the verbatim environment
90 \tabson[4]
91 %this sets the frequency of line numbers displayed in a boxedverbatim environment
92 %\linenumberfrequency{1}
93 %this sets the font size of line numbers in a boxedverbatim environment
94 \linenumberfont{\normalfont\ttfamily\tiny}
95 %this positions line numbers outside the box of a boxedverbatim environment
96 %\bvnumbersoutside
97 %this turns off the box of a boxedverbatim environment
98 \nobvbox
99
100
101 \begin{document}
102
103 \input{Scratchpad.tex}
104
105
106
107 \ifscratch
108 \end{document}
109 \fi
110
111
112 \frontmatter
113 \pagestyle{empty}
114
115 \maketitle
116
117
118
119 \begin{figure}[h]
120 \begin{center}
121 \tdplotmainfig
122 \threedsurfaceplot
123
124 \threedalphabetagamma
125 %A 3d coordinate system rendered in \tikzname using the \tdplot\ package. The user can specify the display perspective by specifying angles $\theta_d$ and $\phi_d$, which rotate the coordinate frame from the ``standard'' display position where $x$ points to the right, $y$ points up.
126 \end{center}
127 \end{figure}
128
129 \cleardoublepage
130
131 {
132
133 \input{ tikz-3dplot_changelog.tex }
134
135 \vfill
136 \parindent=0pt
137 Copyright 2010-2012 Jeff Hein
138
139 \medskip
140 Permission is granted to distribute and/or modify \emph{both
141 the documentation and the code} under the conditions of the LaTeX
142 Project Public License, either version 1.3 of this license or (at
143 your option) any later version. The latest version of this license is in
144 http://www.latex-project.org/lppl.txt
145
146 \clearpage
147 }
148
149 \pagenumbering{roman}
150 \tableofcontents
151 \cleardoublepage
152 \pagenumbering{arabic}
153
154 \mainmatter
155
156 \pagestyle{plain}
157
158 \chapter{Introduction}\label{cha:intro}
159
160 \section{Overview of the \tdplot\ Package}
161 The \tdplot\ package offers commands and coordinate transformation styles for \tikzname, providing relatively straightforward tools to draw three-dimensional coordinate systems and simple three-dimensional diagrams. The package is currently in its infancy, and is subject to change. Comments or suggestions are encouraged.
162
163 This document describes the basics of the \tdplot\ package and provides information about the various available commands. Examples are given where possible.
164
165 \subsection{What \tdplot\ is}
166
167 \tdplot\ provides commands to easily specify coordinate transformations for \tikzname, allowing for relatively easy plotting. I needed to draw accurate 3d vector images for a physics thesis, and this package was developed to meet this need.
168
169 Various plotting commands are used to identify coordinate locations using spherical polar or Cartesian coordinates. Coordinate transformation commands allow for the calculation of a coordinate in one frame based on its values in another frame. Some drawing commands have been developed to assist in the rendering of arcs. These commands do the number crunching required to position and render the arcs. These commands are discussed in Section \ref{sec:tdplotcommands}.
170
171 In addition, the \verb|\tdplotsphericalsurfaceplot| was developed to render three-dimensional surfaces in spherical polar coordinates, where the radius is expressed in terms of a user-defined function of $\theta$ and $\phi$. With this function, the surface hue can be given explicitly, or expressed as a user-defined function of $r$, $\theta$, and $\phi$. This command is discussed in Section \ref{sec:spherical_surface_plot}.
172
173 \begin{figure}[ht]
174 \begin{center}
175 \threedconventions
176 \end{center}
177 \caption{\tdplot\ coordinate and positive angle convention.}\label{fig:conventions}
178 \end{figure}
179
180 In \tdplot, a right-handed coordinate system convention is used. In addition, all positive angles constitute a right-hand screw sense of rotation (see Figure \ref{fig:conventions}). This means that a positive rotation about a given axis refers to a clockwise rotation when viewing along the direction the axis, or counterclockwise when viewing against the direction of the axis.
181
182 \subsection{What \tdplot\ is not}
183
184 \tdplot\ does not, in general, consider polygons, surfaces, or object opacity. The one exception is the \verb|\tdplotsphericalsurfaceplot| command, specifically designed to render spherical polar surfaces. The \verb|\tdplotsphericalsurfaceplot| command is discussed in Section \ref{sec:spherical_surface_plot}.
185
186 Tools like Sketch by Gene Ressler are better suited for more rigorous surface rendering. These can be found at \url{http://www.frontiernet.net/~eugene.ressler/}
187
188 \subsection{Similar Work}
189
190 To my knowledge, there is no other package available which allows straightforward rendering of 3d coordinates in \tikzname, directly in a \LaTeX\ document. Since this project is in its infancy, this may be subject to change based on feedback.
191
192 \subsubsection{Sketch}
193
194 The Sketch project can provide three-dimensional rendering of axes, points, and lines, but (as far as I understand the program) cannot draw arcs without using a series of line segments. Further, Sketch requires an external program to render the image, while \tdplot\ can be developed and maintained right in a \LaTeX\ document.
195
196 \subsubsection{\TeX ample.net}
197
198 There are a variety of \tikzname\ examples listed at \url{http://www.texample.net/tikz/examples}. Some of these examples gave me inspiration to make this package. Some examples of note include the following:
199
200 \begin{itemize}
201 \item 3D cone
202 \begin{description}
203 \item[Author:] Eugene Ressler
204 \item[url:] \url{http://www.texample.net/tikz/examples/3d-cone/}
205 \item[Notes:] This demonstrates the use of Sketch in TikZ figures.
206 \end{description}
207 \item Annotated 3D box
208 \begin{description}
209 \item[Author] Alain Matthes
210 \item[url] \url{http://www.texample.net/tikz/examples/annotated-3d-box/}
211 \item[Notes] This example demonstrates the direct use of coordinate transformations, as well as performing math directly within coordinates.
212 \end{description}
213 \item Cluster of atoms
214 \begin{description}
215 \item[Author] Agustin E. Bolzan
216 \item[url] \url{http://www.texample.net/tikz/examples/clusters-of-atoms/}
217 \item[Notes] This uses shifts and slants rather than rotations to render an isometric look.
218 \end{description}
219 \item Plane partition
220 \begin{description}
221 \item[Author] Jang Soo Kim
222 \item[url] \url{http://www.texample.net/tikz/examples/plane-partition/}
223 \item[Notes] This example draws solid surfaces with coordinate axes defined by rotations around the \tikzname\ standard coordinate frame.
224 \end{description}
225 \item Spherical and cartesian grids
226 \begin{description}
227 \item[Author] Marco Miani
228 \item[url] \url{http://www.texample.net/tikz/examples/spherical-and-cartesian-grids/}
229 \item[Notes] This example renders arcs and lines in three dimensions using explicit calculations. It takes into account the opacity of the spherical example, by showing hidden lines behind the sphere as dashed lines.
230 \end{description}
231 \item Stereographic and cylindrical map projections
232 \begin{description}
233 \item[Author] Thomas M. Trzeciak
234 \item[url] \url{http://www.texample.net/tikz/examples/map-projections/}
235 \item[Notes] This example illustrates the use of coordinate transformations to draw planes and arcs for spherical coordinates.
236 \end{description}
237 \end{itemize}
238
239
240 \section{Installing the \tdplot\ Package}
241
242 Get a copy of \tdplot\ from \tdplotlocation. Place the style file in the same directory as your \LaTeX\ project. In your preamble, add the following line:
243 %
244 \begin{shaded}
245 \begin{verbatim}
246 \usepackage{tikz-3dplot}
247 \end{verbatim}
248 \end{shaded}
249
250 Make sure this line is written after all other required packages.
251
252
253 \subsection{\tdplot\ Requirements}
254
255 To use this package, the following other packages must be loaded in the preamble first:
256 \begin{itemize}
257 \item \tikzname
258 \item \texttt{ifthen} (for the \texttt{tdplotsphericalsurfaceplot} command)
259 \end{itemize}
260
261
262 \subsection{\tdplot\ Package Options}
263
264 Currently there are no options available for the \tdplot\ package.
265
266 \section{Using the \tdplot\ Package}
267
268 \tdplot\ provides styles and commands which are useful in a \texttt{tikzpicture} environment. These commands and styles are described in Chapter \ref{cha:using_tdplot}.
269
270
271
272
273
274
275
276
277
278 \chapter{Overview of 3d in \tdplot}\label{cha:overview3d}
279
280 \section{\tikzname\ 3d Plotting} \label{sec:tikzplotting}
281
282 When setting up a tikzpicture or a drawing style, the $x$, $y$, and $z$ axes can be specified directly in terms of the original coordinate system. The following example shows how a \texttt{tikzpicture} environment can be configured to use customized axes.
283
284 \begin{shaded}
285 \begin{verbatim}
286 \begin{tikzpicture}[%
287 x={(\raarot cm,\rbarot cm)},%
288 y={(\rabrot cm, \rbbrot cm)},%
289 z={(\racrot, \rbcrot cm)}]
290 \end{verbatim}
291 \end{shaded}
292
293 In this example, the terms \verb|\raarot| and so on specify how the coordinates are represented in the original \tikzname\ coordinate system, and are calculated by the \tdplot\ package. Note that units are explicitly required so \tikzname\ understands that these are absolute coordinates, not scales on the existing axis. See the PGF manual Version 2.00, section 21.2 on pages 217-218 for details on \tikzname\ coordinate transformations.
294
295 \section{The \tdplot\ Main Coordinate System}\label{sec:main_theory}
296
297 \tdplot\ offers two coordinate systems, namely the \emph{main} coordinate system $(x,y,z)$, and the \emph{rotated} coordinate system $(x',y',z')$. The latter system is described in Section \ref{sec:rotated_theory}.
298
299 As the name suggests, the main coordinate system provides a user-specified transformation to render 3d points in a \texttt{tikzpicture} environment. The orientation of the main coordinate system is defined by the angles $\theta_{d}$ and $\phi_{d}$. In the unrotated ($\theta_{d} = \phi_{d} = 0$) position, the $xy$ plane of the main coordinate system coincides with the default orientation for a \texttt{tikzpicture} environment, while $z$ points ``out of the page''.
300 %
301 The coordinate system is positioned by the following operations:
302 %
303 \begin{itemize}
304 \item Rotate the coordinate system about the body $x$ axis by the amount $\theta_d$, and
305 \item Rotate the coordinate system about the (rotated) body $z$ axis by the amount $\phi_d$.
306 \end{itemize}
307
308 In this rotation sense, the $z$ axis will always point in the vertical page direction. This transformation is given by the rotation matrix $R_d(\theta_d,\phi_d)$, as
309 %
310 \begin{align}\begin{split}
311 R^d(\theta_d,\phi_d) &= R^{z'}(\phi_d)R^{x}(\theta_d)\\
312 &= \begin{pmatrix}
313 \cos\phi_d & -\sin\phi_d & 0\\
314 \sin\phi_d & \cos\phi_d & 0\\
315 0 & 0 & 1
316 \end{pmatrix}
317 \begin{pmatrix}
318 1 & 0 & 0\\
319 0 & \cos\theta_d & -\sin\theta_d\\
320 0 & \sin\theta_d & \cos\theta_d\\
321 \end{pmatrix}\\
322 &= \begin{pmatrix}
323 \cos\phi_d & \sin\phi_d & 0\\
324 -\cos\theta_d\sin\phi_d & \cos\theta_d\cos\phi_d & -\sin\theta_d\\
325 \sin\theta_d\sin\phi_d & -\sin\theta_d\cos\phi_d & \cos\theta_d\\
326 \end{pmatrix}
327 \end{split}\end{align}
328
329 \begin{figure}[b]
330 \begin{center}
331 \threedcoord{0}{0}
332 \threedcoord{10}{50}
333 \threedcoord{30}{110}
334
335 \threedcoord{40}{150}
336 \threedcoord{60}{170}
337 \threedcoord{90}{180}
338 \end{center}
339 \caption{Examples of coordinate systems for various choices of $\theta_d$ and $\phi_d$.}
340 \end{figure}
341
342 Using this matrix, the \tikzname\ coordinate transformation can be applied as described in Section \ref{sec:tikzplotting} by the various matrix elements, as
343 %
344 \begin{align}\begin{split}
345 x &= (R^d_{1,1}, R^d_{2,1})\\
346 y &= (R^d_{1,2}, R^d_{2,2})\\
347 z &= (R^d_{1,3}, R^d_{2,3})
348 \end{split}\end{align}
349
350 Note that the third row of the rotation matrix is not needed for this transformation, since a screen coordinate is a 2d value. Once the transformed axes have been established, any 3d coordinate specified in \tikzname\ will adhere to the transformation, yielding a 3D representation. Lines and nodes can readily be drawn by using these 3d coordinates.
351
352 This coordinate transformation is accessible through \tdplot\ using the command \texttt{tdplotsetmaincoords}, as described in Chapter \ref{cha:using_tdplot}.
353
354 \section{The \tdplot\ Rotated Coordinate System}\label{sec:rotated_theory}
355
356 Along with the main coordinate system, described in Section \ref{sec:main_theory}, \tdplot\ offers a \emph{rotated} coordinate system that is defined with respect to the main coordinate system. This system can be rotated to any position using Euler rotations, and can be translated so the origin of the rotated coordinate system sits on an arbitrary point in the main coordinate system.
357
358 Three rotations can be performed to give any arbitrary orientation of a rotated coordinate system. By convention, the following rotations are chosen:
359 %
360 \begin{itemize}
361 \item Rotate by angle $\gamma$ about the world $z$ axis,
362 \item Rotate by angle $\beta$ about the (unrotated) world $y$ axis, and
363 \item Rotate by angle $\alpha$ about the (unrotated) world $z$ axis.
364 \end{itemize}
365
366 These rotations are shown in Figure \ref{fig:euler_angles}.
367
368 \begin{figure}[h]
369 \begin{center}
370 \threedalphabetagamma
371 \end{center}
372 \caption{Positioning the rotated coordinate frame $(x', y', z')$ using Euler angles $(\alpha, \beta, \gamma)$.}\label{fig:euler_angles}
373 \end{figure}
374
375
376 This rotation matrix $D(\alpha,\beta,\gamma)$ is given by
377 %
378 \begin{align}\begin{split}
379 D(\alpha,\beta,\gamma) &= R^z(\alpha)R^y(\beta)R^z(\gamma)\\
380 &= \begin{pmatrix}
381 \cos\alpha & -\sin\alpha & 0\\
382 \sin\alpha & \cos\alpha & 0\\
383 0 & 0 & 1\\
384 \end{pmatrix}
385 \begin{pmatrix}
386 \cos\beta & 0 & \sin\beta \\
387 0 & 1 & 0 \\
388 -\sin\beta & 0 & \cos\beta\\
389 \end{pmatrix}
390 \begin{pmatrix}
391 \cos\gamma & -\sin\gamma & 0\\
392 \sin\gamma & \cos\gamma & 0\\
393 0 & 0 & 1\\
394 \end{pmatrix}\\
395 &= \begin{pmatrix}
396 \cos\alpha\cos\beta\cos\gamma - \sin\alpha\sin\gamma & -\cos\alpha\cos\beta\sin\gamma - \sin\alpha\cos\gamma & \cos\alpha\sin\beta\\
397 \sin\alpha\cos\beta\cos\gamma + \cos\alpha\sin\gamma & -\sin\alpha\cos\beta\sin\gamma + \cos\alpha\cos\gamma & \sin\alpha\sin\beta\\
398 -\sin\beta\cos\gamma & \sin\beta\sin\gamma & \cos\beta
399 \end{pmatrix}
400 \end{split}\end{align}
401
402 To define the rotated coordinate frame, this rotation matrix is applied after rotation matrix $R^d(\theta_d,\phi_d)$ used to define the main coordinate frame. The full transformation for the rotated coordinate frame is then given by
403 %
404 \begin{align}
405 R'^d(\theta_d,\phi_d,\alpha,\beta,\gamma) &= D(\alpha,\beta,\gamma)R^d(\theta_d,\phi_d)
406 \end{align}
407
408 Using this matrix, the \tikzname\ coordinate transformation can be applied as described in Section \ref{sec:tikzplotting} by the various matrix elements, as
409 %
410 \begin{align}\begin{split}
411 x' &= (R'^d_{1,1}, R'^d_{2,1})\\
412 y' &= (R'^d_{1,2}, R'^d_{2,2})\\
413 z' &= (R'^d_{1,3}, R'^d_{2,3})
414 \end{split}\end{align}
415
416 This coordinate transformation is accessible through \tdplot\ using the command \texttt{tdplotsetrotatedcoords}, as described in Chapter \ref{cha:using_tdplot}.
417
418 \begin{figure}[h]
419 \begin{center}
420 \threedrotcoordsystem
421 \end{center}
422 \caption{The rotated coordinate frame $(x', y', z')$ displayed within the main coordinate frame $(x,y,z)$. Both are completely specified by user-defined angles: $(\theta_d, \phi_d)$ for the main coordinate frame, and $(\alpha, \beta, \gamma)$ for the rotated coordinate frame.}
423 \end{figure}
424
425
426 \section{Arcs in 3d, and the ``Theta Plane''}
427
428 Arcs can be drawn in \tikzname\ using commands described in the PGF manual Version 2.00, section 2.10 on pages 25-26. However, the arc commands accept 2d coordinates, and thus can only be drawn in the $xy$ plane.
429
430 To draw an arc in any position other than within the $xy$ plane of the main coordinate frame, the rotated coordinate frame must be used, where the $x'y'$ plane lies in the desired orientation within the main coordinate frame. Such an arc is needed, for example, when illustrating the polar angle $\theta$ of some vector. This $\theta$ arc exists in a plane which contains the $z$ axis, and is rotated about the $z$ axis by the angle $\phi$ from the $xz$ plane. For lack of a better name, this plane is referred to as the ``theta plane'' within a given coordinate system.
431
432 \begin{figure}[h]
433 \begin{center}
434 \threedthetaarc
435 \end{center}
436 \caption{Drawing arcs outside the $xy$ plane by using a rotated coordinate frame in the ``theta plane'' of the main coordinate frame.}
437 \end{figure}
438
439 As described in Chapter \ref{cha:using_tdplot}, \tdplot\ offers the commands \texttt{tdplotsetthetaplanecoords} and \texttt{tdplotsetrotatedthetaplanecoords} to easily configure the rotated coordinate frame to lie within the desired theta plane.
440
441
442
443
444
445
446
447
448 \chapter{Using the \tdplot\ Package} \label{cha:using_tdplot}
449
450 The \tdplot\ package was developed to handle the number crunching described in Chapter \ref{cha:overview3d}, and provide a relatively simple and straightforward front-end for users.
451
452 The main and rotated coordinate frames are configured by using commands described in Section \ref{sec:tdplotcommands}. These commands generate \tikzname\ styles which can be used either in defining the \texttt{tikzpicture} environment, or directly in any \tikzname\ command. The styles are described further in Section \ref{sec:tikzstyles}.
453
454 \section{The \tdplot\ \tikzname\ Styles} \label{sec:tikzstyles}
455
456
457 \subsection{\texttt{tdplot\_main\_coords}}
458
459 The \verb|tdplot_main_coords| style stores the coordinate transformation required to generate the main coordinate system. This style can either be used when the \texttt{tikzpicture} environment is started, or when an individual \tikzname\ plotting command is used.
460
461 \subsection{\texttt{tdplot\_rotated\_coords}}
462
463 The \verb|tdplot_rotated_coords| style stores the coordinate transformation (translation and rotation) required to generate the rotated coordinate system within the main coordinate system. This style can either be used when the \texttt{tikzpicture} environment is started, or when an individual \tikzname\ plotting command is used.
464
465 \subsection{\texttt{tdplot\_screen\_coords}}
466
467 The \verb|tdplot_screen_coords| style provides the standard, unrotated \tikzname\ coordinate frame. This is useful to escape out of the user-defined 3d coordinates used at the beginning of the \texttt{tikzpicture} environment, and place something on an absolute scale in the figure. Tables, legends, and captions contained within the same figure as a 3d plot can make use of this style.
468
469 %\section{The \tdplot\ Macros} \label{sec:tdplotmacros}
470 %
471 %\tdplot\ uses various macros to perform all its number crunching. Some of these are only used ``under the hood'', where the user would never need to know about them, while others are required to pass numbers to, or receive results from, the \tdplot\ commands.
472 %
473 %Since my knowledge of LaTeX is limited, there is probably a more streamlined and efficient way I can handle all this. As such, feedback and suggestions are welcome.
474 %
475 %\subsection{``Input'' Macros}
476 %
477 %These macros must be defined by the user before calling the corresponding command. In some cases, they are defined explicitly by another command, as described in the following section.
478 %
479 %\begin{center}
480 % \begin{tabular}{c p{4in}}
481 % \hline
482 % \textbf{Macro} & \textbf{Notes}\\
483 % \hline
484 %
485 % \hline
486 % \end{tabular}
487 %\end{center}
488 %
489 %\subsection{''Output'' Macros}
490 %
491 %These macros are defined as a result of calling a command. These can either be used directly by the user, or by subsequent \tdplot\ commands.
492 %
493 %\begin{center}
494 % \begin{tabular}{c p{4in}}
495 % \hline
496 % \textbf{Macro} & \textbf{Notes}\\
497 % \hline
498 % \verb|\tdplotresx| & Result x value
499 %
500 % \hline
501 % \end{tabular}
502 %\end{center}
503 %
504 %\subsection{``Under the Hood'' Macros}
505 %
506 %These are macros which are not necessary to know about. They are used so \tdplot\ can perform its task, and are not used outside the commands.
507 %
508 %\begin{center}
509 % \begin{tabular}{c p{4in}}
510 % \hline
511 % \textbf{Macro} & \textbf{Notes}\\
512 % \hline
513 % \verb|\lowerphi| & Lower $\phi$ limit for \verb|\tdplotsphericalsurfaceplot| polar plot.\\
514 % \verb|\upperphi| & Upper $\phi$ limit for \verb|\tdplotsphericalsurfaceplot| polar plot.\\
515 % \verb|\lowertheta| & Lower $\theta$ limit for \verb|\tdplotsphericalsurfaceplot| polar plot.\\
516 % \verb|\uppertheta| & Upper $\theta$ limit for \verb|\tdplotsphericalsurfaceplot| polar plot.\\
517 % \hline
518 % \end{tabular}
519 %\end{center}
520
521 \section{The \tdplot\ Commands} \label{sec:tdplotcommands}
522
523 This section lists the various commands provided by the \tdplot\ package. Examples are provided where it is useful.
524
525 \section{Coordinate Configuration Commands}
526
527 \subsection{\texttt{tdplotsetmaincoords}}
528
529 \begin{description}
530 \item[Description:] Generates the style \verb|tdplot_main_coords| which provides the coordinate transformation for the main coordinate frame, based on a user-specified orientation $(\theta_d,\phi_d)$. $\theta_d$ denotes the rotation around the $x$ axis, while $\phi_d$ denotes the rotation around the $z$ axis. Note that $(0,0)$ is the default orientation, where $x$ points right, $y$ points up, and $z$ points ``out of the page''.
531
532 \item[Syntax:] \verb|\tdplotsetmaincoords{| $\theta_d$ \verb|}{| $\phi_d$ \verb|}|
533
534 \item[Parameters:]~
535 \begin{description}
536 \item[$\theta_d$] The angle (in degrees) through which the coordinate frame is rotated about the $x$ axis.
537 \item[$\phi_d$] The angle (in degrees) through which the coordinate frame is rotated about the $z$ axis.
538 \end{description}
539 \item[Example:] ~
540 \begin{shaded}
541 \begin{verbatim}
542 \tdplotsetmaincoords{70}{110}
543 \begin{tikzpicture}[tdplot_main_coords]
544 \draw[thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};
545 \draw[thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};
546 \draw[thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};
547 \end{tikzpicture}
548 \end{verbatim}
549 \tdplotsetmaincoords{70}{110}
550 \begin{tikzpicture}[tdplot_main_coords]
551 \draw[thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};
552 \draw[thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};
553 \draw[thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};
554 \end{tikzpicture}
555 \end{shaded}
556
557 \end{description}
558
559 \subsection{\texttt{tdplotsetrotatedcoords}}
560
561 \begin{description}
562 \item[Description:] Generates the style \verb|tdplot_rotated_coords| which provides the coordinate transformation for rotated coordinate frame within the current main coordinate frame, based on user-specified Euler angles $(\alpha,\beta,\gamma)$. Rotations use the $z(\alpha)y(\beta)z(\gamma)$ convention of Euler rotations, where the system is rotated by $\gamma$ about the $z$ axis, then $\beta$ about the (world) $y$ axis, and then $\alpha$ about the (world) $z$ axis.
563 \item[Syntax:] \verb|\tdplotsetrotatedcoords{|$\alpha$\verb|}{|$\beta$\verb|}{|$\gamma$\verb|}|
564 \item[Parameters:]~
565 \begin{description}
566 \item[$\alpha$] The angle (in degrees) through which the rotated frame is rotated about the world $z$ axis.
567 \item[$\beta$] The angle (in degrees) through which the rotated frame is rotated about the world $y$ axis.
568 \item[$\gamma$] The angle (in degrees) through which the rotated frame is rotated about the world $z$ axis.
569 \end{description}
570 \item[Example:] ~
571 \begin{shaded}
572 \begin{verbatim}
573 \tdplotsetmaincoords{70}{110}
574 \begin{tikzpicture}[tdplot_main_coords]
575 \draw[thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};
576 \draw[thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};
577 \draw[thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};
578
579 \tdplotsetrotatedcoords{60}{40}{30}
580
581 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0) --
582 (.7,0,0) node[anchor=north]{$x'$};
583 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0) --
584 (0,.7,0) node[anchor=west]{$y'$};
585 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0) --
586 (0,0,.7) node[anchor=south]{$z'$};
587 \end{tikzpicture}
588 \end{verbatim}
589 \tdplotsetmaincoords{70}{110}
590 \begin{tikzpicture}[tdplot_main_coords]
591 \draw[thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};
592 \draw[thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};
593 \draw[thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};
594
595 \tdplotsetrotatedcoords{60}{40}{30}
596
597 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0) -- (.7,0,0) node[anchor=north]{$x'$};
598 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0) -- (0,.7,0) node[anchor=west]{$y'$};
599 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0) -- (0,0,.7) node[anchor=south]{$z'$};
600 \end{tikzpicture}
601 \end{shaded}
602 \end{description}
603
604
605 \subsection{\texttt{tdplotsetrotatedcoordsorigin}}
606
607 \begin{description}
608 \item[Description:] Sets the origin of the rotated coordinate system specified by \verb|tdplot_rotated_coords| using a user-defined point. This point can be either a literal or predefined point.
609 \item[Syntax:] \verb|\tdplotsetrotatedcoordsorigin{point}|
610 \item[Parameters:]~
611 \begin{description}
612 \item[\texttt{point}] A point predefined using the \tikzname\ \verb|\coordinate| command.
613 \end{description}
614 \item[Example:] ~
615 \begin{shaded}
616 \begin{verbatim}
617 \tdplotsetmaincoords{70}{110}
618 \begin{tikzpicture}[tdplot_main_coords]
619 \draw[thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};
620 \draw[thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};
621 \draw[thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};
622
623 \tdplotsetrotatedcoords{60}{40}{30}
624
625 \coordinate (Shift) at (0.5,0.5,0.5);
626 \tdplotsetrotatedcoordsorigin{(Shift)}
627
628 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0) --
629 (.7,0,0) node[anchor=north]{$x'$};
630 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0) --
631 (0,.7,0) node[anchor=west]{$y'$};
632 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0) --
633 (0,0,.7) node[anchor=south]{$z'$};
634 \end{tikzpicture}
635 \end{verbatim}
636 \tdplotsetmaincoords{70}{110}
637 \begin{tikzpicture}[tdplot_main_coords]
638 \draw[thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};
639 \draw[thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};
640 \draw[thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};
641
642 \tdplotsetrotatedcoords{60}{40}{30}
643
644 \coordinate (Shift) at (0.5,0.5,0.5);
645 \tdplotsetrotatedcoordsorigin{(Shift)}
646
647 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0) -- (.7,0,0) node[anchor=north]{$x'$};
648 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0) -- (0,.7,0) node[anchor=west]{$y'$};
649 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0) -- (0,0,.7) node[anchor=south]{$z'$};
650 \end{tikzpicture}
651 \end{shaded}
652 \end{description}
653
654 \subsection{\texttt{tdplotresetrotatedcoordsorigin}}
655
656 \begin{description}
657 \item[Description:] Resets the origin of the rotated coordinate system back to the origin of the main coordinate system.
658 \item[Syntax:] \verb|\tdplotresetrotatedcoordsorigin|
659 \item[Parameters:] None
660 \end{description}
661
662 \subsection{\texttt{tdplotsetthetaplanecoords}}
663
664 \begin{description}
665 \item[Description:] Generates a rotated coordinate system such that the $x'y'$ plane is coplanar to a plane containing the polar angle $\theta$ projecting from the main coordinate system $z$ axis. This coordinate system is particularly useful for drawing within this ``theta plane'', as \tikzname\ draws arcs in the $xy$ plane. As with \texttt{tdplotsetrotatedcoords}, this coordinate system is accessible through the \verb|tdplot_rotated_coords| style. Note that any rotated coordinate frame offset previously set by \texttt{tdplotsetrotatedcoordsorigin} is automatically reset when this command is used.
666 \item[Syntax:] \verb|\tdplotsetthetaplanecoords{|$\phi$\verb|}|
667 \item[Parameters:]~
668 \begin{description}
669 \item[$\phi$] The angle (in degrees) through which the ``theta plane'' makes with the $xz$ plane of the main coordinate system.
670 \end{description}
671 \item[Example:]~
672 \begin{shaded}
673 \begin{verbatim}
674 \tdplotsetmaincoords{70}{110}
675
676 \begin{tikzpicture}[scale=3,tdplot_main_coords]
677 \draw[thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};
678 \draw[thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};
679 \draw[thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};
680
681 \tdplotsetcoord{P}{.8}{50}{70}
682
683 %draw a vector from origin to point (P)
684 \draw[-stealth,color=red] (O) -- (P);
685
686 %draw projection on xy plane, and a connecting line
687 \draw[dashed, color=red] (O) -- (Pxy);
688 \draw[dashed, color=red] (P) -- (Pxy);
689
690
691 \tdplotsetthetaplanecoords{70}
692
693 \draw[tdplot_rotated_coords,color=blue,thick,->] (0,0,0)
694 -- (.2,0,0) node[anchor=east]{$x'$};
695 \draw[tdplot_rotated_coords,color=blue,thick,->] (0,0,0)
696 -- (0,.2,0) node[anchor=north]{$y'$};
697 \draw[tdplot_rotated_coords,color=blue,thick,->] (0,0,0)
698 -- (0,0,.2) node[anchor=west]{$z'$};
699
700 \end{tikzpicture}
701 \end{verbatim}
702 \tdplotsetmaincoords{70}{110}
703
704 \begin{tikzpicture}[scale=3,tdplot_main_coords]
705 \draw[thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};
706 \draw[thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};
707 \draw[thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};
708
709 \tdplotsetcoord{P}{.8}{50}{70}
710
711 \coordinate (O) at (0,0,0);
712
713 %draw a vector from origin to point (P)
714 \draw[-stealth,color=red] (O) -- (P);
715
716 %draw projection on xy plane, and a connecting line
717 \draw[dashed, color=red] (O) -- (Pxy);
718 \draw[dashed, color=red] (P) -- (Pxy);
719
720 \tdplotsetthetaplanecoords{70}
721
722 \draw[tdplot_rotated_coords,color=blue,thick,->] (0,0,0)
723 -- (.2,0,0) node[anchor=east]{$x'$};
724 \draw[tdplot_rotated_coords,color=blue,thick,->] (0,0,0)
725 -- (0,.2,0) node[anchor=north]{$y'$};
726 \draw[tdplot_rotated_coords,color=blue,thick,->] (0,0,0)
727 -- (0,0,.2) node[anchor=west]{$z'$};
728
729 \end{tikzpicture}
730 \end{shaded}
731 \end{description}
732
733
734 \subsection{\texttt{tdplotsetrotatedthetaplanecoords}}
735
736 \begin{description}
737 \item[Description:] Just like \texttt{tdplotsetthetaplanecoords}, except this works for the rotated coordinate system. Generates a rotated coordinate system such that the $x'-y'$ plane is coplanar to a plane containing the polar angle $\theta'$ projecting from the current rotated coordinate system $z'$ axis. Note that the current rotated coordinate system is overwritten by this theta plane coordinate system after the command is completed.
738 \item[Syntax:] \verb|\tdplotsetrotatedthetaplanecoords{|$\phi'$\verb|}|
739 \item[Parameters:]~
740 \begin{description}
741 \item[$\phi'$] The angle (in degrees) through which the ``theta plane'' makes with the $x'-z'$ plane of the current rotated coordinate system.
742 \end{description}
743 \item[Example:]~
744 \begin{shaded}
745 \begin{verbatim}
746 \tdplotsetmaincoords{60}{110}
747 \begin{tikzpicture}[scale=3,tdplot_main_coords]
748 \draw[thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};
749 \draw[thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};
750 \draw[thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};
751
752 \coordinate (Shift) at (2,2,2);
753
754 \tdplotsetrotatedcoords{-20}{10}{0}
755 \tdplotsetrotatedcoordsorigin{(Shift)}
756
757 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0)
758 -- (1,0,0) node[anchor=south east]{$x'$};
759 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0)
760 -- (0,1,0) node[anchor=west]{$y'$};
761 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0)
762 -- (0,0,1) node[anchor=south]{$z'$};
763
764 \tdplotsetrotatedthetaplanecoords{30}
765
766 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0)
767 -- (.5,0,0) node[anchor=south east]{$x''$};
768 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0)
769 -- (0,.5,0) node[anchor=west]{$y''$};
770 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0)
771 -- (0,0,.5) node[anchor=south]{$z''$};
772 \end{tikzpicture}
773 \end{verbatim}
774 \ifpdf
775 \tdplotsetmaincoords{60}{110}
776 \begin{tikzpicture}[scale=3,tdplot_main_coords]
777 \draw[thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};
778 \draw[thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};
779 \draw[thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};
780
781 \coordinate (Shift) at (2,2,2);
782
783 \tdplotsetrotatedcoords{-20}{10}{0}
784 \tdplotsetrotatedcoordsorigin{(Shift)}
785
786 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0) -- (1,0,0) node[anchor=south east]{$x'$};
787 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0) -- (0,1,0) node[anchor=west]{$y'$};
788 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z'$};
789
790 \tdplotsetrotatedthetaplanecoords{30}
791
792 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0) -- (.5,0,0) node[anchor=south east]{$x''$};
793 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0) -- (0,.5,0) node[anchor=west]{$y''$};
794 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0) -- (0,0,.5) node[anchor=south]{$z''$};
795 \end{tikzpicture}
796 \fi
797 \end{shaded}
798
799 \end{description}
800
801 \subsection{\texttt{tdplotcalctransformmainrot}}
802
803 \begin{description}
804 \item[Description:] Calculates the rotation matrix used to transform a coordinate from the main coordinate frame to the rotated coordinate frame. The matrix elements are stored in the macros \verb|\raaeul| through \verb|\rcceul|. This transformation is accessed using \verb|\tdplottransformmainrot|.
805 \end{description}
806
807
808 \subsection{\texttt{tdplotcalctransformrotmain}}
809
810 \begin{description}
811 \item[Description:] Calculates the rotation matrix used to define the rotated coordinate frame, as well as transform a coordinate from the rotated coordinate frame to the main coordinate frame. The matrix elements are stored in the macros \verb|\raaeul| through \verb|\rcceul|. This transformation is used in the \verb|\tdplotsetrotatedcoords| command, and is accessed using \verb|\tdplottransformrotmain|.
812 \end{description}
813
814 \subsection{\texttt{tdplotcalctransformmainscreen}}
815
816 \begin{description}
817 \item[Description:] Calculates the rotation matrix used to define the main coordinate frame, as well as transform a coordinate from the main coordinate frame to the screen coordinate frame. The matrix elements are stored in the macros \verb|\raarot| through \verb|\rccrot|. This transformation is used in the \verb|\tdplotsetmaincoords| command, and is accessed using \verb|\tdplottransformmainscreen|.
818 \end{description}
819
820
821 \section{Point Calculation Commands}
822
823 \subsection{\texttt{tdplotsetcoord}}
824
825 \begin{description}
826 \item[Description:] Generates a TikZ coordinate of specified name, along with coordinates for the $x-$, $y-$, $z-$, $xy-$, $xz-$, and $yz-$ projections of the coordinate, based on user-specified spherical coordinates. Note that this coordinate only works in the main coordinate system. All points in the rotated coordinate system must be specified as literal points.
827 \item[Syntax:] \verb|\tdplotsetcoord{point}{|$r$\verb|}{|$\theta$\verb|}{|$\phi$\verb|}|
828 \item[Parameters:]~
829 \begin{description}
830 \item[\texttt{point}] The name of the TikZ coordinate to be assigned. Note that the $()$ parentheses must be excluded.
831 \item[$r$] Point radius.
832 \item[$\theta$] Point polar angle.
833 \item[$\phi$] Point azimuthal angle.
834 \end{description}
835 \item[Example:] ~
836 \begin{shaded}
837 \begin{verbatim}
838 \tdplotsetmaincoords{60}{130}
839 \begin{tikzpicture}[scale=2,tdplot_main_coords]
840
841 \coordinate (O) at (0,0,0);
842
843 \tdplotsetcoord{P}{.8}{55}{60}
844
845 \draw[thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};
846 \draw[thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};
847 \draw[thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};
848
849 \draw[-stealth,color=red] (O) -- (P);
850
851 \draw[dashed, color=red] (O) -- (Px);
852 \draw[dashed, color=red] (O) -- (Py);
853 \draw[dashed, color=red] (O) -- (Pz);
854 \draw[dashed, color=red] (Px) -- (Pxy);
855 \draw[dashed, color=red] (Py) -- (Pxy);
856 \draw[dashed, color=red] (Px) -- (Pxz);
857 \draw[dashed, color=red] (Pz) -- (Pxz);
858 \draw[dashed, color=red] (Py) -- (Pyz);
859 \draw[dashed, color=red] (Pz) -- (Pyz);
860 \draw[dashed, color=red] (Pxy) -- (P);
861 \draw[dashed, color=red] (Pxz) -- (P);
862 \draw[dashed, color=red] (Pyz) -- (P);
863 \end{tikzpicture}
864 \end{verbatim}
865 \tdplotsetmaincoords{60}{130}
866 \begin{tikzpicture}[scale=2,tdplot_main_coords]
867
868 \coordinate (O) at (0,0,0);
869
870 \tdplotsetcoord{P}{.8}{55}{60}
871
872 \draw[thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};
873 \draw[thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};
874 \draw[thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};
875
876 \draw[-stealth,color=red] (O) -- (P);
877
878 \draw[dashed, color=red] (O) -- (Px);
879 \draw[dashed, color=red] (O) -- (Py);
880 \draw[dashed, color=red] (O) -- (Pz);
881 \draw[dashed, color=red] (Px) -- (Pxy);
882 \draw[dashed, color=red] (Py) -- (Pxy);
883 \draw[dashed, color=red] (Px) -- (Pxz);
884 \draw[dashed, color=red] (Pz) -- (Pxz);
885 \draw[dashed, color=red] (Py) -- (Pyz);
886 \draw[dashed, color=red] (Pz) -- (Pyz);
887 \draw[dashed, color=red] (Pxy) -- (P);
888 \draw[dashed, color=red] (Pxz) -- (P);
889 \draw[dashed, color=red] (Pyz) -- (P);
890 \end{tikzpicture}
891 \end{shaded}
892 \end{description}
893
894
895 \subsection{\texttt{tdplottransformmainrot}}
896
897 \begin{description}
898 \item[Description:] Transforms a coordinate from the main coordinate frame to the rotated coordinate frame. This command cannot use a \tikzname\ coordinate, and does not account for a shifted rotated coordinate frame. The results are stored in the \verb|\tdplotresx|, \verb|\tdplotresy|, and \verb|\tdplotresz| macros.
899 \item[Syntax:] \verb|\tdplottransformmainrot{x}{y}{z}|
900 \item[Parameters:]~
901 \begin{description}
902 \item[x] The x-component of the coordinate in the main coordinate frame.
903 \item[y] The y-component of the coordinate in the main coordinate frame.
904 \item[z] The z-component of the coordinate in the main coordinate frame.
905 \end{description}
906 \item[Output:] The following macros are assigned:
907 \begin{description}
908 \item[\texttt{tdplotresx}] The transformed coordinate x component in the rotated coordinate frame.
909 \item[\texttt{tdplotresy}] The transformed coordinate y component in the rotated coordinate frame.
910 \item[\texttt{tdplotresz}] The transformed coordinate z component in the rotated coordinate frame.
911 \end{description}
912 \item[Example:] ~
913 \begin{shaded}
914 \begin{verbatim}
915 \tdplotsetmaincoords{50}{140}
916 \begin{tikzpicture}[scale=2,tdplot_main_coords]
917
918 \draw[thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};
919 \draw[thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};
920 \draw[thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};
921
922 \pgfmathsetmacro{\ax}{2}
923 \pgfmathsetmacro{\ay}{2}
924 \pgfmathsetmacro{\az}{1}
925
926 \tdplotsetrotatedcoords{20}{40}{00}
927
928 \draw[thick,color=red,tdplot_rotated_coords,->] (0,0,0)
929 -- (.7,0,0) node[anchor=east]{$x'$};
930 \draw[thick,color=green!50!black,tdplot_rotated_coords,->] (0,0,0)
931 -- (0,.7,0) node[anchor=west]{$y'$};
932 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0)
933 -- (0,0,.7) node[anchor=south]{$z'$};
934
935
936 \tdplottransformmainrot{\ax}{\ay}{\az}
937
938 \draw[tdplot_rotated_coords,->,blue!50] (0,0,0)
939 -- (\tdplotresx,\tdplotresy,\tdplotresz);
940
941 \node[tdplot_main_coords,anchor=south]
942 at (\ax,\ay,\az){Main coords: (\ax, \ay, \az)};
943 \node[tdplot_rotated_coords,anchor=north]
944 at (\tdplotresx,\tdplotresy,\tdplotresz)
945 {Rotated coords: (\tdplotresx, \tdplotresy, \tdplotresz)};
946
947 \end{tikzpicture}
948 \end{verbatim}
949 \tdplotsetmaincoords{50}{140}
950 \begin{tikzpicture}[scale=2,tdplot_main_coords]
951
952 \draw[thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};
953 \draw[thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};
954 \draw[thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};
955
956 \pgfmathsetmacro{\ax}{2}
957 \pgfmathsetmacro{\ay}{2}
958 \pgfmathsetmacro{\az}{1}
959
960 \tdplotsetrotatedcoords{20}{40}{00}
961
962 \draw[thick,color=red,tdplot_rotated_coords,->] (0,0,0)
963 -- (.7,0,0) node[anchor=east]{$x'$};
964 \draw[thick,color=green!50!black,tdplot_rotated_coords,->] (0,0,0)
965 -- (0,.7,0) node[anchor=west]{$y'$};
966 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0)
967 -- (0,0,.7) node[anchor=south]{$z'$};
968
969
970 \tdplottransformmainrot{\ax}{\ay}{\az}
971
972 \draw[tdplot_rotated_coords,->,blue!50] (0,0,0)
973 -- (\tdplotresx,\tdplotresy,\tdplotresz);
974
975 \node[tdplot_main_coords,anchor=south]
976 at (\ax,\ay,\az){Main coords: (\ax, \ay, \az)};
977 \node[tdplot_rotated_coords,anchor=north]
978 at (\tdplotresx,\tdplotresy,\tdplotresz)
979 {Rotated coords: (\tdplotresx, \tdplotresy, \tdplotresz)};
980
981 \end{tikzpicture}
982 \end{shaded}
983 \end{description}
984
985
986 \subsection{\texttt{tdplottransformrotmain}}
987
988 \begin{description}
989 \item[Description:] Transforms a coordinate from the rotated coordinate frame to the main coordinate frame. This command cannot use a \tikzname\ coordinate, and does not account for a shifted rotated coordinate frame. The results are stored in the \verb|\tdplotresx|, \verb|\tdplotresy|, and \verb|\tdplotresz| macros.
990 \item[Syntax:] \verb|\tdplottransformrotmain{x}{y}{z}|
991 \item[Parameters:]~
992 \begin{description}
993 \item[x] The x-component of the coordinate in the rotated coordinate frame.
994 \item[y] The y-component of the coordinate in the rotated coordinate frame.
995 \item[z] The z-component of the coordinate in the rotated coordinate frame.
996 \end{description}
997 \item[Output:] The following macros are assigned:
998 \begin{description}
999 \item[\texttt{tdplotresx}] The transformed coordinate x component in the main coordinate frame.
1000 \item[\texttt{tdplotresy}] The transformed coordinate y component in the main coordinate frame.
1001 \item[\texttt{tdplotresz}] The transformed coordinate z component in the main coordinate frame.
1002 \end{description}
1003 \item[Example:] ~
1004 \begin{shaded}
1005 \begin{verbatim}
1006 \tdplotsetmaincoords{50}{140}
1007 \begin{tikzpicture}[scale=2,tdplot_main_coords]
1008
1009 \draw[thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};
1010 \draw[thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};
1011 \draw[thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};
1012
1013 \pgfmathsetmacro{\ax}{-.75}
1014 \pgfmathsetmacro{\ay}{2.5}
1015 \pgfmathsetmacro{\az}{0}
1016
1017 \tdplotsetrotatedcoords{20}{40}{00}
1018
1019 \draw[thick,color=red,tdplot_rotated_coords,->] (0,0,0)
1020 -- (.7,0,0) node[anchor=east]{$x'$};
1021 \draw[thick,color=green!50!black,tdplot_rotated_coords,->] (0,0,0)
1022 -- (0,.7,0) node[anchor=west]{$y'$};
1023 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0)
1024 -- (0,0,.7) node[anchor=south]{$z'$};
1025
1026
1027 \tdplottransformrotmain{\ax}{\ay}{\az}
1028
1029 \draw[tdplot_main_coords,->,blue!50] (0,0,0)
1030 -- (\tdplotresx,\tdplotresy,\tdplotresz);
1031
1032 \node[tdplot_rotated_coords,anchor=north]
1033 at (\ax,\ay,\az){Rotated coords: (\ax, \ay, \az)};
1034 \node[tdplot_main_coords,anchor=south]
1035 at (\tdplotresx,\tdplotresy,\tdplotresz)
1036 {Main coords: (\tdplotresx, \tdplotresy, \tdplotresz)};
1037
1038
1039 \end{tikzpicture}
1040 \end{verbatim}
1041 \tdplotsetmaincoords{50}{140}
1042 \begin{tikzpicture}[scale=2,tdplot_main_coords]
1043
1044 \draw[thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};
1045 \draw[thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};
1046 \draw[thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};
1047
1048 \pgfmathsetmacro{\ax}{-.75}
1049 \pgfmathsetmacro{\ay}{2.5}
1050 \pgfmathsetmacro{\az}{0}
1051
1052 \tdplotsetrotatedcoords{20}{40}{00}
1053
1054 \draw[thick,color=red,tdplot_rotated_coords,->] (0,0,0)
1055 -- (.7,0,0) node[anchor=east]{$x'$};
1056 \draw[thick,color=green!50!black,tdplot_rotated_coords,->] (0,0,0)
1057 -- (0,.7,0) node[anchor=west]{$y'$};
1058 \draw[thick,color=blue,tdplot_rotated_coords,->] (0,0,0)
1059 -- (0,0,.7) node[anchor=south]{$z'$};
1060
1061
1062 \tdplottransformrotmain{\ax}{\ay}{\az}
1063
1064 \draw[tdplot_main_coords,->,blue!50] (0,0,0)
1065 -- (\tdplotresx,\tdplotresy,\tdplotresz);
1066
1067 \node[tdplot_rotated_coords,anchor=north]
1068 at (\ax,\ay,\az){Rotated coords: (\ax, \ay, \az)};
1069 \node[tdplot_main_coords,anchor=south]
1070 at (\tdplotresx,\tdplotresy,\tdplotresz)
1071 {Main coords: (\tdplotresx, \tdplotresy, \tdplotresz)};
1072
1073
1074 \end{tikzpicture}
1075 \end{shaded}
1076 \end{description}
1077
1078
1079 \subsection{\texttt{tdplottransformmainscreen}}
1080
1081 \begin{description}
1082 \item[Description:] Transforms a coordinate from the main coordinate frame to the screen coordinate frame. This command cannot use a \tikzname\ coordinate. The results are stored in the \verb|\tdplotresx| and \verb|\tdplotresy| macros.
1083 \item[Syntax:] \verb|\tdplottransformmainscreen{x}{y}{z}|
1084 \item[Parameters:]~
1085 \begin{description}
1086 \item[x] The x-component of the coordinate in the main coordinate frame.
1087 \item[y] The y-component of the coordinate in the main coordinate frame.
1088 \item[z] The z-component of the coordinate in the main coordinate frame.
1089 \end{description}
1090 \item[Output:] The following macros are assigned:
1091 \begin{description}
1092 \item[\texttt{tdplotresx}] The transformed coordinate x component in the screen coordinate frame.
1093 \item[\texttt{tdplotresy}] The transformed coordinate y component in the screen coordinate frame.
1094 \end{description}
1095 \item[Example:] ~
1096 \begin{shaded}
1097 \begin{verbatim}
1098 \tdplotsetmaincoords{50}{140}
1099 \begin{tikzpicture}[scale=2,tdplot_main_coords]
1100
1101 \draw[thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};
1102 \draw[thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};
1103 \draw[thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};
1104
1105 \pgfmathsetmacro{\ax}{2}
1106 \pgfmathsetmacro{\ay}{3}
1107 \pgfmathsetmacro{\az}{1}
1108
1109 \tdplottransformmainscreen{\ax}{\ay}{\az}
1110
1111 \draw[tdplot_screen_coords,->,blue!50] (0,0)
1112 -- (\tdplotresx,\tdplotresy);
1113
1114 \node[tdplot_main_coords,anchor=south]
1115 at (\ax,\ay,\az){Main coords: (\ax, \ay, \az)};
1116 \node[tdplot_screen_coords,anchor=north]
1117 at (\tdplotresx,\tdplotresy)
1118 {Screen coords: (\tdplotresx, \tdplotresy)};
1119
1120 \end{tikzpicture}
1121 \end{verbatim}
1122 \tdplotsetmaincoords{50}{140}
1123 \begin{tikzpicture}[scale=2,tdplot_main_coords]
1124
1125 \draw[thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};
1126 \draw[thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};
1127 \draw[thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};
1128
1129 \pgfmathsetmacro{\ax}{2}
1130 \pgfmathsetmacro{\ay}{3}
1131 \pgfmathsetmacro{\az}{1}
1132
1133 \tdplottransformmainscreen{\ax}{\ay}{\az}
1134
1135 \draw[tdplot_screen_coords,->,blue!50] (0,0)
1136 -- (\tdplotresx,\tdplotresy);
1137
1138 \node[tdplot_main_coords,anchor=south]
1139 at (\ax,\ay,\az){Main coords: (\ax, \ay, \az)};
1140 \node[tdplot_screen_coords,anchor=north]
1141 at (\tdplotresx,\tdplotresy)
1142 {Screen coords: (\tdplotresx, \tdplotresy)};
1143
1144 \end{tikzpicture}
1145 \end{shaded}
1146 \end{description}
1147
1148 \subsection{\texttt{tdplotgetpolarcoords}}
1149
1150 \begin{description}
1151 \item[Description:] Calculates the $\theta$ polar coordinate for the specified point. The result is specified in the \verb|\tdplotrestheta| macro.
1152 \item[Syntax:] \verb|\tdplotgetpolarcoords{x}{y}{z}|
1153 \item[Parameters:]~
1154 \begin{description}
1155 \item[x] The x-component of the coordinate.
1156 \item[y] The y-component of the coordinate.
1157 \item[z] The z-component of the coordinate.
1158 \end{description}
1159 \item[Output:]
1160 \begin{description}
1161 \item[\texttt{tdplotrestheta}] The $\theta$ polar coordinate.
1162 \item[\texttt{tdplotresphi}] The $\phi$ polar coordinate.
1163 \end{description}
1164 \item[Example:] ~
1165 \begin{shaded}
1166 \begin{verbatim}
1167 \tdplotsetmaincoords{70}{110}
1168 \begin{tikzpicture}[tdplot_main_coords]
1169
1170 \draw[thick,->] (0,0,0) -- (3,0,0) node[anchor=north east]{$x$};
1171 \draw[thick,->] (0,0,0) -- (0,3,0) node[anchor=north west]{$y$};
1172 \draw[thick,->] (0,0,0) -- (0,0,3) node[anchor=south]{$z$};
1173
1174 \pgfmathsetmacro{\ax}{1}
1175 \pgfmathsetmacro{\ay}{1}
1176 \pgfmathsetmacro{\az}{1}
1177
1178 \draw[->,red] (0,0,0) -- (\ax,\ay,\az);
1179
1180 \draw[dashed,red] (0,0,0) -- (\ax,\ay,0) -- (\ax,\ay,\az);
1181
1182 \tdplotgetpolarcoords{\ax}{\ay}{\az}
1183
1184 \tdplotsetthetaplanecoords{\tdplotresphi}
1185
1186 \tdplotdrawarc[tdplot_rotated_coords]{(0,0,0)}{1}{0}%
1187 {\tdplotrestheta}{anchor=west}{$\theta = \tdplotrestheta$}
1188 \end{tikzpicture}
1189 \end{verbatim}
1190 \tdplotsetmaincoords{70}{110}
1191 \begin{tikzpicture}[tdplot_main_coords]
1192
1193 \draw[thick,->] (0,0,0) -- (3,0,0) node[anchor=north east]{$x$};
1194 \draw[thick,->] (0,0,0) -- (0,3,0) node[anchor=north west]{$y$};
1195 \draw[thick,->] (0,0,0) -- (0,0,3) node[anchor=south]{$z$};
1196
1197 \pgfmathsetmacro{\ax}{1}
1198 \pgfmathsetmacro{\ay}{1}
1199 \pgfmathsetmacro{\az}{1}
1200
1201 \draw[->,red] (0,0,0) -- (\ax,\ay,\az);
1202
1203 \draw[dashed,red] (0,0,0) -- (\ax,\ay,0) -- (\ax,\ay,\az);
1204
1205 \tdplotgetpolarcoords{\ax}{\ay}{\az}
1206
1207 \tdplotdrawarc{(0,0,0)}{1}{0}%
1208 {\tdplotresphi}{anchor=north}{$\phi = \tdplotresphi$}
1209
1210 \tdplotsetthetaplanecoords{\tdplotresphi}
1211
1212 \tdplotdrawarc[tdplot_rotated_coords]{(0,0,0)}{1}{0}%
1213 {\tdplotrestheta}{anchor=west}{$\theta = \tdplotrestheta$}
1214 \end{tikzpicture}
1215 \end{shaded}
1216 \end{description}
1217
1218
1219 \subsection{\texttt{tdplotcrossprod}}
1220
1221 \begin{description}
1222 \item[Description:] Calculates the cross product of two vectors specified by two coordinates with respect to the origin. The result vector is specified by the coordinates \verb|\tdplotresx|, \verb|\tdplotresy|, and \verb|\tdplotresz| with respect to the origin.
1223 \item[Syntax:] \verb|\tdplotcrossprod(|$a_x$\verb|,|$a_y$\verb|,|$a_z$\verb|)(|$b_x$\verb|,|$b_y$\verb|,|$b_z$\verb|)|
1224 \item[Parameters:]~
1225 \begin{description}
1226 \item[$a_x$] The x-component of the first vector with respect to the origin.
1227 \item[$a_y$] The y-component of the first vector with respect to the origin.
1228 \item[$a_z$] The z-component of the first vector with respect to the origin.
1229 \item[$b_x$] The x-component of the second vector with respect to the origin.
1230 \item[$b_y$] The y-component of the second vector with respect to the origin.
1231 \item[$b_z$] The z-component of the second vector with respect to the origin.
1232 \end{description}
1233 \item[Output:] The following macros are assigned.
1234 \begin{description}
1235 \item[\texttt{tdplotresx}] The x-component of the cross product with respect to the origin.
1236 \item[\texttt{tdplotresy}] The y-component of the cross product with respect to the origin.
1237 \item[\texttt{tdplotresz}] The z-component of the cross product with respect to the origin.
1238 \end{description}
1239 \item[Example:] ~
1240 \begin{shaded}
1241 \begin{verbatim}
1242 \tdplotsetmaincoords{50}{110}
1243 \begin{tikzpicture}[tdplot_main_coords]
1244
1245 \draw[thick,->] (0,0,0) -- (3,0,0) node[anchor=north east]{$x$};
1246 \draw[thick,->] (0,0,0) -- (0,3,0) node[anchor=north west]{$y$};
1247 \draw[thick,->] (0,0,0) -- (0,0,3) node[anchor=south]{$z$};
1248
1249 \pgfmathsetmacro{\ax}{1}
1250 \pgfmathsetmacro{\ay}{1}
1251 \pgfmathsetmacro{\az}{.4}
1252 \pgfmathsetmacro{\bx}{-1}
1253 \pgfmathsetmacro{\by}{1}
1254 \pgfmathsetmacro{\bz}{.6}
1255
1256 \tdplotcrossprod(\ax,\ay,\az)(\bx,\by,\bz)
1257
1258 \draw[->,red] (0,0,0) -- (\ax,\ay,\az) node[anchor=west]{$\vec{A}$};
1259 \draw[dashed,red] (0,0,0) -- (\ax,\ay,0) -- (\ax,\ay,\az);
1260 \draw[->,green!50!black] (0,0,0) --
1261 (\bx,\by,\bz) node[anchor=south west]{$\vec{B}$};
1262 \draw[dashed,green!50!black] (0,0,0) -- (\bx,\by,0) -- (\bx,\by,\bz);
1263
1264 \draw[->,blue] (0,0,0) -- (\tdplotresx,\tdplotresy,\tdplotresz)
1265 node[anchor=south east]{$\vec{A}\times\vec{B}$};
1266 \draw[dashed,blue] (0,0,0) -- (\tdplotresx,\tdplotresy,0)
1267 -- (\tdplotresx,\tdplotresy,\tdplotresz);
1268 \end{tikzpicture}
1269 \end{verbatim}
1270 \tdplotsetmaincoords{50}{110}
1271 \begin{tikzpicture}[tdplot_main_coords]
1272
1273 \draw[thick,->] (0,0,0) -- (3,0,0) node[anchor=north east]{$x$};
1274 \draw[thick,->] (0,0,0) -- (0,3,0) node[anchor=north west]{$y$};
1275 \draw[thick,->] (0,0,0) -- (0,0,3) node[anchor=south]{$z$};
1276
1277 \pgfmathsetmacro{\ax}{1}
1278 \pgfmathsetmacro{\ay}{1}
1279 \pgfmathsetmacro{\az}{.4}
1280 \pgfmathsetmacro{\bx}{-1}
1281 \pgfmathsetmacro{\by}{1}
1282 \pgfmathsetmacro{\bz}{.6}
1283
1284 \tdplotcrossprod(\ax,\ay,\az)(\bx,\by,\bz)
1285
1286 \draw[->,red] (0,0,0) -- (\ax,\ay,\az) node[anchor=west]{$\vec{A}$};
1287 \draw[dashed,red] (0,0,0) -- (\ax,\ay,0) -- (\ax,\ay,\az);
1288 \draw[->,green!50!black] (0,0,0) --
1289 (\bx,\by,\bz) node[anchor=south west]{$\vec{B}$};
1290 \draw[dashed,green!50!black] (0,0,0) -- (\bx,\by,0) -- (\bx,\by,\bz);
1291
1292 \draw[->,blue] (0,0,0) -- (\tdplotresx,\tdplotresy,\tdplotresz)
1293 node[anchor=south east]{$\vec{A}\times\vec{B}$};
1294 \draw[dashed,blue] (0,0,0) -- (\tdplotresx,\tdplotresy,0)
1295 -- (\tdplotresx,\tdplotresy,\tdplotresz);
1296 \end{tikzpicture}
1297 \end{shaded}
1298 \end{description}
1299
1300 \subsection{\texttt{tdplotdefinepoints}}
1301
1302 \begin{description}
1303 \item[Description:] Assigns the values of three coordinates, to be used in the \verb|\tdplotdrawpolytopearc|
1304 \item[Syntax:] \verb|\tdplotdefinepoints(|$v_x$\verb|,|$v_y$\verb|,|$v_z$\verb|)(|$a_x$\verb|,|$a_y$\verb|,|$a_z$\verb|)(|$b_x$\verb|,|$b_y$\verb|,|$b_z$\verb|)|
1305 \item[Parameters:]~
1306 \begin{description}
1307 \item[$v_x$] The x-component of the vertex.
1308 \item[$v_y$] The y-component of the vertex.
1309 \item[$v_z$] The z-component of the vertex.
1310 \item[$a_x$] The x-component of the first point.
1311 \item[$a_y$] The y-component of the first point.
1312 \item[$a_z$] The z-component of the first point.
1313 \item[$b_x$] The x-component of the second point.
1314 \item[$b_y$] The y-component of the second point.
1315 \item[$b_z$] The z-component of the second point.
1316 \end{description}
1317 \item[Output:] The following macros are assigned:
1318 \begin{description}
1319 \item[\texttt{tdplotvertexx}] The x-component of the vertex.
1320 \item[\texttt{tdplotvertexy}] The y-component of the vertex.
1321 \item[\texttt{tdplotvertexz}] The z-component of the vertex.
1322 \item[\texttt{tdplotax}] The x-component of the first point.
1323 \item[\texttt{tdplotay}] The y-component of the first point.
1324 \item[\texttt{tdplotaz}] The z-component of the first point.
1325 \item[\texttt{tdplotbx}] The x-component of the second point.
1326 \item[\texttt{tdplotby}] The y-component of the second point.
1327 \item[\texttt{tdplotbz}] The z-component of the second point.
1328 \end{description}\end{description}
1329
1330
1331 \section{Drawing Commands}
1332
1333 Along with all the conventional \tikzname\ drawing commands, the following \tdplot\ commands can be used.
1334
1335 \subsection{\texttt{tdplotdrawarc}}
1336
1337 \begin{description}
1338 \item[Description:] Draws an arc in the $xy$ (or optionally $x'y'$) plane starting from the specified polar angle $\phi$, of specified radius and angular length, at specified center point, and labels the arc with specified node text and options. By default, draws in the main coordinate frame, but can draw in the rotated coordinate frame by specifying \verb|tdplot_rotated_coords| in the option field.
1339 \item[Syntax:] \verb|\tdplotdrawarc[coordinate system, draw styles]{center}{r}|\\\verb|{angle start}{angle end}{label options}{label}|
1340 \item[Parameters:]~
1341 \begin{description}
1342 \item[(\textit{Optional}) coordinate system,draw styles] Optional argument containing the name of the coordinate system to use (default is main coordinate system), and any optional draw styles.
1343 \item[center] Center point through which to draw the arc. If using the rotated coordinate system, this must be a literal value.
1344 \item[r] The arc radius of curvature.
1345 \item[angle start] the initial angle (in degrees) through which to draw. 0 points along the $x$ (or $x'$) axis.
1346 \item[angle end] the final angle (in degrees) through which to draw.
1347 \item[label options] any style options for a \tikzname \verb|\node| object. If none, make sure to leave a blank delimiter \verb|{}| in its place.
1348 \item[label] any text for the \tikzname\ \verb|\node| which appears at the center of the arc. If none, make sure to leave a blank delimiter \verb|{}| in its place.
1349 \end{description}
1350 \item[Example:]~
1351 \begin{shaded}
1352 \begin{verbatim}
1353 \tdplotsetmaincoords{60}{110}
1354 %
1355 \pgfmathsetmacro{\rvec}{.8}
1356 \pgfmathsetmacro{\thetavec}{30}
1357 \pgfmathsetmacro{\phivec}{60}
1358 %
1359 \begin{tikzpicture}[scale=5,tdplot_main_coords]
1360
1361 \coordinate (O) at (0,0,0);
1362
1363 \draw[thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};
1364 \draw[thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};
1365 \draw[thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};
1366
1367 \tdplotsetcoord{P}{\rvec}{\thetavec}{\phivec}
1368 \draw[-stealth,color=red] (O) -- (P);
1369 \draw[dashed, color=red] (O) -- (Pxy);
1370 \draw[dashed, color=red] (P) -- (Pxy);
1371
1372 \tdplotdrawarc{(O)}{0.2}{0}{\phivec}{anchor=north}{$\phi$}
1373
1374 \tdplotsetthetaplanecoords{\phivec}
1375
1376 \tdplotdrawarc[tdplot_rotated_coords]{(0,0,0)}{0.5}{0}%
1377 {\thetavec}{anchor=south west}{$\theta$}
1378
1379 \draw[dashed,tdplot_rotated_coords] (\rvec,0,0) arc (0:90:\rvec);
1380 \draw[dashed] (\rvec,0,0) arc (0:90:\rvec);
1381
1382 \tdplotsetrotatedcoords{\phivec}{\thetavec}{0}
1383 \tdplotsetrotatedcoordsorigin{(P)}
1384
1385 \draw[thick,tdplot_rotated_coords,->] (0,0,0)
1386 -- (.5,0,0) node[anchor=north west]{$x'$};
1387 \draw[thick,tdplot_rotated_coords,->] (0,0,0)
1388 -- (0,.5,0) node[anchor=west]{$y'$};
1389 \draw[thick,tdplot_rotated_coords,->] (0,0,0)
1390 -- (0,0,.5) node[anchor=south]{$z'$};
1391
1392 \draw[-stealth,color=blue,tdplot_rotated_coords] (0,0,0) -- (.2,.2,.2);
1393 \draw[dashed,color=blue,tdplot_rotated_coords] (0,0,0) -- (.2,.2,0);
1394 \draw[dashed,color=blue,tdplot_rotated_coords] (.2,.2,0) -- (.2,.2,.2);
1395
1396 \tdplotdrawarc[tdplot_rotated_coords,color=blue]{(0,0,0)}{0.2}{0}%
1397 {45}{anchor=north west,color=black}{$\phi'$}
1398
1399 \tdplotsetrotatedthetaplanecoords{45}
1400
1401 \tdplotdrawarc[tdplot_rotated_coords,color=blue]{(0,0,0)}{0.2}{0}%
1402 {55}{anchor=south west,color=black}{$\theta'$}
1403 \end{tikzpicture}
1404 \end{verbatim}
1405 \tdplotsetmaincoords{60}{110}
1406 %
1407 \pgfmathsetmacro{\rvec}{.8}
1408 \pgfmathsetmacro{\thetavec}{30}
1409 \pgfmathsetmacro{\phivec}{60}
1410 %
1411 \begin{tikzpicture}[scale=5,tdplot_main_coords]
1412
1413 \coordinate (O) at (0,0,0);
1414
1415 \draw[thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};
1416 \draw[thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};
1417 \draw[thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};
1418
1419 \tdplotsetcoord{P}{\rvec}{\thetavec}{\phivec}
1420 \draw[-stealth,color=red] (O) -- (P);
1421 \draw[dashed, color=red] (O) -- (Pxy);
1422 \draw[dashed, color=red] (P) -- (Pxy);
1423
1424 \tdplotdrawarc{(O)}{0.2}{0}{\phivec}{anchor=north}{$\phi$}
1425
1426 \tdplotsetthetaplanecoords{\phivec}
1427
1428 \tdplotdrawarc[tdplot_rotated_coords]{(0,0,0)}{0.5}{0}{\thetavec}{anchor=south west}{$\theta$}
1429
1430 \draw[dashed,tdplot_rotated_coords] (\rvec,0,0) arc (0:90:\rvec);
1431 \draw[dashed] (\rvec,0,0) arc (0:90:\rvec);
1432
1433 \tdplotsetrotatedcoords{\phivec}{\thetavec}{0}
1434 \tdplotsetrotatedcoordsorigin{(P)}
1435
1436 \draw[thick,tdplot_rotated_coords,->] (0,0,0) -- (.5,0,0) node[anchor=north west]{$x'$};
1437 \draw[thick,tdplot_rotated_coords,->] (0,0,0) -- (0,.5,0) node[anchor=west]{$y'$};
1438 \draw[thick,tdplot_rotated_coords,->] (0,0,0) -- (0,0,.5) node[anchor=south]{$z'$};
1439
1440 \draw[-stealth,color=blue,tdplot_rotated_coords] (0,0,0) -- (.2,.2,.2);
1441 \draw[dashed,color=blue,tdplot_rotated_coords] (0,0,0) -- (.2,.2,0);
1442 \draw[dashed,color=blue,tdplot_rotated_coords] (.2,.2,0) -- (.2,.2,.2);
1443
1444 \tdplotdrawarc[tdplot_rotated_coords,color=blue]{(0,0,0)}{0.2}{0}{45}{anchor=north west,color=black}{$\phi'$}
1445
1446 \tdplotsetrotatedthetaplanecoords{45}
1447
1448 \tdplotdrawarc[tdplot_rotated_coords,color=blue]{(0,0,0)}{0.2}{0}{55}{anchor=south west,color=black}{$\theta'$}
1449 \end{tikzpicture}
1450 \end{shaded}
1451 \end{description}
1452
1453
1454 \subsection{\texttt{tdplotdrawpolytopearc}}
1455
1456 \begin{description}
1457 \item[Description:] Draws an arc using three user-specified points and a radius. A vertex determines the center of curvature, while two points define the angular extent and the plane of the arc. The three points must be specified in the corresponding macros before this command is issued.
1458 \item[Prerequisites:] The three points must be specified by using the \verb|\tdplotdefinepoints| command.
1459 \item[Syntax:] \verb|\tdplotdrawpolytopearc[draw style]{r}{label options}{label}|
1460 \item[Parameters:]~
1461 \begin{description}
1462 \item[(\textit{Optional}) draw styles] Optional argument containing draw styles for rendering the arc.
1463 \item[r] The arc radius of curvature.
1464 \item[label options] any style options for a \tikzname \verb|\node| object. If none, make sure to leave a blank delimiter \verb|{}| in its place.
1465 \item[label] any text for the \tikzname\ \verb|\node| which appears at the center of the arc. If none, make sure to leave a blank delimiter \verb|{}| in its place.
1466 \end{description}
1467 \item[Example:]~
1468 \begin{shaded}
1469 \begin{verbatim}
1470 \tdplotsetmaincoords{60}{110}
1471 \begin{tikzpicture}[tdplot_main_coords]
1472
1473 \draw[thick,->] (0,0,0) -- (5,0,0) node[anchor=north east]{$x$};
1474 \draw[thick,->] (0,0,0) -- (0,5,0) node[anchor=north west]{$y$};
1475 \draw[thick,->] (0,0,0) -- (0,0,5) node[anchor=south]{$z$};
1476
1477 \tdplotdefinepoints(2,2,2)(3,5,1)(-1,5,3)
1478
1479 \draw[dashed] (0,0,0) -- (\tdplotvertexx,\tdplotvertexy,0) --
1480 (\tdplotvertexx,\tdplotvertexy,\tdplotvertexz);
1481 \draw[dashed] (0,0,0) -- (\tdplotax,\tdplotay,0)
1482 -- (\tdplotax,\tdplotay,\tdplotaz);
1483 \draw[dashed] (0,0,0) -- (\tdplotbx,\tdplotby,0)
1484 -- (\tdplotbx,\tdplotby,\tdplotbz);
1485
1486 \draw[->,red] (\tdplotvertexx,\tdplotvertexy,\tdplotvertexz)
1487 -- (\tdplotax,\tdplotay,\tdplotaz);
1488 \draw[->,green!50!black] (\tdplotvertexx,\tdplotvertexy,\tdplotvertexz)
1489 -- (\tdplotbx,\tdplotby,\tdplotbz);
1490
1491 \node[anchor=east] at (\tdplotvertexx,\tdplotvertexy,\tdplotvertexz){Vertex};
1492 \node[anchor=north west] at (\tdplotax,\tdplotay,\tdplotaz){A};
1493 \node[anchor=south west] at (\tdplotbx,\tdplotby,\tdplotbz){B};
1494
1495 \tdplotdrawpolytopearc[thick]{1}{anchor=west}{$\theta$}
1496 \end{tikzpicture}
1497 \end{verbatim}
1498 \tdplotsetmaincoords{60}{110}
1499 \begin{tikzpicture}[tdplot_main_coords]
1500
1501 \draw[thick,->] (0,0,0) -- (5,0,0) node[anchor=north east]{$x$};
1502 \draw[thick,->] (0,0,0) -- (0,5,0) node[anchor=north west]{$y$};
1503 \draw[thick,->] (0,0,0) -- (0,0,5) node[anchor=south]{$z$};
1504
1505 \tdplotdefinepoints(2,2,2)(3,5,1)(-1,5,3)
1506
1507 \draw[dashed] (0,0,0) -- (\tdplotvertexx,\tdplotvertexy,0) --
1508 (\tdplotvertexx,\tdplotvertexy,\tdplotvertexz);
1509 \draw[dashed] (0,0,0) -- (\tdplotax,\tdplotay,0)
1510 -- (\tdplotax,\tdplotay,\tdplotaz);
1511 \draw[dashed] (0,0,0) -- (\tdplotbx,\tdplotby,0)
1512 -- (\tdplotbx,\tdplotby,\tdplotbz);
1513
1514 \draw[->,red] (\tdplotvertexx,\tdplotvertexy,\tdplotvertexz)
1515 -- (\tdplotax,\tdplotay,\tdplotaz);
1516 \draw[->,green!50!black] (\tdplotvertexx,\tdplotvertexy,\tdplotvertexz)
1517 -- (\tdplotbx,\tdplotby,\tdplotbz);
1518
1519 \node[anchor=east] at (\tdplotvertexx,\tdplotvertexy,\tdplotvertexz){Vertex};
1520 \node[anchor=north west] at (\tdplotax,\tdplotay,\tdplotaz){A};
1521 \node[anchor=south west] at (\tdplotbx,\tdplotby,\tdplotbz){B};
1522
1523 \tdplotdrawpolytopearc[thick]{1}{anchor=west}{$\theta$}
1524 \end{tikzpicture}
1525 \end{shaded}
1526 \end{description}
1527
1528
1529
1530
1531
1532
1533 %make more!
1534 %\subsection{}
1535
1536 %\begin{description}
1537 % \item[Description:]
1538 % \item[Syntax:]
1539 % \item[Parameters:]
1540 % \begin{description}
1541 % \item[]
1542 % \end{description}
1543 %\end{description}
1544
1545 \section{The \texttt{tdplotsphericalsurfaceplot} Command}\label{sec:spherical_surface_plot}
1546
1547 The \verb|\tdplotsphericalsurfaceplot| command is quite complicated, and it seemed appropriate to occupy its own section. This command was initially developed to provide a method of rendering complex polar functions, $z = z(\theta,\phi)$, where the magnitude of the function is expressed by the radius, and the phase of the function is expressed by the hue, as
1548 %
1549 \begin{align}\begin{split}
1550 r &= \left|z(\theta,\phi)\right|\\
1551 hue &= \mathrm{Arg}\left[z(\theta,\phi)\right]
1552 \end{split}\end{align}
1553
1554 The command has been generalized so that the hue can be specified in terms of the three polar coordinates, as
1555 %
1556 \begin{align}\begin{split}
1557 r &= f(\theta,\phi)\\
1558 hue &= g(r,\theta,\phi)
1559 \end{split}\end{align}
1560
1561 \subsection{How \texttt{tdplotsphericalsurfaceplot} Works}
1562
1563 To achieve the illusion of a 3d surface with proper persistence of vision, the \tdplot\ package divides the drawing task into smaller sections. This division ensures the surface on the far side of the viewing perspective is properly occluded from view.
1564
1565 For a given perspective assigned by the main coordinate frame, a ``view orientation'' can be defined, giving the angles $(\theta_{view},\phi_{view})$ that describe the orientation of the view. These angles determine how to dubdivide the surface rendering process. The following divisions are made:
1566 %
1567 \begin{itemize}
1568 \item Divide the surface into ``front'' and ``back'', where the back is drawn before the front.
1569 \item Subdivide into ``left'' and ``right''.
1570 \item Subdivide further into ''top'' and ''bottom''.
1571 \end{itemize}
1572
1573 The entire back half is drawn before the front half. For each half, the entire left or right side is drawn. For each side, all $\theta$ angles are drawn in wedges for each $\phi$ angle. When the back half is rendered, the $\theta$ angle is swept from $\theta_{view}$ toward the poles. When the front half is rendered, the $\theta$ angle is swept from the poles toward $\theta_{view}$.
1574
1575 During this process, the $x$, $y$, and $z$ axes are drawn at the appropriate time, ensuring the axes are occluded properly by the shape. The draw instructions for these axes are specified as user-defined parameters for this command.
1576
1577 \subsection{Using \texttt{tdplotsphericalsurfaceplot}}
1578
1579 \begin{description}
1580 \item[Description:] Draws a user-specified spherical polar function, with user-specified fill hues. Angular range to be displayed is specified with the \verb|\tdplotsetpolarplotrange| command. The line thickness can be specified by issuing the \verb|\pgfsetlinewidth| PGF macro.
1581 \item[Syntax:] \verb|\tdplotsphericalsurfaceplot[fill color style]{theta steps}{phi steps}{function}|\\\verb|{line color}{fill color}{x axis}{y axis}{z axis}|
1582 \item[Parameters:]~
1583 \begin{description}
1584 \item[(\emph{Optional}) fill color style] Specifies whether \texttt{fill color} is a function of (\verb|\tdplotr|, \verb|\tdplottheta|, \verb|\tdplotphi|), or a direct \tikzname\ color. Set to \texttt{parametricfill} to enable functional coloring.
1585 \item[theta steps] The number of steps used to render the surface along the $\theta$ direction. For best results, this number should not be smaller than 12, and should be a factor of 360.
1586 \item[phi steps] The number of steps used to render the surface along the $\phi$ direction. For best results, this number should not be smaller than 12, and should be a factor of 360.
1587 \item[function] A mathematical expression, containing the variables \verb|\tdplottheta| and \verb|\tdplotphi|, used to define the radius of the surface for given angles. Note that the absolute value of the function is plotted.
1588 \item[line color] \tikzname\ color expression for surface lines.
1589 \item[fill color] When the option \textit{parametricfill} is used then this can be some mathematical expression containing \verb|\tdplottheta| and \verb|\tdplotphi|. If not, then this can be any \tikzname\ expression for color. Note that if the function specified by \texttt{function} is negative, a shift of 180 is applied to the color. To avoid this, make sure \texttt{function} is always positive.
1590 \item[x axis] Any draw commands used to render the $x$ axis.
1591 \item[y axis] Any draw commands used to render the $y$ axis.
1592 \item[z axis] Any draw commands used to render the $z$ axis.
1593 \end{description}
1594 \item[Example:]~
1595 \begin{shaded}
1596 \begin{verbatim}
1597 \tdplotsetmaincoords{70}{135}
1598 \begin{tikzpicture}[scale=2,line join=bevel,tdplot_main_coords, fill opacity=.5]
1599 \pgfsetlinewidth{.2pt}
1600 \tdplotsphericalsurfaceplot[parametricfill]{72}{36}%
1601 {sin(\tdplottheta)*cos(\tdplottheta)}{black}{\tdplotphi}%
1602 {\draw[color=black,thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};}%
1603 {\draw[color=black,thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};}%
1604 {\draw[color=black,thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};}%
1605 \node[tdplot_screen_coords,fill opacity=1] at (0,-1) {Parametric Fill in $\phi$};
1606 \end{tikzpicture}
1607 \begin{tikzpicture}[scale=2,tdplot_main_coords,line join=bevel,fill opacity=.8]
1608 \pgfsetlinewidth{.1pt}
1609 \tdplotsphericalsurfaceplot[parametricfill]{72}{36}%
1610 {0.5*abs(cos(\tdplottheta))}{black}{2*abs(\tdplotr)}%
1611 {\draw[color=black,thick,->] (0,0,0)
1612 -- (1,0,0) node[anchor=north east]{$x$};}%
1613 {\draw[color=black,thick,->] (0,0,0)
1614 -- (0,1,0) node[anchor=north west]{$y$};}%
1615 {\draw[color=black,thick,->] (0,0,0)
1616 -- (0,0,1) node[anchor=south]{$z$};}%
1617 \node[tdplot_screen_coords,fill opacity=1] at (0,-1) {Parametric Fill in $r$};
1618 \end{tikzpicture}
1619 \begin{tikzpicture}[scale=2,line join=bevel,tdplot_main_coords, fill opacity=.7]
1620 \pgfsetlinewidth{.4pt}
1621 \tdplotsphericalsurfaceplot{72}{24}%
1622 {0.5*cos(\tdplottheta)^2}{black}{red!80!black}%
1623 {\draw[color=black,thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};}%
1624 {\draw[color=black,thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};}%
1625 {\draw[color=black,thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};}%
1626
1627 \node[tdplot_screen_coords,fill opacity=1] at (0,-1) {Solid Fill};
1628 \end{tikzpicture}
1629 \end{verbatim}
1630 \ifpdf
1631 \beginpgfgraphicnamed{Figures/examplesurfaceplot}
1632 \tdplotsetmaincoords{70}{135}
1633 \begin{tikzpicture}[scale=2,line join=bevel,tdplot_main_coords, fill opacity=.5]
1634 \pgfsetlinewidth{.2pt}
1635 \tdplotsphericalsurfaceplot[parametricfill]{72}{36}%
1636 {sin(\tdplottheta)*cos(\tdplottheta)}{black}{\tdplotphi}%
1637 {\draw[color=black,thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};}%
1638 {\draw[color=black,thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};}%
1639 {\draw[color=black,thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};}%
1640 \node[tdplot_screen_coords,fill opacity=1] at (0,-1) {Parametric Fill in $\phi$};
1641 \end{tikzpicture}
1642 \begin{tikzpicture}[scale=2,tdplot_main_coords,line join=bevel,fill opacity=.8]
1643 \pgfsetlinewidth{.1pt}
1644 \tdplotsphericalsurfaceplot[parametricfill]{72}{36}%
1645 {0.5*abs(cos(\tdplottheta))}{black}{2*abs(\tdplotr)}%
1646 {\draw[color=black,thick,->] (0,0,0)
1647 -- (1,0,0) node[anchor=north east]{$x$};}%
1648 {\draw[color=black,thick,->] (0,0,0)
1649 -- (0,1,0) node[anchor=north west]{$y$};}%
1650 {\draw[color=black,thick,->] (0,0,0)
1651 -- (0,0,1) node[anchor=south]{$z$};}%
1652 \node[tdplot_screen_coords,fill opacity=1] at (0,-1) {Parametric Fill in $r$};
1653 \end{tikzpicture}
1654 \begin{tikzpicture}[scale=2,line join=bevel,tdplot_main_coords, fill opacity=.7]
1655 \pgfsetlinewidth{.4pt}
1656 \tdplotsphericalsurfaceplot{72}{24}%
1657 {0.5*cos(\tdplottheta)^2}{black}{red!80!black}%
1658 {\draw[color=black,thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};}%
1659 {\draw[color=black,thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};}%
1660 {\draw[color=black,thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};}%
1661
1662 \node[tdplot_screen_coords,fill opacity=1] at (0,-1) {Solid Fill};
1663 \end{tikzpicture}
1664 \endpgfgraphicnamed
1665 \fi
1666 \end{shaded}
1667 \end{description}
1668
1669 \subsection{The \texttt{tdplotsetpolarplotrange} Command}
1670
1671 \begin{description}
1672 \item[Description:] Defines the range of angles to be displayed when using \verb|\tdplotsphericalsurfaceplot|
1673 \item[Syntax:] \verb|\tdplotsetpolarplotrange{lowertheta}{uppertheta}{lowerphi}{upperphi}|
1674 \item[Parameters:]~
1675 \begin{description}
1676 \item[lowertheta] The lower limit for \verb|\tdplottheta|, in degrees.
1677 \item[uppertheta] The upper limit for \verb|\tdplottheta|, in degrees.
1678 \item[lowerphi] The lower limit for \verb|\tdplotphi|, in degrees.
1679 \item[upperphi] The upper limit for \verb|\tdplotphi|, in degrees.
1680 \end{description}
1681 \item[Example:]~
1682 \begin{shaded}
1683 \begin{verbatim}
1684 \tdplotsetmaincoords{60}{110}
1685 \begin{tikzpicture}[scale=2,line join=bevel,tdplot_main_coords,%
1686 fill opacity=.5]
1687
1688 \tdplotsetpolarplotrange{90}{180}{180}{360}
1689 \tdplotsphericalsurfaceplot[parametricfill]{72}{36}%
1690 {.5}{black}{\tdplotphi + 3*\tdplottheta}%
1691 {\draw[color=black,thick,->] (0,0,0)
1692 -- (1,0,0) node[anchor=north east]{$x$};}%
1693 {\draw[color=black,thick,->] (0,0,0)
1694 -- (0,1,0) node[anchor=north west]{$y$};}%
1695 {\draw[color=black,thick,->] (0,0,0)
1696 -- (0,0,1) node[anchor=south]{$z$};}%
1697 \end{tikzpicture}
1698 \end{verbatim}
1699 \ifpdf
1700 \beginpgfgraphicnamed{Figures/examplesurfaceplotrange}
1701 \tdplotsetmaincoords{70}{135}
1702 \begin{tikzpicture}[scale=2,line join=bevel,tdplot_main_coords, fill opacity=.5]
1703
1704 \tdplotsetpolarplotrange{90}{180}{180}{360}
1705 \tdplotsphericalsurfaceplot[parametricfill]{72}{36}%
1706 {.5}{black}{\tdplotphi + 3*\tdplottheta}%
1707 {\draw[color=black,thick,->] (0,0,0) -- (1,0,0) node[anchor=north east]{$x$};}%
1708 {\draw[color=black,thick,->] (0,0,0) -- (0,1,0) node[anchor=north west]{$y$};}%
1709 {\draw[color=black,thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};}%
1710 \end{tikzpicture}
1711 \endpgfgraphicnamed
1712 \fi
1713 \end{shaded}
1714 \end{description}
1715
1716 \subsection{The \texttt{tdplotresetpolarplotrange} Command}
1717
1718 \begin{description}
1719 \item[Description:] Resets the range of angles to the default full range when using \verb|\tdplotsphericalsurfaceplot|
1720 \item[Syntax:] \verb|\tdplotresetpolarplotrange|
1721 \end{description}
1722
1723 \subsection{The \texttt{tdplotshowargcolorguide} Command}
1724
1725 \begin{description}
1726 \item[Description:] Draws a ``color guide'' table which associates the hue of a parametric polar plot with an angle. Guide is drawn at user-specified screen coordinates with user-specified size. This guide is intended to illustrate the complex phase representation of the surface for a given $\theta$ and $\phi$ coordinate.
1727 \item[Syntax:] \verb|\tdplotshowargcolorguide{x position}{y position}{x size}{y size}|
1728 \item[Parameters:]~
1729 \begin{description}
1730 \item[x position] The x screen coordinate to place the lower-left corner of the guide.
1731 \item[y position] The y screen coordinate to place the lower-left corner of the guide.
1732 \item[x size] The width of the color guide.
1733 \item[y size] The height of the color guide.
1734 \end{description}
1735 \item[Example:] ~
1736 \begin{shaded}
1737 \begin{verbatim}
1738 \tdplotsetmaincoords{40}{0}
1739 \begin{tikzpicture}[scale=2,line join=bevel,tdplot_main_coords,%
1740 fill opacity=1]
1741 \tdplotsphericalsurfaceplot[parametricfill]{72}{36}%
1742 {sqrt(15/2)/2*sin(\tdplottheta)^2}{black}%
1743 {2*\tdplotphi - 6 * \tdplottheta}{}{}{}%
1744 \tdplotshowargcolorguide{3}{-.2}{.1}{1}
1745 \end{tikzpicture}
1746 \end{verbatim}
1747 \ifpdf
1748 \beginpgfgraphicnamed{Figures/exampleshowargcolorguide}
1749 \tdplotsetmaincoords{40}{0}
1750 \begin{tikzpicture}[scale=2,line join=bevel,tdplot_main_coords, fill opacity=1]
1751 \tdplotsphericalsurfaceplot[parametricfill]{72}{36}%
1752 {sqrt(15/2)/2*sin(\tdplottheta)^2}{black}{2*\tdplotphi - 6 * \tdplottheta}{}{}{}%
1753 \tdplotshowargcolorguide{3}{-.2}{.1}{1}
1754 \end{tikzpicture}
1755 \endpgfgraphicnamed
1756 \fi
1757 \end{shaded}
1758 \end{description}
1759
1760 \section{Miscellaneous Math Commands}
1761
1762 The following commands are used to streamline the \tdplot\ calculations in the background. There is generally no need to use these directly, but may be useful on their own for any desired calculations.
1763
1764 \subsection{\texttt{tdplotsinandcos}}
1765
1766 \begin{description}
1767 \item[Description:] Determines the sine and cosine of the specified angle, and stores in specified macros.
1768 \item[Syntax:] \verb|\tdplotsinandcos{sintheta}{costeta}{theta}|
1769 \item[Parameters:]~
1770 \begin{description}
1771 \item[\texttt{sintheta}] A macro (eg. \verb|\sintheta|) to store the sine of \texttt{theta}.
1772 \item[\texttt{costheta}] A macro (eg. \verb|\costheta|) to store the cosine of \texttt{theta}.
1773 \item[\texttt{theta}] An angle (in degrees) to calculate. Can be a macro or literal value.
1774 \end{description}
1775 \end{description}
1776
1777 \subsection{\texttt{tdplotmult}}
1778
1779 \begin{description}
1780 \item[Description:] Determines the product of two specified values, and stores the result in the specified macro.
1781 \item[Syntax:] \verb|\tdplotmult{result}{multiplicand}{multiplicator}|
1782 \item[Parameters:]~
1783 \begin{description}
1784 \item[\texttt{result}] A macro (eg. \verb|\result|) to store the product of \texttt{multiplicand * multiplicator}.
1785 \item[\texttt{multiplicand}] The multiplicand of the product. Can be a macro or literal value.
1786 \item[\texttt{multiplicator}] The multiplicator of the product. Can be a macro or literal value.
1787 \end{description}
1788 \end{description}
1789
1790 \subsection{\texttt{tdplotdiv}}
1791
1792 \begin{description}
1793 \item[Description:] Determines the quotient of two specified values, and stores the result in the specified macro.
1794 \item[Syntax:] \verb|\tdplotdiv{result}{dividend}{divisor}|
1795 \item[Parameters:]~
1796 \begin{description}
1797 \item[\texttt{result}] A macro (eg. \verb|\result|) to store the quotient of \texttt{dividend / divisor}.
1798 \item[\texttt{dividend}] The dividend of the quotient. Can be a macro or literal value.
1799 \item[\texttt{divisor}] The divisor of the quotient. Can be a macro or literal value.
1800 \end{description}
1801 \end{description}
1802
1803 \chapter{Known Issues}
1804
1805 There are various issues that have been found while developing the \tdplot\ package. Some of these are currently open problems which will hopefully be resolved. Feedback and suggestions are welcome.
1806
1807 \section{Predefined Points Don't Work in Rotated Frame}
1808
1809 When a coordinate is defined using the \tikzname\ command \verb|\coordinate|, it will be transformed by the transformation specified at the beginning of the \texttt{tikzpicture} environment. These coordinates will not work for transformations applied at the actual \verb|\draw| command.
1810
1811 This problem seems to be inherant with \tikzname\ itself. By way of example, the following code is taken right from the PGF manual Version 2.00, section 21.2 on page 218:
1812
1813 \begin{shaded}
1814 \begin{verbatim}
1815 Case A:
1816 %this one works fine using literal coordinates
1817 \begin{tikzpicture}[smooth]
1818 \draw plot coordinates{(1,0)(2,0.5)(3,0)(3,1)};
1819 \draw[x={(0cm,1cm)},y={(1cm,0cm)},color=red]
1820 plot coordinates{(1,0)(2,0.5)(3,0)(3,1)};
1821 \end{tikzpicture}
1822
1823 Two distinct paths shown. All is good.
1824
1825 Case B:
1826 %this one does not work using predefined coordinates
1827 \begin{tikzpicture}[smooth]
1828 \coordinate (A) at (1,0);
1829 \coordinate (B) at (2,0.5);
1830 \coordinate (C) at (3,0);
1831 \coordinate (D) at (3,1);
1832 \draw plot coordinates{(A)(B)(C)(D)};
1833 \draw[x={(0cm,1cm)},y={(1cm,0cm)},color=red] plot coordinates{(A)(B)(C)(D)};
1834 \end{tikzpicture}
1835
1836 Both paths draw overtop each other, and the coordinates are not transformed!
1837 \end{verbatim}
1838
1839 Case A:
1840 %this one works fine using literal coordinates
1841 \begin{tikzpicture}[smooth]
1842 \draw plot coordinates{(1,0)(2,0.5)(3,0)(3,1)};
1843 \draw[x={(0cm,1cm)},y={(1cm,0cm)},color=red] plot coordinates{(1,0)(2,0.5)(3,0)(3,1)};
1844 \end{tikzpicture}
1845
1846 Two distinct paths shown. All is good.
1847
1848 Case B:
1849 %this one does not work using predefined coordinates
1850 \begin{tikzpicture}[smooth]
1851 \coordinate (A) at (1,0);
1852 \coordinate (B) at (2,0.5);
1853 \coordinate (C) at (3,0);
1854 \coordinate (D) at (3,1);
1855 \draw plot coordinates{(A)(B)(C)(D)};
1856 \draw[x={(0cm,1cm)},y={(1cm,0cm)},color=red] plot coordinates{(A)(B)(C)(D)};
1857 \end{tikzpicture}
1858
1859 Both paths draw overtop each other, and the coordinates are not transformed!
1860 \end{shaded}
1861
1862
1863 \section{\texttt{node} Command and \texttt{shift=(P)} Issues}
1864
1865 When placing a node in a shifted coordinate frame, the \verb|\node| command will not position properly. As a workaround, the \verb|\draw| command must be used to position the node. By way of example.
1866 \begin{shaded}
1867 \begin{verbatim}
1868 Case A:
1869 \tdplotsetmaincoords{60}{110}
1870 \begin{tikzpicture}[scale=3,tdplot_main_coords]
1871
1872 \draw[thick,->] (0,0,0) -- (1,0,0) node[anchor=north]{$x$};
1873 \draw[thick,->] (0,0,0) -- (0,1,0) node[anchor=west]{$y$};
1874 \draw[thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};
1875
1876 \coordinate (P) at (3,3,3);
1877 \tdplotsetrotatedcoords{0}{0}{0}
1878 \tdplotsetrotatedcoordsorigin{(P)}
1879
1880 \draw[thick,tdplot_rotated_coords,->] (0,0,0)
1881 -- (.5,0,0) node[anchor=north]{$x'$};
1882 \draw[thick,tdplot_rotated_coords,->] (0,0,0)
1883 -- (0,.5,0) node[anchor=south west]{$y'$};
1884 \draw[thick,tdplot_rotated_coords,->] (0,0,0)
1885 -- (0,0,.5) node[anchor=south east]{$z'$};
1886
1887 \node[tdplot_rotated_coords] at (30:.5){$\theta_{bad}$};
1888 \draw[tdplot_rotated_coords] (0,0,0) + (30:.5) node{$\theta_{good}$};
1889 \end{tikzpicture}
1890
1891 Here, the rotated coordinate frame is shifted by amount (P) within the main%
1892 coordinate frame. The node labelled $\theta_{bad}$ does not accept any%
1893 positioning coordinates.
1894
1895 Case B:
1896 \tdplotsetmaincoords{60}{110}
1897 \begin{tikzpicture}[scale=3,tdplot_main_coords]
1898
1899 \draw[thick,->] (0,0,0) -- (1,0,0) node[anchor=north]{$x$};
1900 \draw[thick,->] (0,0,0) -- (0,1,0) node[anchor=west]{$y$};
1901 \draw[thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};
1902
1903 % \coordinate (P) at (3,3,3);
1904 \tdplotsetrotatedcoords{0}{0}{0}
1905 % \tdplotsetrotatedcoordsorigin{(P)}
1906
1907 \draw[thick,tdplot_rotated_coords,->] (0,0,0)
1908 -- (.5,0,0) node[anchor=north]{$x'$};
1909 \draw[thick,tdplot_rotated_coords,->] (0,0,0)
1910 -- (0,.5,0) node[anchor=south west]{$y'$};
1911 \draw[thick,tdplot_rotated_coords,->] (0,0,0)
1912 -- (0,0,.5) node[anchor=south east]{$z'$};
1913
1914 \node[tdplot_rotated_coords] at (30:.5){$\theta_{bad}$};
1915 \draw[tdplot_rotated_coords] (0,0,0) + (30:.5) node{$\theta_{good}$};
1916 \end{tikzpicture}
1917
1918 Here, the shift is removed from the rotated coordinate frame. The %
1919 previously failing \verb|\node| command works properly.
1920 \end{verbatim}
1921 Case A:
1922 \tdplotsetmaincoords{60}{110}
1923 \begin{tikzpicture}[scale=3,tdplot_main_coords]
1924
1925 \draw[thick,->] (0,0,0) -- (1,0,0) node[anchor=north]{$x$};
1926 \draw[thick,->] (0,0,0) -- (0,1,0) node[anchor=west]{$y$};
1927 \draw[thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};
1928
1929 \coordinate (P) at (3,3,3);
1930 \tdplotsetrotatedcoords{0}{0}{0}
1931 \tdplotsetrotatedcoordsorigin{(P)}
1932
1933 \draw[thick,tdplot_rotated_coords,->] (0,0,0) -- (.5,0,0) node[anchor=north]{$x'$};
1934 \draw[thick,tdplot_rotated_coords,->] (0,0,0) -- (0,.5,0) node[anchor=south west]{$y'$};
1935 \draw[thick,tdplot_rotated_coords,->] (0,0,0) -- (0,0,.5) node[anchor=south east]{$z'$};
1936
1937 \node[tdplot_rotated_coords] at (30:.5){$\theta_{bad}$};
1938 \draw[tdplot_rotated_coords] (0,0,0) + (30:.5) node{$\theta_{good}$};
1939 \end{tikzpicture}
1940
1941 Here, the rotated coordinate frame is shifted by amount (P) within the main coordinate frame. The node labelled $\theta_{bad}$ does not accept any positioning coordinates.
1942
1943 Case B:
1944 \tdplotsetmaincoords{60}{110}
1945 \begin{tikzpicture}[scale=3,tdplot_main_coords]
1946
1947 \draw[thick,->] (0,0,0) -- (1,0,0) node[anchor=north]{$x$};
1948 \draw[thick,->] (0,0,0) -- (0,1,0) node[anchor=west]{$y$};
1949 \draw[thick,->] (0,0,0) -- (0,0,1) node[anchor=south]{$z$};
1950
1951 % \coordinate (P) at (3,3,3);
1952 \tdplotsetrotatedcoords{0}{0}{0}
1953 % \tdplotsetrotatedcoordsorigin{(P)}
1954
1955 \draw[thick,tdplot_rotated_coords,->] (0,0,0) -- (.5,0,0) node[anchor=north]{$x'$};
1956 \draw[thick,tdplot_rotated_coords,->] (0,0,0) -- (0,.5,0) node[anchor=south west]{$y'$};
1957 \draw[thick,tdplot_rotated_coords,->] (0,0,0) -- (0,0,.5) node[anchor=south east]{$z'$};
1958
1959 \node[tdplot_rotated_coords] at (30:.5){$\theta_{bad}$};
1960 \draw[tdplot_rotated_coords] (0,0,0) + (30:.5) node{$\theta_{good}$};
1961 \end{tikzpicture}
1962
1963 Here, the shift is removed from the rotated coordinate frame. The previously failing \verb|\node| command works properly.
1964 \end{shaded}
1965
1966 \section{PGF \texttt{xyz spherical} Coordinate System}
1967
1968 I have recently heard about the \texttt{xyz spherical} coordinate system offered by PGF. Unfortunately, when I try to use it, I get compile errors. I haven't spent much time looking into it though, so I'm probably just doing something silly.
1969 \begin{shaded}
1970 \begin{verbatim}
1971 \draw[-stealth,color=orange] (0,0,0)
1972 -- (xyz spherical cs:radius=.5,longitude=60,latitude=120);
1973 %this gives the following compile error using MikTeX 2.8:
1974 % Undefined control sequence. <argument> \tikz@cs@radius.
1975 \end{verbatim}
1976 \end{shaded}
1977
1978 \chapter{TODO list}
1979
1980 This chapter contains notes and jots of ideas of things to do which can expand or improve the \tdplot package.
1981
1982 \begin{itemize}
1983 \item Figure out how to work in a variable scope that doesn't interfere with other packages.
1984 \item Find a way to check if TikZ is loaded, and give a compile error if necessary.
1985 \item Find a way to use predefined coordinates in rotated or translated coordinate frames, instead of just literal coordinates.
1986 \item Generalize matrix math if such a package exists.
1987 \item Look into using TikZ spherical polar coordinates explicitly to streamline coordinate definitions.
1988 \item Find a way to extract coordinate components defined by the \verb|\coordinate| command and use them in macros defined by the \verb|\pgfmathsetmacro| and \verb|\pgfmathparse| commands.
1989 \end{itemize}
1990
1991
1992
1993
1994
1995
1996
1997 \end{document}