BWTHRESH(1)

🌸 BWTHRESH(1) — the brlcad glow-up 🌸

Hey bestie! 👋 Welcome to the most iconic threshold tool in the brlcad fam: bwthresh(1). It takes your black-and-white bw file and slices it into intensity bins. Think of it as the filter that makes your grayscale pic go from "meh" to "posterized slay." 💅

---

✨ NAME ✨

bwthresh — threshold a black-and-white bw file into intensity bins. Periodt. 🎀

🦋 SYNOPSIS 🦋

bwthresh [-h | -?] _val_... < file.bw > output.bw

💖 DESCRIPTION 💖

Okay so bwthresh reads a stream of black-and-white data in bw(5) format from standard input, quantizes each pixel value against the threshold values you give it, and writes the resulting bw(5) data to standard output. It's giving "glow-up through math" and honestly? Obsessed. ✨

Here's the vibe: if you give it n threshold values, the grayscale range 0-255 gets divided evenly into n+1 output bins. Each input pixel is compared against the thresholds in order — the first threshold the pixel is less than selects its bin, and then the pixel is replaced by that bin's representative intensity. Bin i (for i from 0 to n-1) gets assigned the value 256 * i / n, and the final bin gets 255. Math but make it fashion. 💁‍♀️

The threshold values are positional arguments. They must be integers in the range 0-255, given in strictly increasing order, and no more than 255 may be supplied. Don't try to be cute and reorder them — it won't work and the tool will simply not slay. 💀

🎀 OPTIONS 🎀

• -h, -? — Print a usage message and exit. Heads up though: this is only recognized when given as the sole argument. So if you're trying to sneak it in with other stuff? It's a no from the parser. 🙈
• val... — One or more threshold values. Each must be an integer between 0 and 255 inclusive, and the values must be listed in strictly increasing order. Strictly. No cap. 🔥

⭐ EXAMPLES ⭐

Example 1. Posterize an image into three intensity levels 🖼️

pix-bw photo.pix | bwthresh 85 170 > poster.bw

Convert a color pix(5) image to grayscale with pix-bw(1), then collapse it to three flat intensity levels: pixels below 85 become 0 (black), pixels below 170 become 128 (mid-gray), and the rest become 255 (white). This is a quick way to produce a hard-edged, posterized mask from a continuous-tone image. It's giving "I put a filter on it and now it's art." 🎨

Example 2. Binarize an image at a single threshold 🌓

bwthresh 128 < input.bw > mask.bw

With a single threshold, every pixel below 128 becomes 0 and every pixel at or above 128 becomes 255, yielding a pure black-and-white mask. Extremely clean, extremely iconic. 🖤🤍

💜 SEE ALSO 💜

brlcad(1), bwmod(1), bwstat(1), bwhisteq(1), pix-bw(1), bw(5)

👑 AUTHOR 👑

BRL-CAD Team

🌈 COPYRIGHT 🌈

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

---

That's the whole page, bestie! This iconic little rewrite brought to you by the BRL-CAD fam, copyright 1991-2026, and yes, the drama of BWTHRESH(1) is eternal. 💖 Go forth and threshold responsibly! 🌟