badge generator commit

README.md

@@ -1,2 +1,82 @@
 # badge-generator
 
+Bulk-generates print-ready employee badge PDFs laid out for Avery `8395` adhesive name badges.
+
+The generator is built around the sample badge you provided:
+- employee photo cropped to fill the center frame without stretching
+- auto-sized employee name in the black band
+- auto-sized job title in the blue band, wrapped to two lines if needed
+- two identical labels per employee, kept on the same 8-up sheet
+
+## Avery 8395 layout
+
+This project uses the standard 8-up Avery 8395 / 5395-compatible layout on US Letter:
+- label size: `3.375" x 2.333"`
+- sheet layout: `2 across x 4 down`
+- default margins: about `0.688"` left/right and `0.594"` top/bottom
+- default gaps: about `0.375"` horizontal and `0.187"` vertical
+
+Those dimensions match common Avery-compatible template specs. Printers still vary, so the CLI includes `--left-adjust` and `--top-adjust` for calibration.
+
+## Inputs
+
+Photos go in a directory and should be named as:
+- `firstnamelastname.png`
+- `firstnamelastname.jpg`
+
+Examples:
+- `jaceyplace.jpg`
+- `xylaensign.png`
+
+The CSV must include:
+- `title`
+- either `name` or both `first_name` and `last_name`
+
+Optional CSV columns:
+- `prefix` for text before the name, like `Dr.`
+- `suffix` for credentials after the name, like `MD` or `RN, BSN`
+
+The easiest setup is:
+- keep the photo filenames based on the actual person name only, like `puneetbraich.jpg`
+- put `Dr.` / `MD` / `RN, BSN` in separate CSV columns so badge text changes do not affect photo matching
+
+Example:
+
+```csv
+prefix,name,suffix,title
+,Jacey Place,,Paraoptometric Technician
+Dr.,Puneet Braich,MD,Ophthalmologist
+,Brandi Lourdeau,"RN, BSN",Clinical Manager
+```
+
+## Install
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+## Usage
+
+```bash
+python3 badge_generator.py sample-data/employees.csv photos -o output/badges.pdf
+```
+
+Optional branding and print calibration:
+
+```bash
+python3 badge_generator.py employees.csv photos \
+  -o output/badges.pdf \
+  --brand-text "CHITTICK\nEYE CARE" \
+  --logo-path assets/logo.png \
+  --left-adjust 0.02 \
+  --top-adjust -0.01
+```
+
+## Output behavior
+
+- Each employee gets exactly `2` labels.
+- The two labels are placed consecutively, so both copies stay on the same sheet.
+- Each sheet holds `8` labels total, which means `4 employees per sheet`.
+- The output is a print-ready multi-page PDF.