PIXCLUMP(1)

📦
version 7.44.0 · 2 versions
, in nixpkgs unstable

💅 PIXCLUMP(1) — the pix(5) color quantizer, bestie edition 🎀

okay so real quick, this is a page from the BRL-CAD manual set, and it's about pixclump, which is lowkey one of the most satisfying little tools ever. let's get into it ✨

✨ NAME ✨

pixclump — quantize the colors in a pix(5) stream to a specified set. that's it, that's the whole vibe 🦋

🌸 SYNOPSIS 🌸

pixclump [-c R/G/B] [-f color_file] [-x debug_flags] [infile.pix [outfile.pix]]

💖 DESCRIPTION 💖

so here's the tea ☕: pixclump reads an input stream of pix(5) data, swaps out every single pixel for the most similar color from a set you pick, and writes out the quantized pixels. basically it's a glow-up filter but for color palettes, and it ate 💅

you can hand it your color set two ways:

  • on the command line, with one -c option per color 🎀
  • in a file, named with the -f option 🦋

then, for every pixel in the input, it gets compared against every color in the set, and on the way out it gets replaced by the nearest one. and when we say "nearest", we mean the distance is the sum of the squares of the differences in the red, green, and blue channels — that's the actual math, no cap 📐✨

file behavior, since y'all always ask:

  • no input file named? it reads from standard input 🌈
  • no output file named? it writes to standard output 💜

a super typical use is renormalizing an image: when a tool like pixscale(1) interpolates new colors into an image that originally held only a few, pixclump maps all those interpolated pixels back onto the original palette. it's giving "put it back the way you found it" and honestly? iconic 👑

🔥 OPTIONS 🔥

  • -c R/G/B — add a single color to the set, specified as a slash-separated red/green/blue triple. you can pass this multiple times to build up the whole set. heads up though: using -c discards any color file you previously named with -f 💀
  • -f color_file — read the color set from color_file, one R/G/B color per line. blank lines and lines beginning with '#' are ignored (so comment your palette, bestie, live a little 📝). and same deal in reverse: using -f discards any colors you previously gave with -c 🙈
  • -x debug_flags — turn on diagnostic output. debug_flags is a hexadecimal bit mask, and here's the decoder ring: 0x01 prints the color table, 0x02 traces best-match selection, and 0x04 traces pixel output. nerdy and I respect it 🔍
  • -h, -? — print a usage message and exit. the classic escape hatch 🫶

🎀 EXAMPLES 🎀

Example 1. Map an image onto a four-color palette

pixclump -c 0/0/0 -c 255/255/255 -c 255/0/0 -c 0/0/255 in.pix > out.pix

this quantizes every pixel of in.pix to the nearest of black, white, red, or blue, and writes the result to out.pix. four colors, whole image, done. slay 🖤🤍❤️💙

Example 2. Renormalize a scaled image to its original palette

pixscale -s 512 -w 256 -n 256 orig.pix | pixclump -f palette.txt > fixed.pix

so pixscale(1) interpolates new intermediate colors while it resizes — which is fine, but sometimes you don't want those. this pipeline maps each pixel back onto the original palette listed in palette.txt, restoring that limited color set. pipeline energy fr fr 🔗✨

🦋 SEE ALSO 🦋

brlcad(1), pixscale(1), pix-bw(1), pix(5) — go read those too, they're the supporting cast and they understood the assignment 💜

👑 AUTHOR 👑

BRL-CAD Team — legends, honestly 🫶

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 — please do tell them, they wanna know, iykyk 📬

and that's the whole page!! this one came from the BRL-CAD manual collection, source PIXCLUMP(1) — stay hydrated, back up your files, and go quantize something gorgeous 💖✨🎀

📦 where this page comes from