Composite Netpbm Images with pamcomp, Masks and Opacity

You will finish with a repeatable way to place one Netpbm image over another, position it within the background, blend it with a transparency mask, and check the result without destroying an existing file. The examples use pamcomp from Netpbm 11.5.2, installed here as Debian package netpbm 2:11.05.02-1.1build1.

Allow about fifteen minutes. You need two readable Netpbm images, such as PPM or PAM files, and a shell. A PGM file is also needed for the masked example. The commands normally run as your own user. Nothing in this guide needs sudo; use elevated access only to read inputs or write outputs in a directory your user cannot access.

1. Check the installed command

Start with a read-only version check. This confirms which implementation and release you are about to use:

$ pamcomp --version
pamcomp: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pamcomp: Built from source dated 2024-03-31 09:09:47
pamcomp: Built by Debian

The exact build lines can differ on another host. The useful checkpoint is the Netpbm version. The installed manual describes the command as accepting an overlay image, an optional underlying image, and an optional output file. It writes a PAM image, even when the inputs use other Netpbm formats.

2. Inspect the input files

Confirm that the files exist and that a Netpbm reader recognises their dimensions before composing them:

$ ls -l /path/to/overlay.ppm /path/to/underlying.ppm
$ file /path/to/overlay.ppm /path/to/underlying.ppm
/path/to/overlay.ppm: Netpbm image data, size 640 x 480, pixmap
/path/to/underlying.ppm: Netpbm image data, size 1920 x 1080, pixmap

Replace the paths with real files. The overlay is the image placed on top. The underlying image controls the output dimensions, so differently sized inputs are allowed. pamcomp keeps only the part of the overlay that lies over the underlying image. If you position it entirely outside the background, it warns and contributes no pixels.

Checkpoint: make sure the destination is new or backed up. The output-file argument is created or truncated before writing. Shell redirection is not involved when you give an output path, but the overwrite risk is still real.

3. Make a solid overlay

Use the simplest form to put an overlay flush with the top-left corner:

$ pamcomp /path/to/overlay.ppm /path/to/underlying.ppm /path/to/composite.pam
$ file /path/to/composite.pam
/path/to/composite.pam: Netpbm image data, size = 1920 x 1080, rawbits, pixmap

The positional order matters. The first file is the overlay, the second is the underlying image, and the third is the output. With no -align or -valign, the overlay starts at the left and top edges. The output dimensions remain those of the underlying image, not the overlay.

There is also a useful default for pipelines: if you omit the underlying-file argument, it comes from standard input. Do not use standard input for both an image and a mask. For example, this reads the background from a pipe and still names the overlay and output explicitly:

$ cat /path/to/underlying.ppm | pamcomp /path/to/overlay.ppm - /path/to/composite.pam

Check the exit status after a scripted run:

$ printf 'exit status: %s\n' "$?"
exit status: 0

4. Position the overlay deliberately

Choose a basic horizontal and vertical position, then adjust it in pixels:

$ pamcomp \
    -align=center -valign=bottom \
    -xoff=-12 -yoff=-24 \
    /path/to/overlay.ppm /path/to/underlying.ppm /path/to/composite.pam

The horizontal setting used above centres the overlay, while the bottom setting anchors it to the bottom. The negative offsets move it 12 pixels left and 24 pixels up from those basic positions. Positive -xoff moves right; positive -yoff moves down. The full horizontal alignment choices are flush left, centred, flush right, just beyond the left edge, and just beyond the right edge. Vertical choices are top, middle, bottom, just above, and just below.

The beyond-frame choices are mainly useful with an offset. They let you place an image just outside the corresponding edge and move part of it into view. Do not confuse alignment with resizing: pamcomp never scales the overlay.

5. Add a PGM transparency mask

A mask controls how much of each overlay pixel is visible. It must have the same dimensions as the overlay. White means opaque, black means transparent, and grey values produce translucency.

$ pamcomp \
    -align=center -valign=middle \
    -alpha /path/to/overlay-mask.pgm \
    /path/to/overlay.ppm /path/to/underlying.ppm /path/to/masked.pam
$ file /path/to/masked.pam
/path/to/masked.pam: Netpbm image data, size = 1920 x 1080, rawbits, pixmap

If the mask dimensions do not match the overlay, stop and fix the mask rather than guessing. Use pamfile if it is installed, or inspect it with file. The mask is multiplied by the value supplied to -opacity, whose normal range is 0.0 to 1.0. For a half-strength overlay, use:

$ pamcomp -alpha /path/to/overlay-mask.pgm -opacity=0.5 \
    /path/to/overlay.ppm /path/to/underlying.ppm /path/to/half-strength.pam

-invert reverses the mask sense. It does not reverse the separate -opacity value. Although the program accepts opacity outside the usual range and clips the resulting samples, that is an effect operation, not a safer transparency setting. Keep ordinary compositing between 0.0 and 1.0.

6. Handle alpha channels and colour maths

If the overlay is a PAM image with tuple type RGB_ALPHA or GRAYSCALE_ALPHA, pamcomp can use its own opacity channel. Supplying -alpha as well combines the two opacities. The underlying image determines whether the output has an opacity channel. By default, the underlying transparency does not alter the colour contribution. Add -mixtransparency when you want the two images treated as stacked transparent slides.

Use -linear only when the sample values are proportional to light intensity rather than normal gamma-adjusted PNM or PAM samples. It skips the conversions used for ordinary image data. Applying it casually can change blended colours. If you are unsure what the inputs represent, leave it out and verify the visual result.

7. Protect and verify the output

Never test an untrusted composition by overwriting the only copy of a useful image. Write to a temporary name, inspect it, then replace the destination only after checking it:

$ pamcomp -align=center -valign=middle \
    /path/to/overlay.ppm /path/to/underlying.ppm /path/to/composite.pam.new
$ file /path/to/composite.pam.new
$ test -s /path/to/composite.pam.new && echo 'output is non-empty'
output is non-empty
$ mv /path/to/composite.pam.new /path/to/composite.pam

The final mv replaces the old output, so treat it as a deliberate destructive step. If composition fails, leave the original in place and remove only the incomplete .new file after checking its path. If you need an undo path, copy the existing destination first:

$ cp --preserve=all /path/to/composite.pam /path/to/composite.pam.bak

Keep that backup until you have opened or converted the new PAM and confirmed its dimensions, position and transparency. A successful exit status proves that the command completed; it does not prove that the visual result matches your intention.