path: root/upstream/debian-unstable/man1/ppmforge.1

\
.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
.\" the corresponding HTML page on the Netpbm website, generate a patch
.\" against that, and send it to the Netpbm maintainer.
.TH "Ppmforge User Manual" 1 "27 March 2021" "netpbm documentation"

.SH NAME

ppmforge - fractal forgeries of clouds, planets, and starry skies
.UN synopsis
.SH SYNOPSIS

\fBppmforge\fP

[\fB-clouds\fP]
[\fB-night\fP]
[\fB-dimension\fP \fIdimen\fP]
[\fB-hour\fP \fIhour\fP]
[\fB-inclination|-tilt\fP \fIangle\fP]
[\fB-mesh\fP \fIsize\fP]
[\fB-power\fP \fIfactor\fP]
[\fB-glaciers\fP \fIlevel\fP]
[\fB-ice\fP \fIlevel\fP]
[\fB-saturation\fP \fIsat\fP]
[\fB-seed\fP \fIseed\fP]
[\fB-stars\fP \fIfraction\fP]
[{\fB-xsize\fP|\fB-width\fP} \fIwidth\fP]
[{\fB-ysize\fP|\fB-height\fP} \fIheight\fP]

.UN description
.SH DESCRIPTION
.PP
This program is part of
.BR "Netpbm" (1)\c
\&.
.PP
\fBppmforge\fP generates three kinds of ``random fractal forgeries,''
the term coined by Richard F. Voss of the IBM Thomas J. Watson
Research Center for seemingly realistic pictures of natural objects
generated by simple algorithms embodying randomness and fractal
self-similarity.  The techniques used by \fBppmforge\fP are
essentially those given by Voss[1], particularly the technique of
spectral synthesis explained in more detail by Dietmar Saupe[2].
.PP
The program generates two varieties of pictures: planets and
clouds, which are just different renderings of data generated in an
identical manner, illustrating the unity of the fractal structure of
these very different objects.  A third type of picture, a starry sky,
is synthesised directly from pseudorandom numbers.
.PP
The generation of planets or clouds begins with the preparation of
an array of random data in the frequency domain.  The size of this
array, the ``mesh size,'' can be set with the \fB-mesh\fP option; the
larger the mesh the more realistic the pictures but the calculation
time and memory requirement increases as the square of the mesh size.
The fractal dimension, which you can specify with the
\fB-dimension\fP option, determines the roughness of the terrain on
the planet or the scale of detail in the clouds.  As the fractal
dimension is increased, more high frequency components are added into
the random mesh.
.PP
Once the mesh is generated, an inverse two dimensional Fourier
transform is performed upon it.  This converts the original random
frequency domain data into spatial amplitudes.  We scale the real
components that result from the Fourier transform into numbers from 0
to 1 associated with each point on the mesh.  You can further modify
this number by applying a ``power law scale'' to it with the
\fB-power\fP option.  Unity scale leaves the numbers unmodified; a
power scale of 0.5 takes the square root of the numbers in the mesh,
while a power scale of 3 replaces the numbers in the mesh with their
cubes.  Power law scaling is best envisioned by thinking of the data
as representing the elevation of terrain; powers less than 1 yield
landscapes with vertical scarps that look like glacially-carved
valleys; powers greater than one make fairy-castle spires (which
require large mesh sizes and high resolution for best results).
.PP
After these calculations, we have a array of the specified size
containing numbers that range from 0 to 1.  \fBppmforge\fP generates
as follows:
.PP
The randomness in the image is limited before Netpbm 10.37 (December
2006) -- if you run the program twice in the same second, you may get
identical output.


.TP
\fBClouds\fP
A color map is created that ranges from pure blue to white by
increasing admixture (desaturation) of blue with white.  Numbers less
than 0.5 are colored blue, numbers between 0.5 and 1.0 are colored
with corresponding levels of white, with 1.0 being pure white.

