PIXMATTE(1)

📦
version 7.44.0 · 2 versions
, in nixpkgs unstable

💅 PIXMATTE(1) — the BRL-CAD one where you matte two images together

okay so bestie, picture this: it's a pixmatte(1) page from BRL-CAD, and it's literally the glow-up your compositing bag needed. it merges two pix(5) or bw(5) images by a formula. no cap. let's get into it 🎀

✨ NAME ✨

pixmatte — matte (merge) two pix(5) or bw(5) images by a formula. she's giving "chroma key but make it a whole program" 💖

🦋 SYNOPSIS 🦋

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

like, yes, that's a lot of args. she's high-maintenance and worth it. 💅

🌸 DESCRIPTION 🌸

okay so here's the whole vibe. you hand pixmatte four streams of data elements, and each element can be any width you want (typically pix(5) or bw(5) images, iykyk). then it outputs a stream with the same number of data elements. same count, no notes. ✨

the value of the output stream gets decided element-by-element, by comparing the first stream — the foreground in1 — with the second stream — the background, aka the matte, in2. the way that works is:

  • if the formula holds true → the element from the true_out stream gets written 💖
  • otherwise → the element from the false_out stream gets written 🫶

and because this whole routine works element-by-element, it's completely independent of image resolution. literally doesn't care how big your image is. main character energy. 👑

now, where do those four streams come from? each one is either a file or a constant. and here's the cute part: a single file can feed more than one stream — for example, the foreground file can also be the true-output file, no drama. also, the name - means stdin. periodt. 🎀

a constant is what you get when you specify it instead of a filename, and you do that 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. like this, bestie: =255/0/0. 🍓

heads up: if both in1 and in2 are constants, the output gets bounded to a 512 x 512 image. noted. 💀

the comparison formula is built from -g (greater than), -l (less than), -e (equal to), and -n (not equal to), and you can combine them — so -ge means in1 greater than or equal to in2. iconic. but important: the condition must hold for every byte of the element for the true output to be selected. every single one. no partial credit. 😭

🧚 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 count as equal when they match within plus or minus one, which is super useful for matting dithered backgrounds. when combined with -e or -n it gives you approximately-equal or approximately-not-equal. when combined with -g and/or -l it excludes the elements that meet the approximately-equal criterion. also — and this is important, bestie — -a is a modifier only; you still gotta give at least one of -g, -l, -e, or -n. don't leave her hanging 🙈
  • -w width_in_bytes — set the width in bytes of each element. default is 3 (that's the pix(5) format); use 1 to process bw(5) files. the width must be between 1 and 31. no zero, no 32, we don't do that here 💅
  • -h, -? — print a usage message and exit. the classic escape hatch 🫶

🎀 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, then displays the result with pix-fb(1). this is, like, the classic way to drop an rt(1) image over a nicer background. chef's kiss. 💖

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. slay. ✨

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's white where fg.pix and bg.pix differ and black where they match, all ready for further compositing. she's a stencil, she's a vibe. 🦋

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. dithered backgrounds found quaking. 😭🔥

👑 SEE ALSO 👑

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

go read them, bestie, they're all in the group chat 💜

💜 AUTHOR 💜

BRL-CAD Team — the collective, the moment, the icon 👑

This software is Copyright (c) 1989-2026 by the United States Government as represented by U.S. Army Research Laboratory. fr fr, that's the whole line. 🫶

🍓 BUG REPORTS 🍓

Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org — go tell them, they want to know, do not gatekeep 💌

okay that's the whole page!! and before you go — this gorgeous thing comes to you from BRL-CAD (that's the source/version bit at the bottom, don't @ me), so when you're piping mattes at 2am just remember who raises you 💅✨🎀

📦 where this page comes from