Generate Repeatable Cratered Terrain with pgmcrater

You will generate a small, repeatable cratered terrain image as a PGM file, with no input image and no elevated privileges. The command is useful for testing Netpbm pipelines, making simple terrain studies, or keeping an old script working. Allow about ten minutes for a first run, including checking the output.

1. Check the installed command

This guide assumes a Linux system with the netpbm package installed. On the machine used for these examples, the package 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 is the useful reference for the command you are actually 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: on this installation it is rejected as an unknown option. Use man pgmcrater for the option list. You can run all commands below as an ordinary user.

2. Generate a small deterministic image

Choose the crater count, dimensions and random seed explicitly while testing. A fixed seed makes repeated runs produce the same pixels, which is useful when comparing a pipeline or diagnosing 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 program writes the image to standard output, so a successful command normally prints no progress message. The output from this installed wrapper is a PGM image suitable for programs that read Netpbm PGM.

3. Understand what the numbers control

-number is the number of generated craters, not a limit on visible crater outlines. The documented default is 50,000. A power-law size distribution means many small craters can affect the terrain without being individually obvious. More craters generally produce a more heavily worked surface, but larger images and higher counts take longer.

-width and -height set the output dimensions in pixels. Their documented defaults are 256 by 256. -xsize is an alias for -width, and -ysize is an alias for -height; use the full names in new scripts so the intent is easy to review.

The generated terrain is an elevation map, not a finished visual picture. The compatibility command then shades that map and converts it to PGM. The visible brightness represents slope, as though the terrain were lit from the left. The old command therefore hides a three-stage pipeline: pamcrater, pamshadedrelief, then pamtopnm.

4. Make a repeatable comparison

Run the same command twice and compare checksums. This checks the seed and the complete command, rather than relying on a viewer to make two images look similar.

$ 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

Without -randomseed, the component uses a seed derived from the time of day and process ID, so separate invocations are intended to differ. Do not use an unseeded run as a fixture in a test. The option was added in Netpbm 10.61, well before the 11.5.2 package used here.

5. Adjust contrast with gamma

Use -gamma when the terrain is valid but the shaded result needs a different contrast. A value of 1 is the default-equivalent setting. Values above 1 lighten and reduce contrast; values below 1 darken and increase contrast.

$ 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

The installed pgmcrater wrapper parses this option as an integer even though the manual describes the underlying gamma factor generally. Values such as 1.0 are rejected by this package's wrapper. If you need fractional contrast values, use the supported component pipeline directly and check its local 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

Shell redirection truncates the destination before pgmcrater starts. If the output name already matters, write a temporary sibling and replace the old file only after verification.

$ 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, remove only the incomplete .new file and the original remains in place. Do not delete the old image until the replacement has the expected dimensions and looks correct in your image viewer. No command in this workflow needs sudo.

7. Diagnose the usual failures

• Unknown option: check the spelling against man pgmcrater. The wrapper accepts the documented terrain options and does not provide a general help flag.
• Invalid gamma: try an integer with the compatibility wrapper, or move to pamshadedrelief for a fractional factor.
• Unexpected appearance: confirm the dimensions, seed and gamma, then inspect the PGM with a trusted viewer. A valid file can still be visually unsuitable.
• Slow generation: reduce -number or the image dimensions while testing. The default 50,000 craters is not a small workload for every output size.