Skip to content
Maksim-NikolaevPublic

About

Convert images to mouse-driven contour drawings

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

Inkspire

Inkspire traces line art by moving the mouse along contours extracted from images, SVGs, or text. It drives drawing applications that accept synthetic pointer input, using native ctypes calls for low-latency mouse control on Linux (X11), Windows, and macOS.

Inkspire tracing a corgi into KolourPaint

Image mode Text / SVG mode
Image mode with a traced corgi in the live preview Text mode rendering a line of text from a system font

Examples

Source Result
corgi source corgi drawing
github source github drawing

Features

  • Multiple detection modes – threshold, Canny edge, adaptive threshold, and auto-detect for black & white line art, colored images, and halftones.
  • Text and SVG input – render text from system fonts or load SVG paths directly, with independent settings.
  • Cross-platform – Linux (X11 and Wayland via Xwayland), Windows, and macOS, with native mouse and keyboard control via ctypes (XTest, SendInput, Quartz CGEvent).
  • Live preview – a docked preview redraws the contours as you tune parameters, and pops out into its own window when you need more room.
  • Canvas picker – drag-select your target drawing area on screen.
  • Pause/resume – F5 toggles start, pause, and resume. Escape cancels.
  • Path optimization – optional nearest-neighbor reordering to minimize pen-up travel between contours.
  • Session persistence – settings, source file, and tab state are restored automatically on next launch.
  • Customizable keybinds – reassign the start/pause and cancel keys from the Keybinds dialog.
  • Light and dark theme – follows the system setting on all three platforms.

Install

Linux (x86_64) and macOS:

curl -fsSL https://raw.githubusercontent.com/Maksim-Nikolaev/inkspire/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/Maksim-Nikolaev/inkspire/main/install.ps1 | iex

The scripts install the latest release for the current user without admin rights, and running them again updates Inkspire:

  • Linux: ~/.local/bin/inkspire, plus an app menu entry and icon.
  • macOS: /Applications/Inkspire.app, or ~/Applications when /Applications is not writable. An app installed this way carries no quarantine flag, so the Gatekeeper step below does not apply.
  • Windows: %LOCALAPPDATA%\Programs\Inkspire\inkspire.exe, plus a Start menu shortcut.

To uninstall, run curl -fsSL https://raw.githubusercontent.com/Maksim-Nikolaev/inkspire/main/install.sh | sh -s -- --uninstall, or on Windows & ([scriptblock]::Create((irm https://raw.githubusercontent.com/Maksim-Nikolaev/inkspire/main/install.ps1))) -Uninstall. Settings in ~/.config/inkspire are kept. Set INKSPIRE_VERSION=v0.6.0 (PowerShell: $env:INKSPIRE_VERSION = "v0.6.0") to install a specific release.

Manual download

Download the build for your platform from Releases:

Platform File
Linux (x86_64, glibc 2.35+) inkspire.tar.gz – extract and run ./inkspire
Windows (x86_64) inkspire.exe
macOS (Apple Silicon, macOS 13+) inkspire-macos-arm64.dmg
macOS (Intel, macOS 14+) inkspire-macos-x86_64.dmg

macOS first launch

The macOS builds are not notarized yet, so Gatekeeper stops the first launch of a DMG downloaded in the browser:

  1. Open the DMG and drag Inkspire to Applications.
  2. Open Inkspire. When macOS says it cannot verify the developer, go to System Settings → Privacy & Security and click Open Anyway (on older macOS versions, right-click the app and choose Open). Alternatively run xattr -dr com.apple.quarantine /Applications/Inkspire.app.
  3. On first launch Inkspire explains and requests Accessibility access, which macOS requires before an app may move the pointer and click. Click Open System Settings, switch Inkspire on under Privacy & Security → Accessibility, and return to Inkspire. The prompt closes by itself once access is granted.
  4. Builds without a Developer ID signature get a new code signature with every update, so macOS may forget the permission after updating. The install script resets the old entry when it updates Inkspire, so the prompt appears again. Otherwise, if drawing does nothing, remove Inkspire from the Accessibility list with − and add it again.

Mac keyboards send media keys from the top row unless you hold fn, so press fn+F5 to start, or pick another key under Keybinds. The global start and cancel keys are read with CGEventSourceKeyState; whether that needs extra permission while another app has focus is untested, so use the on-screen buttons if the keys do not react.

