Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-library-3d.tex

raw
1 % Copyright 2019 by Till Tantau
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{Three Dimensional Drawing Library}
12
13 \begin{tikzlibrary}{3d}
14 This package provides some styles and options for drawing three dimensional
15 shapes.
16 \end{tikzlibrary}
17
18
19 \subsection{Coordinate Systems}
20
21 \begin{coordinatesystem}{xyz cylindrical}
22 The |xyz cylindrical| coordinate system allows to you specify a point in
23 terms of cylindrical coordinates, sometimes also referred to as cylindrical
24 polar coordinates or polar cylindrical coordinates. It is very similar to
25 the |canvas polar| and |xy polar| coordinate systems with the difference
26 that you provide an elevation over the $xy$-plane using the |z| key.
27 %
28 \begin{key}{/tikz/cs/angle=\meta{degrees} (initially 0)}
29 The angle of the coordinate interpreted in the ellipse whose axes are
30 the $x$-vector and the $y$-vector.
31 \end{key}
32 %
33 \begin{key}{/tikz/cs/radius=\meta{number} (initially 0)}
34 A factor by which the $x$-vector and $y$-vector are multiplied prior to
35 forming the ellipse.
36 \end{key}
37 %
38 \begin{key}{/tikz/cs/z=\meta{number} (initially 0)}
39 Factor by which the $z$-vector is multiplied.
40 \end{key}
41 %
42 \begin{codeexample}[preamble={\usetikzlibrary{3d}}]
43 \begin{tikzpicture}[->]
44 \draw (0,0,0) -- (xyz cylindrical cs:radius=1);
45 \draw (0,0,0) -- (xyz cylindrical cs:radius=1,angle=90);
46 \draw (0,0,0) -- (xyz cylindrical cs:z=1);
47 \end{tikzpicture}
48 \end{codeexample}
49 %
50 \end{coordinatesystem}
51
52 \begin{coordinatesystem}{xyz spherical}
53 The |xyz spherical| coordinate system allows you to specify a point in
54 terms of spherical coordinates.
55 %
56 \begin{key}{/tikz/cs/radius=\meta{number} (initially 0)}
57 Factor by which the $x$-, $y$-, and $z$-vector are multiplied.
58 \end{key}
59 %
60 \begin{key}{/tikz/cs/latitude=\meta{degrees} (initially 0)}
61 Angle of the coordinate between the $y$- and $z$-vector, measured from
62 the $y$-vector.
63 \end{key}
64 %
65 \begin{key}{/tikz/cs/longitude=\meta{degrees} (initially 0)}
66 Angle of the coordinate between the $x$- and $y$-vector, measured from
67 the $y$-vector.
68 \end{key}
69 %
70 \begin{key}{/tikz/cs/angle=\meta{degrees} (initially 0)}
71 Same as |longitude|.
72 \end{key}
73 %
74 \begin{codeexample}[preamble={\usetikzlibrary{3d}}]
75 \begin{tikzpicture}[->]
76 \draw (0,0,0) -- (xyz spherical cs:radius=1);
77 \draw (0,0,0) -- (xyz spherical cs:radius=1,latitude=90);
78 \draw (0,0,0) -- (xyz spherical cs:radius=1,longitude=90);
79 \end{tikzpicture}
80 \end{codeexample}
81 %
82 \end{coordinatesystem}
83
84
85 \subsection{Coordinate Planes}
86
87 Sometimes drawing with full three dimensional coordinates is not necessary and
88 it suffices to draw in two dimensions but in a different coordinate plane. The
89 following options help you to switch to a different plane.
90
91
92 \subsubsection{Switching to an arbitrary plane}
93
94 \begin{key}{/tikz/plane origin=\meta{point} (initially {(0,0)})}
95 Origin of the plane.
96 \end{key}
97
98 \begin{key}{/tikz/plane x=\meta{point} (initially {(1,0)})}
99 Unit vector of the $x$-direction in the new plane.
100 \end{key}
101
102 \begin{key}{/tikz/plane y=\meta{point} (initially {(0,1)})}
103 Unit vector of the $y$-direction in the new plane.
104 \end{key}
105
106 \begin{key}{/tikz/canvas is plane}
107 Perform the transformation into the new canvas plane using the units above.
108 Note that you have to set the units \emph{before} calling
109 |canvas is plane|.
110 %
111 \begin{codeexample}[preamble={\usetikzlibrary{3d}}]
112 \begin{tikzpicture}[
113 ->,
114 plane x={(0.707,-0.707)},
115 plane y={(0.707,0.707)},
116 canvas is plane,
117 ]
118 \draw (0,0) -- (1,0);
119 \draw (0,0) -- (0,1);
120 \end{tikzpicture}
121 \end{codeexample}
122 %
123 \end{key}
124
125
126 \subsubsection{Predefined planes}
127
128 \begin{key}{/tikz/canvas is xy plane at z=\meta{dimension}}
129 A plane with
130 %
131 \begin{itemize}
132 \item |plane origin={(0,0,|\meta{dimension}|)}|,
133 \item |plane x={(1,0,|\meta{dimension}|)}|, and
134 \item |plane y={(0,1,|\meta{dimension}|)}|.
135 \end{itemize}
136 \end{key}
137
138 \begin{key}{/tikz/canvas is yx plane at z=\meta{dimension}}
139 A plane with
140 %
141 \begin{itemize}
142 \item |plane origin={(0,0,|\meta{dimension}|)}|,
143 \item |plane x={(0,1,|\meta{dimension}|)}|, and
144 \item |plane y={(1,0,|\meta{dimension}|)}|.
145 \end{itemize}
146 \end{key}
147
148 \begin{key}{/tikz/canvas is xz plane at y=\meta{dimension}}
149 A plane with
150 %
151 \begin{itemize}
152 \item |plane origin={(0,|\meta{dimension}|,0)}|,
153 \item |plane x={(1,|\meta{dimension}|,0)}|, and
154 \item |plane y={(0,|\meta{dimension}|,1)}|.
155 \end{itemize}
156 \end{key}
157
158 \begin{key}{/tikz/canvas is zx plane at y=\meta{dimension}}
159 A plane with
160 %
161 \begin{itemize}
162 \item |plane origin={(0,|\meta{dimension}|,0)}|,
163 \item |plane x={(0,|\meta{dimension}|,1)}|, and
164 \item |plane y={(1,|\meta{dimension}|,0)}|.
165 \end{itemize}
166 \end{key}
167
168 \begin{key}{/tikz/canvas is yz plane at x=\meta{dimension}}
169 A plane with
170 %
171 \begin{itemize}
172 \item |plane origin={(|\meta{dimension}|,0,0)}|,
173 \item |plane x={(|\meta{dimension}|,1,0)}|, and
174 \item |plane y={(|\meta{dimension}|,0,1)}|.
175 \end{itemize}
176 \end{key}
177
178 \begin{key}{/tikz/canvas is zy plane at x=\meta{dimension}}
179 A plane with
180 %
181 \begin{itemize}
182 \item |plane origin={(|\meta{dimension}|,0,0)}|,
183 \item |plane x={(|\meta{dimension}|,0,1)}|, and
184 \item |plane y={(|\meta{dimension}|,1,0)}|.
185 \end{itemize}
186 \end{key}
187
188
189 \subsection{Examples}
190
191 \begin{codeexample}[preamble={\usetikzlibrary{3d}}]
192 \begin{tikzpicture}[z={(10:10mm)},x={(-45:5mm)}]
193 \def\wave{
194 \draw[fill,thick,fill opacity=.2]
195 (0,0) sin (1,1) cos (2,0) sin (3,-1) cos (4,0)
196 sin (5,1) cos (6,0) sin (7,-1) cos (8,0)
197 sin (9,1) cos (10,0)sin (11,-1)cos (12,0);
198 \foreach \shift in {0,4,8}
199 {
200 \begin{scope}[xshift=\shift cm,thin]
201 \draw (.5,0) -- (0.5,0 |- 45:1cm);
202 \draw (1,0) -- (1,1);
203 \draw (1.5,0) -- (1.5,0 |- 45:1cm);
204 \draw (2.5,0) -- (2.5,0 |- -45:1cm);
205 \draw (3,0) -- (3,-1);
206 \draw (3.5,0) -- (3.5,0 |- -45:1cm);
207 \end{scope}
208 }
209 }
210 \begin{scope}[canvas is zy plane at x=0,fill=blue]
211 \wave
212 \node at (6,-1.5) [transform shape] {magnetic field};
213 \end{scope}
214 \begin{scope}[canvas is zx plane at y=0,fill=red]
215 \draw[help lines] (0,-2) grid (12,2);
216 \wave
217 \node at (6,1.5) [rotate=180,xscale=-1,transform shape] {electric field};
218 \end{scope}
219 \end{tikzpicture}
220 \end{codeexample}
221
222 \begin{codeexample}[preamble={\usetikzlibrary{3d}}]
223 \begin{tikzpicture}
224 \begin{scope}[canvas is zy plane at x=0]
225 \draw (0,0) circle (1cm);
226 \draw (-1,0) -- (1,0) (0,-1) -- (0,1);
227 \end{scope}
228
229 \begin{scope}[canvas is zx plane at y=0]
230 \draw (0,0) circle (1cm);
231 \draw (-1,0) -- (1,0) (0,-1) -- (0,1);
232 \end{scope}
233
234 \begin{scope}[canvas is xy plane at z=0]
235 \draw (0,0) circle (1cm);
236 \draw (-1,0) -- (1,0) (0,-1) -- (0,1);
237 \end{scope}
238 \end{tikzpicture}
239 \end{codeexample}
240
241
242 %%% Local Variables:
243 %%% mode: latex
244 %%% TeX-master: "pgfmanual-pdftex-version"
245 %%% End: