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
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
The program is a single
.py file. Put
somewhere in your path and make it executable (
chmod +x imagelayout.py).
If on Linux/Unix, put the man page
imagelayout.1 in your MANPATH, e.g.
NOTE: On Unix/Linux, you can rename the
imagelayout.py file to
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.
DEVELOPING THE CONFIGURATION FILE
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
imagelayout can be used semi-interactively.
DEFINING THE LAYOUT
imagelayout constructs the output image by joining some input
images horizontally or vertically (
vjoin keywords), and
then again combining the resulting images horizontally or vertically,
etc. Thus, the layout is specified as an arbitrarily nested list of
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).
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
layout: hjoin: - 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:
The full configuration file is imagelayout_demo.yaml.
To create a grid of images, either horizontally joined images should be joined vertically:
layout: vjoin: - hjoin: [A, B, C] - hjoin: [D, E, F] - hjoin: [G, H, I]
or the other way around:
layout: hjoin: - 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 imagelayout.py line as the first line of the configuration file, and
make the file executable. Then you can execute the configuration file
as a command.