Turn a Netpbm Elevation Map into a Shaded Relief PAM

You will finish with a grayscale PAM image in which slopes in an elevation map appear as light and dark terrain. The workflow uses the installed Netpbm 11.5.2 tools, keeps the data on standard input and output, and writes only an explicitly chosen file.

Allow about fifteen minutes. You need the netpbm package, a shell, and an elevation map in a Netpbm format that pamshadedrelief can read. The examples use pamcrater to create a small, repeatable test map, so no source data is required. No command below needs sudo or changes a service.

1. Check the installed command

Confirm which executable will run and record the package version. This is a read-only checkpoint:

$ command -v pamshadedrelief
/usr/bin/pamshadedrelief
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1
$ pamshadedrelief --version
pamshadedrelief: Using libnetpbm from Netpbm Version: Netpbm 11.5.2

The version text may include build details after the library version. If the command is missing, stop here and install Netpbm through your normal package-management process. That installation is an elevated, state-changing action and is outside this guide.

2. Make a deterministic elevation map

For a safe first run, pipe a small cratered terrain map into pamshadedrelief. The -randomseed=42 value makes the test reproducible, while the dimensions keep the output small:

$ pamcrater -width=32 -height=24 -number=100 -randomseed=42 \
    | pamshadedrelief > /tmp/relief-default.pam

pamcrater creates elevation data, not a finished picture. pamshadedrelief reads that data from standard input because its synopsis has no input-file operand. The shell redirection writes the result to the path after >. Check that the file is a PAM and that its dimensions and tuple type are as expected:

$ pamfile /tmp/relief-default.pam
/tmp/relief-default.pam: PAM, 32 by 24 by 1 maxval 255
    Tuple type: GRAYSCALE

Your file contains binary image samples, so do not open it in a text editor. If the destination already exists, redirection replaces it. Use a new filename when preserving an earlier result matters; the command has no undo operation for an overwritten file.

3. Apply the default relief rendering

The default gamma factor is 1.0. It produces a medium-contrast result. The light direction is built into the program: the terrain is rendered as though lit from the left and viewed from above.

To use an existing elevation PAM, replace the pamcrater part with a command or file-producing pipeline that emits that data:

$ cat /path/to/elevation-map.pam \
    | pamshadedrelief > /tmp/relief.pam
$ pamfile /tmp/relief.pam
/tmp/relief.pam: PAM, 32 by 24 by 1 maxval 255
    Tuple type: GRAYSCALE

The dimensions in the verification output must match your input. The sample dimensions above are only the output from the small pamcrater example; use the values reported for your own data.

4. Tune contrast with gamma

Use -gamma, or its short form -g, when the relief is too flat or too harsh. Values greater than 1 lighten the image and reduce contrast. Values between 0 and 1 darken it and increase contrast:

$ pamcrater -width=32 -height=24 -number=100 -randomseed=42 \
    | pamshadedrelief -gamma 1.5 > /tmp/relief-light.pam
$ pamfile /tmp/relief-light.pam
/tmp/relief-light.pam: PAM, 32 by 24 by 1 maxval 255
    Tuple type: GRAYSCALE

Start with a modest change such as 1.2 or 0.8 and inspect the image in a PAM-capable viewer. Keep the input and output filenames distinct while comparing variants. The option changes contrast; it is separate from the gamma-corrected definition of the PAM GRAYSCALE format, so it does not turn the output into a different colour model.

A factor must be greater than zero. This deliberate failure confirms the boundary:

$ pamshadedrelief -gamma 0 < /tmp/relief-default.pam > /tmp/unused.pam
pamshadedrelief: gamma correction must be greater than 0
$ echo $?
1

Do not treat a non-zero status as a usable image. Check the status of the last command in any longer pipeline, or save the output only after a successful run.

5. Keep the pipeline safe and repeatable

For repeatable tests, fix the elevation generator's seed and dimensions, and keep each output under a separate name. For production data, preserve the original elevation map and write the shaded result elsewhere. There is no persistent configuration to restore: removing an unwanted generated file is the only cleanup, and you should first confirm its exact path and that it is not your source data.

The output is a one-depth PAM with tuple type GRAYSCALE, not an RGB photograph. A viewer or later tool must support PAM, or you must add a separately verified Netpbm conversion step for the format you need. Do not infer success from a command that returned no terminal text; inspect the exit status and the output header.