color-counter

A command-line tool to count and analyze colors in PDF files. It rasterizes each page, extracts pixel color frequencies, and displays ranked color tables with terminal swatches.

Features

• Per-page color tables and a cross-page summary
• Three quantization methods to group similar colors: exact top-N, k-means (RGB), k-means (perceptual LAB)
• Optional gray separation: isolate near-gray colors into their own table
• Page range selection
• Pixel-sampling stride for faster analysis of large documents
• Configurable terminal color system for accurate swatch rendering

Installation

Requires Python 3.10+.

pip install -e .

For development (includes pytest):

pip install -e ".[dev]"

The lab quantization method additionally requires scikit-image:

pip install scikit-image

Usage

color-counter file.pdf

By default, only the global summary is printed. Add --per-page to also print a table for every page.

Examples

# Summary only (default)
color-counter report.pdf

# Per-page tables + summary
color-counter report.pdf --per-page

# Analyze only pages 2 to 5
color-counter report.pdf --pages 2-5

# Reduce to 8 dominant colors using perceptual clustering
color-counter report.pdf --reduce 8 --method lab

# Separate gray shades (max channel spread ≤ 15) into their own table
color-counter report.pdf --gray-threshold 15

# Fix swatches that all look the same color
color-counter report.pdf --color-system truecolor

# Fast pass on a large document (sample every 4th pixel)
color-counter report.pdf --sample-step 4

Options

Color reduction methods

Gray threshold

A color is classified as gray when its maximum RGB channel minus its minimum RGB channel is at or below the threshold.

• 0 — only exact grays where R = G = B (pure black, white, neutral)
• 15 — also catches near-grays from anti-aliasing or compression artifacts

Swatch colors look wrong

If swatches all appear as the same color, your terminal's color depth is being misdetected. Run with --color-system truecolor to force 24-bit color output.

Architecture

License

MIT — see LICENSE.