Generate and Preview Cratered Terrain with pamcrater

You will finish with a reproducible PAM elevation map and a shaded relief preview made from it. The examples use pamcrater from Netpbm 11.5.2, installed here as Debian package version 2:11.05.02-1.1build1. Allow about ten minutes. You need pamcrater, pamfile and pamshadedrelief from the Netpbm tools.

These commands run as an ordinary user. No elevated privileges are needed. The output files are new files in the current directory, so the only state change is file creation. If you want to remove the examples afterwards, delete those files explicitly with rm -- craters.pam relief.pam after checking their names.

1. Confirm the installed tools

Check the package version and the programs that will take part in the pipeline:

$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1
$ command -v pamcrater pamfile pamshadedrelief
/usr/bin/pamcrater
/usr/bin/pamfile
/usr/bin/pamshadedrelief

The local command reports itself as Netpbm 11.5.2. The manpage documents the -randomseed option as new in Netpbm 10.61 and -verbose as new in 10.69, so both are available in this installation.

2. Create a small, repeatable terrain map

Start with a small map so that the command runs quickly while you learn the output. This creates 12 craters in an 8 by 6 pixel elevation map and fixes the random seed:

$ pamcrater -number=12 -width=8 -height=6 -randomseed=7 > craters.pam
$ pamfile craters.pam
craters.pam: PAM, 8 by 6 by 1 maxval 65535
    Tuple type: elevation

-number controls the crater count. The default is 50,000, which is useful for a more densely worked landscape but unnecessary for a smoke test. The default width and height are both 256 pixels. -randomseed=7 makes the generated map repeatable, which is useful for tests, documentation and later comparisons.

The equals form shown above is accepted by this installed binary and matches the documented examples. The output is not a normal picture: it is a depth-one PAM image whose tuple type is elevation. Its maxval is always 65535. The sample values represent terrain elevation rather than red, green and blue channels.

3. Verify deterministic output

Run the same command into a temporary comparison file and compare the bytes. This is read-only apart from creating the second temporary file:

$ pamcrater -number=12 -width=8 -height=6 -randomseed=7 > craters-again.pam
$ cmp --silent craters.pam craters-again.pam && echo 'maps are identical'
maps are identical

A fixed seed controls the pseudorandom sequence, so identical inputs produce identical output with this installed version. If you omit -randomseed, pamcrater derives a seed from the time of day and process ID. That is appropriate when you want a fresh terrain map, but it makes byte-for-byte comparisons unsuitable.

Remove the comparison file when you no longer need it:

$ rm -- craters-again.pam

This is the only destructive command in the guide. It removes a file you just created; check the exact name before running it. Keep craters.pam if you want to continue.

4. Turn the elevations into a visible preview

Pipe the terrain map through pamshadedrelief. The first program supplies elevations, and the second converts them into a shaded relief image:

$ pamcrater -number=50000 -width=256 -height=256 -randomseed=7 \
    | pamshadedrelief > relief.pam
$ pamfile relief.pam
relief.pam: PAM, 256 by 256 by 1 maxval 255
    Tuple type: GRAYSCALE

The visible result is a grayscale PAM file, not the original elevation map. Keeping the two stages separate lets you reuse the same terrain with a different relief or image-processing pipeline. The manpage also notes that high-resolution maps with millions of craters take longer and that pnmsmooth can soften jagged pixels. Treat larger counts as a deliberate workload increase, not as a default quality switch.

For an interactive preview, the documented pipeline sends the shaded output to pamx:

$ pamcrater -number=50000 -width=256 -height=256 -randomseed=7 \
    | pamshadedrelief \
    | pamx

pamx opens a display window when a graphical environment and the corresponding Netpbm viewer are available. If your session is headless, keep the redirected relief.pam file and inspect it with an image viewer that supports PAM, or convert it using a separate, trusted Netpbm workflow. Do not mistake a viewer failure for a pamcrater failure: first save the pipeline output and check it with pamfile.

5. Tune size and count without losing the baseline

Change one dimension at a time and keep the seed fixed when comparing results. For example, this creates a square test map with more craters:

$ pamcrater -number=500 -width=512 -height=512 -randomseed=7 \
    > craters-512.pam
$ pamfile craters-512.pam
craters-512.pam: PAM, 512 by 512 by 1 maxval 65535
    Tuple type: elevation

More craters generally give a more extensively worked terrain, but the size distribution deliberately contains many more small craters than large ones. The program generates small, hemispherical craters; it does not model large lunar-style walled plains with central peaks. That boundary matters if the result is being used as a physical or scientific model rather than as procedural artwork.

Use -verbose when you need additional progress messages:

$ pamcrater -number=500 -width=512 -height=512 -randomseed=7 -verbose \
    > craters-verbose.pam

Keep diagnostic output separate from the PAM stream. Redirecting standard output to a file, as above, preserves the binary image; do not add shell text to that stream.

6. Handle common failures

A non-positive dimension is rejected before a useful map is produced:

$ pamcrater -number=1 -width=0 -height=1 > /tmp/invalid.pam
pamcrater: -width must be positive

Check both dimensions and use positive integers. A large image can also consume noticeable time and disk space, so estimate the size of the job before increasing width, height and crater count together.

If the output is not visible, check the boundary between generation and display. First save and inspect the shaded result:

$ pamcrater -number=50000 -width=256 -height=256 -randomseed=7 \
    | pamshadedrelief > relief.pam
$ pamfile relief.pam

If that reports a PAM grayscale image, generation and shading worked. The remaining issue is the viewer or display session. If pamfile cannot read the result, check the earlier command's exit status and rerun the pipeline without hiding its diagnostics.