Debian Codegraph @

texmf-dist/doc/latex/tikz-planets/planets-doc.tex

raw
1 % tikz-planets documentation -- illustrate celestial mechanics with TikZ
2 % Version 1.0.2
3
4 % Isabelle M. Santos
5 % This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License.
6 % To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/
7
8 % This program is distributed in the hope that it will be useful,
9 % but WITHOUT ANY WARRANTY; without even the implied warranty of
10 % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
11
12 \documentclass[12pt, twocolumn]{article}
13
14 \usepackage{url}
15 \usepackage[hidelinks]{hyperref}
16
17 \usepackage{planets}
18
19 \usepackage[top=2cm, bottom=2cm, right=1.7cm, left=1.7cm]{geometry}
20
21 \title{The TikZ-planets package}
22 \author{Isabelle M. Santos}
23 \date{Version 1.0.4 -- 202/05/15}
24
25 \begin{document}
26 \maketitle
27 \tableofcontents
28
29 \section{Introduction}
30 I initially created this package to illustrate celestial mechanics for an astronomy course I taught in 2019.
31 It makes it easy to add sketches of solar system objects to illustrate seasons, moon phases,...
32 The commands provided by this package are to be used in a \verb|tikzpicture| environment.
33
34 This package is a work in progress and is my first attempt at creating a TikZ package. I would be really happy to receive suggestions on how to improve it.
35
36 \subsection{Installation}
37 Move the package (.sty file) to a latex search directory (usually \url{~/texmf/} on a Unix-type system) if you want to be able to use it from any directory.
38 Ask you system administrator if you need help.
39
40 \subsection{Requirements}
41 Tikz-planets requires the following standard packages to be installed
42 \begin{itemize}
43 \item xcolor
44 \item pgfkeys
45 \item xstring
46 \item tikz
47 \end{itemize}
48
49 \subsection{Source}
50 This package is available on CTAN.
51
52 The source code, along with an issue tracker can be found at \url{https://framagit.org/Moutmout/tikz-planets.git}.
53
54 \subsection{License}
55 This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. To view a copy of this license, visit \url{http://creativecommons.org/licenses/by-sa/4.0/}.
56
57 \section{Usage}
58 To use the commands provided by this package in a TikZ picture, add the \verb|\usepackage{planets}| command to the header of your document.
59
60 \subsection{Drawing a planet}
61 Drawing one of the eight solar system planets is rather straightforward: Use \verb|\planet[surface=earth]|, replacing the option \verb|earth| with the name of any planet.
62 Although they are not planets, the \verb|\planet| command can also be used to draw the Sun, the Moon and Pluto, by setting the \verb|surface=<name>| keyword.
63
64 \begin{verbatim}
65 \planet[surface=sun]
66 \planet[surface=earth]
67 \planet[surface=moon]
68 \planet[surface=mars]
69 \end{verbatim}
70 \begin{tikzpicture}
71 \planet[surface=sun]
72 \planet[surface=earth, centerx=2.2]
73 \planet[surface=moon, centerx=4.4]
74 \planet[surface=mars, centerx=6.6]
75 \end{tikzpicture}
76
77 The celestial bodies available in this package are:
78 \begin{itemize}
79 \setlength\itemsep{-.5em}
80 \item \verb|sun|
81 \item \verb|mercury|
82 \item \verb|venus|
83 \item \verb|earth|
84 \item \verb|moon|
85 \item \verb|mars|
86 \item \verb|jupiter|
87 \item \verb|saturn|
88 \item \verb|uranus|
89 \item \verb|neptune|
90 \item \verb|pluto|
91 \end{itemize}
92
93 In addition to this list, it is possible to represent Jupiter with a different graphical style.
94 This option was created purely for esthetic reasons and is not (yet) available for any other planets.
95
96 \begin{verbatim}
97 \planet[surface=shaded jupiter]
98 \end{verbatim}
99 \begin{tikzpicture}
100 \planet[surface=shaded jupiter]
101 \end{tikzpicture}
102
103 If you need a planet that isn't in the solar system, you can make a generic one with a solid color surface.
104
105 \begin{verbatim}
106 \planet
107 \planet[color=brown]
108 \end{verbatim}
109 \begin{tikzpicture}
110 \planet
111 \planet[color=brown, centerx=2.2]
112 \end{tikzpicture}
113
114 \subsection{Rings}
115 The four gas giants in the solar system sport a ring, but only Saturn is shown with a ring by default.
116 A "Saturn-like" set of rings can be drawn around any planet with the \verb|rings| option.
117 A thin ring with a custom radius can be drawn with the \verb|ring=<radius>| option.
118 %and a thin ring with the \verb|thin ring| option.
119 %Thin rings can be set with a custom radius.
120
121 \begin{verbatim}
122 \planet[surface=mercury, rings]
123 \planet[surface=neptune, ring=1.5]
124 \end{verbatim}
125 \begin{tikzpicture}
126 \planet[surface=mercury, rings]
127 \planet[surface=neptune, ring=1.5, centerx=4.4]
128 \end{tikzpicture}
129
130 \subsection{Rotational characteristics}
131 Most planets rotate around a set axis that can be tilted with respect to the plane of orbit.
132 The rotation axis of the Earth, for instance, is tilted by 23.5 degrees.
133 Uranus spins on its side, with a rotation axis tilted at 90 degrees.
134 This can be illustrated using the \verb|tilt=<angle in degrees>| and the \verb|rotation| options.
135
136 The equator and rotational axis of a planet can be shown respectively with the \verb|equator| and \verb|axis| options.
137
138 Venus rotates in the opposite direction compared to the other planets in the solar system.
139 This can be illustrated with the \verb|retrograde| option.
140
141 \begin{verbatim}
142 \planet[surface=pluto, tilt=22.5, equator]
143 \planet[surface=uranus, tilt=90, axis,
144 ring=1.7]
145 \planet[surface=venus,
146 retrograde, rotation]
147 \end{verbatim}
148 \begin{tikzpicture}
149 \planet[surface=pluto, tilt=22.5, equator]
150 \planet[surface=uranus, tilt=90, axis, ring=1.7, centerx=3.3]
151 \planet[surface=venus, rotation, retrograde, centerx=6.6]
152 \end{tikzpicture}
153
154 \subsection{Phases}
155 Half of a planet or moon is in the shadow of the Sun. This can be illustrated with the \verb|phase=<name>| keyword, which can take the following values: \verb|new|, \verb|first crescent|, \verb|first half|, \verb|waxing gibbous|, \verb|full|, \verb|waning gibbous|, \verb|last half| or \verb|last crescent|.
156
157 \hspace{1em}
158
159 \begin{tikzpicture}
160 \planet[surface=moon, phase=new, centerx=0]
161 \node[red] at (0, 0) {new};
162 \planet[surface=moon, phase=first crescent, centerx=2]
163 \node[red, align=center] at (2, 0) {first \\ crescent};
164 \planet[surface=moon, phase=first half, centerx=4]
165 \node[red, align=center] at (4, 0) {first \\ half};
166 \planet[surface=moon, phase=waxing gibbous, centerx=6]
167 \node[red, align=center] at (6, 0) {waxing \\ gibbous};
168 \planet[surface=moon, phase=full, centery=-2, centerx=6]
169 \node[red, align=center] at (6, -2) {full};
170 \planet[surface=moon, phase=waning gibbous, centerx=4, centery=-2]
171 \node[red, align=center] at (4, -2) {waning \\ gibbous};
172 \planet[surface=moon, phase=last half, centerx=2, centery=-2]
173 \node[red, align=center] at (2, -2) {last \\ half};
174 \planet[surface=moon, phase=last crescent, centerx=0, centery=-2]
175 \node[red, align=center] at (0, -2) {last \\ crescent};
176 \end{tikzpicture}
177
178 If the phase is specified for a planet with ``Saturn-like" rings, then the rings will also be shaded.
179
180 \begin{verbatim}
181 \planet[surface=saturn,
182 phase=first half, tilt=20]
183 \planet[surface=saturn,
184 phase=waxing gibbous, tilt=-20]
185 \end{verbatim}
186 \begin{tikzpicture}
187 \planet[surface=saturn, phase=first half, tilt=20]
188 \planet[surface=saturn, phase=waxing gibbous, centerx=4.5, tilt=-20]
189 \end{tikzpicture}
190
191 It is possible to specify a phase such that only the top half or bottom half of the planet is visible.
192 \begin{verbatim}
193 \planet[phase=top half]
194 \planet[phase=bottom half, centerx=4]
195 \end{verbatim}
196 \begin{tikzpicture}
197 \planet[phase=top half]
198 \planet[phase=bottom half, centerx=4]
199 \end{tikzpicture}
200
201 \subsection{Size and position}
202 By default, a planet has a radius of $1$ and is centered at $(0, 0)$.
203 To draw schematics illustrating celestial mechanics, it is useful to use several \verb|\planet|s in one figure.
204
205 The size of the planet is set with the \verb|scale=<planet radius>| keyword.
206 For instance, \verb|scale=2| makes the radius of the planet twice as big.
207
208 The position of the center of the planet can be set by specifying the $x$ and $y$ coordinates of the center with the \verb|centerx=<x coordinate>| and/or \verb|centery=<y coordinate>| keywords.
209 Alternatively, the coordinates of the planet's center can be set using the \verb|center={<point>}| keyword.
210 This makes it possible to specify the center of the planet in either cartesian, polar coordinates or named points.
211
212 \begin{verbatim}
213 \planet[center={(0, 1.5)}, scale=.6]
214 \planet[centerx=4, centery = 1]
215 \planet[center={(45 : 3)}, scale=1.2]
216 \node (A) at (7, 2) {};
217 \planet[center={A}]
218 \end{verbatim}
219 \begin{tikzpicture}
220 \planet[center={(0, 1.5)}, scale=.6]
221 \planet[centerx=4, centery = 1]
222 \planet[center={(45 : 3)}, scale=1.2]
223 \node (A) at (7, 2) {};
224 \planet[center={A}]
225 \end{tikzpicture}
226
227 \subsection{Polar view of planets}
228 In a diagram, you may want to show a planet seen from one of its poles, like an observer sitting above or below the elliptical plane.
229 This is achieved with the \verb|surface=<surface>| option.
230
231 \begin{verbatim}
232 \planet[surface=north pole]
233 \planet[surface=south pole, centerx=2.2]
234 \planet[surface=mars pole, centerx=4.4]
235 \end{verbatim}
236 \begin{tikzpicture}
237 \planet[surface=north pole]
238 \planet[surface=south pole, centerx=2.2]
239 \planet[surface=mars pole, centerx=4.4]
240 \end{tikzpicture}
241
242 This feature is (currently) only available for the Earth and for Mars.
243
244 \onecolumn
245 \section{Complete examples}
246 Here are a few examples of what can be done with the TikZ-planets package. More examples can be found at \url{https://framagit.org/search?utf8=%E2%9C%93&snippets=true&scope=snippet_titles&repository_ref=&search=tikz-planets}.
247 \subsection{The seasons}
248 Season's are caused by the tilt of Earth's axis.
249 This is why summer in the northern hemisphere happens at the same time as winter in the southern hemisphere.
250
251 \begin{verbatim}
252 \planet[surface=sun]
253
254 \planet[surface=earth, phase = first half, rotation, tilt=23.5, centerx=-5]
255 \planet[surface=earth, phase = last half, rotation, tilt=23.5, centerx=5]
256 \planet[surface=earth, phase = new, rotation, tilt=23.5, centery=-3]
257 \planet[surface=earth, phase = full, rotation, tilt=23.5, centery=3]
258 \end{verbatim}
259 \begin{tikzpicture}
260 \planet[surface=sun]
261
262 \planet[surface=earth, phase = first half, rotation, tilt=23.5, centerx=-5]
263 \planet[surface=earth, phase = last half, rotation, tilt=23.5, centerx=5]
264
265 \planet[surface=earth, phase = new, rotation, tilt=23.5, centery=-3]
266 \planet[surface=earth, phase = full, rotation, tilt=23.5, centery=3]
267 \end{tikzpicture}
268
269 \subsection{The phases of the Moon}
270 Half of the Moon is in the shadow of the Sun.
271 Since the Moon goes around the Earth, the shadows on the near-side of the Moon change.
272
273 \begin{verbatim}
274 \planet[surface=earth, phase=first half]
275 \planet[surface=sun, centerx=10, scale=2]
276
277 \planet[surface=moon, phase=first half, centerx=-2.5, scale=.5]
278 \planet[surface=moon, phase=first half, centerx=2.5, scale=.5]
279 \planet[surface=moon, phase=first half, centery=-2.5, scale=.5]
280 \planet[surface=moon, phase=first half, centery=2.5, scale=.5]
281 \end{verbatim}
282 \begin{tikzpicture}
283 \planet[surface=earth, phase=first half]
284 \planet[surface=sun, centerx=10, scale=2]
285
286 \planet[surface=moon, phase=first half, centerx=-2.5, scale=.5]
287 \planet[surface=moon, phase=first half, centerx=2.5, scale=.5]
288 \planet[surface=moon, phase=first half, centery=-2.5, scale=.5]
289 \planet[surface=moon, phase=first half, centery=2.5, scale=.5]
290 \end{tikzpicture}
291
292 \subsection{The solar system}
293 You might have learned ``My Violent Evil Monster Just Scared Us Nuts'', ``My Very Excellent Mother Just Served Us Nachos'', or some other mnemonic to remember the order of the eight (or nine if you're old enough) planets in the solar system.
294 The distances in the following sketch are not to scale, but the radii roughly are.
295
296 \begin{verbatim}
297 \clip (0,-3) rectangle (20, 3);
298 \planet[surface=sun, scale=28, centerx=-27]
299 \planet[surface=mercury, centerx=1.5, tilt=0, scale=.1]
300 \planet[surface=venus, centerx=2.5, tilt=2.6, scale=.25]
301 \planet[surface=earth, centerx=3.5, tilt=23.5, scale=.25]
302 \planet[surface=mars, centerx=4.5, tilt=25.2, scale=.13]
303 \planet[surface=jupiter, centerx=8, tilt=3, scale=2.75]
304 \planet[surface=saturn, centerx=12, tilt=26.7, scale=2.3]
305 \planet[surface=uranus, centerx=15.5, tilt=97.8, scale=1]
306 \planet[surface=neptune, centerx=17.3, tilt=28.3, scale=.97]
307 \end{verbatim}
308 \begin{tikzpicture}
309 \clip (0,-3) rectangle (20, 3);
310 \planet[surface=sun, scale=28, centerx=-27]
311 \planet[surface=mercury, centerx=1.5, tilt=0, scale=.1]
312 \planet[surface=venus, centerx=2.5, tilt=2.6, scale=.25]
313 \planet[surface=earth, centerx=3.5, tilt=23.5, scale=.25]
314 \planet[surface=mars, centerx=4.5, tilt=25.2, scale=.13]
315 \planet[surface=jupiter, centerx=8, tilt=3, scale=2.75]
316 \planet[surface=saturn, centerx=12, tilt=26.7, scale=2.3]
317 \planet[surface=uranus, centerx=15.5, tilt=97.8, scale=1]
318 \planet[surface=neptune, centerx=17.3, tilt=28.3, scale=.97]
319 \end{tikzpicture}
320
321 \twocolumn
322
323 \section{Changelog}
324
325 \subsection{Version 1.0.4 - May 2025}
326 \begin{itemize}
327 \item Fixed bug with \verb|center| keyword.
328 \item Updated documentation for \verb|center| keyword.
329 \item Updated documentation with version number and date.
330 \item Added polar view of Earth and Mars.
331 \item Updated documentation for polar views of planets.
332 \item Documented options surface=shaded jupiter, phase=top half and phase=bottom half.
333 \item Documented the options to show the rotation axis and equator independently.
334 \end{itemize}
335
336 \subsection{Version 1.0.3}
337 \begin{itemize}
338 \item Changed internal command names to avoid clashes with user namespace
339 \item Rotation axis of planets is now show to "go through" the planet, rather than be drawn on top of planet.
340 \end{itemize}
341
342 \subsection{Version 1.0.2}
343 \begin{itemize}
344 \item Made planets and wasysym compatible
345 \item Possibility to use a point to specify the center of a planet (thus use polar coordinates)
346 \item Make a more schematic representation of Jupiter that better fits with the graphical style used for the telluric planets
347 \item A ring system can be added around any planet
348 \item Ensure the radius of a planet is exactly 1 by default
349 \item Thin rings can be drawn with any radius
350 \item Draw the phase before rings to avoid having a strange shadow on the rings
351 \item Rings typically are in the equatorial plane of their planet: make rings tilt with axial tilt
352 \item Use solid color rather than shading for rings so that they have the same appearance when tilted
353 \item Added Pluto
354 \item Added shading to the rings for each phase
355 \item Fixed documentation typos
356 \end{itemize}
357
358 \subsection{Version 1.0.1}
359 \begin{itemize}
360 \item Crescent and gibbous phases
361 \item Added Mercury, Venus, Jupiter, Saturn, Uranus and Neptune surfaces
362 \item Rotation can now be retrograde
363 \item Color used no longer depends on x11names
364 \end{itemize}
365
366 \end{document}