PIXMATTE(1)

NAME

pixmatte - matte (merge) two pix(5) or bw(5) images by a formula

On this page

SYNOPSIS
DESCRIPTION
OPTIONS
EXAMPLES
SEE ALSO
AUTHOR
COPYRIGHT
BUG REPORTS

SYNOPSIS

pixmatte [-w _width_in_bytes_] {-g -l -e -n -a} _in1_ _in2_ _true_out_ _false_out_ > _output_

Given four streams of data elements, where each element is of arbitrary width (typically pix(5) or bw(5) images), pixmatte outputs a stream of the same number of data elements. The value of the output stream is determined element-by-element by comparing the first (foreground) input stream in1 with the second (background, or matte) input stream in2. If the formula holds true, the element from the true_out stream is written; otherwise the element from the false_out stream is written. This routine operates element-by-element and is thus independent of image resolution.

Each of the four streams comes from a file or is given as a constant. A single file may feed more than one stream (for example, the foreground file may also be the true-output file), and the name '-' specifies stdin. A constant is specified instead of a filename when the first character is an equal sign (=); the value is a slash-separated string of width_in_bytes decimal numbers with no separating white space (e.g. =255/0/0). If both in1 and in2 are constants, the output is bounded to a 512 x 512 image.

The comparison formula is built from -g (greater than), -l (less than), -e (equal to), and -n (not equal to), which may be combined: -ge specifies in1 greater than or equal to in2. The condition must hold for every byte of the element for the true output to be selected.

OPTIONS

-g: Select the true output where in1 is greater than in2.
-l: Select the true output where in1 is less than in2.
-e: Select the true output where in1 is equal to in2.
-n: Select the true output where in1 is not equal to in2.
-a: Approximate matching: bytes are treated as equal when they match within plus or minus one, useful for matting dithered backgrounds. When combined with -e or -n it yields approximately-equal or approximately-not-equal. When combined with -g and/or -l it excludes the elements that meet the approximately-equal criterion. -a is a modifier only; at least one of -g, -l, -e, or -n must also be given.
-w width_in_bytes: Set the width in bytes of each element. The default is 3 (the pix(5) format); use 1 to process bw(5) files. The width must be between 1 and 31.
-h, -?: Print a usage message and exit.

EXAMPLES

Example 1. Composite a foreground over a generated background

pixbackgnd -t0 160 200 | pixmatte -n fg.pix =63/0/127 fg.pix - | pix-fb

Keeps every foreground pixel that is not equal to the chroma-key color 63/0/127 and replaces matching pixels with a pixbackgnd(1) gradient read from stdin, displaying the result with pix-fb(1). This is a common way to drop an rt(1) image over a nicer background.

Example 2. Threshold against a constant

pixmatte -g fg.pix =20/20/20 fg.pix =200/0/200 > out.pix

Keeps foreground pixels whose bytes are all greater than 20/20/20 and replaces the rest with the constant magenta 200/0/200.

Example 3. Build a black-and-white stencil matte

pixmatte -n fg.pix bg.pix =255/255/255 =0/0/0 > matte.pix

Produces a stencil that is white where fg.pix and bg.pix differ and black where they match, for further compositing.

Example 4. Match a dithered background approximately

pixmatte -a -e fg.pix bg.pix =0/0/0 fg.pix > out.pix

Sets to black all foreground pixels that match bg.pix to within plus or minus one per byte, preserving everything else.