Composite Netpbm Images Safely with pnmcomp

You will finish with a repeatable way to put one Netpbm image over another, position the overlay, and apply either a uniform opacity or a per-pixel mask. 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 edit either input.

Allow about fifteen minutes. You need the Netpbm package, two readable PBM, PGM, PPM or PAM images, and a writable destination for the output. The examples use temporary test images so that they do not overwrite real photographs or diagrams. No elevated privileges are needed.

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. That 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. 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 is placed 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 has the underlying image's dimensions. The .pam suffix in this example 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 shown here:

$ 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 often 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 normal 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. 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 whose dimensions match the underlay instead of the overlay; 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. 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 is created or truncated before writing. Warning: do not use an existing source path as the output path. Write to a new file, verify it with pamfile, then replace the old file yourself only after keeping a backup:

$ 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, a non-zero exit and an error naming the failed path are expected. Fix the path or permissions first. sudo is not a normal remedy for an input typo, and is not needed for the examples.