pnmcomp

View documentation for the current command

$ tldr pamcomp

pnmcomp [-left=C] [-top=R] [-bottom=R] [-right=C] [-xleft=C] [-xtop=R] [-xbottom=R] [-xright=C] [-align=X] [-valign=Y] [-opacity=PERCENT] [-alpha] [-mask=MASKFILE] [-background=BGFILE] [-blend=PERCENT] [-operator={add|subtract|average|difference|multiply|mask-add|mask-subtract}] [mainimage [compositeimage]]

mainimage
    The base image onto which the composite image will be placed. If omitted, it is read from standard input.

compositeimage
    The image to be overlaid on the main image. If omitted, it is read from standard input after the main image (if mainimage is also stdin).

-left=C
    Specifies the column (C) for the left edge of the composite image on the main image.

-top=R
    Specifies the row (R) for the top edge of the composite image on the main image.

-right=C
    Specifies the column (C) for the right edge of the composite image on the main image.

-bottom=R
    Specifies the row (R) for the bottom edge of the composite image on the main image.

-xleft=C
    Specifies a relative horizontal offset (C) from the left edge of the main image.

-xtop=R
    Specifies a relative vertical offset (R) from the top edge of the main image.

-xright=C
    Specifies a relative horizontal offset (C) from the right edge of the main image.

-xbottom=R
    Specifies a relative vertical offset (R) from the bottom edge of the main image.

-align=X
    Horizontal alignment for the composite image (left, center, or right). Overrides explicit column positioning.

-valign=Y
    Vertical alignment for the composite image (top, middle, or bottom). Overrides explicit row positioning.

-opacity=PERCENT
    Sets the opacity of the composite image, as a percentage (0-100). 0 means fully transparent, 100 means fully opaque. Uses 'over' operator.

-alpha
    Treats the composite image as having an alpha channel if it's a PAM file. Not fully supported for all operations compared to pamcomp.

-mask=MASKFILE
    Uses a PBM mask file to determine transparency. Black pixels in the mask mean transparent, white pixels mean opaque.

-background=BGFILE
    Uses the specified image file as a background, filling areas where the main image is smaller than the composite image.

-blend=PERCENT
    Legacy option for blending the composite image with the main image, equivalent to -opacity with a simpler 'over' blend.

-operator={add|subtract|average|difference|multiply|mask-add|mask-subtract}
    Specifies the compositing operator to use. Determines how pixel values from the two images are combined arithmetically.

pnmcomp is a versatile Netpbm command-line tool used to overlay or composite one Netpbm image onto another. It takes a 'main image' and a 'composite image' and places the composite image on top of the main image, producing a new combined image. The command offers extensive control over the positioning of the composite image, allowing for absolute coordinates, relative offsets, and various alignment options. Beyond simple overlay, pnmcomp supports transparency through several mechanisms: implicit transparency (where black pixels in a PBM composite image are treated as transparent), an external mask file, or an alpha channel if present in the composite image. It also provides different blending modes and arithmetic operators (e.g., add, subtract, multiply, average) to determine how the pixel values of the two images are combined. This makes it a powerful utility for tasks like watermarking, superimposing graphics, or combining different visual elements programmatically within image processing pipelines.

pnmcomp is part of the Netpbm suite, which primarily handles PBM, PGM, and PPM formats. While it has an -alpha option, its alpha channel handling is not as robust or comprehensive as the more modern pamcomp(1) command, especially for complex alpha blending scenarios. For true alpha blending with arbitrary transparency, pamcomp is generally preferred. Furthermore, the behavior of some operators (e.g., mask-add, mask-subtract) can be specific to the Netpbm color space and may not behave as expected with all image types or pixel ranges.

pnmcomp reads its input images (main and composite) from files specified as arguments or from standard input (`-`). The resulting composite image is always written to standard output. This behavior allows it to be easily integrated into shell pipelines with other Netpbm utilities.

By default, for PBM input, black pixels in the composite image are transparent. For PGM/PPM, black pixels or pixels with the same color as the first pixel of the main image can be treated as transparent. The -mask option provides a more explicit and flexible way to define transparent areas using a separate PBM file, where black represents transparency and white represents opacity. The -alpha option attempts to use an actual alpha channel if the composite image is in PAM format, but this is less robust than pamcomp.

pnmcomp is a long-standing utility within the Netpbm project, a comprehensive toolkit for manipulating graphic images. Netpbm originated from the `pbmplus` package created by Jef Poskanzer in the late 1980s. pnmcomp was developed to provide basic image overlay and blending capabilities, a fundamental operation in graphics processing. Its design reflects the era before widespread true alpha channel support, hence its emphasis on explicit mask files and simple pixel-wise arithmetic operations. While newer tools like pamcomp have emerged to handle modern alpha blending more efficiently, pnmcomp remains a valuable tool for simpler compositing tasks, particularly within scripts leveraging the Netpbm format's stream-based processing.

pamcomp(1), pnmpad(1), pnmcat(1), pnmcrop(1), pnmcut(1)