it-figures v0.5.1
It Figures
figures
is a node based command line utility for building up figure panels out of multiple images
that can be used in publications.
Installation
It can be installed by:
npm i -g it-figures
Why?
A lot of my figures are generated programatically in jupyter
notebooks. Building up multi-part
figures is a real pain in Word / LaTeX or in Photoshop. This is an attempt to automate the process
with a simple CLI tool that uses JSON
figure definitions.
Example
To start with save a JSON
file, e.g. figure-a.json
.
{
"data": [
{
"output": "output.png",
"width": "16",
"height": "9",
"sizex": "100",
"sizey": "100",
"images": [
{ "source": "input.svg", "top": "0", "left": "0", "rows": "7", "cols": "9", "caption": "A" },
{ "source": "input.png", "top": "6", "left": "5", "rows": "2", "cols": "3", "offsety": "20" }
]
}
]
}
Then in the same directory run
figures build figure-a.json
Here two images input.svg
and input.png
will be combined and exported to output.png
. See below for more
details about the data format.
NOTE This will build synchronously, which helps reduce some font detection issues in
cairo
on the Windows platform. If you are on another platform or don't use captions, theasync
version of this command may run a little faster.figures async figure-a.json
Documentation
CLI
figure
ships as a CLI. Once installed globally, up to date documentation can be viewed by running:
$ figures --help
All of the figure panels defined in the definition file can be built at once by running the build
command:
$ figures build my_input_file.json
Definition Files
The basic JSON
file is a definition file, which contains information about the figure panels that are
being generated. Multiple figure panels can be generated at once.
The definition file has only one key, data
which contains an array of figure panel definitions.
Figure Panel
The definition files contain an array of figure panel objects. Figure Builder uses a grid system to position the sub figures. Each panel in the definition file can have separate grid dimensions. Images can then be placed on the grid and are automatically scaled to fit (with aspect ratio preserved).
The figure panel definition object has the following structure:
- output: string the file name including extension where the panel should be exported
- fontSize: Number (optional, default: 32) the size of font to use for figure captions
- mode: string (option, default: 'DEFAULT') allows selecting different parser modes. See Parser Modes below for more details
- width: Number the width of a single grid item in pixels
- height: Number the height of a single grid item in pixels
- sizex: Number the number of grids in the x-direction
- sizey: Number the number of grids in the y-direction
- images: ImageDefinition[] an array of images that should be included in the figure panel
For example, to create a 1000 x 500 pixel image from a 10 x 10 grid, the following could be provided:
{
// ...
"width": "100",
"sizex": "10",
"height": "50",
"sizey": "10",
// ...
}
Image Definition
Each panel can have an array of included images (which are essentially sub figures of the panel). The image definition object has the following structure:
- source: string the path to the input file
- top: Number the grid "square" to place the image in, from the top starting at 0
- left: Number the grid "square" to place the image in, from the left starting at 0
- rows: Number the number of rows in the grid that the image should occupy
- cols: Number the number of columns in the grid that the image should occupy
- caption: string (optional, default: no caption) the caption to write for this image (i.e. an "A" for figure A)
- offsetx: number (optional, default: 0) the amount to move the image by in the x-direction
- offsety: number (optional, default: 0) the amount to move the image by in the y-direction
Note that as aspect ratio is preserved, then the sub figure may not occupy an entire grid square as defined by the top/left and rows/cols
Parser Modes
There are currently two supported modes - DEFAULT
and SVG
.
DEFAULT
mode
In this mode, all supported input formats are parsed using sharp
. Text captions are added by embedding SVG,
with limited font support.
SVG
mode
In SVG mode, all input files must be in SVG format and the output will also be in SVG format
regardless of the supplied file extension. The SVG documents will be positioned, moved and exported
in a new SVG document using svg.js
and svgdom
. Captions will be added as SVG text
elements.
License
MIT. Contributions welcome.