Provided by: netpbm_10.0-15.3_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)