HALFTONE(1)

📦
version 7.44.0 · 2 versions
, in nixpkgs unstable

💅 halftone(1) — the BRL-CAD glow-up for your black & white pics

okay so bestie, this is halftone from the BRL-CAD manual, section 1. sit down, hydrate, and let's get into it 🫶

✨ NAME ✨

halftone — literally takes a black and white image and turns it into a halftoned black and white image. that's the whole gig. iconic behavior only 💅

🌸 SYNOPSIS 🌸

halftone [-R] [-S] [-a] [-s _squaresize_] [-w _width_] [-n _height_] [-B _contrast_] [-I _levels_] [-M _method_] [-T _x1 y1 x2 y2 ..._] [-D _debug_level_] [_file.bw_]

🦋 DESCRIPTION 🦋

so here's the tea: halftone reads a black and white image in bw(5) format from the file you name (or from standard input if you don't name any file at all, no pressure) and writes a halftoned bw(5) image straight to standard output. ✨

and like, what is halftoning? it's reducing the number of distinct intensity levels — 256 by default, down to 2, which is just black and white — while using dithering to keep as much apparent shading and detail as possible. so it still looks like it has depth, it's just faking it gorgeously. several dithering algorithms are available via the -M option, ranging from Floyd-Steinberg error diffusion all the way to ordered halftone screens. we love range.

the output is itself a bw(5) file whose pixels take a limited set of values; each output level is scaled to the range 0 to 255 (as 255 / (levels - 1) value) so the result displays correctly with tools such as bw-pix(1). and the dithering algorithms are drawn largely from Digital Halftoning by Robert Ulichney — cite your sources, always 📚

🎀 OPTIONS 🎀

  • -s _squaresize_ — sets both the width and height of the input image to squaresize pixels. one number, two jobs, multitasking queen 👑
  • -w _width_ — sets the width of the input image in pixels. the default is 512.
  • -n _height_ — sets the height of the input image in scanlines. the default is also 512.
  • -a — automatically figures out the input image dimensions from the file name or the file size. so smart. but heads up: automatic sizing cannot be used with pipes or standard input 🫠
  • -B _contrast_ — a floating-point beta coefficient applied by a Laplacian edge sharpening filter before dithering. the default is 0.0, which means no sharpening. zero effort, zero sharpening, we respect it.
  • -I _levels_ — number of output intensity levels. default is 2 (that's 1-bit black/white) and the max is 256.
  • -M _method_ — pick your halftoning method, bestie:
    • 0 — Floyd-Steinberg error diffusion (this is the default, the main character)
    • 1 — 45-degree classical clustered-dot halftone screen
    • 2 — simple thresholding dither
    • 3 — 0-degree dispersed-dot halftone screen
ngl if you pass a value outside the range 0-3 it gets reported and then reset to the default (0). the program will simply choose for you 💀
  • -R — adds random noise to the dither threshold. this can break up repeating screen patterns and improve how the output looks. chaos as a design tool, we love to see it 🌈
  • -S — use a serpentine scan path — reversing direction on every other row instead of always scanning left to right. slay. but this option only has an effect with Floyd-Steinberg error diffusion (-M 0); it is ignored for the other methods 🙈
  • -T _x1 y1 x2 y2 ..._ — define a tone-scale mapping from a list of integer coordinate pairs (each one in the range 0 to 255). a cubic spline is fit through the points to map input intensities to output intensities. the default mapping is the straight line equivalent to -T 0 0 255 255.
  • -D _debug_level_ — sets the debug level. a value of 9 emits all the debugging messages (we're talking full lore dump mode 🔥).
  • -h, -? — print a usage message and exit. the classic escape hatch 🏃‍♀️

⭐ EXAMPLES ⭐

Example 1. Render a model and halftone the result for a 1-bit display

rt -s 512 -o image.pix model.g component.r
pix-bw image.pix > image.bw
halftone -M 0 -S image.bw > image.ht.bw

so what's happening: it ray traces a region to a 512x512 color image, converts it to bw(5) grayscale, then applies Floyd-Steinberg error diffusion with a serpentine scan to produce a dithered black-and-white image suitable for a 1-bit device. full pipeline, chef's kiss 🧚

Example 2. Coarse newsprint-style halftone with four gray levels

halftone -w 1024 -n 768 -M 1 -I 4 photo.bw > photo.ht.bw

this one treats the input as a 1024x768 image and applies the 45-degree classical clustered-dot screen quantized to four intensity levels, mimicking a coarse printed halftone. it's giving vintage zine energy, honestly 🍓

💜 SEE ALSO 💜

brlcad(1), rt(1), pix-bw(1), bw-pix(1), bwmod(1), bw(5)

go read them, iykwyk 📖✨

👑 AUTHOR 👑

BRL-CAD Team — legends, every single one of them.

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

🐛 BUG REPORTS 🐛

Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org. if something's broken, tell them! they want to know! no gatekeeping bugs fr fr 😭

and that's the page bestie 🎀 — brought to you by BRL-CAD, HALFTONE(1), the one and only. go dither something gorgeous 💖✨🦋

📦 where this page comes from