PIXMERGE(1)

💅 PIXMERGE(1) — the BRL-CAD one, bestie

okay so welcome to pixmerge, a genuinely iconic little BRL-CAD tool. it takes two streams of pixels and picks a winner for each one. no cap.

---

✨ SYNOPSIS ✨

pixmerge [-glen] [-w bytes_wide] [-C r/g/b] foreground.pix [background.pix] > out.pix

---

🌸 DESCRIPTION 🌸

so here's the vibe: you hand pixmerge two streams of data — usually pix(5) or bw(5) images — and it hands you back an output stream of the same size. for every single pixel in the output, it picks either the pixel from the first (foreground) stream or the pixel from the second (background) stream, based on a comparison formula. you can also drop a constant color in where the background stream would go, if that's your thing. 🎀

the way that this works is pixel-by-pixel, which means it literally does not care about your image resolution. it's resolution-independent and thriving. if you want something fancier and more sophisticated for compositing, go look at pixmatte(1) instead, iykyk.

the formula is any combination of these four flags:

• -g — fg greater than bg
• -l — fg less than bg
• -e — fg equal to bg
• -n — fg not equal to bg

here's the rule, and it's strict: a comparison has to hold for every byte of the pixel for the foreground to get selected. if even one byte doesn't cooperate, the background pixel gets selected instead. periodt.

for example, -le selects the foreground pixel when each of its bytes is less than or equal to the corresponding background byte. slay.

if you don't specify any formula at all, the default is -g against a constant of all zeroes (that's black, bestie), which is exactly equivalent to:

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

and if you do supply a constant with -C, then the background.pix argument is omitted entirely — you don't pass it, it's just not invited. 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 (that's pix(5) format); use 1 for bw(5) files. heads up though: 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. same energy, older name. 🫶
• -h, -? — print a usage message. very helpful of it.

---

🦋 EXAMPLES 🦋

Example 1. Composite a rendered image over a shaded background

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

a shaded background gets generated by pixbackgnd(1) and read from stdin — that's the "-" background argument right there, sneaky but iconic. then 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, and then displays the result with pix-fb(1). full main character pipeline honestly. 🌈

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. cute, effective, done. 💅

---

🔥 SEE ALSO 🔥

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

---

🍓 AUTHOR 🍓

BRL-CAD Team

---

⭐ COPYRIGHT ⭐

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

---

🙈 BUG REPORTS 🙈

found a bug or a problem? don't suffer in silence — reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org. they want to hear from you fr fr.

---

and that's the page!! brought to you by BRL-CAD, the PIXMERGE(1) era, with that copyright stretch running 1989-2026 — go forth and merge some pixels bestie 💜✨