Photomosaic Poster

Photomosaic Poster takes a target image and a collection of photos through selection, matching, printer checks and paper previews, then exports files for different print workflows.

The Problem

A photo mosaic has to preserve two views at once: individual photos should be recognizable up close, while their colors and placement form the target image from across the room. Preparing a poster adds practical constraints. Photos arrive in different formats, the image has to fit a paper size, and each printer may require a particular color mode, resolution or file-size limit.

What I Built

Photomosaic Poster is a Python command-line tool for making photo mosaic posters, with a browser version of the same engine. Its workflow starts before rendering: friends can upload photos to the user’s computer, and compare scores target candidates and shows mosaic previews. The check command tests a proposed job against a printer preset before a full render.

The renderer writes a report alongside each poster. The HTML report includes views at different scales and a paper preview, printer-rule checks with recommendations, and a checklist for taking the file to the printer. When a printer rejects a file, --fallbacks can produce PDF, JPEG, RGB and CMYK alternatives; --test-strip can create a small test print.

How It Works

1. Collect and chooseFriends can upload photos from their phones to the computer running the collection command. The compare command scores target candidates and shows side-by-side mosaic previews.
2. Check the printerSelect a preset such as plotter-bond, photo-lab or canvas. The preset supplies requirements such as resolution, color mode, file type and size limit; command-line options can override them.
3. Prepare the photosImages are decoded upright, cropped square and cached. Exact duplicates and Mac zip junk are dropped, while similar photos are grouped using a perceptual hash. Zip archives can be read directly, and video frames are opt-in.
4. Match tilesThe target is cropped to the poster shape and averaged into a grid. Each tile is matched to a photo by color in CIE Lab; the matcher limits repeats, separates look-alikes and gives every distinct photo a spot.
5. Render for printTint and an optional faint, sharpened target overlay adjust the image. The poster is drawn in strips to limit memory use, then converted to the requested color mode and saved at the best quality that fits the size limit.
6. Review and recoverThe HTML report previews the poster on the selected paper and lists printer checks and recommendations. Test strips, panels and alternate output formats provide options for print jobs that need adjustment.

Limits

• The browser version runs on the user’s device and creates RGB files only. Use the Python command-line tool for CMYK output, camera RAW decoding and batch work.
• Camera RAW decoding requires the optional rawpy dependency. Video-frame support requires optional av and must be enabled with --include-videos.
• Paper simulation is an approximation. When the print shop provides an ICC profile for the printer and paper, the tool can use it for a soft proof.
• Repeats become noticeable above about four to five uses per photo. The README’s default grid aims for tiles about half an inch across, and suggests collecting more photos or reducing the number of columns when repeats are too frequent.
• The documented demo images are generated, rather than photos from a real event.