plotline 0.2.0

Turn images into drawings for pen plotters.

Open it in your browser  ·  Command line  ·  Design brief

plotline converts raster images into vector line art, such as stippling, single continuous lines, dashes and sketched strokes. It comes with a live preview that shows the algorithm at work, so you can see what a setting does before you commit ink to paper.

The image	grid: dots on a regular grid	hatch: crossing parallel lines
waves: rippling lines, one stroke each	spiral: one rippling spiral	ink: dark areas as filled shapes, at threshold 0.3
scribble: loops along one line	mosaic: patches of parallel lines	truchet: nested arcs on tiles in random turns

_{plotline drew every picture above with a 0.3 mm pen, from images it renders in code.}

Features

• Twenty-one styles, from dots on a grid to one continuous spiral. The table below describes each one, and the style guide shows each on the same picture with its settings and pen tips.
• Live preview. The browser GUI shows the drawing being built. It runs the engine inside the page as WebAssembly, so your image is never uploaded.
• Suggestions. The engine measures a new image and suggests changes: line art, levels, uneven paper, invert, noise, page orientation, framing, which crops the image to its subject when that fills only part of it, and colour, for which it picks two to four ink pens that draw the image's colours best. You apply each one with a click. The tone stage's Levels can also be Auto, which sets black and white from the image.
• Focus points. Click the preview, or have an assistant set tone.focus, to mark where the picture matters: every style keeps its detail near those points and smooths it further away, so a drawing's detail sits where you want it.
• Plot lint. After every run the engine checks the drawing for trouble on paper: marks drawn over each other, specks, lines closer than the pen, a drawing too light for the image's darks, heavy pen lifting or travel, and marks off the page or the machine. Where a setting fixes one, it says which.
• Budgets. Give a plot time, a path count, metres of pen-down line or a dot count, and plotline finds the value of the style's density setting, such as its line spacing, that meets it in up to eight runs.
• Tone match. Every run scores how closely the drawing's tones follow the image, seen from a metre or two, as a tone error and an SSIM. Optimize tries the style's density setting from a quarter to four times its value and suggests the one that brings them closest, with its plot time. It skips values that would plot over twice as long (or an hour) or that the plot lint warns about, and stays within a budget if you give one; nothing changes until you apply it. The tone stage's Response can also be Auto, which measures how much paper the style covers at each grey on a small test wedge and corrects the image for it.
• Short pen travel. Every run orders its paths to keep the pen's travel short, and the line styles lift the pen far less often than grid.
• Plotter-ready output. An SVG in millimetres holds one layer per pen that draws, each labelled with the name of its pen. A run can also write the paths as JSON, and a PNG preview that draws each mark at its real pen width. For a pen-fitted 3D printer, the GUI, the command line and the MCP server write one G-code file per pen. For pen plotters that read HPGL, the same front ends write the whole drawing as one HPGL file, with a pen selected for each layer.
• Several pens. Pen use shares a drawing between your pens: light to dark in list order, or each pen by its colour, so cyan, magenta, yellow and black pens can draw a colour image. By default the first pen draws alone.
• Real pens. A bank of common fineliners, technical pens, gel pens, ballpoints and markers gives each pen its maker's line width, and a list of common inks gives it a colour.
• Looks. Most styles offer a few starting points chosen by measuring test images: Balanced is the defaults, Faithful follows the image's tones most closely, Quick plots in about half an hour and Fine draws the densest marks that still plot cleanly. A look changes only the few settings that set it.
• Presets. A small JSON file holds the style, page, pens, settings and machine of a run, so you can keep a setup and share it. An exported SVG or JSON drawing carries the preset of the run that made it, and loads as a preset too.
• One engine. The engine is written in Rust and compiled twice: to a native extension for the Python package, and to WebAssembly for the browser. The Python package and the command line are thin layers over it.

stipple, line, dashes, tree, mesh, cells and scribble share one placement of points, so switching between them reuses the points. A style switch keeps the settings you changed wherever the new style has the same stage, Pen use included, and gives the rest the new style's defaults; Reset to defaults puts them all back.

In the browser

Open jonathanrjoyner.github.io/plotline. There is nothing to install.

1. Drop or paste a PNG, JPEG or WebP image, or click Sample image.
2. Pick a style and a look, change its settings and click Run to watch it draw. Try all styles, under the style menu, draws every style small on your image so you can choose by eye, and Undo in the toolbar (Ctrl+Z) steps back through changes to the style, settings, page and pens.
3. Set up your pens in the Pens dialog, and choose how they share the drawing under Pen use. The page remembers your setup between visits.
4. Click Export SVG in the toolbar, ready for a pen plotter's own software.

For a new image the Suggestions panel, at the top of the right column, lists what would suit it, each with an Apply button. Nothing changes until you click. Under the stats, the plot lint lists what it found in the last drawing, with an Apply button where a setting fixes it. Optimize, beside Fit to target, suggests the density that makes the drawing's tones follow the image best, with an Apply button too.

To check a pen and a page on paper, Test chart in the export panel replaces the drawing with a page of labelled patches: lines at growing spacings, dots of growing sizes, and a solid fill drawn over one to eight times. Plot it and see where lines merge, how big dots come out and how many passes the paper takes, and time the plot against the estimate. It needs no image.

For G-code, enter your machine in the Settings dialog: the drawable area, pen heights, feeds, and start and end G-code. The export panel then writes one G-code file per pen. The preset carries the machine, so save a preset to keep it. A short tour of the page opens on your first visit, and Tour in the toolbar opens it again.

Command line

There is no release yet, so work from a clone of this repository. Building the Python extension needs a Rust toolchain: install one with rustup. With uv installed as well, run this in the clone, where uv sync builds the extension and installs the package:

uv sync
uv run plotline --help

Then draw an image of your own:

uv run plotline run grid your-photo.jpg --out drawing.svg --preview preview.png

This writes drawing.svg and preview.png, and prints a one-line summary with the path count and an estimated plot time, then the tone error and SSIM. The plot lint's findings follow on stderr, each with the --set options that fix it where a setting does.

A machine file holds the same object as a preset's machine: name, area (x, y, width and height in the machine's mm), z_down_mm, z_up_mm, z_safe_mm, draw_feed, travel_feed and z_feed in mm per minute, settle_ms, start_gcode and end_gcode. A pen lifted by a servo or a solenoid instead of Z takes "pen_lift": "gcode" with pen_down_gcode and pen_up_gcode, the lines written in place of each Z move. max_segment_mm cuts every move into pieces no longer than it, for firmware that would draw a long straight move as a curve. The easiest way to make one is to enter the machine in the GUI's Settings dialog and save a preset, which --machine also reads.

plotline gui serves the browser GUI from your machine. Building it needs Node, wasm-pack and the wasm32-unknown-unknown Rust target: run npm run wasm, npm ci and npm run build in web/.

With an AI assistant

plotline mcp serves plotline to an AI assistant over the Model Context Protocol, on stdio. From a clone, uv sync installs the MCP extra; once there is a release, pip install "plotline[mcp]" will. Give an MCP client the server as {"command": "plotline", "args": ["mcp"]}, where command is the plotline on the client's PATH or the full path to it (for a clone, the one in its .venv). The assistant can load an image, ask analyse_image what would suit it, run styles, starting from one of their looks if it likes, and read the tone match and the plot lint's findings in each result, fit one to a budget, ask optimize for the density that matches the image's tones best, draw a testchart for the pen, look at previews, also zoomed in on a part of the page, and export the result, as G-code too once set_machine has described the plotter.

Roadmap

plotline is early software. The goals, architecture, decisions and everything still planned are in the design brief.

License

MIT