Inklet

Scientific figures from Python, with measured layout and editable SVG/PDF output.

Combine plots, diagrams, images and native 3D artwork on a page sized in millimetres. Keep data and labels live, compile the figure, and inspect its layout and print diagnostics before exporting.

Get started · Documentation · Examples · API reference

This twenty-panel stress test includes 30,000 scatter points, 5,580 mesh triangles and 7,200 vector events. Its data are simulated. Only the dense scatter and scalar field are rasterized; the other artwork remains vector.

Install

Python 3.11 or later is required. Install from this repository using an account with access to Mapika/inklet:

git clone https://github.com/Mapika/inklet.git
cd inklet
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .

SVG/PDF output and the built-in 3D renderer need no browser or external rendering engine. Text needs an installed font. For PNG layers and visual review, install python -m pip install -e '.[images]' plus Chrome/Chromium and Poppler. See installation for system packages, Windows activation, optional dependencies and environment checks.

Your first figure

Save this as first_figure.py and run python first_figure.py:

import inklet as i


def make_document():
    data = i.dataset(
        {'time': [0, 1, 2, 3], 'signal': [1, 3, 2, 4]},
        name='response',
        source=i.Source('Quickstart demonstration', method='simulated'),
    )
    plot = i.plot_spec(x=(0, 3), y=(0, 5))
    plot.line(data.points('time', 'signal'), name='Signal', stroke='#176b9b')
    plot.axes(x='Time / s', y='Signal / mV').legend(side='bottom')

    doc = i.publication('single-column').document()
    doc.add('response', plot, min_height=55)
    return doc


if __name__ == '__main__':
    figure = make_document().compile()
    figure.save('response.svg', 'response.pdf')
    print(figure.report())

The document measures axis labels and the legend, fits the plot to an 89 mm page, and saves SVG and PDF with embedded text. It does not shrink the font to make the plot fit. The quickstart continues with live data edits, multiple panels and review exports.

Build, inspect, revise

With the preview dependencies installed:

inklet doctor
inklet build first_figure.py --output out/review
inklet watch first_figure.py --output out/review

build writes the vector files, PNG previews, diagnostics, a provenance manifest and a local HTML review page. watch serves a preview at http://127.0.0.1:8765/ and rebuilds when the authoring code changes. Review pages support diagnostic filters, SVG highlights and comparisons with a saved revision.

For an environment without preview tools, use inklet build first_figure.py --output out/review --vectors-only.

What you can build

How Inklet works

A Document holds live definitions. compile() measures their contents, places them, routes connections and produces a snapshot used by both export backends. Updating a dataset or named instruction invalidates dependent components; unchanged definitions can reuse their cached geometry. Earlier snapshots remain unchanged.

Numeric lengths, including low-level text sizes, are millimetres. Use i.pt(8) for an 8-point text size; publication profile options such as font_pt=8 take points explicitly. Plot coordinates follow their data scales.

The direct Figure, Panel and Diagram APIs remain supported for fixed drawings. See the authoring model for when to use each layer.

Scope and limits

• Layout respects physical constraints. Impossible fits raise LayoutError; changing page width does not automatically rearrange the number of columns.
• Diagnostics help find collisions, small type and other print issues. Review the rendered figure as well; a clean report does not establish scientific accuracy.
• Rasterization keeps dense exports compact, but dense-scatter rebuilds can still be expensive. The stress report records the workload, timings and remaining limitations.
• Reproducible appearance requires consistent inputs, fonts and dependencies. The export manifest records dataset and font hashes for comparison.

Documentation and development

Start at the documentation index. The source Markdown is readable on GitHub; a searchable site can also be served locally:

python -m pip install -e '.[docs]'
python -m mkdocs serve

See contributing for tests, documentation checks and visual regressions. Existing users can consult migration, the v2.5 changes and the changelog.

License

Inklet code is available under the MIT license. Included third-party meshes and structural data retain their own terms; see third-party notices.