PIXBGSTRIP(1)

📦
version 7.44.0 · 2 versions
, in nixpkgs unstable

💅 PIXBGSTRIP(1) — bestie's guide to the BRL-CAD pixel background stripper 🎀

okay so this is pixbgstrip from the BRL-CAD crew, and it's genuinely one of those little tools that eats every single time. no cap. ✨

🌸 NAME 🌸

pixbgstrip — strips a uniform background color out of a pix(5) file 🫶

✨ SYNOPSIS ✨

pixbgstrip [-a] [-t thresh] [-x x_offset] [-s squaresize] [-w width] [-n height] [file.pix]

like, that's the whole vibe. flags then a file, or no file at all, iykyk 💅

💖 DESCRIPTION 💖

So pixbgstrip reads a pix(5) image from the file you name — or from standard input if you don't name one, main character energy — and then writes a brand new pix(5) image to standard output where the background color has been replaced with black (0/0/0). literally that's it and it's iconic.

Here's the tea on how it actually works: for each scanline, the pixel sitting at the background X offset (peep -x) gets grabbed and used as the reference background color for that line. Every pixel on that scanline whose color falls within the matching threshold (that's -t) of the reference gets set to black, and every other pixel gets passed through unchanged, untouched, unbothered. 👑

This is lowkey perfect for keying out a solid or smoothly shaded backdrop — like, say, the kind pixbackgnd(1) produces — before you composite an image over a whole new background. it's giving chroma key but make it pix. 🦋

Also important bestie: the image dimensions have to be known so the program can read each scanline properly. By default the input is assumed to be 512x512 pixels. You can set the dimensions explicitly with -w, -n, and -s, or let the program guess from the file length with -a. your call, no pressure. 🌈

🎀 OPTIONS 🎀

  • -a — autosize the input 💫 the length of the input file gets compared against a table of common image sizes, and if there's a match, the corresponding width is used. only works when reading from a file — not from a pipe, bestie, don't try it. 😭
  • -t thresh — set the matching threshold (default 0). a pixel only counts as background if each of its red, green, and blue channels differs from the reference background pixel by less than thresh. bigger value = tolerates a slightly noisy background. slay. 🔥
  • -x x_offset — set the X offset, in pixels, of the pixel that gets sampled as the background color for each scanline (default 0, aka the leftmost pixel). use this when the image has a border so you can sample the actual background instead of the border. the offset must be smaller than the image width, periodt. ⭐
  • -s squaresize — set both the width and height of the input to squaresize pixels. this disables autosizing. two birds, one flag. 🕊️
  • -w width — set the width, in pixels, of each input scanline. disables autosizing. 📏
  • -n height — set the height, in scanlines, of the input. disables autosizing. (the program reads until end of file anyway, so this value chiefly serves to turn off autosizing — like, that's its whole job tbh.) 🙈

👑 EXAMPLES 👑

🌟 Example 1. Key out a rendered background and composite over a new one

rt -o image.pix model.g component.r
pixbgstrip -w 1024 -n 1024 image.pix > stripped.pix
pixmerge -g stripped.pix newbg.pix > composite.pix

A 1024x1024 image gets rendered with rt(1), its solid background color gets swapped to black by pixbgstrip, and then the result gets layered over a replacement backdrop with pixmerge(1) — whose -g option treats black as transparent — giving you a composite image. the whole glow-up pipeline fr fr 💖

🌟 Example 2. Strip a slightly noisy bordered background

pixbgstrip -a -x 5 -t 4 frame.pix > clean.pix

The input size gets guessed automatically (-a), the background color gets sampled five pixels in from the left edge to skip a thin border (-x 5), and a threshold of 4 (-t 4) tolerates minor noise in the background. chef's kiss. 🍓

🦋 SEE ALSO 🦋

brlcad(1), pixbackgnd(1), pixmerge(1), pix-fb(1), fb-pix(1), pix(5) — go read them bestie, they're all part of the fam 💜

💀 DIAGNOSTICS 💀

If the input file is shorter than a whole number of scanlines, the trailing partial scanline gets discarded and the program exits. so like, that data's gone, no takebacks, be aware. 😭

🧚 AUTHOR 🧚

BRL-CAD Team 🫶

This software is Copyright (c) 1991-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 — they genuinely want to hear about it, so like, don't be shy ✨

okay that's the whole page bestie, go strip some backgrounds 💖✨🎀🦋 -- brought to you by BRL-CAD, and yes we're still here serving looks 💅👑

📦 where this page comes from