Masksmith

Masksmith is a fast desktop mask-painting tool for image segmentation datasets.

It is built for the boring part of computer vision work: opening a folder of images, painting binary masks quickly, fixing rough edges, and moving on without fighting a heavyweight annotation suite.

Why this project exists

• Lightweight local workflow: point it at a folder and start painting.
• Binary-mask first: no hidden alpha semantics, no surprise grayscale exports.
• Fast iteration loop: brush, erase, rotated rectangles, undo/redo, autosave.
• No web backend, no accounts, no labeling platform overhead.

Demo

Features

• Freehand brush and eraser
• Adjustable brush size with live cursor preview
• Filled and rotated rectangle tools
• Zoom, pan, cursor-centered wheel zoom
• Autosave or manual-save workflows
• Undo/redo stack for mask edits
• Loads existing masks and normalizes non-binary masks
• Saves masks with source filenames into a dedicated folder

Install with uv

Run locally

uv sync
uv run masksmith path/to/images --masks-dir path/to/masks

If you omit path/to/images, Masksmith opens folder-pickers.

Install as a tool

uv tool install .
masksmith path/to/images

Development

uv run pytest -q
uv run python scripts/generate_demo_assets.py

Controls

Key	Action
e	Toggle eraser
t	Toggle rectangle mode
o / p	Rotate rectangle preview
+ / -	Increase / decrease brush size
z / x	Zoom in / out
Ctrl + wheel	Zoom around cursor
Wheel	Vertical scroll when zoomed
Right drag	Pan
c	Stamp a filled circle at cursor
s	Save mask when autosave is off
a	Toggle autosave
q / w	Next / previous image
Ctrl+Z / Ctrl+Y	Undo / redo
Esc	Exit confirmation

Project layout

src/masksmith/        package and CLI
scripts/              asset generation helpers
docs/assets/          README and landing-page media
images/               sample input image
masks/                sample mask

Open source

MIT licensed. If you publish results, star the repo and use the landing assets in social previews.