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

       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 uncorrelated 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 implied 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  programs, one (pamcrater) to compute elevations, and the other (pamshadedrelief) to
       generate a shaded relief visual image 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)