pamshadedrelief

Generate a shaded relief image with the input image interpreted as an elevation map

$ pamshadedrelief < [path/to/input.pam] > [path/to/output.pam]

$ pamshadedrelief [[-g|-gamma]] [factor] < [path/to/input.pam] > [path/to/output.pam]

pamshadedrelief [options] [input_image]
If input_image is omitted, pamshadedrelief reads from standard input.

-azimuth=angle
    Sets the horizontal angle (azimuth) of the virtual light source, in degrees. 0 degrees is from the east, increasing clockwise.

-elevation=angle
    Sets the vertical angle (elevation) of the virtual light source, in degrees. 0 degrees is on the horizon, 90 degrees is directly overhead.

-vertical-exaggeration=factor
    A floating-point value that controls the vertical scaling of the terrain relative to its horizontal extent. A factor of 1 means no exaggeration; values greater than 1 exaggerate vertical features.

-input-type=height|slope
    Specifies how input pixel values should be interpreted. height (default) means values are elevations. slope means values represent pre-calculated slope.

-output-type=intensity|composite
    Determines the type of output image. intensity (default) produces a new grayscale image based solely on light intensity. composite overlays the shaded relief onto the original image (if input is grayscale).

-output-value-range=minval:maxval
    Maps the calculated light intensity values to a specific output pixel value range. This can be used to stretch or compress the output contrast.

-nocomment
    Prevents pamshadedrelief from writing comments (like its command line) into the output file's header.

-verbose
    Outputs informational messages about the processing steps to standard error.

The pamshadedrelief command, part of the Netpbm toolkit, transforms a grayscale image into a shaded relief map, creating the illusion of three-dimensional terrain.

It interprets the input image's pixel values as heights (or slopes), calculating the local surface normal based on these values. A virtual light source, whose position can be controlled by the user, then illuminates this calculated terrain. The output image's pixel intensities correspond to how brightly each point on the simulated terrain would be lit, effectively visualizing features like hills, valleys, and ridges.

This utility is particularly useful for visualizing Digital Elevation Models (DEMs) or other height map data, providing a more intuitive and visually appealing representation of topographic features. It supports various Netpbm input formats, including PGM and PAM.

The command assumes that the input image's pixels have a square aspect ratio. If pixels are not square, the resulting relief may appear distorted. Furthermore, the interpretation of input values as height is linear; non-linear height scales must be pre-processed.
It is important to remember that this is an approximation of 3D relief; it does not perform full 3D rendering.

The input image to pamshadedrelief is typically a grayscale image (PGM or a single-channel PAM) where each pixel's value represents an elevation or height. By default, darker pixels are considered lower elevations and brighter pixels higher, creating a topological map for the command to process.

The resolution of the input image directly affects the detail of the generated relief.

The output is also a grayscale image (PGM or PAM), but its pixel values now represent the intensity of light reflected from the simulated terrain. Brighter areas indicate surfaces facing the virtual light source, while darker areas are in shadow. This results in an image that visually simulates hills and valleys, enhancing the perception of depth and terrain features.

pamshadedrelief is an integral part of the Netpbm image processing suite, a collection of graphics utilities that has been continuously developed since the early 1990s. Netpbm originated from a set of simple image format converters and tools, later expanding to include more complex image manipulation capabilities like shaded relief generation.

The `pam` prefix indicates its compatibility with the Portable Arbitrary Map (PAM) format, a versatile Netpbm format that can represent various types of image data, including multi-channel and depth-varying images, which made the implementation of advanced features like pamshadedrelief more robust and flexible than with older Netpbm formats.

pnm(1), pam(1), pgm(5), pnmdepth(1), pnmgamma(1)