http://www.jwz.org/xscreensaver/xscreensaver-5.13.tar.gz
[xscreensaver] / hacks / epicycle.man
1 .de EX          \"Begin example
2 .ne 5
3 .if n .sp 1
4 .if t .sp .5
5 .nf
6 .in +.5i
7 ..
8 .de EE
9 .fi
10 .in -.5i
11 .if n .sp 1
12 .if t .sp .5
13 ..
14 .TH XScreenSaver 1 "27-Apr-97" "X Version 11"
15 .SH NAME
16 epicycle - draws a point moving around a circle which moves around a cicle which...
17 .SH SYNOPSIS
18 .B epicycle 
19 [\-display \fIhost:display.screen\fP] [\-root] [\-window] [\-mono] [\-install] [\-noinstall] [\-visual \fIviz\fP] [\-colors \fIN\fP] [\-foreground \fIname\fP] [\-color\-shift \fIN\fP] [\-delay \fImicroseconds\fP] [\-holdtime \fIseconds\fP] [\-linewidth \fIN\fP] [\-min_circles \fIN\fP] [\-max_circles \fIN\fP] [\-min_speed \fInumber\fP] [\-max_speed \fInumber\fP] [\-harmonics \fIN\fP] [\-timestep \fInumber\fP] [\-divisor_poisson \fIprobability\fP] [\-size_factor_min \fInumber\fP] [\-size_factor_max \fInumber\fP]
20 [\-fps]
21 .SH DESCRIPTION
22 The epicycle program draws the path traced out by a point on the edge
23 of a circle.  That circle rotates around a point on the rim of another
24 circle, and so on, several times.  The random curves produced can be
25 simple or complex, convex or concave, but they are always closed
26 curves (they never go in indefinitely).
27
28 You can configure both the way the curves are drawn and the way in
29 which the random sequence of circles is generated, either with
30 command-line options or X resources.
31 .SH OPTIONS
32 .TP 8
33 .B \-display \fIhost:display.screen\fP
34 Specifies which X display we should use (see the section DISPLAY NAMES in
35 .BR X (1)
36 for more information about this option).
37 .TP 8
38 .B \-root
39 Draw on the root window.
40 .TP 8
41 .B \-window
42 Draw on a newly-created window.  This is the default.
43 .TP 8
44 .B \-mono
45 If on a color display, pretend we're on a monochrome display.
46 If we're on a mono display, we have no choice.
47 .TP 8
48 .B \-install
49 Install a private colormap for the window.
50 .TP 8
51 .B \-noinstall
52 Don't install a private colormap for the window.
53 .TP 8
54 .B \-visual \fIviz\fP
55 Specify which visual to use.  Legal values are the name of a visual
56 class, or the id number (decimal or hex) of a specific visual.
57 Possible choices include
58
59 .RS
60 default, best, mono, monochrome, gray, grey, color, staticgray, staticcolor, 
61 truecolor, grayscale, greyscale, pseudocolor, directcolor, \fInumber\fP
62
63 If a decimal or hexadecimal number is used, 
64 .BR XGetVisualInfo (3X)
65 is consulted to obtain the required visual.
66 .RE
67 .TP 8
68 .B \-colors \fIN\fP
69 How many colors should be used (if possible).  The colors are chosen
70 randomly.
71 .TP 8
72 .B \-foreground \fIname\fP
73 With 
74 .BR \-mono ,
75 this option selects the foreground colour.   
76 .TP 8
77 .B \-delay \fImicroseconds\fP
78 Specifies the delay between drawing successive line segments of the
79 path.   If you do not specify 
80 .BR -sync ,
81 some X servers may batch up several drawing operations together,
82 producing a less smooth effect.   This is more likely to happen 
83 in monochrome mode (on monochrome servers or when 
84 .B \-mono 
85 is specified).
86 .TP 8
87 .B \-holdtime \fIseconds\fP
88 When the figure is complete, 
89 .I epicycle
90 pauses this number of seconds.
91 .TP 8
92 .B \-linewidth \fIN\fP
93 Width in pixels of the body's track.   Specifying values greater than
94 one may cause slower drawing.   The fastest value is usually zero,
95 meaning one pixel.   
96 .TP 8
97 .B \-min_circles \fIN\fP
98 Smallest number of epicycles in the figure.
99 .TP 8
100 .B \-max_circles \fIN\fP
101 Largest number of epicycles in the figure.
102 .TP 8
103 .B \-min_speed \fInumber\fP
104 Smallest possible value for the base speed of revolution of the
105 epicycles.  The actual speeds of the epicycles vary from this down
106 to
107 .IB "min_speed / harmonics" .
108 .TP 8
109 .B \-max_speed \fInumber\fP
110 Smallest possible value for the base speed of revolution of the 
111 epicycles.
112 .TP 8
113 .B \-harmonics \fIN\fP
114 Number of possible harmonics; the larger this value is, the greater
115 the possible variety of possible speeds of epicycle.
116 .TP 8
117 .B \-timestep \fInumber\fP
118 Decreasing this value will reduce the distance the body moves for
119 each line segment, possibly producing a smoother figure.  Increasing
120 it may produce faster results.  
121 .TP 8
122 .B \-divisor_poisson \fIprobability\fP
123 Each epicycle rotates at a rate which is a factor of the base speed.
124 The speed of each epicycle is the base speed divided by some integer
125 between 1 and the value of the 
126 .B \-harmonics 
127 option.  This integer is decided by starting at 1 and tossing 
128 a biased coin.  For each consecutive head, the value is incremented by
129 one.  The integer will not be incremented above the value of the 
130 .B \-harmonics
131 option.  The argument of this option decides the bias of the coin; it
132 is the probability that that coin will produce a head at any given toss.
133 .TP 8
134 .B \-size_factor_min \fInumber\fP
135 Epicycles are always at least this factor smaller than their
136 parents.  
137 .TP 8
138 .B \-size_factor_max \fInumber\fP
139 Epicycles are never more than this factor smaller than their parents.
140 .TP 8
141 .B \-fps
142 Display the current frame rate and CPU load.
143 .SH RESOURCES
144 .EX
145 Option            Resource               Default Value
146 ------            --------               -------------
147 -colors           .colors                100
148 -delay            .delay                 1000
149 -holdtime         .holdtime              2
150 -linewidth        .lineWidth             4
151 -min_circles      .minCircles            2
152 -max_circles      .maxCircles            10
153 -min_speed        .minSpeed              0.003
154 -max_speed        .maxSpeed              0.005
155 -harmonics        .harmonics             8
156 -timestep         .timestep              1.0
157 -divisor_poisson  .divisorPoisson        0.4
158 -size_factor_min  .sizeFactorMin         1.05
159 -size_factor_max  .sizeFactorMax         2.05
160                   .timestepCoarseFactor  1.0
161 .EE
162 Before the drawing of the figure is begun, a preliminary calculation
163 of the path is done in order to scale the radii of the epicycles so
164 as to fit the figure on the screen or window.  For the sake of speed,
165 This calculation is done with a larger timestep than the actual
166 drawing.  The time-step used is the value of the
167 .B \-timestep 
168 option multiplied by the timestepCoarseFactor resource.  The default
169 value of 1 will almost always work fast enough and so this resource
170 is not available as a command-line option.
171 .SH USER INTERFACE
172 The program runs mostly without user interaction.  When running on the
173 root window, no input is accepted.  When running in its own window,
174 the program will exit if mouse button 3 is pressed.  If any other
175 mouse button is pressed, the current figure will be abandoned and
176 another will be started.
177 .SH HISTORY
178 The geometry of epicycles was perfected by Hipparchus of Rhodes at
179 some time around 125 B.C., 185 years after the birth of Aristarchus of
180 Samos, the inventor of the heliocentric universe model.  Hipparchus
181 applied epicycles to the Sun and the Moon.  Ptolemy of Alexandria went
182 on to apply them to what was then the known universe, at around 150
183 A.D.  Copernicus went on to apply them to the heliocentric model at
184 the beginning of the sixteenth century.  Johannes Kepler discovered
185 that the planets actually move in elliptical orbits in about 1602.
186 The inverse-square law of gravity was suggested by Boulliau in 1645.
187 Isaac Newton's 
188 .I Principia Mathematica
189 was published in 1687, and proved that Kepler's laws derived from
190 Newtonian gravitation.
191 .SH BUGS
192 The colour selection is re-done for every figure.  This may 
193 generate too much network traffic for this program to work well 
194 over slow or long links.   
195 .SH COPYRIGHT
196 Copyright \(co 1998, James Youngman.  Permission to use, copy, modify,
197 distribute, and sell this software and its documentation for any purpose is
198 hereby granted without fee, provided that the above copyright notice appear
199 in all copies and that both that copyright notice and this permission notice
200 appear in supporting documentation.  No representations are made about the
201 suitability of this software for any purpose.  It is provided "as is" without
202 express or implied warranty.
203 .SH AUTHOR
204 James Youngman <jay@gnu.org>, April 1998.