PIXMERGE(1)

NAME

pixmerge - merge two pix(5) or bw(5) images using a per-pixel comparison

On this page

SYNOPSIS
DESCRIPTION
OPTIONS
EXAMPLES
SEE ALSO
AUTHOR
COPYRIGHT
BUG REPORTS

SYNOPSIS

pixmerge [-glen] [-w _bytes_wide_] [-C _r/g/b_] _foreground.pix_ [_background.pix_] > _out.pix_

pixmerge, given two streams of data, typically pix(5) or bw(5) images, generates an output stream of the same size where each output pixel is taken from either the first (foreground) stream or the second (background) stream, according to a comparison formula. A constant color may be used in place of the background stream. pixmerge operates pixel-by-pixel and is therefore independent of the image resolution. For more sophisticated compositing, see pixmatte(1).

The formula is any combination of -g (fg greater than bg), -l (fg less than bg), -e (fg equal to bg), and -n (fg not equal to bg). A comparison must hold for every byte of the pixel to select the foreground; otherwise the background pixel is selected. For example, -le selects the foreground pixel when each of its bytes is less than or equal to the corresponding background byte.

If no formula is specified, the default is -g against a constant of all zeroes (black), equivalent to:

pixmerge -g -C 0/0/0 fg.pix

If a constant is supplied with -C, the background.pix argument is omitted. The constant is given as up to bytes_wide slash-separated values.

OPTIONS

-g: Select the foreground pixel when it is greater than the background.
-l: Select the foreground pixel when it is less than the background.
-e: Select the foreground pixel when it is equal to the background.
-n: Select the foreground pixel when it is not equal to the background.
-w bytes_wide: Set the width in bytes of each "pixel". The default is 3 (pix(5) format); use 1 for bw(5) files. The value must be at least 1 and less than 32.
-C r/g/b: Use a constant color in place of the background stream. The constant is given as up to bytes_wide slash-separated byte values (0-255). When this option is used, the background.pix argument is omitted.
-c r/g/b: Backward-compatible alias for -C.
-h, -?: Print a usage message.

EXAMPLES

Example 1. Composite a rendered image over a shaded background

pixbackgnd -t0 160 200 | pixmerge -n fg.pix - | pix-fb

A shaded background is generated by pixbackgnd(1) and read from stdin (the "-" background argument); pixmerge selects each foreground pixel from fg.pix wherever it differs from the background, compositing an rt(1) generated image on top of the gradient, then displays the result with pix-fb(1).

Example 2. Key out a flat color and replace it with a generated fill

gencolor 200 0 200 | pixmerge -g fg.pix - > out.pix

Pixels of fg.pix that are greater than the magenta stream produced by gencolor(1) are kept; all others are replaced by that color, writing the merged result to out.pix.