.TP
\fBPlanet\fP
The mesh is projected onto a sphere.  Values less than 0.5 are treated
as water and values between 0.5 and 1.0 as land.  The water areas are
colored based upon the water depth, and land based on its elevation.
The random depth data are used to create clouds over the oceans.  An
atmosphere approximately like the Earth's is simulated; its light
absorption is calculated to create a blue cast around the limb of the
planet.  A function that rises from 0 to 1 based on latitude is
modulated by the local elevation to generate polar ice caps--high
altitude terrain carries glaciers farther from the pole.  Based on the
position of the star with respect to the observer, the apparent color
of each pixel of the planet is calculated by ray-tracing from the star
to the planet to the observer and applying a lighting model that sums
ambient light and diffuse reflection (for most planets ambient light
is zero, as their primary star is the only source of illumination).
Additional random data are used to generate stars around the planet.

.TP
\fBNight\fP
A sequence of pseudorandom numbers is used to generate stars with a
user specified density.

.PP
Cloud pictures always contain 256 or fewer colors and may be
displayed on most color mapped devices without further processing.
Planet pictures often contain tens of thousands of colors which must
be compressed with \fBpnmquant\fP or \fBppmdither\fP before encoding
in a color mapped format.  If the display resolution is high enough,
\fBppmdither\fP generally produces better looking planets.
\fBpnmquant\fP tends to create discrete color bands, particularly in
the oceans, which are unrealistic and distracting.  The number of
colors in starry sky pictures generated with the \fB-night\fP option
depends on the value specified for \fB-saturation\fP.  Small values
limit the color temperature distribution of the stars and reduce the
number of colors in the image.  If the \fB-saturation\fP is set to
0, none of the stars will be colored and the resulting image will
never contain more than 256 colors.  Night sky pictures with many
different star colors often look best when color compressed by
\fBpamdepth\fP rather than \fBpnmquant\fP or \fBppmdither\fP.  Try
\fInewmaxval\fP settings of 63, 31, or 15 with \fBpamdepth\fP to
reduce the number of colors in the picture to 256 or fewer.


.UN options
.SH OPTIONS
.PP
In addition to the options common to all programs based on libnetpbm
(most notably \fB-quiet\fP, see 
.UR index.html#commonoptions
 Common Options
.UE
\&), \fBppmforge\fP recognizes the following
command line options:
.PP
You can abbreviate any options to its shortest unique prefix.


.TP
\fB-clouds\fP
Generate clouds.  An image of fractal clouds is generated.  Selecting clouds
sets the default for fractal dimension to 2.15 and power scale factor
to 0.75.

.TP
\fB-dimension\fP \fIdimen\fP
 Sets the fractal dimension to the specified \fIdimen\fP, which may be
any real number between 0 and 5 inclusive.  Higher fractal dimensions create
more ``chaotic'' images, which require higher resolution output and a larger
FFT mesh size to look good.  If no dimension is specified, the program uses
2.4 when generating planets and 2.15 for clouds.

.TP
\fB-glaciers\fP \fIlevel\fP
The floating point \fIlevel\fP setting controls the extent to
which terrain elevation causes ice to appear at lower latitudes.  The
default value of 0.75 makes the polar caps extend toward the equator
across high terrain and forms glaciers in the highest mountains, as on
Earth.  Higher values make ice sheets that cover more and more of the
land surface, simulating planets in the midst of an ice age.  Lower
values tend to be boring, resulting in unrealistic
geometrically-precise ice cap boundaries.

.TP
\fB-hour\fP \fIhour\fP
When generating a planet, \fBppmforge\fP uses \fIhour\fP as the
"hour angle at the central meridian."  If you specify \fB-hour
12\fP, for example, the planet will be fully illuminated,
corresponding to high noon at the longitude at the center of the
screen.  You can specify any floating point value between 0 and 24 for
\fIhour\fP, but values which place most of the planet in darkness (0
to 4 and 20 to 24) result in crescents which, while pretty, don't give
you many illuminated pixels for the amount of computing that's
required.  If no \fB-hour\fP option is specified, a random hour angle
is chosen, biased so that only 25% of the images generated will be
crescents.

