Turn a Netpbm Elevation Map into a Shaded Relief PAM

Flat elevation data tells you nothing at a glance, but pamshadedrelief turns it into a grayscale PAM where slopes read as light and dark terrain. The workflow keeps 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, 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's an elevated, state-changing action and sits outside this guide.

2. Make a deterministic elevation map

For a safe first run, pipe a small cratered terrain map into pamshadedrelief. -randomseed=42 makes the test reproducible, and the small dimensions keep the output easy to eyeball:

$ 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, its synopsis has no input-file operand at all. The shell redirection writes the result to the path after >. Check the file is a PAM with the dimensions and tuple type you expect:

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

3. Apply the default relief rendering

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

To use an existing elevation PAM, swap the pamcrater part for whatever command or pipeline 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 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 result in a PAM-capable viewer, keeping input and output filenames distinct while you compare variants. This option changes contrast only; it's separate from the gamma-corrected definition of the PAM GRAYSCALE format, so it doesn't 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

Don't 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.

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'll need a separately verified Netpbm conversion step for the format you actually need. Don't infer success from a command that returned no terminal text; inspect the exit status and the output header instead.