Run from source

  • Python 3.10+
  • Linux: X11 or Wayland session, system packages:
    sudo apt install python3-tk python3-venv libx11-6 libxtst6 xclip
  • Windows and macOS: Python from python.org (it includes Tk).
  • Python packages, in a virtual environment (Debian and Ubuntu refuse a system-wide pip install):
    python3 -m venv .venv
    .venv/bin/pip install .
.venv/bin/python main.py

On Windows the venv commands are .venv\Scripts\pip and .venv\Scripts\python.

  1. Open an image (Open… or Ctrl+V), or switch to Text / SVG to type text or open an SVG.
  2. Adjust the detection settings. The preview updates as you go; turn off Live to update it only on Refresh.
  3. Choose where to draw: At pointer starts with the mouse pointer as the bottom-left corner, Pick area on screen… drag-selects a fixed area and fits the drawing into it.
  4. Press F5 (or click Start drawing) and switch to your drawing app during the countdown. F5 pauses and resumes, Escape cancels.

On Linux, Open… uses the desktop's own file picker (kdialog on KDE, zenity elsewhere) when one is installed.

Wayland notes

Inkspire runs under Wayland through Xwayland and injects input via the XTest extension. Requirements and caveats:

  • Xwayland 23.2+ with libei and a compositor that bridges XTest to Wayland (KDE Plasma 6.1+, GNOME 46+). Older Xwayland cannot reach native Wayland apps.
  • Grant remote input on first draw. The first drawing action triggers a "remote control / remote desktop" permission prompt from the desktop portal. Approve it (and choose remember) or nothing will move: the injected pointer and clicks are silently dropped until the remote-desktop portal permission is granted.
  • Global F5/Escape while another app is focused rely on reading the keyboard across apps. On KDE, enable System Settings → Apps & Windows → Legacy X11 App Support → allow legacy apps to read all keystrokes. Otherwise use the on-screen Start/Pause button, or keep Inkspire focused.
  • At pointer reads the pointer position through Xwayland, which only knows it while the pointer is over an X11 window. Use Pick area on screen… when drawing into a native Wayland app.
  • Canvas picker cannot capture a screenshot on Wayland, so its overlay shows a translucent tint instead of a live screen preview. Drag-to-select still returns the correct screen coordinates.

Building

./build.sh builds with PyInstaller on the machine it runs on, starts the result with --self-test, and writes the release file to builds/ under the name the install scripts download:

Platform Command Output
Linux ./build.sh --docker builds/inkspire.tar.gz
Windows ./build.sh in Git Bash builds/inkspire.exe
macOS (Apple Silicon) ./build.sh builds/inkspire-macos-arm64.dmg
macOS (Intel) ./build.sh builds/inkspire-macos-x86_64.dmg

PyInstaller does not cross-compile, so each file has to be built on its own platform. On Linux, --docker builds inside Ubuntu 22.04 so the binary also runs on distributions with glibc 2.35; a plain ./build.sh links against the build machine's glibc and may not start on older systems. Windows and macOS builds need Python 3.13, because the python.org 3.14 installers ship Tk 9, which CustomTkinter is not tested against. On Windows py -3.13 is the default; elsewhere set PYTHON=python3.13 if python3 is a different version. macOS builds are ad-hoc signed unless INKSPIRE_CODESIGN_IDENTITY names a Developer ID.

Releasing

Releases are built locally and uploaded by hand. Push main first, since the install scripts are served from it:

git push origin main
git tag v0.6.0 && git push origin v0.6.0
gh release create v0.6.0 --draft --verify-tag --title v0.6.0 --generate-notes builds/inkspire.tar.gz
gh release upload v0.6.0 builds/inkspire.exe              # on the Windows machine
gh release upload v0.6.0 builds/inkspire-macos-arm64.dmg  # on each Mac
gh release edit v0.6.0 --draft=false

Files can also be dragged into the draft on the release page. The install scripts download from the latest published release, so they keep serving the previous version until the draft is published. Keep the four file names unchanged, or the scripts stop finding them.

The build workflow runs only when started from Actions → Build → Run workflow. It builds all four files, starts each with --self-test, and keeps them as run artifacts. macOS Developer ID signing and notarization switch on there once these repository secrets exist: MACOS_CERTIFICATE (base64 .p12), MACOS_CERTIFICATE_PASSWORD, MACOS_CODESIGN_IDENTITY, NOTARY_KEY (base64 App Store Connect .p8), NOTARY_KEY_ID, and NOTARY_ISSUER_ID.

License

Released under the MIT License.

About

Convert images to mouse-driven contour drawings

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages