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  ⟨index.html#commonoptions⟩ ), 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