ppmdist

Produce a grayscale version of the specified PPM image

$ ppmdist [path/to/input.ppm] > [path/to/output.pgm]

$ ppmdist -[frequency|intensity] [path/to/input.ppm] > [path/to/output.pgm]

ppmdist [-maxval N] [-weight N] [-power N] [-origin X Y] [ppmfile ...]

-maxval N
    Sets the maximum pixel value for the output image. By default, this is determined from the maximum maxval of the input images. Using a higher value like 65535 (2^16-1) allows for 16-bit color depth, enabling a wider range of colors or intensities.

-weight N
    Specifies a base weight (a floating-point number) to be applied to each input image's pixels before the distance calculation. The default value is 1.0. This value acts as a fundamental multiplier for the distance-derived weight.

-power N
    Defines the exponent (a floating-point number) for the distance calculation. A higher power results in a steeper decrease in pixel weight as distance from the origin increases, causing a more rapid falloff effect. The default value is 2.0, mimicking an inverse square law.

-origin X Y
    Sets the coordinates (column X, row Y) for the origin point from which all distances are calculated. Coordinates are 0-indexed. The default origin is the geometric center of the input images, calculated based on their dimensions.

ppmfile ...
    One or more paths to the input Portable Pixmap (PPM) image files. If no filenames are provided, ppmdist reads image data from standard input. All input files must have identical dimensions and maxval, otherwise an error will occur.

ppmdist is a Netpbm utility that processes multiple Portable Pixmap (PPM) images and outputs a single composite PPM image.

For each pixel location in the output, it calculates a weighted average of the corresponding pixels from all input images. The weighting factor for each input image's pixel is determined by its Euclidean distance from a specified "origin" point (defaulting to the image's center). This distance is then modified by a configurable power and a base weight. This technique effectively emphasizes or clarifies areas closer to the origin while fading or blurring areas further away.

It's particularly useful for creating visual effects such as simulating depth-of-field, spotlight effects, or for compositing multiple images where a central subject or region needs to be highlighted or made dominant. All input images must be of identical dimensions (width and height) and possess the same maximum pixel value (maxval).

All input PPM images must have the exact same dimensions (width and height) and the same maximum pixel value (maxval) to be processed successfully. Mismatched images will result in an error and program termination. The output is always a single PPM image.

For each pixel position (x, y) in the output, ppmdist calculates the Euclidean distance d from (x, y) to the specified origin (origin_x, origin_y). The weight for an input pixel at (x, y) is then derived using the formula: weight_factor = base_weight / (d^power + 1). The ' + 1' in the denominator is crucial as it prevents division by zero if the origin is exactly on a pixel, and ensures a finite, non-zero weight. The final color of the output pixel is the weighted average of all input pixels at that corresponding position, considering their respective weights.

This command is widely used in artistic image processing and scientific visualization. Common applications include creating soft focus or depth-of-field effects in rendered images, simulating a light source or 'hotspot' by making areas near the origin brighter and more dominant, or combining multiple frames of an animation where the primary action is centered to produce a composite still image that highlights movement.

ppmdist is an integral part of the Netpbm package, a comprehensive suite of graphics utilities. Netpbm evolved from Jef Poskanzer's original PBMplus toolkit, which first appeared in the early 1990s. The command exemplifies the Unix philosophy of small, specialized tools that perform a single task well, providing a fundamental capability for image manipulation through weighted averaging based on spatial distribution, serving as a reliable utility for image compositing for decades.

ppm(5), pnm(5), ppmblend(1), ppmcompose(1), ppmcat(1)