Photo Collager

A Python script that automatically arranges photos into efficient grid layouts for printing on standard paper sizes.

Features

• Smart Layout: Automatically determines the most efficient 2×n grid arrangement
• Orientation Aware: Handles portrait and landscape photos intelligently
• Paper Size Support: A4 and A3 paper sizes
• Flexible Borders: Configurable white borders around photos (default enabled)
• Optimal Packing: May separate portrait and landscape photos onto different prints for better space utilization

Usage

uv run photo_collager.py <input_directory> <paper_size> [options]

Arguments

• input_directory: Directory containing input photos
• paper_size: Paper size (a4 or a3)

Required Options (choose one)

• --max-pages: Force all photos to fit within this many pages
• --max-photos-per-page: Maximum number of photos per page

Additional Options

• --border-size: Border size in pixels (default: 50)
• --no-border: Remove all borders between photos
• --output-dir: Output directory (default: current directory)
• --order: Photo ordering (date-asc, date-desc, default: date-asc)
• --orient: Page orientation (portrait, landscape, default: portrait)

Examples

# Collage photos from 'vacation_pics' folder for A4 printing with max 2 pages
uv run photo_collager.py vacation_pics a4 --max-pages 2

# A3 layout with maximum 6 photos per page
uv run photo_collager.py photos a3 --max-photos-per-page 6

# Custom border and landscape orientation
uv run photo_collager.py photos a4 --max-pages 1 --border-size 20 --orient landscape

# No borders, sorted by date descending
uv run photo_collager.py photos a4 --max-photos-per-page 4 --no-border --order date-desc

Layout Logic

• 2×n Grid: Always creates 2-row layouts (2×1, 2×2, 2×3, etc.)
• Orientation Optimization:
  • 4 landscape photos on A4 → 2×2 grid
  • 6 photos on A3 → 2×3 grid
  • Mixed orientations may be split across multiple prints for optimal fit
• Efficient Packing: Maximizes photo size while maintaining aspect ratios

Output

Generated collages are saved as high-resolution images ready for printing.