Hmbown/CodeWhale · error · SystemExit

braille-mark.py requires pillow (`pip install pillow`)

Error message

braille-mark.py requires pillow (`pip install pillow`)

What it means

braille-mark.py imports PIL (Pillow) at module top; if Pillow is not installed, the ImportError is converted into this SystemExit message instead of a traceback. The script cannot manipulate the brand raster without Pillow.

Solutions

1. Install Pillow for the current interpreter: `pip install pillow`
2. If using a venv, activate it first (`source .venv/bin/activate`) then install
3. Verify with `python -c "import PIL; print(PIL.__version__)"` that the same interpreter running the script has Pillow
4. On some distros install via package manager (e.g. `apt install python3-pil`) if pip is restricted

Example fix

# before
$ python scripts/brand/braille-mark.py
braille-mark.py requires pillow (`pip install pillow`)
# after
$ pip install pillow
$ python scripts/brand/braille-mark.py

import importlib.util
if importlib.util.find_spec("PIL") is None:
    raise SystemExit("install pillow first: pip install pillow")

try:
    run_braille_mark()
except SystemExit as e:
    if "pillow" in str(e):
        subprocess.run([sys.executable, "-m", "pip", "install", "pillow"], check=True)
        run_braille_mark()

When it happens

Trigger: Running `python scripts/brand/braille-mark.py` in an environment where the `pillow` package is not installed for the active interpreter (harness.py-equivalent: scripts/brand/braille-mark.py:26-29 try/except around `from PIL import Image`).

Common situations: Fresh machine/CI container without dev dependencies; running with a different Python (system vs venv) that lacks Pillow; forgetting `pip install pillow` after cloning.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• founder raster missing
• no navy hero whale found in the founder sheet
• unexpected founder sheet geometry
• accepted_requests must equal requests_attempted; sender…
• applied_version is not the final sent version

AI-assisted analysis of Hmbown/CodeWhale@433685b202 (2026-09-15). Data as JSON: /api/errors/302e8f2ad611ef24. Report an issue: GitHub.

Appendix: source

Thrown at scripts/brand/braille-mark.py:36

  resized.

    scripts/brand/braille-mark.py                 # print + Rust consts
    scripts/brand/braille-mark.py --png crates/tui/assets/mark-96.png --px 96

Requires `pillow` (`pip install pillow`). No other dependencies.
"""

from __future__ import annotations

import argparse
import collections
import pathlib
import sys

try:
    from PIL import Image
except ImportError:
    raise SystemExit("braille-mark.py requires pillow (`pip install pillow`)")

ROOT = pathlib.Path(__file__).resolve().parents[2]
RASTER = ROOT / "brand" / "codewhalemarkfinal.png"

# Search bands as fractions of the sheet, so the boxes track the layout
# rather than absolute pixels. The app-icon caption ("APP ICON", navy text)
# sits above the icon band; the band starts below it.
HERO_BAND = (0.0, 1.0, 0.0, 0.52)  # x0, x1, y0, y1
ICON_BAND = (0.65, 1.0, 0.55, 0.78)
HERO_MARGIN = 12
ICON_PAD = 10
# Sheet background (and the icon's drop shadow, darkest ~211) keys out;
# founder navy (~15,33,65) never approaches this.
BG_CUTOFF = 200
# Braille dot bit for (dot_row, dot_col) inside one cell — U+2800 layout:
# dots 1,2,3 are column 0 rows 0..2 (bits 0..2), dots 4,5,6 column 1 rows
# 0..2 (bits 3..5), dots 7,8 are row 3 (bits 6,7).
DOT_BITS = {

View on GitHub (pinned to 433685b202)