.TP
\fB-ice\fP \fIlevel\fP
Sets the extent of the polar ice caps to the given floating point
\fIlevel\fP.  The default level of 0.4 produces ice caps similar to
those of the Earth.  Smaller values reduce the amount of ice, while
larger \fB-ice\fP settings create more prominent ice caps.
Sufficiently large values, such as 100 or more, in conjunction with
small settings for \fB-glaciers\fP (try 0.1) create "ice
balls" like Europa.

.TP
\fB-inclination|-tilt\fP \fIangle\fP
The inclination angle of the planet with regard to its primary
star is set to \fIangle\fP, which can be any floating point value
from -90 to 90.  The inclination angle can be thought of as
specifying, in degrees, the ``season'' the planet is currently
experiencing or, more precisely, the latitude at which the star
transits the zenith at local noon.  If 0, the planet is at equinox;
the star is directly overhead at the equator.  Positive values
represent summer in the northern hemisphere, negative values summer in
the southern hemisphere.  The Earth's inclination angle, for example,
is about 23.5 at the June solstice, 0 at the equinoxes in March and
September, and -23.5 at the December solstice.  If no inclination
angle is specified, a random value between -21.6 and 21.6 degrees is
chosen.

.TP
\fB-mesh\fP \fIsize\fP
A mesh of \fIsize\fP by \fIsize\fP will be used for the fast
Fourier transform (FFT).  Note that memory requirements and
computation speed increase as the square of \fIsize\fP; if you double
the mesh size, the program will use four times the memory and run four
times as long.  The default mesh is 256x256, which produces reasonably
good looking pictures while using half a megabyte for the 256x256
array of single precision complex numbers required by the FFT.  On
machines with limited memory capacity, you may have to reduce the mesh
size to avoid running out of RAM.  Increasing the mesh size produces
better looking pictures; the difference becomes particularly
noticeable when generating high resolution images with relatively high
fractal dimensions (between 2.2 and 3).

.TP
\fB-night\fP
A starry sky is generated.  The stars are created by the same
algorithm used for the stars that surround planet pictures, but the
output consists exclusively of stars.

.TP
\fB-power\fP \fIfactor\fP
Sets the "power factor" used to scale elevations
synthesised from the FFT to \fIfactor\fP, which can be any floating
point number greater than zero.  If no factor is specified a default
of 1.2 is used if a planet is being generated, or 0.75 if clouds are
selected by the \fB-clouds\fP option.  The result of the FFT image
synthesis is an array of elevation values between 0 and 1.  A
non-unity power factor exponentiates each of these elevations to the
specified power.  For example, a power factor of 2 squares each value,
while a power factor of 0.5 replaces each with its square root.  (Note
that exponentiating values between 0 and 1 yields values that remain
within that range.)  Power factors less than 1 emphasise large-scale
elevation changes at the expense of small variations.  Power factors
greater than 1 increase the roughness of the terrain and, like high
fractal dimensions, may require a larger FFT mesh size and/or higher
screen resolution to look good.

.TP
\fB-saturation\fP \fIsat\fP
Controls the degree of color saturation of the stars that surround
planet pictures and fill starry skies created with the \fB-night\fP
option.  The default value of 125 creates stars which resemble the sky
as seen by the human eye from Earth's surface.  Stars are dim; only
the brightest activate the cones in the human retina, causing color to
be perceived.  Higher values of \fIsat\fP approximate the appearance
of stars from Earth orbit, where better dark adaptation, absence of
skyglow, and the concentration of light from a given star onto a
smaller area of the retina thanks to the lack of atmospheric
turbulence enhances the perception of color.  Values greater than 250
create ``science fiction'' skies that, while pretty, don't occur in
this universe.
.sp
Thanks to the inverse square law combined with Nature's love of
mediocrity, there are many, many dim stars for every bright one.  This
population relationship is accurately reflected in the skies created
by \fBppmforge\fP.  Dim, low mass stars live much longer than bright
massive stars, consequently there are many reddish stars for every
blue giant.  This relationship is preserved by \fBppmforge\fP.  You
can reverse the proportion, simulating the sky as seen in a starburst
galaxy, by specifying a negative \fIsat\fP value.

