Plotbox

Plotbox is a local-first browser application for turning generated artwork, raster images and linocut vectors into machine-ready G-code. Its canonical artwork format is vector geometry measured in millimetres; the preview and G-code exporter consume that same geometry.

• Local project list with A4, A3, A2 and custom paper sizes, portrait/landscape orientation and a 10 mm default safe margin
• SQLite project persistence and debounced autosave
• Zoomable/pannable SVG preview with pen-colour and physical line-width rendering
• Viewport zoom that scales and pans the entire sheet while keeping plot geometry unchanged
• Editable pen, paint and linocut passes, including Z up/down, feed rates, brush width, paint-well calibration and fixed-blade direction indexing
• Paint G-code with FluidNC XY position capture, configurable dip depth/dwell, distance-based reloading and optional variable-Z brush pressure
• Combined or per-pass G-code with configurable origin, park position and pen-change pause
• A built-in physical test pattern
• Raster preprocessing: brightness, contrast, gamma, blur, threshold and inversion
• Raster contain, cover and stretch fitting with independent scale and millimetre offsets
• Worker-based edge, contour-tracing, hatch, crosshatch, adaptive crosshatch, dither, stipple, tonal-dash and scanline vectorisation
• Continuous spiroglyph image rendering with adjustable line spacing, wave frequency, smoothing, tone thresholds, amplitude, shape and placement
• Continuous scribble image rendering: a drifting, irregular looping path over a tone-weighted point cloud, with loose highlight coverage and overlapping shadows. Loop density accounts for the selected pen width; smaller loops follow tonal boundaries without a visible tile grid. Covers the placed image within safe margins; accepts up to 2400-pixel source resolution. Fine detail size is in millimetres, so pen width and plot size determine the smallest visible features. Extremely dense jobs report a point-budget error instead of leaving an incomplete drawing. Preview paths are cached in bounded chunks, and fine pens display at their actual width.
• Straight line sketch rendering: short, independently plotted lines build darkness from the source image and turn along local tonal edges. White areas remain blank. An optional definition pass overlaps shadows and detail using a separately selected pen pass, so it can use a different colour. Lines, tone contrast, fine detail size, line length and each pass's pen width control the result.
• Optional continuous-scribble under-colour passes: separates the source palette into solid, clipped colour fills for thicker pens, orders those passes before the fine scribble pass, and leaves pale paper blank when requested.
• Paint-aware pressure scribble and scanline image modes map source tone to a calibrated brush-contact Z range.
• Seeded flow-field, Truchet and guilloché generators
• Generative → Isometric 3D maze builds connected terrace cities with stairways, optional towers and dead-end obelisks or stepped pyramids. Set 4–24 rows/columns, branching, extra connections, terrace levels and height exaggeration. A fixed seed preserves the map while adjusting rotation or viewing elevation; Plan view shows the complete overhead map. Zero extra connections gives a unique start-to-exit route. Optional S/E markers and a dashed solution use separate pen passes: architecture uses the first, landmarks the second, and the solution the third, falling back to available passes. Exact vector hidden-line removal is shared by preview and export; use plan view to see routes hidden behind tall buildings. All settings autosave with the project.
• Standard TurtleToy script execution through the turtletoy package in a disposable worker
• SVG import with named-group decomposition, transform flattening and editable per-layer treatments
• Linocut projects import SVG cuts and group them into configurable straight-blade direction steps. The tool lifts and parks before each group, then emits a mandatory pause and angle instruction for manual blade rotation; opposite travel directions share one blade axis.
• Engraving projects fit raster artwork to a tile, with tonal area fills, independent colour tonal passes, and colour-separated dense pockets for later enamel filling. Rotary tool passes use configurable bit width, clearance and engraving Z, feeds, manual power pauses or controller M3/M5 with spin-up dwell. Colour passes can be exported as separate G-code files.
• Map place search and bounded feature import with classified OpenStreetMap roads, railways, buildings, water, parks and boundaries
• OpenStreetMap-only, terrain-only, or combined downloads, with plot-ready contours at selectable 5–200 m intervals and separate index-contour layers
• Rectangle, square and circle region selections in both map modes. Square and round standard maps are centred without stretching; circles clip roads and closed fill areas to the selected footprint. Choose the shape before downloading a region.
• Isometric topography projects retain real elevation data and render adjustable rotation, viewing elevation, vertical exaggeration, contour interval and a flat cut base. An optional visible-depth limit trims oversized side walls while leaving the terrain surface unchanged. Six editable pen passes separate low/middle/high elevation fills, slope shading, water and contours. Surface-following hatch strokes and hidden-slope removal are shared by the preview and G-code. Choose OSM + terrain to include mapped water; terrain-only downloads omit water. Elevation grids are capped at 241 samples per side and circular selections appear as disks viewed in perspective.
• Large-area map selection beyond 50 mi²; OpenStreetMap detail automatically scales from local streets and buildings to regional roads, railways, water, waterways and administrative boundaries
• Per-layer outline, hatch, crosshatch and stipple treatments with independent pen-pass assignment
• Shared path optimisation before G-code generation
• Glyphbox Cityscape collection: 18 residential, commercial and industrial buildings (1–11 storeys), 15 connected road tiles with signs, arrows, signals and zebra crossings, five tree-lined road shapes, plus 10 plot-ready trees, parks, gardens and green spaces. A consistent six-colour SVG style shares its exact vertices with the plotted artwork.
• Isometric artwork colours map to editable pen passes, with outline or hatched surface treatments. Pale surfaces reserve the paper; foreground shapes and windows clip underlying pen paths. Select Use whole Cityscape collection to use all its buildings and roads together. Existing projects retain their snapshots until Reload glyphs is selected; uploaded glyphs survive the library upgrade.
• Rebuilt parks share the buildings' stonework and fine outlines, with leafy trees, raised planters, slatted benches, a pergola, reflecting pool, timber playground, community garden and café kiosk. Green spaces per city block mixes zero, one or two green lots into building blocks rather than reserving whole districts for parks. Tree-lined avenues uses five connected leafy road shapes along continuous streets; canopies stay upright when rotated. Buildings have paved aprons and pedestrians. Coasts & lakes adds 12 tiles: open water, beaches, bay corners, quays, reed banks, fishing docks, cargo ships, fishing boats, sailing yachts, sharks and whales.
• Choose Coastal town or Lakeside city in the isometric scene generator for connected water regions and matching shores; roads stop at the waterfront. Water extent and automatic boats/marine life are adjustable.
• Use Edit tiles above the canvas to drag tiles between grid cells, swap occupied cells, or choose a tile from the placement menu and click to place/replace it. Select a tile to duplicate, delete or rotate ground tiles. Arrow keys move a selection; R rotates; Delete removes; Ctrl/Cmd+Z undoes (Shift redoes). Alt-drag pans and the wheel zooms. Manual layouts autosave with the project and are used for the plot preview and G-code. Return to generated layout reapplies the generator; Reload glyphs updates the artwork while retaining tile positions.

Map provider configuration

Map imports are initiated only when the user submits a place search or chooses a result. Search responses, Overpass extracts and requested elevation tiles are cached in SQLite. Plotbox identifies its requests, limits public Nominatim traffic to one request per second, bounds imports to 1,000 km²/60 km across, and displays attribution for the selected sources. Regions up to 25 km² retain full OSM detail; larger requests omit buildings, paths and minor roads, with overview-scale requests retaining major roads, railways, water, waterways and administrative boundaries. Terrain contours are generated locally from keyless Mapzen Terrain Tiles on AWS Open Data; the source is a global bare-earth elevation mosaic whose resolution varies by location.

Provider endpoints can be changed without rebuilding the app:

NOMINATIM_URL=https://your-nominatim.example
OVERPASS_URL=https://your-overpass.example/api/interpreter
TERRAIN_TILE_URL=https://your-terrain.example/terrarium/{z}/{x}/{y}.png
PLOTBOX_USER_AGENT="Plotbox/0.2 (your contact URL or email)"

Review the Nominatim usage policy, Overpass API guidance, and Terrain Tiles source attribution before distributing or operating Plotbox for multiple users. A self-hosted or commercial provider is recommended beyond light personal use of OSM services.

Run locally

Requirements: Node.js 24 or newer and npm 11 or newer.

npm install
npm run dev

