ppmforge(1)						      General Commands Manual						       ppmforge(1)

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 synthe-
       sised 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 ar-
       ray, 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, de-
       termines 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  associ-
       ated  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 eleva-
       tion 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  wa-
		 ter  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 eleva-
		 tion 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 dimen-
		 sions create more ``chaotic'' images, which require higher resolution output and a larger FFT mesh size to look good.	If no  di-
		 mension 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 de-
		 fault value of 0.75 makes the polar caps extend toward the equator across high terrain and forms glaciers in  the  highest  moun-
		 tains,  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)  re-
		 sult 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.  Suffi-
		 ciently 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	experienc-
		 ing  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  se-
		 lected by the -clouds option.	The result of the FFT image synthesis is an array of elevation values between 0 and 1.	A non-uni-
		 ty 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 ppm-
		 forge.  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 con-
       straints 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  com-
       prehensive 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)