ppmrelief

Produce a relief of the specified PPM image

$ ppmrelief [path/to/input_file.ppm] > [path/to/output_file.ppm]

ppmrelief [-azimuth A] [-elevation E] [-lightx X] [-lighty Y] [-lightz Z] [-ambient A] [-diffuse D] [-specular S] [-shininess H] [-gray] [-normal] [-normalize] [-smooth] [-noclamp] [ppmfile [pgmfile]]

-azimuth A
    Specifies the azimuth of the light source in degrees (0-360). Mutually exclusive with -lightx/-lighty/-lightz.

-elevation E
    Specifies the elevation of the light source in degrees (0-90, 0 is horizontal). Mutually exclusive with -lightx/-lighty/-lightz.

-lightx X, -lighty Y, -lightz Z
    Defines the x, y, and z coordinates of the light source relative to the image center. Mutually exclusive with -azimuth/-elevation.

-ambient A
    Sets the ambient light component (0.0-1.0). Default is 0.3.

-diffuse D
    Sets the diffuse light component (0.0-1.0). Default is 0.7.

-specular S
    Sets the specular light component (0.0-1.0). Default is 0.5.

-shininess H
    Sets the shininess of the surface (0.0-100.0). Default is 10.0.

-gray
    Outputs a PGM (Portable Graymap) image instead of a PPM. This produces a grayscale relief map.

-normal
    Outputs a normal map in PPM format, where color channels represent surface normals (x, y, z components).

-normalize
    Normalizes the light vector to unit length before calculations.

-smooth
    Applies a smoothing filter to the input image before calculating relief, which can reduce noise and harshness.

-noclamp
    Prevents clamping of output colors to the valid range (0-255). Can result in colors outside this range.

The ppmrelief command creates a simulated 3D relief map from an input image, giving it a shaded, sculpted appearance. It interprets the intensity (brightness) of pixels in the input image as elevation data: darker pixels represent lower points, and brighter pixels represent higher points.

You can use ppmrelief in two primary ways:
1. With a single PPM image: The color information from this image is used as the surface texture, and its intensity determines the elevation.
2. With two images: The first input is a PPM image used as the texture map, and the second is a PGM (Portable Graymap) image explicitly providing the elevation data.

The command applies a lighting model (based on ambient, diffuse, and specular components) from a user-defined light source. The resulting image is a PPM (or PGM if the -gray option is used) that visually represents the terrain or surface defined by the input image's intensity/elevation, as if lit from a specific direction.

The primary assumption of ppmrelief is that brighter pixels correspond to higher elevations and darker pixels to lower elevations. Understanding this is crucial for effective use. The effect is a 'pseudo-3D' rendering, not a true 3D model, meaning it's a 2D image with shading to simulate depth. Results can vary significantly with different input image characteristics and lighting parameters.

When providing two input files (PPM texture and PGM elevation), ensure they have identical dimensions, otherwise the behavior is undefined or an error will occur.

By default, ppmrelief expects a PPM (Portable Pixmap) image as input and produces a PPM image as output. If a second PGM (Portable Graymap) image is provided, it serves exclusively as the elevation map. Output can be redirected to a file or piped to another Netpbm command.

The command employs a simplified Phong reflection model to simulate how light interacts with the surface. This model combines three components:
Ambient light: Uniform light that illuminates all surfaces equally.
Diffuse light: Light scattered uniformly in all directions from the surface, dependent on the angle of the light source.
Specular light: Highlights that appear on shiny surfaces, dependent on the angle of the light source, surface normal, and viewer position (though the viewer is assumed to be directly above in ppmrelief's model).
The -shininess option controls the size and intensity of specular highlights.

ppmrelief is part of the Netpbm project, a widely used toolkit for manipulating graphic images. Netpbm originated from Jef Poskanzer's Pbmplus package in the late 1980s and early 1990s, becoming a standard component in Unix and Linux systems for its versatility in converting, filtering, and processing image files in various formats. ppmrelief was developed to add sophisticated relief shading capabilities to the suite, extending its utility for artistic and analytical image transformations.

pnm(5), pgm(5), pbm(5), pnmsmooth(1), pnmtopng(1), pnmgamma(1)