Open http://localhost:5173. The API runs at http://127.0.0.1:8787 and creates data/plotter.sqlite on first use.

Validation

npm test
npm run typecheck
npm run build

The production server serves apps/web/dist after a build:

npm run build
npm start

Open http://127.0.0.1:8787.

Home Assistant add-on

This repository is also a Home Assistant add-on repository. Add the repository URL in Settings → Apps → App store → ⋮ → Repositories, then install Plotbox. The add-on stores its SQLite database in Home Assistant's persistent /data volume, so projects survive upgrades and restarts.

Plotbox publishes TCP port 8787 and does not use Home Assistant Ingress. Point your Home Assistant reverse proxy at the add-on's port, or use the add-on's Open Web UI button for a direct local URL. The app is served from /, so proxy it as its own host or location without a path prefix. WebSocket forwarding is needed for direct FluidNC control from the browser.

The add-on settings expose the Nominatim and Overpass endpoints and the identifying User-Agent used for map imports. Keep the defaults for light personal use, or set them to a self-hosted/commercial provider as described above.

TurtleToy scripts

Plotbox accepts standard TurtleToy code using Canvas, new Turtle(), and an optional walk(i) function. The official-compatible turtletoy npm package captures the resulting lines directly into Plotbox geometry. Scripts are intended for trusted local use and run in a disposable Web Worker so a new render can terminate the previous job.

Repository layout

apps/web          React/Vite editor and render worker
apps/server       Fastify API and SQLite persistence
packages/core     Project and canonical geometry types
packages/geometry Geometry processing and path ordering
packages/algorithms Seeded vector generators and algorithm metadata
packages/gcode    Deterministic machine output
tests             Core algorithm and G-code tests

Colour separation for flat artwork

In a raster project, select Vectorisation → Colour separation. Start with 6–8 palette colours, then use Colours & pieces to set a treatment and pen pass for each colour. Every detected colour gets an automatic pass; set its physical pen colour, width and calibration under Pens & passes. Individual connected pieces can override the colour treatment or use a separate pass. Selecting a piece highlights it in the preview; choose the empty option to see all pieces normally.

Treatments include hatching, crosshatching, dense fill, outline only and no fill, with optional outlines. Hatch spacing and angle are independent per colour or piece. Dense fill uses spacing of 85% of the assigned pen width. Existing combined and split G-code exports support these passes, and intentional gaps are preserved during path optimisation.

The algorithm uses deterministic, weighted CIELAB palette clustering, conservative edge cleanup and four-connected component separation. It intersects hatch lines with each region’s boundaries using even–odd filling, so interior holes remain unfilled. Segments are clipped to the paper’s safe area. Transparent pixels and, optionally, pale neutral paper remain blank. Grayscale preprocessing is bypassed. Images use the editor’s existing maximum processing dimension of 1000 pixels; minimum region size is measured at that resolution.

This separates connected colour shapes rather than recognising semantic objects. Small omitted regions become blank; thin details may require a smaller pen or denser hatching. Outlines follow pixel boundaries; dense fill is a pen-line approximation, and real coverage depends on the pen and paper. Changing palette/segmentation settings or replacing the source resets colour treatments and automatic pens, so finish separation before calibrating those pens. Placement changes retain treatments.

Engraving tiles and glass

Create an Engraving project, enter the tile dimensions and safe margin, and import a raster image. Tonal area fill makes nested hatching for light and dark regions. Colour tonal area fill keeps each detected colour in a separate pass. Colour separation defaults to dense engraved pockets with outlines, giving each colour a separate area that can be filled with enamel after engraving; edit individual colours and pieces under Colours & pieces. The detected palette is a machining plan, not a promise that the final enamel will match the image exactly.

Under Rotary tool & passes, set the measured bit mark width, surface-relative engraving Z, clearance Z and feeds for the mounted head. The default rotary power setting inserts pauses so a manually switched Dremel can be turned on and off while lifted. Select controller power only when the machine has a wired spindle relay or speed controller; that option emits M3 with the configured speed, a spin-up dwell, and M5 before parking. Use split G-code when engraving enamel colours independently. Establish Z zero at the material surface and verify a shallow test cut and clearance on scrap before running a full tile.