Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help

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

       pixmatte	[-a] [-w bytes_wide] [-glen] in1 in2 true_out false_out	>

       Given four streams of data elements, where 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 with the second (background, or matte) input stream. If
       the formula holds true, the element from	the true-output	stream is
       written,	otherwise, the element from the	false-output stream is
       written.	Each of	these streams comes from a file, or is given as	a
       constant. A particular file may be used to feed more than one stream,
       and the name '-'	specifies stdin. For example, the foreground file may
       also be the true-output file. This routine operates on an
       element-by-element basis, and thus is independent of the	resolution of
       the image.

       A constant value	is specified instead of	a filename if the first
       character of what would be the filename is an equal sign	(=). The value
       is specified as a slash-separated string	of bytes_wide decimal numbers,
       with no separating white	space. If in1 and in2 are both specified as
       constant	values,	the output file	will be	512 x 512.

       The formula can be any combination of -g	(in1 greater than in2),	-l
       (in1 less than in2), -e (in1 equal to in2), -n (in1 not equal to	in2).
       For example: -ge	specifies in1 greater than or equal to in2; that is,
       when each byte of the in1 element is greater than or equal to the
       corresponding byte of the in2 element.

       The -a flag can be used with -n or -e to	specify	approximately equal or
       approximately not equal to match	dithered backgrounds. (Approximate
       equality	exists when all	bytes in the elements match to within plus or
       minus one.) It can also be used in combination with -g and/or -l; the
       effect of this usage is to exclude those	elements which meet the
       approximately-equal criterion. If -a is used, at	least one of -g, -l,
       -e, -n must be used.

       The -w# flag specifies the width	(in bytes) of each element; the
       default is 3, i.e.  pix(5) file format. A width of 1 is used for
       processing bw(5)	files. It is unclear if	other widths are useful.

       To compare all foreground pixels	to black (all bytes zero), selecting
       the foreground pixels when true and a background	elsewhere, specify:

       pixmatte	-g fg.pix =0/0/0 fg.pix	bg.pix

       To keep all foreground pixels greater than 20/20/20, and	replace	all
       those less than or equal	to it with 200/0/200, use:

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

       To keep all foreground pixels which are not equal to 63/0/127, and to
       replace those which are equal with a generated background from stdin,
       use the following commands (can be useful when compositing an rt(1)
       generated image on top of a nicer background):

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

       To produce a black-and-white stencil matte file for further processing,

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

       To set to black all pixels that approximately match (by +/- 1) a	given
       background file,	use:

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

       brlcad(1), gencolor(1), pixbackgnd(1), pixmerge(1), pix(5), bw(5)

       BRL-CAD Team

       This software is	Copyright (c) 1989-2019	by the United States
       Government as represented by U.S. Army Research Laboratory.

       Reports of bugs or problems should be submitted via electronic mail to

BRL-CAD				  03/02/2021			   PIXMATTE(1)


Want to link to this manual page? Use this URL:

home | help