Convert images, photos and SVGs into smooth multi-tool G-code, with a live preview GUI for Windows and Linux and a small CLI.
- fill mode: splits the image by colour (K-means, or an SVG's own fill colours), one tool per colour, and draws each region as perimeters plus infill. Best for logos, text, flat-colour art and SVGs.
- edge mode: detects edges (CLAHE, bilateral filter, multi-scale Canny), thins them and traces them as continuous strokes. Best for portraits and photos.
Paths are smooth rather than pixel-stepped. Fill mode cuts perimeters and infill ends from a smoothed signed distance field with sub-pixel iso-lines. Edge strokes are smoothed along their length. Both are then simplified to a tolerance in mm, so the G-code has few, evenly spaced points.
Download from Releases:
- Windows installer (
…-windows-x64-setup.exe): no admin needed. Tick Add img2gcode to PATH to use the CLI from any terminal; the GUI goes in the Start menu. Uninstall from Settings > Apps. - Windows portable (
…-windows-x64-portable.zip): unzip anywhere.img2gcode-gui.exeopens the GUI,img2gcode.exeis the CLI. - Debian / Ubuntu (
…_amd64.deb):sudo apt install ./img2gcode_*.debputsimg2gcodein/usr/binand the GUI in the application menu. - Other Linux (
…-linux-x86_64.tar.gz): unpack and run./install.sh(installs to~/.local, or/usr/localas root;--uninstallremoves it).
Releases are built by .github/workflows/release.yml when a v* tag is
pushed.
Requires Rust 1.88+.
cargo build --release # target/release/img2gcode(.exe)
cargo install --path . # or put it on PATHLinux needs a C linker only; at run time the GUI uses X11 or Wayland with
OpenGL, and file dialogs go through xdg-desktop-portal. For a machine without
a display, build the CLI alone: cargo build --release --no-default-features.
img2gcode # open the GUI
img2gcode gui logo.png # open the GUI on an image
img2gcode convert logo.png # writes logo.gcode next to it
img2gcode convert logo.svg -o out.gcode --size 300x200
img2gcode convert logo.png --preview logo-preview.png
img2gcode convert face.jpg --mode edge --set edge.collapse=1.0
img2gcode convert logo.png -c my.toml --set infill.density=40 --set layers.count=3
img2gcode view out.gcode # preview an existing G-code file
img2gcode config > my.toml # start a config file| Option | |
|---|---|
-o, --output FILE |
Output G-code (default: input name with .gcode) |
-c, --config FILE |
Config file (TOML) |
--mode fill|edge |
Generation mode |
--tools N |
Number of colours / tools |
--size WxH |
Print area in mm; the image is scaled to fit, aspect kept. One number means a square |
--set key=value |
Any config key, repeatable: --set infill.angle=0 |
--preview PNG |
Also save a picture of the toolpaths at printed line width |
--debug-edges PNG |
Edge mode: save the detected edge map, for tuning |
-q, --quiet |
Print nothing but errors |
Every parameter is on the left; any change regenerates on a background thread and the canvas updates within milliseconds (loading, colour segmentation and edge detection are cached, so most changes skip them).
- Open an image, SVG or G-code file, or drop one on the window.
- The canvas shows the print area as white paper, toolpaths at their real line width, each tool in its image colour (infill a little lighter). Drag to pan, scroll to zoom, double-click to fit.
- Bottom bar: travel moves, source image overlay, line width on/off, layer filter, and a progress slider that replays the print order.
- Infill exclusions: turn on Draw exclusions and drag rectangles where infill should be left out; right-click one to remove it.
- Save and load the configuration as TOML; Export G-code writes the file.
Add text in any installed font, on its own or on top of an image. Each text item is placed on the canvas in mm (centred on X/Y, independent of the image) and printed like a fill-mode region: perimeters, plus infill unless you turn it off for outline-only lettering.
- GUI: Text > Add text, then pick the font (type to search), size, position, bold/italic, infill, wrap width, alignment and tool. On the canvas, click text (or the image) to select it: drag to move, drag a corner to resize, drag a side handle to set the wrap width; Delete removes the selected text. Changes preview live.
- CLI, one item:
--text "Rowan Wuz Here" --font "Arial Black" --text-size 40 --text-pos 0,-250(--text-outlinefor no infill,--bold,--italic,--text-width MMto wrap words,--text-align left|center|right,--text-tool N,\nfor a new line). With no input image the job is just the text. - Several items:
[[text]]blocks in a config file (seeimg2gcode config). img2gcode fonts [filter]lists the names you can use: single-line fonts first, then families ("Arial") and the full names of their faces ("Arial Black", "Segoe UI Semibold").
A single-line (stroke) font draws each letter as a few open strokes that the tool follows once, instead of an outline to fill: much faster, and the natural choice for pen plotters, engraving and laser cutting.
- Relief SingleLine is built in: pick it in the font list (marked
single-line) or
--font "Relief SingleLine". - Any SVG font works too, the format Inkscape's Hershey Text uses. The
Hershey fonts of an Inkscape install are listed automatically; for others,
give the file's path as the font:
--font ~/fonts/EMSReadability.svg. - Size, position, italic, wrapping, alignment and tool work as usual. Bold and infill do not apply; the stroke is one line width wide.
Relief SingleLine is by Élisa Garzelli, Noëlie Dayma and François Chastanet (isdaT), from isdat-type/Relief-SingleLine, under the SIL Open Font License (fonts/ReliefSingleLine-OFL.txt).
The size is the font size in mm; capital letters are roughly 0.7 of it.
Outlines follow layers.perimeter_inset like everything else: 0.5 keeps the
printed edge on the letter's edge, 0 traces the outline itself.
img2gcode config prints the default file with every key documented
(configs/default.toml). Every key is optional. The main sections:
[canvas]print area (width,height) and where its centre lands.[extrusion]nozzle, line width, filament, multiplier.[layers]count, height, perimeters,perimeter_inset.[image]tools,white_threshold,min_area,resolution,trim(crop white margins so the drawing itself fills the canvas), and its placementx,y,scale: offset from the canvas centre and size relative to the fitted image (dragging it in the GUI sets these).[infill]densityorspacing,angle,connect(serpentine),overlap.[path]smoothing(px) andtolerance(mm): smoother curves vs detail.[edge]edge-mode detection and stroke settings.[gcode]start, tool-change and end blocks with{tool},{travel_speed}and{print_speed}placeholders.exclusionsinfill exclusion rectangles as image fractions.
- Run with
--debug-edges edges.png(or watch the GUI). If the edges are wrong, tune detection:clahe_clip,bilateral_d,scales, or pincanny_low/canny_high. - If the edges are right but the strokes look fragmented: raise
collapsetoward 1.0 to merge close parallel edges, raisechain_gapto join broken strokes, or lowermin_separationto let nearby strokes coexist. - Chunkier strokes:
collapse1.5. Maximum texture: add0toscales.
cargo test
cargo clippy --all-targets -- -D warnings
IMG2GCODE_LAYOUT_PROBE=1 cargo run -- gui some.png # GUI layout-shift checkThe layout probe steps the GUI through results arriving, canvas and tool changes and an error, then reports any control whose position changed.
MIT. The bundled Relief SingleLine font is under the SIL Open Font License
1.1 (fonts/ReliefSingleLine-OFL.txt).