pnmpaste

Paste a PNM image into another PNM image at the specified coordinates

$ pnmpaste [x] [y] [path/to/image1.pnm] [path/to/image2.pnm] > [path/to/output.pnm]

$ [command] | pnmpaste [x] [y] [path/to/image.pnm] > [path/to/output.pnm]

$ pnmpaste -[and|nand|or|nor|xor|xnor] [x] [y] [path/to/image1.pnm] [path/to/image2.pnm] > [path/to/output.pnm]

pnmpaste [options] [background_file] [foreground_image_file ...]

-r row
    Sets the top row coordinate (Y-axis) for pasting the image. Default is 0.

-c col
    Sets the left column coordinate (X-axis) for pasting the image. Default is 0.

-mix level
    Blends the foreground with the background. level is a float from 0.0 (background only) to 1.0 (foreground only).

-transparent color_spec
    Defines a specific color in the foreground image to be treated as transparent.

-alpha
    Uses the foreground image's inherent alpha channel for transparency, if available.

-alphafile file
    Reads an external PGM or PBM file to use as an alpha mask for the foreground image.

-clip
    Clips the pasted foreground image to the dimensions of the background. This is the default.

-no-clip
    Prevents clipping, allowing the output image to expand if the foreground goes beyond the background's boundaries.

-width pixels
    Sets the output image's width. The canvas expands or contracts as needed.

-height pixels
    Sets the output image's height. The canvas expands or contracts as needed.

-verbose
    Displays informational messages about the processing.

pnmpaste is a fundamental command within the Netpbm suite, designed for image composition. It allows users to overlay one or more Portable Anymap (PNM) format images (PBM, PGM, PPM) onto a specified background PNM image. This tool excels at positioning foreground images using coordinates, applying various forms of transparency, and blending them with the background.

Its core strength lies in its ability to be integrated seamlessly into shell scripts and automated workflows, leveraging the simple, uncompressed nature of the PNM formats as a universal intermediate. Whether combining logos, watermarks, or creating composite scenes, pnmpaste provides a robust and flexible solution for programmatic image layering, adhering to the modular Unix philosophy of chaining simple utilities for complex tasks.

pnmpaste exclusively processes Netpbm (PBM, PGM, PPM) image formats. Any other image type must first be converted using appropriate Netpbm conversion tools (e.g., jpegtopnm, pngtopnm). While versatile, achieving precise transparency or blending effects may require a clear understanding of color spaces and alpha channel handling within the Netpbm framework. When pasting multiple foregrounds, their application order significantly affects the final composite image.

pnmpaste is designed for seamless integration into shell pipelines. The background image can be read from standard input by default, specified as the first positional argument, or explicitly with the -background option. All resulting composite images are written to standard output, facilitating direct piping to other Netpbm tools or image format converters.

While pnmpaste supports PBM (monochrome), PGM (grayscale), and PPM (color) images, mixing them typically results in an automatic conversion to the highest common format (e.g., PGM or PBM converting to PPM). Transparency and blending operations are intelligently applied across these various Netpbm color formats.

pnmpaste is an integral part of the widely recognized Netpbm graphics utilities package. This suite evolved from the earlier Pbmplus package, released in 1991, which itself built upon the original Portable BitMap (PBM) utilities created by Jef Poskanzer in 1988. The development philosophy behind these tools emphasizes modularity and pipe-friendliness, enabling complex image manipulations through the chaining of simple commands. pnmpaste perfectly embodies this principle, providing a foundational image composition operation that is both flexible and highly scriptable, making it a long-standing staple in Unix and Linux environments for automated image processing tasks.

pnmcat(1), pnmblend(1), pnmcut(1), pnmremap(1), netpbm(1)