Manual: pamcrater

Pamcrater User Manual(1)			   General Commands Manual			    Pamcrater User Manual(1)

NAME
       pamcrater - create cratered terrain by fractal forgery

SYNOPSIS
       pamcrater

       [-number n]

       [-height pixels]

       [-width pixels]

       [-randomseed=integer]

       [-verbose]

DESCRIPTION
       This program is part of Netpbm(1).

       pamcrater  creates a PAM image which is a terrain map (not a visual image) of cratered terrain.	The terrain is as if
       a given number of impacts into a surface create craters with random position and size.

       The size distribution of the craters is based on a power law which results in many  more	 small	craters	 than  large
       ones.   The number of craters of a given size varies as the reciprocal of the area as described on pages 31 and 32 of
       Peitgen and Saupe[1]; cratered bodies in the Solar System are observed to obey this relationship.  The  formula	used
       to  obtain crater radii governed by this law from a uniformly distributed pseudorandom sequence was developed by Rudy
       Rucker.

       A terrain map is a two dimensional map of terrain elevations.  the PAM image that pamcrater produces is therefore not
       a visual image but a depth-one image of tuple type "elevation", with the sample value being proportional to an eleva‐
       tion.

       You can visualize the terrain map by generating a shaded relief image of it with pamshadedrelief.

       High resolution images with large numbers of craters often benefit from being piped through pnmsmooth.  The averaging
       performed by this process eliminates some of the jagged pixels and lends a mellow ``telescopic image''  feel  to	 the
       overall picture.

       pamcrater  generates  only  small craters, which are hemispherical in shape (regardless of the incidence angle of the
       impacting body, as long as the velocity is sufficiently high).  Large craters, such as Copernicus and  Tycho  on	 the
       Moon, have a ``walled plain'' shape with a cross-section more like:

		       /\			     /\
		 _____/	 \____________/\____________/  \_____

       Larger  craters	should	really use this profile, including the central peak, and totally obliterate the pre-existing
       terrain.

       The maxval of the PAM image is always 65535.

       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.

OPTIONS
       In  addition  to	 the  options common to all programs based on libnetpbm (most notably -quiet, see  Common Options ),
       pamcrater recognizes the following command line options:

       All options can be abbreviated to their shortest unique prefix.

       -number n
	      This causes pamcrater to generate n craters.  If you do not  specify  -number,  it  generates  50000  craters.
	      Don't expect to see them all!  For every large crater there are many, many more tiny ones which tend simply to
	      erode  the  landscape.   In  general, the more craters you specify, the more realistic the result; ideally you
	      want the entire terrain to have been extensively turned over again and again by  cratering.   High  resolution
	      images containing five to ten million craters are stunning but take longer to create.

       -height height
	      This sets the height of the generated image to height pixels.  The default height is 256 pixels.

       -width width
	      This sets the width of the generated image to width pixels.  The default width is 256 pixels.

       -randomseed=integer
	      This is the seed for the random number generator that generates the pixels.

	      Use this to ensure you get the same image on separate invocations.

	      By default, pamcrater uses a seed derived from the time of day and process ID, which gives you fairly uncorre‐
	      lated results in multiple invocations.

	      This option was new in Netpbm 10.61 (December 2012).

       -verbose
	      This causes pamcrater to issue additional messages about what it is doing.

	      This option was new in Neptbm 10.69 (December 2014).

EXAMPLES
	   $ pamcrater | pamshadedrelief | pamx

	   $ pamcrater -number=500000 -height=1000 -width=1000 >craters.pam

DESIGN NOTES
       Real craters have two distinct morphologies.

SEE ALSO
       pamshadedrelief(1), ppmrelief(1), pnmsmooth(1) pam(1),

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

AUTHOR
       pgmcrater, from which this is derived, was written by John Walker:

       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	 im‐
       plied warranty.

HISTORY
       John  Walker  wrote  pgmcrater  in  1991 and it was included in Pbmplus.	 pgmcrater did the equivalent of pamcrater |
       pamshadedrelief.	 In Netpbm 10.68 (September 2014), Bryan Henderson split the functions of pgmcrater  into  two	pro‐
       grams,  one (pamcrater) to compute elevations, and the other (pamshadedrelief) to generate a shaded relief visual im‐
       age showing those elevations.  Bryan did this because it is more in keeping with Netpbm's modular  architecture,	 and
       because the pamshadedrelief might be useful with other inputs.

       (Like  all Netpbm programs, pgmcrater was not static between the two events described above; minor changes, including
       replacement of most of the code, happened in between).

       The original 1991 pgmcrater manual contains the following:

   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.

DOCUMENT SOURCE
       This manual page was generated by the Netpbm tool 'makeman' from HTML source.  The master documentation is at

	      http://netpbm.sourceforge.net/doc/pamcrater.html

netpbm documentation				      03 November 2014				    Pamcrater User Manual(1)