phomo
What it is
phomo is a free tool for making photographic mosaics by arranging tile images to recreate a master image. It compares color distributions in tiles and regions of the master, then assigns tiles with a linear sum assignment algorithm. The project can be installed with pip as a Python package, or used from the command line with a master image and a directory of tile images. CLI controls include cropping and resizing the master and tiles, converting to black and white, displaying the grid, and setting how often tiles may appear. Matching options include greyscale, norm, and luv_approx distance metrics, color equalization, and color-distribution matching. A greedy assignment option is described as improving performance at the expense of accuracy. GPU acceleration is available through a CUDA extra and requires a compatible GPU and CUDA toolkit. The package requires Python 3.9 or later and below 3.13, runs on Linux, macOS, and Windows, and outputs PNG. The project is published under the MIT License; PyPI identifies Loic Coyle as author and lists one maintainer.
For and against
For
- Available as a pip package and command-line tool.
- Offers multiple tile-matching metrics.
- Tile appearance count can be controlled.
- MIT-licensed and free.
Against
- Requires Python 3.9 or later and below 3.13.
- CUDA acceleration requires a compatible GPU and CUDA toolkit.
- Greedy assignment trades accuracy for performance.
- PNG is the listed output format.
The verdict
phomo provides detailed matching and image controls for generating mosaics from a tile collection. Users should check its Python version range and CUDA requirements if they want GPU acceleration.
Who it suits
phomo may suit Python users who want to create image mosaics from their own tile libraries. It is also suited to command-line workflows on Linux, macOS, or Windows.
Plans and prices
Open-source package
Python >=3.9 and <3.13 · local CLI/Python use · optional CUDA extra
Read 15 Oct 2026 · pypi.org
phomo
Python package and CLI utility · CUDA acceleration requires a compatible GPU and CUDA toolkit
Read 3 Oct 2026 · github.com
On the record
- Assignment algorithm
- The default builder solves the tile-placement assignment problem with SciPy's linear-sum-assignment implementation.loiccoyle.com · read 15 Oct 2026
- Changelog: dependency security
- The 1.1.2 changelog entry dated January 18, 2025 says dependencies were updated to close Dependabot security alerts.github.com · read 15 Oct 2026
- Changelog: greedy flag
- The 1.2.0 changelog entry dated January 21, 2025 records exposing greedy assignment through the CLI and documenting its flag.github.com · read 15 Oct 2026
- CLI image controls
- CLI flags cover cropping, resizing, black-and-white conversion, tile reuse count, grid display, and verbosity.github.com · read 15 Oct 2026
- CLI inputs
- The command accepts a master image path and a directory of tile images and writes a mosaic output file.github.com · read 15 Oct 2026
- CLI isolation
- The documentation recommends pipx when the user only needs the command-line tool.docs.loiccoyle.com · read 15 Oct 2026
- Color-distribution matching
- Its distance calculation compares color distributions within tiles and master regions rather than only average colors.loiccoyle.com · read 15 Oct 2026
- Color matching flags
- CLI options can equalize colors or match the master palette to tiles and tiles to the master.github.com · read 15 Oct 2026
- Command line
- The package provides a `phomo` command that accepts a master image and a directory of tile images.github.com · read 3 Oct 2026
- CUDA API limit
- The CUDA distance-matrix method supports only norm and greyscale metrics and requires Numba with CUDA installed.docs.loiccoyle.com · read 15 Oct 2026
- Distance-matrix API
- Mosaic.d_matrix accepts a worker count, a named metric, or a custom callable and returns a NumPy array.docs.loiccoyle.com · read 15 Oct 2026
- Distance metrics
- The CLI exposes greyscale, norm, and luv_approx metrics.github.com · read 15 Oct 2026
- Documentation depth
- The documentation includes installation, CLI help, examples, class references, and performance guidance.docs.loiccoyle.com · read 15 Oct 2026
- GPU acceleration
- An optional CUDA path uses Numba kernels to accelerate distance-matrix computation.loiccoyle.com · read 15 Oct 2026
- GPU support
- GPU acceleration is available through the CUDA extra and requires a CUDA-compatible GPU and CUDA toolkit.github.com · read 3 Oct 2026
- Greedy mode
- A greedy assignment option is documented as faster while sacrificing matching accuracy.github.com · read 15 Oct 2026
- Grid visualization
- The package can display a master-image tile grid and subdivide high-contrast regions.loiccoyle.com · read 15 Oct 2026
- Image controls
- CLI options include cropping and resizing the master and tile images, black-and-white conversion, grid display, and tile appearance count.github.com · read 3 Oct 2026
