Generate Repeatable Cratered Terrain with pgmcrater

pgmcrater builds a small, repeatable cratered terrain image as a PGM file, with no input image and no elevated privileges required. It is handy for testing Netpbm pipelines, running quick terrain studies, or keeping an old script alive. Allow about ten minutes for a first run, checking the output included.

1. Check the installed command

This guide assumes a Linux system with the netpbm package installed. On the machine used here, that is Netpbm 11.5.2, and pgmcrater is a Perl compatibility wrapper. The local manual page is dated 26 July 2014, so the package version below is the reference that actually matches what you are running.

$ command -v pgmcrater
/usr/bin/pgmcrater
$ pgmcrater --version
pamcrater: Using libnetpbm from Netpbm Version: Netpbm 11.5.2

--help is not a documented interface here: this installation rejects it as an unknown option. Use man pgmcrater for the option list instead. Everything below runs fine as an ordinary user.

2. Generate a small, deterministic image

Set the crater count, dimensions and random seed explicitly while you are testing. A fixed seed makes repeated runs produce identical pixels, which is exactly what you want when comparing a pipeline or chasing down a change.

$ pgmcrater -number 3 -width 64 -height 48 -randomseed 7 > crater-64x48.pgm
$ file crater-64x48.pgm
crater-64x48.pgm: Netpbm image data, size = 64 x 48, rawbits, greymap

The redirection creates or truncates crater-64x48.pgm. The image goes to standard output, so a successful run normally prints nothing at all. The result is a PGM ready for any program that reads Netpbm PGM.

3. Understand what the numbers actually control

-number sets how many craters get generated, not a cap on the ones you can see. The documented default is 50,000. A power-law size distribution means plenty of small craters shape the terrain without any single one standing out. More craters, and bigger images, both take longer to render.

-width and -height set the output dimensions in pixels; both default to 256. -xsize and -ysize are aliases for them, but spell out the full names in new scripts so intent is obvious on review.

The generated terrain is an elevation map, not a finished picture. The compatibility command shades that map and converts it to PGM for you, so the brightness you see represents slope, as if the terrain were lit from the left. In other words, the old command name hides a three-stage pipeline: pamcrater, then pamshadedrelief, then pamtopnm.

4. Prove the result is repeatable

Run the same command twice and diff the checksums rather than trusting a viewer to make two images "look the same":

$ pgmcrater -number 3 -width 64 -height 48 -randomseed 7 > crater-a.pgm
$ pgmcrater -number 3 -width 64 -height 48 -randomseed 7 > crater-b.pgm
$ cmp -s crater-a.pgm crater-b.pgm && echo identical
identical

Skip -randomseed and the generator falls back to a seed derived from the time of day and process ID, so separate runs are meant to differ. Never use an unseeded run as a test fixture. The option itself dates back to Netpbm 10.61, well before the 11.5.2 package used here.

5. Adjust contrast with gamma

Reach for -gamma when the terrain shape is right but the shading needs different contrast. A value of 1 matches the default look; above 1 lightens and flattens the contrast, below 1 darkens and sharpens it.

$ pgmcrater -number 3 -width 64 -height 48 -randomseed 7 -gamma 1 > crater-medium.pgm
$ file crater-medium.pgm
crater-medium.pgm: Netpbm image data, size = 64 x 48, rawbits, greymap

Here is a wrinkle worth knowing: this installed wrapper parses -gamma as an integer, even though the manual describes the underlying factor as a general number. A value like 1.0 gets rejected outright. Need a fractional value? Drop to the component pipeline directly and check its own manual page:

$ pamcrater -number 3 -width 64 -height 48 -randomseed 7 | pamshadedrelief -gamma 0.8 | pamtopnm > crater-high-contrast.pgm

6. Avoid losing an existing image

Redirection truncates the destination the moment the shell opens it, before pgmcrater even starts. If the output name already holds something you care about, write a temporary sibling first and swap it in after checking it:

$ pgmcrater -number 3 -width 64 -height 48 -randomseed 7 > crater-64x48.pgm.new
$ file crater-64x48.pgm.new
$ mv crater-64x48.pgm.new crater-64x48.pgm

If generation fails, delete only the incomplete .new file and the original is untouched. Do not remove the old image until the replacement has the right dimensions and looks correct in your viewer. Nothing in this workflow needs sudo.

7. Diagnose the usual failures

• Unknown option: check the spelling against man pgmcrater. The wrapper only accepts the documented terrain options, and there is no general help flag.
• Invalid gamma: try an integer with the compatibility wrapper, or switch to pamshadedrelief for a fractional factor.
• Unexpected appearance: confirm dimensions, seed and gamma, then look at the PGM in a trusted viewer. A technically valid file can still be visually wrong.
• Slow generation: cut -number or the image dimensions while testing. The default of 50,000 craters is not light work at every size.