Debian Codegraph @

upstream/debian-unstable/man1/ppmforge.1

raw
1 \
2 .\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
3 .\" Do not hand-hack it! If you have bug fixes or improvements, please find
4 .\" the corresponding HTML page on the Netpbm website, generate a patch
5 .\" against that, and send it to the Netpbm maintainer.
6 .TH "Ppmforge User Manual" 1 "27 March 2021" "netpbm documentation"
7
8 .SH NAME
9
10 ppmforge - fractal forgeries of clouds, planets, and starry skies
11 .UN synopsis
12 .SH SYNOPSIS
13
14 \fBppmforge\fP
15
16 [\fB-clouds\fP]
17 [\fB-night\fP]
18 [\fB-dimension\fP \fIdimen\fP]
19 [\fB-hour\fP \fIhour\fP]
20 [\fB-inclination|-tilt\fP \fIangle\fP]
21 [\fB-mesh\fP \fIsize\fP]
22 [\fB-power\fP \fIfactor\fP]
23 [\fB-glaciers\fP \fIlevel\fP]
24 [\fB-ice\fP \fIlevel\fP]
25 [\fB-saturation\fP \fIsat\fP]
26 [\fB-seed\fP \fIseed\fP]
27 [\fB-stars\fP \fIfraction\fP]
28 [{\fB-xsize\fP|\fB-width\fP} \fIwidth\fP]
29 [{\fB-ysize\fP|\fB-height\fP} \fIheight\fP]
30
31 .UN description
32 .SH DESCRIPTION
33 .PP
34 This program is part of
35 .BR "Netpbm" (1)\c
36 \&.
37 .PP
38 \fBppmforge\fP generates three kinds of ``random fractal forgeries,''
39 the term coined by Richard F. Voss of the IBM Thomas J. Watson
40 Research Center for seemingly realistic pictures of natural objects
41 generated by simple algorithms embodying randomness and fractal
42 self-similarity. The techniques used by \fBppmforge\fP are
43 essentially those given by Voss[1], particularly the technique of
44 spectral synthesis explained in more detail by Dietmar Saupe[2].
45 .PP
46 The program generates two varieties of pictures: planets and
47 clouds, which are just different renderings of data generated in an
48 identical manner, illustrating the unity of the fractal structure of
49 these very different objects. A third type of picture, a starry sky,
50 is synthesised directly from pseudorandom numbers.
51 .PP
52 The generation of planets or clouds begins with the preparation of
53 an array of random data in the frequency domain. The size of this
54 array, the ``mesh size,'' can be set with the \fB-mesh\fP option; the
55 larger the mesh the more realistic the pictures but the calculation
56 time and memory requirement increases as the square of the mesh size.
57 The fractal dimension, which you can specify with the
58 \fB-dimension\fP option, determines the roughness of the terrain on
59 the planet or the scale of detail in the clouds. As the fractal
60 dimension is increased, more high frequency components are added into
61 the random mesh.
62 .PP
63 Once the mesh is generated, an inverse two dimensional Fourier
64 transform is performed upon it. This converts the original random
65 frequency domain data into spatial amplitudes. We scale the real
66 components that result from the Fourier transform into numbers from 0
67 to 1 associated with each point on the mesh. You can further modify
68 this number by applying a ``power law scale'' to it with the
69 \fB-power\fP option. Unity scale leaves the numbers unmodified; a
70 power scale of 0.5 takes the square root of the numbers in the mesh,
71 while a power scale of 3 replaces the numbers in the mesh with their
72 cubes. Power law scaling is best envisioned by thinking of the data
73 as representing the elevation of terrain; powers less than 1 yield
74 landscapes with vertical scarps that look like glacially-carved
75 valleys; powers greater than one make fairy-castle spires (which
76 require large mesh sizes and high resolution for best results).
77 .PP
78 After these calculations, we have a array of the specified size
79 containing numbers that range from 0 to 1. \fBppmforge\fP generates
80 as follows:
81 .PP
82 The randomness in the image is limited before Netpbm 10.37 (December
83 2006) -- if you run the program twice in the same second, you may get
84 identical output.
85
86
87 .TP
88 \fBClouds\fP
89 A color map is created that ranges from pure blue to white by
90 increasing admixture (desaturation) of blue with white. Numbers less
91 than 0.5 are colored blue, numbers between 0.5 and 1.0 are colored
92 with corresponding levels of white, with 1.0 being pure white.
93
94 .TP
95 \fBPlanet\fP
96 The mesh is projected onto a sphere. Values less than 0.5 are treated
97 as water and values between 0.5 and 1.0 as land. The water areas are
98 colored based upon the water depth, and land based on its elevation.
99 The random depth data are used to create clouds over the oceans. An
100 atmosphere approximately like the Earth's is simulated; its light
101 absorption is calculated to create a blue cast around the limb of the
102 planet. A function that rises from 0 to 1 based on latitude is
103 modulated by the local elevation to generate polar ice caps--high
104 altitude terrain carries glaciers farther from the pole. Based on the
105 position of the star with respect to the observer, the apparent color
106 of each pixel of the planet is calculated by ray-tracing from the star
107 to the planet to the observer and applying a lighting model that sums
108 ambient light and diffuse reflection (for most planets ambient light
109 is zero, as their primary star is the only source of illumination).
110 Additional random data are used to generate stars around the planet.
111
112 .TP
113 \fBNight\fP
114 A sequence of pseudorandom numbers is used to generate stars with a
115 user specified density.
116
117 .PP
118 Cloud pictures always contain 256 or fewer colors and may be
119 displayed on most color mapped devices without further processing.
120 Planet pictures often contain tens of thousands of colors which must
121 be compressed with \fBpnmquant\fP or \fBppmdither\fP before encoding
122 in a color mapped format. If the display resolution is high enough,
123 \fBppmdither\fP generally produces better looking planets.
124 \fBpnmquant\fP tends to create discrete color bands, particularly in
125 the oceans, which are unrealistic and distracting. The number of
126 colors in starry sky pictures generated with the \fB-night\fP option
127 depends on the value specified for \fB-saturation\fP. Small values
128 limit the color temperature distribution of the stars and reduce the
129 number of colors in the image. If the \fB-saturation\fP is set to
130 0, none of the stars will be colored and the resulting image will
131 never contain more than 256 colors. Night sky pictures with many
132 different star colors often look best when color compressed by
133 \fBpamdepth\fP rather than \fBpnmquant\fP or \fBppmdither\fP. Try
134 \fInewmaxval\fP settings of 63, 31, or 15 with \fBpamdepth\fP to
135 reduce the number of colors in the picture to 256 or fewer.
136
137
138 .UN options
139 .SH OPTIONS
140 .PP
141 In addition to the options common to all programs based on libnetpbm
142 (most notably \fB-quiet\fP, see
143 .UR index.html#commonoptions
144 Common Options
145 .UE
146 \&), \fBppmforge\fP recognizes the following
147 command line options:
148 .PP
149 You can abbreviate any options to its shortest unique prefix.
150
151
152 .TP
153 \fB-clouds\fP
154 Generate clouds. An image of fractal clouds is generated. Selecting clouds
155 sets the default for fractal dimension to 2.15 and power scale factor
156 to 0.75.
157
158 .TP
159 \fB-dimension\fP \fIdimen\fP
160 Sets the fractal dimension to the specified \fIdimen\fP, which may be
161 any real number between 0 and 5 inclusive. Higher fractal dimensions create
162 more ``chaotic'' images, which require higher resolution output and a larger
163 FFT mesh size to look good. If no dimension is specified, the program uses
164 2.4 when generating planets and 2.15 for clouds.
165
166 .TP
167 \fB-glaciers\fP \fIlevel\fP
168 The floating point \fIlevel\fP setting controls the extent to
169 which terrain elevation causes ice to appear at lower latitudes. The
170 default value of 0.75 makes the polar caps extend toward the equator
171 across high terrain and forms glaciers in the highest mountains, as on
172 Earth. Higher values make ice sheets that cover more and more of the
173 land surface, simulating planets in the midst of an ice age. Lower
174 values tend to be boring, resulting in unrealistic
175 geometrically-precise ice cap boundaries.
176
177 .TP
178 \fB-hour\fP \fIhour\fP
179 When generating a planet, \fBppmforge\fP uses \fIhour\fP as the
180 "hour angle at the central meridian." If you specify \fB-hour
181 12\fP, for example, the planet will be fully illuminated,
182 corresponding to high noon at the longitude at the center of the
183 screen. You can specify any floating point value between 0 and 24 for
184 \fIhour\fP, but values which place most of the planet in darkness (0
185 to 4 and 20 to 24) result in crescents which, while pretty, don't give
186 you many illuminated pixels for the amount of computing that's
187 required. If no \fB-hour\fP option is specified, a random hour angle
188 is chosen, biased so that only 25% of the images generated will be
189 crescents.
190
191 .TP
192 \fB-ice\fP \fIlevel\fP
193 Sets the extent of the polar ice caps to the given floating point
194 \fIlevel\fP. The default level of 0.4 produces ice caps similar to
195 those of the Earth. Smaller values reduce the amount of ice, while
196 larger \fB-ice\fP settings create more prominent ice caps.
197 Sufficiently large values, such as 100 or more, in conjunction with
198 small settings for \fB-glaciers\fP (try 0.1) create "ice
199 balls" like Europa.
200
201 .TP
202 \fB-inclination|-tilt\fP \fIangle\fP
203 The inclination angle of the planet with regard to its primary
204 star is set to \fIangle\fP, which can be any floating point value
205 from -90 to 90. The inclination angle can be thought of as
206 specifying, in degrees, the ``season'' the planet is currently
207 experiencing or, more precisely, the latitude at which the star
208 transits the zenith at local noon. If 0, the planet is at equinox;
209 the star is directly overhead at the equator. Positive values
210 represent summer in the northern hemisphere, negative values summer in
211 the southern hemisphere. The Earth's inclination angle, for example,
212 is about 23.5 at the June solstice, 0 at the equinoxes in March and
213 September, and -23.5 at the December solstice. If no inclination
214 angle is specified, a random value between -21.6 and 21.6 degrees is
215 chosen.
216
217 .TP
218 \fB-mesh\fP \fIsize\fP
219 A mesh of \fIsize\fP by \fIsize\fP will be used for the fast
220 Fourier transform (FFT). Note that memory requirements and
221 computation speed increase as the square of \fIsize\fP; if you double
222 the mesh size, the program will use four times the memory and run four
223 times as long. The default mesh is 256x256, which produces reasonably
224 good looking pictures while using half a megabyte for the 256x256
225 array of single precision complex numbers required by the FFT. On
226 machines with limited memory capacity, you may have to reduce the mesh
227 size to avoid running out of RAM. Increasing the mesh size produces
228 better looking pictures; the difference becomes particularly
229 noticeable when generating high resolution images with relatively high
230 fractal dimensions (between 2.2 and 3).
231
232 .TP
233 \fB-night\fP
234 A starry sky is generated. The stars are created by the same
235 algorithm used for the stars that surround planet pictures, but the
236 output consists exclusively of stars.
237
238 .TP
239 \fB-power\fP \fIfactor\fP
240 Sets the "power factor" used to scale elevations
241 synthesised from the FFT to \fIfactor\fP, which can be any floating
242 point number greater than zero. If no factor is specified a default
243 of 1.2 is used if a planet is being generated, or 0.75 if clouds are
244 selected by the \fB-clouds\fP option. The result of the FFT image
245 synthesis is an array of elevation values between 0 and 1. A
246 non-unity power factor exponentiates each of these elevations to the
247 specified power. For example, a power factor of 2 squares each value,
248 while a power factor of 0.5 replaces each with its square root. (Note
249 that exponentiating values between 0 and 1 yields values that remain
250 within that range.) Power factors less than 1 emphasise large-scale
251 elevation changes at the expense of small variations. Power factors
252 greater than 1 increase the roughness of the terrain and, like high
253 fractal dimensions, may require a larger FFT mesh size and/or higher
254 screen resolution to look good.
255
256 .TP
257 \fB-saturation\fP \fIsat\fP
258 Controls the degree of color saturation of the stars that surround
259 planet pictures and fill starry skies created with the \fB-night\fP
260 option. The default value of 125 creates stars which resemble the sky
261 as seen by the human eye from Earth's surface. Stars are dim; only
262 the brightest activate the cones in the human retina, causing color to
263 be perceived. Higher values of \fIsat\fP approximate the appearance
264 of stars from Earth orbit, where better dark adaptation, absence of
265 skyglow, and the concentration of light from a given star onto a
266 smaller area of the retina thanks to the lack of atmospheric
267 turbulence enhances the perception of color. Values greater than 250
268 create ``science fiction'' skies that, while pretty, don't occur in
269 this universe.
270 .sp
271 Thanks to the inverse square law combined with Nature's love of
272 mediocrity, there are many, many dim stars for every bright one. This
273 population relationship is accurately reflected in the skies created
274 by \fBppmforge\fP. Dim, low mass stars live much longer than bright
275 massive stars, consequently there are many reddish stars for every
276 blue giant. This relationship is preserved by \fBppmforge\fP. You
277 can reverse the proportion, simulating the sky as seen in a starburst
278 galaxy, by specifying a negative \fIsat\fP value.
279
280 .TP
281 \fB-seed\fP \fInum\fP
282 Sets the seed for the random number generator to the integer
283 \fInum\fP. The seed used to create each picture is displayed on
284 standard output (unless suppressed with the \fB-quiet\fP option).
285 Pictures generated with the same seed will be identical. If no
286 \fB-seed\fP is specified, a random seed derived from the date and
287 time will be chosen. Specifying an explicit seed allows you to
288 re-render a picture you particularly like at a higher resolution or
289 with different viewing parameters.
290
291 .TP
292 \fB-stars\fP \fIfraction\fP
293 Specifies the percentage of pixels, in tenths of a percent, which
294 will appear as stars, either surrounding a planet or filling the
295 entire frame if \fB-night\fP is specified. The default
296 \fIfraction\fP is 100.
297
298 .TP
299 \fB-xsize|-width\fP\fI width\fP
300 Sets the width of the generated image to \fIwidth\fP pixels. The
301 default width is 256 pixels. Images must be at least as wide as they
302 are high; if a width less than the height is specified, it will be
303 increased to equal the height. If you must have a long skinny image,
304 make a square one with \fBppmforge\fP, then use \fBpamcut\fP to
305 extract a portion of the shape and size you require.
306
307 .TP
308 \fB-ysize|-height\fP \fIheight\fP
309 Sets the height of the generated image to \fIheight\fP pixels.
310 The default height is 256 pixels. If the height specified exceeds the
311 width, the width will be increased to equal the height.
312
313
314
315 .UN limitations
316 .SH LIMITATIONS
317 .PP
318 The algorithms require the output image to be at least as wide as
319 it is high, and the width to be an even number of pixels. These
320 constraints are enforced by increasing the size of the requested
321 image if necessary.
322 .PP
323 You may have to reduce the FFT mesh size on machines with 16 bit
324 integers and segmented pointer architectures.
325
326 .UN seealso
327 .SH SEE ALSO
328 .BR "pamcut" (1)\c
329 \&,
330 .BR "pamdepth" (1)\c
331 \&,
332 .BR "ppmdither" (1)\c
333 \&,
334 .BR "pnmquant" (1)\c
335 \&,
336 .BR "ppm" (1)\c
337 \&
338
339
340 .TP
341 [1]
342 Voss, Richard F., ``Random Fractal Forgeries,'' in Earnshaw
343 et. al., Fundamental Algorithms for Computer Graphics, Berlin:
344 Springer-Verlag, 1985.
345
346 .TP
347 [2]
348 Peitgen, H.-O., and Saupe, D. eds., The Science Of Fractal Images,
349 New York: Springer Verlag, 1988.
350
351
352
353 .UN author
354 .SH AUTHOR
355
356 .nf
357 John Walker
358 Autodesk SA
359 Avenue des Champs-Montants 14b
360 CH-2074 MARIN
361 Suisse/Schweiz/Svizzera/Svizra/Switzerland
362 \fBUsenet:\fP\[email protected]\fP
363 \fBFax:\fP038/33 88 15
364 \fBVoice:\fP038/33 76 33
365
366 .fi
367 .PP
368 Permission to use, copy, modify, and distribute this software and its
369 documentation for any purpose and without fee is hereby granted,
370 without any conditions or restrictions. This software is provided ``as
371 is'' without express or implied warranty.
372
373 .SS PLUGWARE!
374
375 If you like this kind of stuff, you may also enjoy ``James Gleick's
376 Chaos--The Software'' for MS-DOS, available for $59.95 from your
377 local software store or directly from Autodesk, Inc., Attn: Science
378 Series, 2320 Marinship Way, Sausalito, CA 94965, USA. Telephone:
379 (800) 688-2344 toll-free or, outside the U.S. (415) 332-2344 Ext
380 4886. Fax: (415) 289-4718. ``Chaos--The Software'' includes a more
381 comprehensive fractal forgery generator which creates
382 three-dimensional landscapes as well as clouds and planets, plus five
383 more modules which explore other aspects of Chaos. The user guide of
384 more than 200 pages includes an introduction by James Gleick and
385 detailed explanations by Rudy Rucker of the mathematics and algorithms
386 used by each program.
387 .SH DOCUMENT SOURCE
388 This manual page was generated by the Netpbm tool 'makeman' from HTML
389 source. The master documentation is at
390 .IP
391 .B http://netpbm.sourceforge.net/doc/ppmforge.html
392 .PP