| 1 |
\ |
| 2 |
.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. |
| 3 |
.\" Do not hand-hack it! If you have bug fixes or improvements, please find |
| 4 |
.\" the corresponding HTML page on the Netpbm website, generate a patch |
| 5 |
.\" against that, and send it to the Netpbm maintainer. |
| 6 |
.TH "Pamcrater User Manual" 1 "03 November 2014" "netpbm documentation" |
| 7 |
|
| 8 |
.SH NAME |
| 9 |
|
| 10 |
pamcrater - create cratered terrain by fractal forgery |
| 11 |
|
| 12 |
|
| 13 |
.UN synopsis |
| 14 |
.SH SYNOPSIS |
| 15 |
|
| 16 |
\fBpamcrater\fP |
| 17 |
|
| 18 |
[\fB-number\fP \fIn\fP] |
| 19 |
|
| 20 |
[\fB-height\fP \fIpixels\fP] |
| 21 |
|
| 22 |
[\fB-width\fP \fIpixels\fP] |
| 23 |
|
| 24 |
[\fB-randomseed=\fP\fIinteger\fP] |
| 25 |
|
| 26 |
[\fB-verbose\fP] |
| 27 |
|
| 28 |
.UN description |
| 29 |
.SH DESCRIPTION |
| 30 |
.PP |
| 31 |
This program is part of |
| 32 |
.BR "Netpbm" (1)\c |
| 33 |
\&. |
| 34 |
.PP |
| 35 |
\fBpamcrater\fP creates a PAM image which is a terrain map (not a visual |
| 36 |
image) of cratered terrain. The terrain is as if a given number of impacts |
| 37 |
into a surface create craters with random position and size. |
| 38 |
.PP |
| 39 |
The size distribution of the craters is based on a power law which results |
| 40 |
in many more small craters than large ones. The number of craters of a given |
| 41 |
size varies as the reciprocal of the area as described on pages 31 and 32 of |
| 42 |
Peitgen and Saupe[1]; cratered bodies in the Solar System are observed to obey |
| 43 |
this relationship. The formula used to obtain crater radii governed by this |
| 44 |
law from a uniformly distributed pseudorandom sequence was developed by Rudy |
| 45 |
Rucker. |
| 46 |
.PP |
| 47 |
A terrain map is a two dimensional map of terrain elevations. the PAM |
| 48 |
image that \fBpamcrater\fP produces is therefore not a visual image but a |
| 49 |
depth-one image of tuple type "elevation", with the sample value |
| 50 |
being proportional to an elevation. |
| 51 |
.PP |
| 52 |
You can visualize the terrain map by generating a shaded relief image of it |
| 53 |
with \fBpamshadedrelief\fP. |
| 54 |
.PP |
| 55 |
High resolution images with large numbers of |
| 56 |
craters often benefit from being piped through \fBpnmsmooth\fP. The |
| 57 |
averaging performed by this process eliminates some of the jagged pixels and |
| 58 |
lends a mellow ``telescopic image'' feel to the overall picture. |
| 59 |
.PP |
| 60 |
\fBpamcrater\fP generates only small craters, which are hemispherical in |
| 61 |
shape (regardless of the incidence angle of the impacting body, as long as the |
| 62 |
velocity is sufficiently high). Large craters, such as Copernicus and Tycho |
| 63 |
on the Moon, have a ``walled plain'' shape with a cross-section more like: |
| 64 |
|
| 65 |
.nf |
| 66 |
/\e /\e |
| 67 |
_____/ \e____________/\e____________/ \e_____ |
| 68 |
|
| 69 |
.fi |
| 70 |
.PP |
| 71 |
Larger craters should really use this profile, including the central |
| 72 |
peak, and totally obliterate the pre-existing terrain. |
| 73 |
.PP |
| 74 |
The maxval of the PAM image is always 65535. |
| 75 |
.PP |
| 76 |
The randomness in the image is limited before Netpbm 10.37 (December |
| 77 |
2006) -- if you run the program twice in the same second, you may get |
| 78 |
identical output. |
| 79 |
|
| 80 |
|
| 81 |
.UN options |
| 82 |
.SH OPTIONS |
| 83 |
.PP |
| 84 |
In addition to the options common to all programs based on libnetpbm |
| 85 |
(most notably \fB-quiet\fP, see |
| 86 |
.UR index.html#commonoptions |
| 87 |
Common Options |
| 88 |
.UE |
| 89 |
\&), \fBpamcrater\fP recognizes the following |
| 90 |
command line options: |
| 91 |
.PP |
| 92 |
All options can be abbreviated to their shortest unique prefix. |
| 93 |
|
| 94 |
|
| 95 |
.TP |
| 96 |
\fB-number\fP \fIn\fP |
| 97 |
This causes \fBpamcrater\fP to generate \fIn\fP craters. If you do not |
| 98 |
specify \fB-number\fP, it generates 50000 craters. Don't expect to see them |
| 99 |
all! For every large crater there are many, many more tiny ones which tend |
| 100 |
simply to erode the landscape. In general, the more craters you specify, the |
| 101 |
more realistic the result; ideally you want the entire terrain to have been |
| 102 |
extensively turned over again and again by cratering. High resolution images |
| 103 |
containing five to ten million craters are stunning but take longer to create. |
| 104 |
|
| 105 |
.TP |
| 106 |
\fB-height\fP \fIheight\fP |
| 107 |
This sets the height of the generated image to \fIheight\fP pixels. |
| 108 |
The default height is 256 pixels. |
| 109 |
|
| 110 |
.TP |
| 111 |
\fB-width\fP \fIwidth\fP |
| 112 |
This sets the width of the generated image to \fIwidth\fP pixels. The |
| 113 |
default width is 256 pixels. |
| 114 |
|
| 115 |
.TP |
| 116 |
\fB-randomseed=\fP\fIinteger\fP |
| 117 |
This is the seed for the random number generator that generates the |
| 118 |
pixels. |
| 119 |
.sp |
| 120 |
Use this to ensure you get the same image on separate invocations. |
| 121 |
.sp |
| 122 |
By default, \fBpamcrater\fP uses a seed derived from the time of day and |
| 123 |
process ID, which gives you fairly uncorrelated results in multiple |
| 124 |
invocations. |
| 125 |
.sp |
| 126 |
This option was new in Netpbm 10.61 (December 2012). |
| 127 |
|
| 128 |
.TP |
| 129 |
\fB-verbose\fP |
| 130 |
This causes \fBpamcrater\fP to issue additional messages about what it |
| 131 |
is doing. |
| 132 |
.sp |
| 133 |
This option was new in Neptbm 10.69 (December 2014). |
| 134 |
|
| 135 |
|
| 136 |
|
| 137 |
.UN examples |
| 138 |
.SH EXAMPLES |
| 139 |
|
| 140 |
.nf |
| 141 |
\f(CW |
| 142 |
$ pamcrater | pamshadedrelief | pamx |
| 143 |
|
| 144 |
$ pamcrater -number=500000 -height=1000 -width=1000 >craters.pam |
| 145 |
\fP |
| 146 |
|
| 147 |
.fi |
| 148 |
|
| 149 |
.UN designnotes |
| 150 |
.SH DESIGN NOTES |
| 151 |
.PP |
| 152 |
Real craters have two distinct morphologies. |
| 153 |
|
| 154 |
|
| 155 |
.UN seealso |
| 156 |
.SH SEE ALSO |
| 157 |
.BR "pamshadedrelief" (1)\c |
| 158 |
\&, |
| 159 |
.BR "ppmrelief" (1)\c |
| 160 |
\&, |
| 161 |
.BR "pnmsmooth" (1)\c |
| 162 |
\& |
| 163 |
.BR "pam" (1)\c |
| 164 |
\&, |
| 165 |
|
| 166 |
|
| 167 |
.TP |
| 168 |
[1] |
| 169 |
Peitgen, H.-O., and Saupe, D. eds., The Science Of Fractal Images, |
| 170 |
New York: Springer Verlag, 1988. |
| 171 |
|
| 172 |
|
| 173 |
|
| 174 |
.UN author |
| 175 |
.SH AUTHOR |
| 176 |
.PP |
| 177 |
\fBpgmcrater\fP, from which this is derived, was written by John Walker: |
| 178 |
|
| 179 |
.nf |
| 180 |
John Walker |
| 181 |
Autodesk SA |
| 182 |
Avenue des Champs-Montants 14b |
| 183 |
CH-2074 MARIN |
| 184 |
Suisse/Schweiz/Svizzera/Svizra/Switzerland |
| 185 |
\fBUsenet:\fP\[email protected]\fP |
| 186 |
\fBFax:\fP038/33 88 15 |
| 187 |
\fBVoice:\fP038/33 76 33 |
| 188 |
|
| 189 |
.fi |
| 190 |
.PP |
| 191 |
Permission to use, copy, modify, and distribute this software and |
| 192 |
its documentation for any purpose and without fee is hereby granted, |
| 193 |
without any conditions or restrictions. This software is provided |
| 194 |
"as is" without express or implied warranty. |
| 195 |
|
| 196 |
|
| 197 |
.UN history |
| 198 |
.SH HISTORY |
| 199 |
.PP |
| 200 |
John Walker wrote \fBpgmcrater\fP in 1991 and it was included in Pbmplus. |
| 201 |
\fBpgmcrater\fP did the equivalent of \f(CWpamcrater | pamshadedrelief\fP. |
| 202 |
In Netpbm 10.68 (September 2014), Bryan Henderson split the functions |
| 203 |
of \fBpgmcrater\fP into two programs, one (\fBpamcrater\fP) to compute |
| 204 |
elevations, and the other (\fBpamshadedrelief\fP) to generate a shaded relief |
| 205 |
visual image showing those elevations. Bryan did this because it is more in |
| 206 |
keeping with Netpbm's modular architecture, and because |
| 207 |
the \fBpamshadedrelief\fP might be useful with other inputs. |
| 208 |
.PP |
| 209 |
(Like all Netpbm programs, \fBpgmcrater\fP was not static between the two |
| 210 |
events described above; minor changes, including replacement of most of the |
| 211 |
code, happened in between). |
| 212 |
.PP |
| 213 |
The original 1991 \fBpgmcrater\fP manual contains the following: |
| 214 |
|
| 215 |
.SS PLUGWARE! |
| 216 |
.PP |
| 217 |
If you like this kind of stuff, you may also enjoy "James Gleick's |
| 218 |
Chaos--The Software" for MS-DOS, available for $59.95 from your |
| 219 |
local software store or directly from Autodesk, Inc., Attn: Science |
| 220 |
Series, 2320 Marinship Way, Sausalito, CA 94965, USA. Telephone: |
| 221 |
(800) 688-2344 toll-free or, outside the U.S. (415) 332-2344 Ext |
| 222 |
4886. Fax: (415) 289-4718. "Chaos--The Software" includes a more |
| 223 |
comprehensive fractal forgery generator which creates |
| 224 |
three-dimensional landscapes as well as clouds and planets, plus five |
| 225 |
more modules which explore other aspects of Chaos. The user guide of |
| 226 |
more than 200 pages includes an introduction by James Gleick and |
| 227 |
detailed explanations by Rudy Rucker of the mathematics and algorithms |
| 228 |
used by each program. |
| 229 |
.SH DOCUMENT SOURCE |
| 230 |
This manual page was generated by the Netpbm tool 'makeman' from HTML |
| 231 |
source. The master documentation is at |
| 232 |
.IP |
| 233 |
.B http://netpbm.sourceforge.net/doc/pamcrater.html |
| 234 |
.PP |