imagegen

Disclaimer: This is an AI-generated project. I've had this idea lingering in my mind for a while, but I never actually reviewed the code itself.

imagegen is a Go CLI that builds a photo mosaic from a source image and a directory of tile images.

It splits the main image into a grid, computes the mean RGB color of each cell, finds a close tile image for that cell, crop-fits the tile to a uniform cell size, and renders a final collage image.

What it does

• Supports PNG and JPEG inputs
• Scans tile images recursively from a directory
• Caches tile mean colors in memory for faster matching
• Uses parallel indexing, matching, and render preparation
• Shows a progress bar during CLI runs
• Supports optional controlled randomization to reduce visible repetition

Requirements

• Go 1.26+

Example

./bin/imagegen -main ./imgsrc/real_dataset/people_111.jpg \
   -grid-height 72 -grid-width 108 -scale 10 -tiles ./imgsrc/real_dataset \
   -output out.jpg -randomness 0.5

Build

make build

The binary is written to:

./bin/imagegen

Development commands

make fmt
make lint
make test
make build

Usage

./bin/imagegen \
  --main ./main.jpg \
  --tiles ./imgsrc \
  --grid-width 80 \
  --grid-height 60 \
  --scale 4 \
  --output ./mosaic.png

Flags

Flag	Required	Description
--main	yes	Path to the main source image
--tiles	yes	Directory containing tile images; scanned recursively
--grid-width	yes	Number of columns in the source grid
--grid-height	yes	Number of rows in the source grid
--scale	yes	Output size multiplier relative to the source image
--output	yes	Output file path; supports .png, .jpg, .jpeg
--randomness	no	Variation amount from 0.0 to 1.0; default 0.0
--seed	no	Seed for reproducible randomized matching

How matching works

Default mode

With --randomness 0, matching is deterministic:

1. Compute the mean RGB color of each source cell.
2. Compute the mean RGB color of each tile image.
3. Pick the single closest tile by RGB distance.

Randomized mode

When --randomness is greater than 0:

1. The matcher keeps a small pool of near-best candidates.
2. It chooses from that pool randomly, with a bias toward the better color matches.
3. If you pass --seed, the result is reproducible.

This helps reduce repeating patterns when the tile set is small or the source image contains many similar regions.

Output sizing

The output image size is derived from:

• the source image size
• the grid dimensions
• the scale multiplier

Each grid cell in the final output has the same size. Tile images are center-cropped and resized to fit that cell.

Notes

• Only PNG and JPEG are supported.
• Tile reuse is currently unlimited.
• Randomization changes tile choice, not output dimensions.
• The progress bar is written to stderr.