hatchsvg

Turn raster images into pen-plotted hatched SVGs. Optimized for Cricut, Axidraw, and any pen plotter that reads SVG.

What's new in 2.0.0

• Package renamed to hatchsvg (was png2svg). Matches the repo name. Install: pip install hatchsvg. Use: hatchsvg photo.jpg out.svg.
• All v1.2.0 features still ship: --preview, --split-layers, --optimize-travel, --hatch-angles, plus 5 inline examples in --help.
• Pure Python — no C compiler required. Works on every platform pip supports.

What it does

hatchsvg converts raster images (PNG, JPG, WebP, BMP, GIF, TIFF) into hatched SVG vector files. Each color in the image becomes a separate SVG layer, and each layer is filled with parallel hatch lines sized to match a physical marker set. The output is optimized for Cricut pen plotters and similar pen-plotting machines — it includes continuous serpentine paths, arc smoothing at row ends, and connected-component chaining to minimize pen lifts and ringing artifacts.

Quickstart

pip install hatchsvg
hatchsvg photo.jpg drawing.svg --preset portrait

That's it. Open drawing.svg in Inkscape, Cricut Design Space, or any vector editor. The output uses Inkscape-compatible layer names so each color is selectable individually.

No SVG file? Try it on the included sample:

hatchsvg examples/scene.png /tmp/scene.svg --preset fast

Why use hatchsvg?

Comparison with similar tools

hatchsvg is the right choice when you want stylized, low-pen-lift, marker-accurate output rather than a photo-faithful trace.

Presets

Presets are named combinations of parameters tuned for common use cases. Apply one with --preset NAME. You can still override any individual flag on top of the preset.

hatchsvg drawing.png out.svg --preset portrait
hatchsvg drawing.png out.svg --preset logo --max-palette 4  # override one flag

See hatchsvg --help for full preset descriptions.

Installation

pip install hatchsvg

Pure Python: hatchsvg has zero C extensions. No compiler needed, no potracer/pypotrace build failures. Works on Windows, macOS, Linux, ARM, anywhere Python 3.11+ runs.

Optional extras:

pip install hatchsvg[plot]      # progress bars (rich) + scipy for component chaining
pip install hatchsvg[palette]   # Streamlit app to build custom palettes from photos

Building a custom palette

If you have a set of physical markers (Crayola, Jot, Copic, Sharpie, whatever), you can take a photo and turn it into a hatchsvg palette JSON in ~30 seconds:

pip install hatchsvg[palette]
streamlit run scripts/palette_extractor.py

Upload a photo of your markers, edit the names, click Download palette JSON, and pass it to hatchsvg via --palette-file. You can also download a standalone HTML preview to keep alongside the JSON for visual reference:

# Generate the JSON via the Streamlit app, then:
python scripts/palette_preview.py my_palette.json
# Writes my_palette.html — open in any browser.

For development:

git clone https://github.com/Veedubin/hatchsvg
cd hatchsvg
python -m venv .venv
.venv/bin/pip install -e ".[dev,plot]"

CLI Reference

hatchsvg [OPTIONS] INPUT OUTPUT_SVG

Cookbook

Basic conversion

hatchsvg photo.jpg drawing.svg

Recommended for Cricut pen plotters

The two flags that matter most:

hatchsvg photo.jpg drawing.svg --continuous-paths --arc-radius 5

• --continuous-paths chains rows into a single zigzag, eliminating the thousands of micro-pen-lifts that cause "ringing" artifacts.
• --arc-radius 5 smooths the 180° U-turns with arc commands so the pen carriage doesn't slam to a stop.

Use a bundled marker palette

hatchsvg photo.jpg drawing.svg --palette-file color_palettes/crayola_10ct_fine_line_classic.json

Bundled palettes: crayola_10ct_fine_line_classic.json and jot_20ct_washable_fineline.json.

Reproducible output

# First run: save the exact config used
hatchsvg photo.jpg drawing.svg --preset portrait --save-session

# Later: replay the exact same config
hatchsvg photo.jpg drawing2.svg --use-session drawing.svg.session.json

Multi-format input

hatchsvg scan.webp out.svg        # WebP
hatchsvg photo.bmp out.svg        # BMP
hatchsvg photo.tiff out.svg       # TIFF
hatchsvg anim.gif out.svg         # GIF (uses first frame)

Show processing stats

hatchsvg photo.jpg out.svg --progress --stats

Outputs a Rich table with image dimensions, color count, layer count, pen-lift reduction percentage, and estimated plot time savings.

Project Structure

hatchsvg/
├── src/
│   └── hatchsvg/
│       ├── __init__.py        # __version__
│       ├── __main__.py        # python -m hatchsvg
│       ├── core.py            # Algorithm (hatching, color matching, SVG emission)
│       ├── cli.py             # CLI + friendly error handling
│       └── presets.py         # Named presets (portrait, logo, line-art, photo, sketch, fast)
├── tests/
│   ├── unit/                  # 51 unit tests (segments, color, palette, session, hatch, presets)
│   ├── integration/           # 9 integration tests (golden file + CLI subprocess)
│   ├── fixtures/              # Golden SVG for regression
│   └── conftest.py
├── examples/                  # Sample input/output pairs (4 presets × 1 image)
├── color_palettes/            # Bundled Crayola + Jot palettes
├── .github/workflows/ci.yml   # CI: ruff + pytest on Linux+macOS × 3.11/3.12/3.13
├── pyproject.toml             # Build + project config
├── LICENSE                    # MIT
├── CHANGELOG.md               # Version history
├── REVIEW.md                  # Audit + release plan
├── PLAN.md                    # v1.0.0 implementation plan
└── README.md                  # This file

Tech Stack

• Python 3.11+ (uses PEP 604 unions, tomllib, modern type hints)
• NumPy — image array processing and color quantization
• Pillow — image decoding (PNG, JPG, WebP, BMP, GIF, TIFF)
• dataclasses — RenderParams, LayerResult, StrokeStyle
• Rich (optional) — progress bars and statistics table
• scipy (optional) — connected component detection for pen-lift reduction

Development

# Run all tests with coverage
.venv/bin/pytest

# Lint
.venv/bin/ruff check src tests
.venv/bin/ruff format --check src tests

# Build a wheel for local testing
.venv/bin/python -m build

See PLAN.md for the v1.0.0 implementation plan and REVIEW.md for the comprehensive audit, feature roadmap, and 30-day release timeline.

Compatibility

• Python: 3.11, 3.12, 3.13 (CI matrix covers all three on Linux + macOS)
• Input formats: PNG, JPG, JPEG, WebP, BMP, GIF, TIFF, TIF
• Output: SVG 1.1 with Inkscape-compatible layer names
• Consumers: Inkscape, Cricut Design Space, Illustrator, browser preview

License

MIT — see LICENSE.

Credits

Algorithm extracted from the original hatchsvg.py script. Bundled marker palettes (Crayola, Jot) are trademarks of their respective owners and are included only as practical examples.