Composite Netpbm Images Safely with pnmcomp

pnmcomp lays one Netpbm image over another, with control over position, opacity and a per-pixel mask, and it never edits either input. On this machine, pnmcomp is the compatibility name for pamcomp, supplied by Netpbm 11.5.2. The command writes a composite image; it does not touch the source files.

• You need: the Netpbm package, two readable PBM, PGM, PPM or PAM images, and a writable destination for the output.
• No elevated privileges needed. The examples use temporary test images, so they never overwrite real photographs or diagrams.

1. Check the installed command

Confirm both the package version and the compatibility link before relying on a particular behaviour:

$ command -v pnmcomp
/usr/bin/pnmcomp
$ readlink -f /usr/bin/pnmcomp
/usr/bin/pamcomp
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1
$ pnmcomp --version
pnmcomp: Using libnetpbm from Netpbm Version: Netpbm 11.5.2

The local pnmcomp(1) page describes the command as replaced by pamcomp, which is slightly confusing when the executable is still present: this package keeps pnmcomp as a symlink, so the current pamcomp implementation and its extra options are what you are actually running.

2. Create harmless input images

Use ppmmake to create a blue underlay and a smaller yellow overlay. Replace these files with your own Netpbm images once the workflow is understood:

$ workdir=$(mktemp -d /tmp/pnmcomp-example.XXXXXX)
$ ppmmake blue 6 4 > "$workdir/underlay.ppm"
$ ppmmake yellow 2 2 > "$workdir/overlay.ppm"
$ pamfile "$workdir/underlay.ppm" "$workdir/overlay.ppm"
/tmp/pnmcomp-example.XXXXXX/underlay.ppm:  PPM raw, 6 by 4  maxval 255
/tmp/pnmcomp-example.XXXXXX/overlay.ppm:    PPM raw, 2 by 2  maxval 255

The directory name is deliberately variable, so keep the same shell session for the following commands, because workdir points to these temporary files. The output path is created by pnmcomp, so choose a destination you are happy to replace.

3. Place an opaque overlay

The basic positional form is pnmcomp overlay underlying output. The overlay sits at the upper left by default and completely covers the underlying pixels where the two images overlap:

$ pnmcomp "$workdir/overlay.ppm" "$workdir/underlay.ppm" "$workdir/opaque.pam"
$ pamfile "$workdir/opaque.pam"
/tmp/pnmcomp-example.XXXXXX/opaque.pam:    PPM raw, 6 by 4  maxval 255

The output takes the underlying image's dimensions. The .pam suffix here is only a filename choice; the installed command reports the actual output as PPM. Do not infer a file format from the suffix: pamfile is the useful verification step.

To centre the overlay horizontally and vertically, use the alignment and vertical-position options:

$ pnmcomp -align center -valign middle \
    "$workdir/overlay.ppm" "$workdir/underlay.ppm" "$workdir/centred.ppm"
$ pamfile "$workdir/centred.ppm"
/tmp/pnmcomp-example.XXXXXX/centred.ppm:   PPM raw, 6 by 4  maxval 255

Other horizontal positions are left and right; vertical positions are top, middle and bottom. These are placement rules, not cropping commands: an overlay may extend outside the underlay, and only the part above the underlay is used.

4. Adjust the position precisely

Add -xoff or -yoff when alignment alone is not exact. Positive -xoff moves the overlay right, and positive -yoff moves it down; negative values move it left or up:

$ pnmcomp -align right -valign bottom -xoff -1 -yoff -1 \
    "$workdir/overlay.ppm" "$workdir/underlay.ppm" "$workdir/offset.ppm"
$ pamfile "$workdir/offset.ppm"
/tmp/pnmcomp-example.XXXXXX/offset.ppm:    PPM raw, 6 by 4  maxval 255

Be careful with a large offset. If the overlay ends up entirely outside the underlay, pnmcomp warns and the result contains only the underlay. That is usually a positioning mistake, not a successful invisible overlay.

5. Blend the overlay uniformly

Use -opacity for one opacity value across the whole overlay. A value of 1.0 is fully opaque and 0.0 is fully transparent; the useful range is 0 to 1:

$ pnmcomp -align center -valign middle -opacity 0.5 \
    "$workdir/overlay.ppm" "$workdir/underlay.ppm" "$workdir/blended.ppm"
$ pamfile "$workdir/blended.ppm"
/tmp/pnmcomp-example.XXXXXX/blended.ppm:   PPM raw, 6 by 4  maxval 255

Values outside that range are accepted and perform arithmetic that can brighten, darken or clip colour components. That is a specialised effect, not a safer way to express transparency, so keep ordinary compositing between 0 and 1.

6. Use a transparency mask

For different opacity at each pixel, provide a PGM mask with -alpha. It must have the same dimensions as the overlay. White means opaque, black means transparent, and grey gives an intermediate blend:

$ printf 'P2\n2 2\n255\n255 0\n0 255\n' > "$workdir/mask.pgm"
$ pnmcomp -alpha "$workdir/mask.pgm" \
    "$workdir/overlay.ppm" "$workdir/underlay.ppm" "$workdir/masked.ppm"
$ pamfile "$workdir/masked.ppm"
/tmp/pnmcomp-example.XXXXXX/masked.ppm:    PPM raw, 6 by 4  maxval 255

-invert reverses the mask's sense. If you also use -opacity, the mask's opacity and the uniform opacity are multiplied. A common error is supplying a mask sized to the underlay instead of the overlay, so check both images before running the command.

7. Avoid input and output traps

The underlying image defaults to standard input if you omit its filename, and either input may be - for standard input. Standard input cannot supply two different things at once, so for a script, spell out all three file paths unless a pipeline is the deliberate design.

The output argument is unusual for a Netpbm program: it is a real file argument, and it is created or truncated before writing.

$ cp -- "$workdir/underlay.ppm" "$workdir/underlay.ppm.backup"
$ pnmcomp "$workdir/overlay.ppm" "$workdir/underlay.ppm" "$workdir/new-underlay.ppm"
$ pamfile "$workdir/new-underlay.ppm"
# Recovery if you later decide to restore the backup:
$ cp -- "$workdir/underlay.ppm.backup" "$workdir/underlay.ppm"

For a missing file, expect a non-zero exit and an error naming the failed path. Fix the path or permissions first: sudo is not a normal remedy for an input typo, and is not needed for the examples.