.TP
\fB-seed\fP \fInum\fP
Sets the seed for the random number generator to the integer
\fInum\fP.  The seed used to create each picture is displayed on
standard output (unless suppressed with the \fB-quiet\fP option).
Pictures generated with the same seed will be identical.  If no
\fB-seed\fP is specified, a random seed derived from the date and
time will be chosen.  Specifying an explicit seed allows you to
re-render a picture you particularly like at a higher resolution or
with different viewing parameters.

.TP
\fB-stars\fP \fIfraction\fP
Specifies the percentage of pixels, in tenths of a percent, which
will appear as stars, either surrounding a planet or filling the
entire frame if \fB-night\fP is specified.  The default
\fIfraction\fP is 100.

.TP
\fB-xsize|-width\fP\fI width\fP
Sets the width of the generated image to \fIwidth\fP pixels.  The
default width is 256 pixels.  Images must be at least as wide as they
are high; if a width less than the height is specified, it will be
increased to equal the height.  If you must have a long skinny image,
make a square one with \fBppmforge\fP, then use \fBpamcut\fP to
extract a portion of the shape and size you require.

.TP
\fB-ysize|-height\fP \fIheight\fP
Sets the height of the generated image to \fIheight\fP pixels.
The default height is 256 pixels.  If the height specified exceeds the
width, the width will be increased to equal the height.



.UN limitations
.SH LIMITATIONS
.PP
The algorithms require the output image to be at least as wide as
it is high, and the width to be an even number of pixels.  These
constraints are enforced by increasing the size of the requested
image if necessary.
.PP
You may have to reduce the FFT mesh size on machines with 16 bit
integers and segmented pointer architectures.

.UN seealso
.SH SEE ALSO
.BR "pamcut" (1)\c
\&,
.BR "pamdepth" (1)\c
\&,
.BR "ppmdither" (1)\c
\&,
.BR "pnmquant" (1)\c
\&,
.BR "ppm" (1)\c
\&


.TP
[1] 
Voss, Richard F., ``Random Fractal Forgeries,'' in Earnshaw
et. al., Fundamental Algorithms for Computer Graphics, Berlin:
Springer-Verlag, 1985.

.TP
[2]
Peitgen, H.-O., and Saupe, D. eds., The Science Of Fractal Images,
New York: Springer Verlag, 1988.



.UN author
.SH AUTHOR

.nf
John Walker
Autodesk SA
Avenue des Champs-Montants 14b
CH-2074 MARIN
Suisse/Schweiz/Svizzera/Svizra/Switzerland
    \fBUsenet:\fP\fIkelvin@Autodesk.com\fP
    \fBFax:\fP038/33 88 15
    \fBVoice:\fP038/33 76 33

.fi
.PP
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
without any conditions or restrictions.  This software is provided ``as
is'' without express or implied warranty.

.SS PLUGWARE!

If you like this kind of stuff, you may also enjoy ``James Gleick's
Chaos--The Software'' for MS-DOS, available for $59.95 from your
local software store or directly from Autodesk, Inc., Attn: Science
Series, 2320 Marinship Way, Sausalito, CA 94965, USA.  Telephone:
(800) 688-2344 toll-free or, outside the U.S. (415) 332-2344 Ext
4886.  Fax: (415) 289-4718.  ``Chaos--The Software'' includes a more
comprehensive fractal forgery generator which creates
three-dimensional landscapes as well as clouds and planets, plus five
more modules which explore other aspects of Chaos.  The user guide of
more than 200 pages includes an introduction by James Gleick and
detailed explanations by Rudy Rucker of the mathematics and algorithms
used by each program.
.SH DOCUMENT SOURCE
This manual page was generated by the Netpbm tool 'makeman' from HTML
source.  The master documentation is at
.IP
.B http://netpbm.sourceforge.net/doc/ppmforge.html
.PP