Team Grid Generator

Create a single team image from a folder full of portraits. The script in src/team_grid.py crops each photo, applies a rounded border, and renders the person’s name underneath so you can drop the finished grid into presentations or documentation.

Requirements

• Python 3.9+ (ships with macOS and most Linux distributions)
• pip to install the one dependency (Pillow, for image processing)

python3 -m venv .venv
source .venv/bin/activate
pip install Pillow

The virtual environment is optional, but it keeps the dependency isolated.

Prepare Your Input

• Add portrait images (.png, .jpg, .jpeg) to the import/ directory. The folder is in .gitignore, so none of the source photos are checked in.
• Provide labels so the script knows which name goes with each file. By default it looks for import/labels.json:

{
  "portrait-ada.png": "Ada Lovelace",
  "grace_hopper.jpg": "Grace Hopper"
}

You can also supply labels as a CSV (filename,name) or a plain text file with filename=Name pairs, and point to it with --labels. Individual overrides are supported with --name image.png="Display Name" or with inline JSON via --labels-json '{"image.png": "Display Name"}'.

Generate the Grid

python3 src/team_grid.py \
  --input-dir import \
  --labels import/labels.json \
  --output export/team-grid.png

• --input-dir defaults to import.
• --output defaults to export/team-grid.png; the folder is created automatically.
• --sort label sorts the grid by the rendered name instead of the filename.

When the command finishes, open the PNG in export/ to review the result.

Layout & Style Tweaks

• --columns 5 changes how many portraits fit per row, or omit it to let the script pick an even grid.
• --width / --height control the canvas size.
• --background "#f5f5f5" fills the canvas instead of staying transparent.
• --image-size, --border, and --border-radius tune the portrait frame.
• --font, --font-size, --min-font-size, and --text-color adjust the label pill.
• --focus-x / --focus-y bias the crop for portraits that need extra headroom.

Run python3 src/team_grid.py --help for the full list of options.

Troubleshooting

• “No supported images found”: confirm the input directory contains .png, .jpg, or .jpeg files.
• “Labels file not found”: either create import/labels.json or point to a different file with --labels.
• Missing font characters: supply a custom font file via --font path/to/font.ttf.

Keep this README close, drop fresh portraits in import/, update labels.json, and rerun the command whenever you need an updated team grid.