Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


imagelayout arranges several images according to a predefined layout and produces a larger image consisting of the sub-images. It can optionally label the individual images. Additional features include the ability to crop and add borders to the images, to add a border and a title to the final image, and to add arbitrary labels and lines or arrows to the final image.

imagelayout can use any image format known to the Python PIL module. This includes JPG, GIF, PNG, TIF, BMP, and lots of other formats.


The intended use of imagelayout is the automated creation of figures from sub-figures for articles and science publications. imagelayout is a command-line Python application guided by a configuration file; it has no graphical interface or interactive features. Thus, it is suitable for use in scripts, Makefiles, and automated and reproducible workflows. Instead of manually creating the illustration in a visual image editor, you can write a simple configuration file and generate the illustration with a single command. Whenever one of the input images changes, simply rerun the program and the illustration is immediately re-generated, saving you from again starting up an image editor and doing the manual work again.


imagelayout runs under Python 3.x, and needs PyYAML and Pillow to be installed.


The program is a single .py file. Put somewhere in your path and make it executable (chmod +x

If on Linux/Unix, put the man page imagelayout.1 in your MANPATH, e.g. /usr/local/man/man1.

NOTE: On Unix/Linux, you can rename the file to just imagelayout. On Windows, the .py extension may be required for Windows to recognize the file as a Python program, and associate it with the Python interpreter.


See the man page for detailed instructions. The man page is also available in man page format and in html format.


The configuration file uses the YAML format which is an intuitive, human-readable language, easily written manually. See the man page for a detailed specification of the configuration file. A quick introduction to the general YAML syntax can be found here.

A template configuration file is available; it demonstrates the available options, and can be used as a start to develop your own configuration file.

To facilitate the writing of the configuration file, imagelayout also has a "watch" mode (-w option) which monitors the configuration file and immediately regenerates the output image when it detects a change in the configuration file (i.e. you save it from an editor). Combined with an image viewer that also monitors the output image for changes and immediately displays the changed file, imagelayout can be used semi-interactively.


imagelayout constructs the output image by joining some input images horizontally or vertically (hjoin and vjoin keywords), and then again combining the resulting images horizontally or vertically, etc. Thus, the layout is specified as an arbitrarily nested list of hjoin/vjoin lists. During joining, all images are resized (upscaled) to match the highest image in height (for horizontal joining) or the widest image in width (for vertical joining).

If the fixedsize option is used for an image, padding will be used for that image instead of resizing. When fixedsize is used for several images, the relative size of those images will be retained in the final image. This is useful e.g. to avoid font sizes becoming different when images containing text are combined.

More details on how to specify the layout can be found in the man page.


A simple example of how imagelayout works can be found in the demo directory. Here, 6 input images are combined and labeled from A to F, and a title is added. The layout is defined as

    - vjoin:
      - hjoin: [A, B, C]
      - D
    - vjoin: [E, F]

Thus, A, B, and C are joined horizontally, then joined with D vertically; this is then joined horizontally with the vertically joined E and F. The result is:

imagelayout demo

The full configuration file is imagelayout_demo.yaml.


To create a grid of images, either horizontally joined images should be joined vertically:

    - hjoin: [A, B, C]
    - hjoin: [D, E, F]
    - hjoin: [G, H, I]

or the other way around:

    - vjoin: [A, D, G]
    - vjoin: [B, E, H]
    - vjoin: [C, F, I]


Although the main purpose of imagelayout is to combine multiple images, it can also be used as a quick way to resize, crop/autocrop, add borders, labels, lines or arrows to single images. If only a single input image is specified, the layout does not have to be specified, but all the other functions are available.


On Unix-based systems, you can write the #!/usr/bin/env line as the first line of the configuration file, and make the file executable. Then you can execute the configuration file as a command.


Program to arrange images into a large image according to a predefined layout





No releases published


No packages published