Codebase Knowledge Base

Patterns & Conventions

Single-file Python project (main.py), Pillow + numpy for image processing
CLI interface: python main.py <input> <output_dir> <palette>
Platforms defined as tuples in PLATFORMS list: (name, width, height, cols, rows)
Pixel grid sizes are log-distributed via pick_grid_sizes()
Palette mapping uses numpy vectorized nearest-color matching

pixelate() — core pixel art function: downscale → optional palette → upscale with NEAREST
apply_palette() — maps every pixel to closest color in a palette array
create_banner() — composes grid of pixelated cells + generates GIF animation
pick_grid_sizes() — generates log-spaced pixelation levels, capped at end_fraction of cell size
Output: PNG (static grid banner) + GIF (animated progression) per platform

Pillow quantize() fails when colors > actual unique pixels in image (caused bugs with 1x1, 2x2 grids)
end_fraction must be relative to cell size, not source image size, or high-res stages look like originals
GIF frames use full banner dimensions — can get large for substack (1500x300)
.gitignore uses /banner_*.png (root only) to avoid ignoring previews/ subdirectories

Unsplash direct URLs work for sample images (free license, no auth needed)
4 palettes implemented: original, gameboy (4 colors), nes (36 colors), sepia (12 colors)
Influencer seeding identified as top growth strategy
GIF animation is the #1 viral hook — auto-plays on Twitter/X
Font caching matters — draw_label was probing filesystem on every cell
Floyd-Steinberg dithering is pure Python (slow on large images) — consider Cython or Pillow's built-in quantize dither for perf
create_banner has 11 params now — next refactor should bundle into a config dataclass
Legacy positional args via parse_known_args silently swallows typos — acceptable trade-off for backwards compat