| 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 |