pamcomp

Overlay two images such with the overlay blocking parts of the underlay

$ pamcomp [path/to/overlay.pam] [path/to/underlay.pam] > [path/to/output.pam]

$ pamcomp [[-ali|-align]] [left|center|right|beyondleft|beyondright] [[-x|-xoff]] [x_offset] [path/to/overlay.pam] [path/to/underlay.pam] > [path/to/output.pam]

$ pamcomp [[-va|-valign]] [top|middle|bottom|above|below] [[-y|-yoff]] [y_offset] [path/to/overlay.pam] [path/to/underlay.pam] > [path/to/output.pam]

$ pamcomp [[-o|-opacity]] [0.7] [path/to/overlay.pam] [path/to/underlay.pam] > [path/to/output.pam]

pamcomp [options] [foreground_file] [background_file]

-blend
    Blends the foreground image into the background using its alpha channel (if present) or transparency.

-alpha
    Uses the foreground's alpha channel for blending operations, interpreting foreground transparency.

-fill
    Fills transparent areas of the foreground image with a specified color, or black by default.

-bgfill
    Fills transparent areas of the background image (where foreground is transparent) with a specified color.

-x
    Specifies the X-coordinate (horizontal position) for the top-left corner of the foreground image relative to the background.

-y
    Specifies the Y-coordinate (vertical position) for the top-left corner of the foreground image relative to the background.

-n
    Repeats the foreground image 'n' times within the composite area, effectively tiling it.

-w
    Sets the width of the output composite image. The foreground image will be scaled or cropped accordingly.

-h
    Sets the height of the output composite image. The foreground image will be scaled or cropped accordingly.

-min
    Composites by taking the component-wise minimum of corresponding foreground and background pixel values.

-max
    Composites by taking the component-wise maximum of corresponding foreground and background pixel values.

-mul
    Composites by component-wise multiplication of foreground and background pixel values.

-add
    Composites by component-wise addition of foreground and background pixel values.

-avg
    Composites by component-wise averaging of foreground and background pixel values.

-sub
    Composites by subtracting background pixel values from foreground pixel values (foreground - background).

-subb
    Composites by subtracting foreground pixel values from background pixel values (background - foreground).

-div
    Composites by dividing foreground pixel values by background pixel values (foreground / background).

-test
    Generates a test image for debugging purposes, showing internal calculations and image regions.

-verbose
    Prints informative messages about the processing progress to standard error.

-color
    Specifies a color using comma-separated RGB values (e.g., '255,0,0') for operations like -fill.

-backgroundcolor
    Specifies a background color using RGB values for filling or background operations.

-opacity
    Sets a global opacity value (0.0 to 1.0) for the foreground image during blending.

-alphafile
    Uses an external image file as a dedicated alpha mask for the composite operation.

-alphaopacity
    Applies an opacity value (0.0 to 1.0) to the external alpha mask specified by -alphafile.

-clip
    Clips the foreground image to the dimensions of the background image.

-nocache
    Disables caching of image data, which can be useful for debugging or memory constrained systems.

-dump
    Dumps internal data structures to standard error for debugging purposes.

-debug
    Enables verbose debug output for troubleshooting command behavior.

-version
    Prints the Netpbm version information and exits.

foreground_file
    The path to the foreground image file. If omitted, the foreground image is read from standard input.

background_file
    The path to the background image file. If omitted, and a foreground file is specified, the background is read from standard input. If both file arguments are omitted, the foreground is from stdin and there is no background image (it's considered null).

pamcomp is a versatile command-line utility from the Netpbm suite designed for compositing two images: a foreground image and a background image. It supports a wide array of operations, allowing users to blend, overlay, and combine images based on different mathematical or alpha blending modes. This makes it ideal for tasks such as superimposing logos, creating transparent overlays, or generating complex visual effects by manipulating image channels. The command can handle various Netpbm formats, including PPM, PGM, PBM, and especially PAM, which fully supports alpha channels for sophisticated transparency effects. It offers precise control over positioning, size, and blending parameters, making it a powerful tool for automated image processing workflows.

pamcomp is part of the Netpbm suite, which primarily handles its own image formats (PPM, PGM, PBM, PAM). While versatile, its direct integration with other image formats like JPEG or PNG requires piping through other Netpbm tools like anytopnm or pamtopng. For optimal results with transparency and alpha channels, the PAM format is highly recommended. Be mindful of arithmetic overflow/underflow when using mathematical composition modes (e.g., -add, -sub, -div), as pixel values are typically clamped to the valid range (0-maxval).

Unless specific input files are provided, pamcomp defaults to reading image data from standard input. The resulting composite image is always written to standard output, making it highly suitable for piping with other Netpbm utilities in complex image processing pipelines.

Colors for options like -color and -backgroundcolor are specified as comma-separated RGB triples (e.g., '255,0,0' for red). Each component should be an integer between 0 and 255, representing the intensity of red, green, and blue respectively.

pamcomp is a modern replacement for the older pnmcomp command within the Netpbm project. It was introduced to leverage the capabilities of the PAM (Portable Arbitrary Map) format, which allows for images with arbitrary numbers of channels, including a dedicated alpha channel. This evolution enabled pamcomp to handle true transparency and more sophisticated composite operations compared to its predecessor, which was limited to traditional RGB (PPM) or grayscale (PGM) images without native alpha support. Its development aligns with Netpbm's goal of providing a robust, modular, and scriptable toolkit for image manipulation.

pnmcomp(1), pamstack(1), pamarith(1), pampaste(1), anytopnm(1)