Provided by: netpbm_10.0-15.4_amd64 bug

NAME

       ppmforge - fractal forgeries of clouds, planets, and starry skies

SYNOPSIS

       ppmforge [-clouds] [-night] [-dimension dimen] [-hour hour] [-inclination|-tilt angle] [-mesh size]
                [-power factor] [-glaciers level] [-ice level] [-saturation sat] [-seed seed] [-stars fraction]
                [-xsize|-width width] [-ysize|-height height]

DESCRIPTION

       ppmforge 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 ppmforge are
       essentially those given by Voss[1], particularly the technique of spectral synthesis  explained  in  more
       detail by Dietmar Saupe[2].

       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.

       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 -mesh 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 -dimension 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.

       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  -power  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).

       After  these  calculations, we have a array of the specified size containing numbers that range from 0 to
       1.  The pixmaps are generated as follows:

       Clouds    A colour map  is  created  that  ranges  from  pure  blue  to  white  by  increasing  admixture
                 (desaturation)  of  blue  with white.  Numbers less than 0.5 are coloured blue, numbers between
                 0.5 and 1.0 are coloured with corresponding levels of white, with 1.0 being pure white.

       Planet    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 coloured 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 colour 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.

       Night     A sequence of pseudorandom numbers is used to generate stars with a user specified density.

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

OPTIONS

       -clouds   Generate  clouds.   A pixmap of fractal clouds is generated.  Selecting clouds sets the default
                 for fractal dimension to 2.15 and power scale factor to 0.75.

       -dimension dimen
                 Sets the fractal dimension to the specified dimen,  which  may  be  any  floating  point  value
                 between  0  and  3.   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, 2.4 is used when generating planets and 2.15 for clouds.

       -glaciers level
                 The  floating  point level 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.

       -hour hour
                 When generating a planet, hour is used as the ``hour angle at the central meridian.''   If  you
                 specify -hour 12, for example, the planet will be fully illuminated, corresponding to high noon
                 at the longitude at the centre of the screen.  You can specify any floating point value between
                 0  and 24 for hour, 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 -hour option is specified, a random hour angle is chosen,
                 biased so that only 25% of the images generated will be crescents.

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

       -inclination|-tilt angle
                 The inclination angle of the planet with regard to its primary star is set to angle, 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 presently 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.

       -mesh size
                 A mesh of size by size will be used for the fast Fourier transform  (FFT).   Note  that  memory
                 requirements and computation speed increase as the square of size; 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).

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

       -power factor
                 Sets  the  ``power  factor'' used to scale elevations synthesised from the FFT to factor, 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 -clouds 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.

       -saturation sat
                 Controls  the  degree  of colour saturation of the stars that surround planet pictures and fill
                 starry skies created with the -night 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  colour  to  be  perceived.   Higher
                 values  of  sat  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
                 colour.  Values greater than 250 create ``science fiction'' skies  that,  while  pretty,  don't
                 occur in this universe.

                 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 ppmforge.  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 ppmforge.  You can reverse the proportion, simulating the sky as seen in a starburst galaxy,
                 by specifying a negative sat value.

       -seed num Sets the seed for the random number generator to the integer num.  The seed used to create each
                 picture  is  displayed on standard output (unless suppressed with the -quiet option).  Pictures
                 generated with the same seed will be identical.  If  no  -seed  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.

       -stars fraction
                 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 -night is specified.  The default  fraction
                 is 100.

       -xsize|-width width
                 Sets  the  width  of  the  generated  image  to width 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 pixmap, make a square
                 one with ppmforge, then use pnmcut to extract a portion of the shape and size you require.

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

       All flags can be abbreviated to their shortest unique prefix.

BUGS

       The  algorithms  require  the  output pixmap 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 pixmap  if
       necessary.

       You  may  have  to  reduce  the  FFT  mesh  size  on  machines with 16 bit integers and segmented pointer
       architectures.

SEE ALSO

       pnmcut(1), pnmdepth(1), ppmdither(1), ppmquant(1), ppm(5)

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

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

AUTHOR

            John Walker
            Autodesk SA
            Avenue des Champs-Montants 14b
            CH-2074 MARIN
            Suisse/Schweiz/Svizzera/Svizra/Switzerland
            Usenet:  kelvin@Autodesk.com
            Fax:     038/33 88 15
            Voice:   038/33 76 33

       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.

       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.

                                                 25 October 1991                                     ppmforge(1)