BWHIST(1)

📦
version 7.44.0 · 2 versions
, in nixpkgs unstable

🎀 BWHIST(1) — the histogram glow-up for your bw files 🎀

okay so bestie, bwhist is from the BRL-CAD fam, and it's literally the moment your black-and-white image gets its vibe check on a framebuffer. let's get into it 💅

✨ NAME ✨

bwhist — display a histogram of a black and white bw file on a framebuffer 🌈

🦋 SYNOPSIS 🦋

bwhist [-v] [file.bw]

💖 DESCRIPTION 💖

so here's the tea: bwhist calculates and displays a histogram of the pixel values in a bw(5) format file. if you don't specify a file, no worries — it just reads from standard input, lowkey chill like that 🫶

the histogram shows up on the framebuffer selected via the FB_FILE environment variable (peep libfb(3) for the deets), and it's opened at 512x512.

the relative frequency of each pixel value gets drawn as a horizontal bar of white pixels along the x-axis ✨ and it's scaled so that the most frequent value spans the full width of the screen — main character bar energy, honestly 👑. the 256 pixel values map to the y-axis, with 0 (black) at the bottom and 255 (white) at the top. iconic vertical arrangement, no cap.

and the pixel count corresponding to a full-width bar? it's always reported to standard output as a Full screen = N pixels line. every single time. that's the rule 📏

💅 OPTIONS 💅

  • -v — Verbose mode, bestie! in addition to displaying the histogram, this prints each pixel value, its count, and its relative frequency to standard output. 🗣️ but heads up: it must appear before the optional file argument. order matters, fr fr.
  • -h, -? — Print a usage summary and exit. the classic "wait how does this work again" escape hatch 🙈

🌸 EXAMPLES 🌸

Example 1. Inspect the tonal distribution of a rendered image 🌟

pix-bw scene.pix > scene.bw
bwhist -v scene.bw

okay so what's happening here: it converts a color pix(5) image to black and white with pix-bw(1), then displays its intensity histogram on the framebuffer while dumping the per-value counts and frequencies to the terminal. 🖥️✨

and like, the printed table is genuinely so useful — it makes it easy to spot clipping at 0 or 255 and to judge overall exposure before adjusting a render. it's giving "I actually know what I'm doing" energy 💀🔥

🔥 SEE ALSO 🔥

brlcad(1), bwhisteq(1), bwstat(1), bw(5)

💀 BUGS 💀

this program assumes the framebuffer has at least 512 scanlines to display the full histogram (that's 2 lines per pixel value). so if your framebuffer is shorter than that… yeah, it's giving "not enough room for the whole vibe" 😭 plan accordingly!

👑 AUTHOR 👑

BRL-CAD Team 🫶

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 📧

and that's the whole page, bestie — go forth and histogram 💜

signing off: this lil doc is part of BRL-CAD, and it's dated with the BRL-CAD release info — catch you on the framebuffer side 🧚✨

📦 where this page comes from