Skip to main content

Concat photos together in a matrix

Project description


Simple command-line application which concatenates a list of photos into a single photo showing them in a matrix (in other words, a grid).


First of all, you need Python 3.7 or greater installed in your system.

Then, as photomatrix is a command line application, open a terminal and be ready to type commands.

Install automatically with pip

photomatrix is available from the Python Package Index (PyPI), so installable with pip:

pip3 install photomatrix

You should now have photomatrix available in your shell. For example, print the command help:

photomatrix -h

Build locally

Alternatively, you can build locally from source code. First, clone this project from Github.

Cd into the root folder.

Create a virtual environment (e.g. named my_env) and activate it:

python3 -m venv my_venv
source my_venv/bin/activate

Install the dev dependencies and the app dependencies into the virtual environment:

pip3 install -r requirements_dev.txt
pip3 install -e .

Run like this:

python3 -m photomatrix -h


The basic usage is:


where all the images found in the specified input path will be loaded, sorted, combined in a matrix and the result will be written in the specified output path.

Further options that you can customize are:

  • Number of rows vs columns
  • Resize and crop
  • Sorting
  • Border
  • Text to print (e.g. filename or Exif original date)

See the command help (with -h) for more info on these options.


The following examples use these test input images:

up to

Matrix with border

To build a matrix with a simple border:

photomatrix "data/input/*.jpg" data/output/matrix_border.jpg --border-width-ratio 0.1

resulting in:

Matrix sorted and with text

To build a matrix with inverse filename order, printing the filename in top center position:

photomatrix "data/input/*.jpg" data/output/matrix_sort_text.jpg --sort filename_desc --text-type filename --text-position top_center

resulting in:

Integration Tests

Run the integration tests with:

python3 -m pytest tests/integration

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

photomatrix-0.0.5.tar.gz (7.3 kB view hashes)

Uploaded source

Built Distribution

photomatrix-0.0.5-py3-none-any.whl (13.2 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page