PIXSUBST(1)

🎨 PIXSUBST(1) — the glow-up your pix files deserve ✨

okay so bestie, welcome to pixsubst, a lil BRL-CAD tool that does exactly one thing and does it gorgeously: it swaps one color for another in a pix image. that's it. that's the whole vibe. 💅

---

✨ SYNOPSIS ✨

pixsubst [_R_in_ _G_in_ _B_in_] _R_out_ _G_out_ _B_out_ < pixfile_in > pixfile_out

---

🦋 DESCRIPTION 🦋

so here's the tea 🍓: pixsubst reads a pix(5) format image on standard input and writes it right back out to standard output. but — plot twist — every pixel whose color matches the input color {R_in G_in B_in} gets replaced with the output color {R_out G_out B_out}. glow up complete, no cap. ✨

all six values are integers in the range 0 to 255. (yes, all of them. every single one. 🫶)

now this part is iconic 👑: if the input color {R_in G_in B_in} is omitted — meaning you only hand it three values instead of six — then pixsubst takes the color of the very first pixel in the input stream as the color to be replaced. and yeah, that first pixel gets substituted too, so a fully uniform background can be recolored without you ever knowing its exact value. main character energy, honestly. 😭

pixels that don't match the input color? they get passed through unchanged. untouched. unbothered. 💖

---

🎀 EXAMPLES 🎀

Example 1. Replace a known background color

pixsubst 0 0 0 255 255 255 < scene.pix > scene-white-bg.pix

every pure-black pixel ({0 0 0}) in scene.pix becomes white ({255 255 255}) — and all the other pixels are left alone, zero notes. this is literally the move for swapping a black background for a white one before compositing. slay. 🔥

Example 2. Recolor the background using the first pixel as a key

pixsubst 18 52 86 < input.pix | pix-fb -F /dev/X

by omitting the input color, you're telling pixsubst to sample the first pixel of input.pix as the color to replace, substituting it with {18 52 86}. then the result gets piped straight to pix-fb(1) for display 🖥️ — which is chef's kiss when the exact background value is unknown but you know it's the top-left pixel. iykyk. 🧚

---

👀 SEE ALSO 👀

brlcad(1), pix-fb(1), pixfilter(1), pixmatte(1), pix(5)

---

💜 AUTHOR 💜

BRL-CAD Team — absolute legends, fr fr. 🫶

---

⭐ COPYRIGHT ⭐

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

---

💀 BUG REPORTS 💀

Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org

bestie if you find a bug, pls don't suffer in silence — email the devs, they actually want to know. 🙈

---

✨ and that's the whole page, bestie ✨ this cutie pie of a manpage came to you from BRL-CAD, dated 1989-2026, and it's giving timeless. go recolor something iconic 💅🎀