vfab

Headless-first FSM plotter manager with vpype optimization, smart multi-pen detection, and per-session recording (IP feed v1; native v4l2 later).

📚 Documentation

• Quickstart Guide - 🚀 Get your first plot running in 5 minutes!
• Cheat Sheets - ⭐ Quick reference for common tasks
• Installation Guide - Multi-platform setup instructions
• User Guide - Complete usage documentation
• vpype-vfab Integration Guide - Bridge creative tools with vfab production
• API Reference - Developer documentation and integration
• Troubleshooting - Common issues and solutions
• Changelog - Version history and release notes

Archived Documentation: Historical development status, reports, and old release notes are available in .github/docs-archive/ for reference.

🚀 Performance Highlights (v0.8.0)

• Enterprise-Grade Performance: 114,087 jobs/second database throughput
• Memory Efficient: Peak 7.4KB usage, no memory leaks detected
• Lightning Fast CLI: All commands respond in < 0.5 seconds
• Cross-Platform: Full Linux/macOS/Windows compatibility
• Load Tested: Handles 500+ concurrent jobs without issues

Quick Start

Prerequisites

# install uv (Arch)
pacman -Qi uv >/dev/null 2>&1 || curl -LsSf https://astral.sh/uv/install.sh | sh

# ensure Python 3.11+ available (uv can manage it too)
uv python install 3.12

Installation

For Planning & Simulation (no AxiDraw hardware):

# create venv + install project in editable mode
uv venv
source .venv/bin/activate
uv pip install -e ".[dev,vpype]"

# DB migrate + smoke test
uv run alembic upgrade head
uv run pytest -q

# try CLI
uv run vfab --help

For AxiDraw Hardware Support:

# install with AxiDraw integration
uv pip install -e ".[dev,vpype,axidraw]"

# DB migrate + smoke test  
uv run alembic upgrade head
uv run pytest -q

# try CLI
uv run vfab --help

Note: vfab works perfectly without AxiDraw hardware for planning, optimization, and simulation. Install axidraw extra only if you have physical hardware.

AxiDraw Integration

vfab provides smart AxiDraw integration with automatic multipen detection and graceful degradation.

Installation

# Install with AxiDraw support
uv pip install -e ".[dev,vpype,axidraw]"

Important: vfab works without AxiDraw hardware for planning and simulation. The axidraw extra is only needed for physical plotting.

AxiDraw CLI Commands

# Plan a job with smart multipen detection
uv run vfab plan <job_id> --interactive

# Plot a job with AxiDraw (supports multipen)
uv run vfab plot <job_id>

# Preview plot without moving pen
uv run vfab plot <job_id> --preview

# Interactive XY control
uv run vfab interactive

# Test pen up/down movement
uv run vfab check servo

# List available pens from database
uv run vfab list pens

# Add new pen to database
uv run vfab setup

Smart Multipen Detection

vfab automatically detects layers in your SVG files and provides:

• 🎨 Color-coded layer overview with element counts
• 🚫 Hidden layer filtering (skips Inkscape hidden layers and % documentation layers)
• 🖊️ Interactive pen mapping for multi-layer designs
• ⚡ Automatic mode selection (single-pen vs multi-pen)

vpype Optimization Presets

vfab includes vpype presets for different optimization levels with dynamic paper sizing:

# config/vpype-presets.yaml
presets:
  fast:
    pipe: "read {src} pagesize {pagesize} crop 0 0 {width_mm:g}mm {height_mm:g}mm linemerge linesort write {dst}"
  
  hq:
    pipe: "read {src} pagesize {pagesize} crop 0 0 {width_mm:g}mm {height_mm:g}mm linemerge linesort linesimplify write {dst}"

Available presets:

• fast: Quick optimization (linemerge + linesort) - default
• hq: High quality (adds linesimplify for segment reduction)

Dynamic paper sizing: Presets automatically use the paper size from your config:

# config/config.yaml
vpype:
  preset: fast                    # or hq
  presets_file: "config/vpype-presets.yaml"

paper:
  default_size: A4               # A3, A4, Letter, etc.
  default_margin_mm: 10.0
  default_orientation: portrait

The {pagesize}, {width_mm}, and {height_mm} placeholders are automatically replaced with your configured paper size, so you don't need separate presets for different paper sizes!

AxiDraw Configuration

Add AxiDraw device configuration to your config:

device:
  port: /dev/ttyUSB0          # or COM3 on Windows, auto-detect if None
  model: 1                   # 1=V2/V3/SE/A4, 2=V3/A3/SE/A3, etc.
  pen_pos_up: 60              # 0-100, higher = more up
  pen_pos_down: 40            # 0-100, lower = more down
  speed_pendown: 25           # 1-100, percentage of max speed
  speed_penup: 75             # 1-100, percentage of max speed
  units: inches               # mm, cm, or inches

Error Handling

If AxiDraw support is not installed, vfab provides clear guidance:

❌ AxiDraw support not available. Install with: uv pip install -e '.[axidraw]'

All non-AxiDraw features (planning, optimization, simulation) work without the axidraw extra.

AxiDraw CLI Commands

# Check system readiness including AxiDraw
uv run vfab check ready

# Check servo operation (pen up/down)
uv run vfab check servo

# Plot a job with AxiDraw (with time estimation)
uv run vfab plot <job_id>

# Preview plot without moving pen
uv run vfab plot <job_id> --dry-run

# Interactive XY control
uv run vfab interactive

# Check device timing
uv run vfab check timing

AxiDraw Configuration

Add AxiDraw device configuration to your config:

device:
  port: /dev/ttyUSB0          # or COM3 on Windows
  model: 1                   # 1=V2/V3/SE/A4, 2=V3/A3/SE/A3, etc.
  pen_pos_up: 60              # 0-100, higher = more up
  pen_pos_down: 40            # 0-100, lower = more down
  speed_pendown: 25           # 1-100, percentage of max speed
  speed_penup: 75             # 1-100, percentage of max speed
  units: inches               # mm, cm, or inches

Common Development Tasks

# lint / format
uvx ruff check .
uvx black .

# pre-commit (once)
uvx pre-commit install
uvx pre-commit run -a

# run tools without activating venv
uv run plotty add --src demo.svg --paper A3 | tee /tmp/J
uv run plotty plan "$(cat /tmp/J)" --interactive
uv run plotty record_test "$(cat /tmp/J)" --seconds 5

# test AxiDraw integration (if hardware available)
uv run plotty check servo --cycles 1
uv run plotty interactive --help

Feature Highlights

• 🧠 Smart Multipen Detection: Automatically detects SVG layers and suggests pen mapping
• 🎨 Color-Coded Overview: Visual layer display with element counts and colors
• 🚫 Hidden Layer Filtering: Skips Inkscape hidden layers per AxiDraw standards
• ⚡ Graceful Degradation: Works perfectly without AxiDraw hardware
• 📊 Time Estimation: Accurate plotting time estimates with vpype optimization
• 🎥 Session Recording: IP camera integration for plot documentation
• 🖊️ Pen Database: Manage multiple pens with width and speed settings

CI/CD Debug