7c223db84a565aa4dc2facda87b34b73b4964511
[xscreensaver] / hacks / glx / klein.man
1 .TH XScreenSaver 1 "" "X Version 11"
2 .SH NAME
3 klein - Draws a 4d Klein bottle.
4 .SH SYNOPSIS
5 .B klein
6 [\-display \fIhost:display.screen\fP]
7 [\-install]
8 [\-visual \fIvisual\fP]
9 [\-window]
10 [\-root]
11 [\-delay \fIusecs\fP]
12 [\-fps]
13 [\-klein-bottle \fIbottle-name\fP]
14 [-figure-8]
15 [-squeezed-torus]
16 [-lawson]
17 [\-mode \fIdisplay-mode\fP]
18 [\-wireframe]
19 [\-surface]
20 [\-transparent]
21 [\-appearance \fIappearance\fP]
22 [\-solid]
23 [\-bands]
24 [\-colors \fIcolor-scheme\fP]
25 [\-twosided]
26 [\-rainbow]
27 [\-depth]
28 [\-view-mode \fIview-mode\fP]
29 [\-walk]
30 [\-turn]
31 [\-walk-turn]
32 [\-orientation-marks]
33 [\-projection-3d \fImode\fP]
34 [\-perspective-3d]
35 [\-orthographic-3d]
36 [\-projection-4d \fImode\fP]
37 [\-perspective-4d]
38 [\-orthographic-4d]
39 [\-speed-wx \fIfloat\fP]
40 [\-speed-wy \fIfloat\fP]
41 [\-speed-wz \fIfloat\fP]
42 [\-speed-xy \fIfloat\fP]
43 [\-speed-xz \fIfloat\fP]
44 [\-speed-yz \fIfloat\fP]
45 [\-walk-direction \fIfloat\fP]
46 [\-walk-speed \fIfloat\fP]
47 .SH DESCRIPTION
48 The \fIklein\fP program shows three different Klein bottles in 4d: the
49 figure-8 Klein bottle, the squeezed torus Klein bottle, or the Lawson
50 Klein bottle.  You can walk on the Klein bottle, see it turn in 4d, or
51 walk on it while it turns in 4d.  The figure-8 Klein bottle is well
52 known in its 3d form.  The 4d form used in this program is an
53 extension of the 3d form to 4d that does not intersect itself in 4d
54 (which can be seen in the depth colors mode).  The squeezed torus
55 Klein bottle also does not intersect itself in 4d (which can be seen
56 in the depth colors mode).  The Lawson Klein bottle, on the other
57 hand, does intersect itself in 4d.  Its primary use is that it has a
58 nice appearance for walking and for turning in 3d.  The Klein bottle
59 is a non-orientable surface.  To make this apparent, the two-sided
60 color mode can be used.  Alternatively, orientation markers (curling
61 arrows) can be drawn as a texture map on the surface of the Klein
62 bottle.  While walking on the Klein bottle, you will notice that the
63 orientation of the curling arrows changes (which it must because the
64 Klein bottle is non-orientable).  The program projects the 4d Klein
65 bottle to 3d using either a perspective or an orthographic projection.
66 Which of the two alternatives looks more appealing depends on the
67 viewing mode and the Klein bottle.  For example, the Lawson Klein
68 bottle looks nicest when projected perspectively.  The figure-8 Klein
69 bottle, on the other hand, looks nicer while walking when projected
70 orthographically from 4d.  For the squeezed torus Klein bottle, both
71 projection modes give equally acceptable projections.  The projected
72 Klein bottle can then be projected to the screen either perspectively
73 or orthographically.  When using the walking modes, perspective
74 projection to the screen should be used.  There are three display
75 modes for the Klein bottle: mesh (wireframe), solid, or transparent.
76 Furthermore, the appearance of the Klein bottle can be as a solid
77 object or as a set of see-through bands.  Finally, the colors with
78 with the Klein bottle is drawn can be set to two-sided, rainbow, or
79 depth.  In the first case, the Klein bottle is drawn with red on one
80 "side" and green on the "other side".  Of course, the Klein bottle
81 only has one side, so the color jumps from red to green along a curve
82 on the surface of the Klein bottle.  This mode enables you to see that
83 the Klein bottle is non-orientable.  The second mode draws the Klein
84 bottle with fully saturated rainbow colors.  This gives a very nice
85 effect when combined with the see-through bands mode or with the
86 orientation markers drawn.  The third mode draws the Klein bottle with
87 colors that are chosen according to the 4d "depth" of the points.
88 This mode enables you to see that the figure-8 and squeezed torus
89 Klein bottles do not intersect themselves in 4d, while the Lawson
90 Klein bottle does intersect itself.  The rotation speed for each of
91 the six planes around which the Klein bottle rotates can be chosen.
92 For the walk-and-turn more, only the rotation speeds around the true
93 4d planes are used (the xy, xz, and yz planes).  Furthermore, in the
94 walking modes the walking direction in the 2d base square of the Klein
95 bottle and the walking speed can be chosen.  This program is somewhat
96 inspired by Thomas Banchoff's book "Beyond the Third Dimension:
97 Geometry, Computer Graphics, and Higher Dimensions", Scientific
98 American Library, 1990.
99 .SH OPTIONS
100 .I klein
101 accepts the following options:
102 .TP 8
103 .B \-window
104 Draw on a newly-created window.  This is the default.
105 .TP 8
106 .B \-root
107 Draw on the root window.
108 .TP 8
109 .B \-install
110 Install a private colormap for the window.
111 .TP 8
112 .B \-visual \fIvisual\fP
113 Specify which visual to use.  Legal values are the name of a visual
114 class, or the id number (decimal or hex) of a specific visual.
115 .TP 8
116 .B \-delay \fImicroseconds\fP
117 How much of a delay should be introduced between steps of the
118 animation.  Default 10000, or 1/100th second.
119 .TP 8
120 .B \-fps
121 Display the current frame rate, CPU load, and polygon count.
122 .PP
123 The following three options are mutually exclusive.  They determine
124 which Klein bottle is displayed.
125 .TP 8
126 .B \-klein-bottle random
127 Display a random Klein bottle (default).
128 .TP 8
129 .B \-klein-bottle figure-8 \fP(Shortcut: \fB\-figure-8\fP)
130 Display the figure-8 Klein bottle.
131 .TP 8
132 .B \-klein-bottle squeezed-torus \fP(Shortcut: \fB\-squeezed-torus\fP)
133 Display the squeezed torus Klein bottle.
134 .TP 8
135 .B \-klein-bottle lawson \fP(Shortcut: \fB\-lawson\fP)
136 Display the Lawson Klein bottle.
137 .PP
138 The following four options are mutually exclusive.  They determine
139 how the Klein bottle is displayed.
140 .TP 8
141 .B \-mode random
142 Display the Klein bottle in a random display mode (default).
143 .TP 8
144 .B \-mode wireframe \fP(Shortcut: \fB\-wireframe\fP)
145 Display the Klein bottle as a wireframe mesh.
146 .TP 8
147 .B \-mode surface \fP(Shortcut: \fB\-surface\fP)
148 Display the Klein bottle as a solid surface.
149 .TP 8
150 .B \-mode transparent \fP(Shortcut: \fB\-transparent\fP)
151 Display the Klein bottle as a transparent surface.
152 .PP
153 The following three options are mutually exclusive.  They determine the
154 appearance of the Klein bottle.
155 .TP 8
156 .B \-appearance random
157 Display the Klein bottle with a random appearance (default).
158 .TP 8
159 .B \-appearance solid \fP(Shortcut: \fB\-solid\fP)
160 Display the Klein bottle as a solid object.
161 .TP 8
162 .B \-appearance bands \fP(Shortcut: \fB\-bands\fP)
163 Display the Klein bottle as see-through bands.
164 .PP
165 The following four options are mutually exclusive.  They determine
166 how to color the Klein bottle.
167 .TP 8
168 .B \-colors random
169 Display the Klein bottle with a random color scheme (default).
170 .TP 8
171 .B \-colors twosided \fP(Shortcut: \fB\-twosided\fP)
172 Display the Klein bottle with two colors: red on one "side" and green
173 on the "other side".
174 .TP 8
175 .B \-colors rainbow \fP(Shortcut: \fB\-rainbow\fP)
176 Display the Klein bottle with fully saturated rainbow colors.  If the
177 Klein bottle is displayed as see-through bands, each band will be
178 displayed with a different color.
179 .TP 8
180 .B \-colors depth \fP(Shortcut: \fB\-depth\fP)
181 Display the Klein bottle with colors chosen depending on the 4d
182 "depth" of the points.
183 .PP
184 The following four options are mutually exclusive.  They determine
185 how to view the Klein bottle.
186 .TP 8
187 .B \-view-mode random
188 View the Klein bottle in a random view mode (default).
189 .TP 8
190 .B \-view-mode walk \fP(Shortcut: \fB\-walk\fP)
191 View the Klein bottle as if walking on its surface.
192 .TP 8
193 .B \-view-mode turn \fP(Shortcut: \fB\-turn\fP)
194 View the Klein bottle while it turns in 4d.
195 .TP 8
196 .B \-view-mode walk-turn \fP(Shortcut: \fB\-walk-turn\fP)
197 View the Klein bottle as if walking on its surface.  Additionally, the
198 Klein bottle turns around the true 4d planes (the xy, xz, and yz
199 planes).
200 .PP
201 The following options determine whether orientation marks are shown on
202 the Klein bottle.
203 .TP 8
204 .B \-orientation-marks
205 Display orientation marks on the Klein bottle.
206 .TP 8
207 .B \-no-orientation-marks
208 Don't display orientation marks on the Klein bottle (default).
209 .PP
210 The following three options are mutually exclusive.  They determine
211 how the Klein bottle is projected from 3d to 2d (i.e., to the screen).
212 .TP 8
213 .B \-projection-3d random
214 Project the Klein bottle from 3d to 2d using a random projection mode
215 (default).
216 .TP 8
217 .B \-projection-3d perspective \fP(Shortcut: \fB\-perspective-3d\fP)
218 Project the Klein bottle from 3d to 2d using a perspective projection.
219 .TP 8
220 .B \-projection-3d orthographic \fP(Shortcut: \fB\-orthographic-3d\fP)
221 Project the Klein bottle from 3d to 2d using an orthographic
222 projection.
223 .PP
224 The following three options are mutually exclusive.  They determine
225 how the Klein bottle is projected from 4d to 3d.
226 .TP 8
227 .B \-projection-4d random
228 Project the Klein bottle from 4d to 3d using a random projection mode
229 (default).
230 .TP 8
231 .B \-projection-4d perspective \fP(Shortcut: \fB\-perspective-4d\fP)
232 Project the Klein bottle from 4d to 3d using a perspective projection.
233 .TP 8
234 .B \-projection-4d orthographic \fP(Shortcut: \fB\-orthographic-4d\fP)
235 Project the Klein bottle from 4d to 3d using an orthographic
236 projection.
237 .PP
238 The following six options determine the rotation speed of the Klein
239 bottle around the six possible hyperplanes.  The rotation speed is
240 measured in degrees per frame.  The speeds should be set to relatively
241 small values, e.g., less than 4 in magnitude.  In walk mode, all
242 speeds are ignored.  In walk-and-turn mode, the 3d rotation speeds are
243 ignored (i.e., the wx, wy, and wz speeds).  In walk-and-turn mode,
244 smaller speeds must be used than in the turn mode to achieve a nice
245 visualization.  Therefore, in walk-and-turn mode the speeds you have
246 selected are divided by 5 internally.
247 .TP 8
248 .B \-speed-wx \fIfloat\fP
249 Rotation speed around the wx plane (default: 1.1).
250 .TP 8
251 .B \-speed-wy \fIfloat\fP
252 Rotation speed around the wy plane (default: 1.3).
253 .TP 8
254 .B \-speed-wz \fIfloat\fP
255 Rotation speed around the wz plane (default: 1.5).
256 .TP 8
257 .B \-speed-xy \fIfloat\fP
258 Rotation speed around the xy plane (default: 1.7).
259 .TP 8
260 .B \-speed-xz \fIfloat\fP
261 Rotation speed around the xz plane (default: 1.9).
262 .TP 8
263 .B \-speed-yz \fIfloat\fP
264 Rotation speed around the yz plane (default: 2.1).
265 .PP
266 The following two options determine the walking speed and direction.
267 .TP 8
268 .B \-walk-direction \fIfloat\fP
269 The walking direction is measured as an angle in degrees in the 2d
270 square that forms the coordinate system of the surface of the Klein
271 bottle (default: 7.0).
272 .TP 8
273 .B \-walk-speed \fIfloat\fP
274 The walking speed is measured in percent of some sensible maximum
275 speed (default: 20.0).
276 .SH INTERACTION
277 If you run this program in standalone mode in its turn mode, you can
278 rotate the Klein bottle by dragging the mouse while pressing the left
279 mouse button.  This rotates the Klein bottle in 3D, i.e., around the
280 wx, wy, and wz planes.  If you press the shift key while dragging the
281 mouse with the left button pressed the Klein bottle is rotated in 4D,
282 i.e., around the xy, xz, and yz planes.  To examine the Klein bottle
283 at your leisure, it is best to set all speeds to 0.  Otherwise, the
284 Klein bottle will rotate while the left mouse button is not pressed.
285 This kind of interaction is not available in the two walk modes.
286 .SH ENVIRONMENT
287 .PP
288 .TP 8
289 .B DISPLAY
290 to get the default host and display number.
291 .TP 8
292 .B XENVIRONMENT
293 to get the name of a resource file that overrides the global resources
294 stored in the RESOURCE_MANAGER property.
295 .SH SEE ALSO
296 .BR X (1),
297 .BR xscreensaver (1)
298 .SH COPYRIGHT
299 Copyright \(co 2005-2013 by Carsten Steger.  Permission to use, copy,
300 modify, distribute, and sell this software and its documentation for
301 any purpose is hereby granted without fee, provided that the above
302 copyright notice appear in all copies and that both that copyright
303 notice and this permission notice appear in supporting documentation.
304 No representations are made about the suitability of this software for
305 any purpose.  It is provided "as is" without express or implied
306 warranty.
307 .SH AUTHOR
308 Carsten Steger <carsten@mirsanmir.org>, 25-dec-2013.