EasyStitch - SVG to Embroidery Converter

EasyStitch is a Python application that converts SVG files into embroidery machine files. Support various embroidery formats like DST, PES, EXP, and JEF for use with embroidery machines.

Features

• Convert multiple formats - SVG files and raster images (PNG, JPG, etc.) to embroidery formats (DST, PES, EXP, JEF)
• Ultra-fine detail - Default 0.4mm stitch spacing for high quality output
• Intelligent semantic analysis - Automatic stitch type classification (running, fill, satin) with human override capability
• Advanced path optimization - Minimize travel distance and thread changes with multiple algorithms
• Professional color matching - Delta E-based color matching with thread library support
• Advanced fill algorithms - Tatami patterns with offset algorithms to prevent stitch junction alignment
• Complete visualization & analysis - Generate previews and detailed stitch analysis reports
• Machine-specific optimization - Support for Brother, Tajima, Melco, Janome and other machine profiles
• Configurable stitch parameters - Fine-tune density, spacing, and other settings per element type
• Command-line interface - Comprehensive CLI with dozens of options for advanced control
• Automatic raster vectorization - Convert bitmap images to vector paths for embroidery
• Quality validation - Automatic checking for common embroidery issues and thread conflicts

Quick Start

Basic Usage

# Convert SVG to DST (most common format)
python src/main.py input.svg

# Convert to specific format with output file
python src/main.py input.svg -f pes -o output/my_design.pes

# Convert raster image (automatic vectorization)
python src/main.py logo.png -f dst -o logo.dst

Enhanced Options

# Generate with analysis and visualization
python src/main.py design.svg --visualize --analyze

# Optimize path for minimal travel and thread changes
python src/main.py design.svg --optimize-path --analyze

# Fine-detail conversion (0.4mm spacing for high quality)
python src/main.py detailed_design.svg --fill-density 0.4 --satin-stitch-spacing 0.4

First time setup

# Clone the repository
git clone <repository-url>
cd easystitch

# Create a local virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the pinned project dependencies
pip install -r requirements.txt

# Install EasyStitch in editable mode so the `src` package is importable
pip install -e .

Verify the environment:

python -c "from src.main_pipeline import EmbroideryPipeline"

For a fully reproducible environment, install from the transitive lock file instead:

pip install -r requirements.lock
pip install -e .

Usage

Basic Conversion

# Basic conversion to DST format (default)
python src/main.py input.svg

# Specify output format
python src/main.py input.svg -f pes -o output.pes

# Convert raster image to embroidery format
python src/main.py input.png -f dst -o output.dst

Advanced Usage with New Features

Fine Detail Options (0.4mm defaults)

The system now uses 0.4mm default spacing for superior quality:

# Use default 0.4mm spacing (recommended for most applications)
python src/main.py input.svg --fill-density 0.4 --running-stitch-spacing 0.4

# Customize stitch density for specific quality
python src/main.py input.svg --fill-density 0.3 --satin-stitch-spacing 0.4 --running-stitch-spacing 0.4

Semantic Analysis & Visualization

# Generate visualization of embroidery pattern
python src/main.py input.svg --visualize

# Generate analysis report
python src/main.py input.svg --analyze

# Generate both visualization and analysis
python src/main.py input.svg --visualize --analyze

Path Optimization

# Enable path optimization to minimize travel distance between elements
python src/main.py input.svg --optimize-path

# Use specific optimization method
python src/main.py input.svg --optimize-path --path-optimization-method nearest_neighbor

Fill Pattern Customization

# Use advanced fill algorithms with offset patterns
python src/main.py input.svg --fill-type advanced_tatami

# Set fill angle and density
python src/main.py input.svg --fill-angle 45 --fill-density 0.4

Custom Thread Management

# Process with thread analysis and optimization
python src/main.py input.svg --analyze

# Use thread configuration file (when available)
python src/main.py input.svg --threads config/threads.json

Complete Example with All Features

# Full featured conversion with optimization and analysis
python src/main.py design.svg \
  -f pes \
  -o output/design.pes \
  --fill-density 0.4 \
  --fill-type advanced_tatami \
  --fill-angle 45 \
  --optimize-path \
  --path-optimization-method color_grouped \
  --visualize \
  --analyze

By default EasyStitch writes generated embroidery files next to the input SVG. Set the EASYSTITCH_OUTPUT_DIR environment variable to direct all generated files (including analysis PNGs) into a dedicated folder:

export EASYSTITCH_OUTPUT_DIR=outputs
python src/main.py input.svg          # writes to outputs/input.dst

CLI migration notes (issue #124)

The CLI now matches the documented surface end-to-end:

• python src/main.py input.svg works as the README quick-start shows. All three invocation forms (python src/main.py …, python -m src.main …, easystitch …) are equivalent.
• All four formats (DST, PES, EXP, JEF) are produced via the real EmbroideryPipeline.process(...). The old "Format pes not yet implemented" stub branch is gone.
• Raster inputs (PNG/JPG/BMP/GIF/TIFF/WebP) are accepted and routed through auto-vectorization. The old "Input file must be an SVG file" error is gone.
• EASYSTITCH_OUTPUT_DIR is now honoured as documented.
• The following flags are accepted for backward compatibility but currently no-op with a one-line stderr warning (issue #124 follow-up work will land real engine support): --optimize-path, --path-optimization-method, --fill-type, --fill-angle, --threads.

Supported Input Formats

• SVG (Scalable Vector Graphics) - vector input
• PNG, JPG, BMP, GIF, TIFF, WebP - raster input (automatically vectorized)

Supported Output Formats

• DST (Tajima) - Most widely supported format
• PES (Brother) - For Brother and compatible machines
• EXP (Melco) - For commercial embroidery machines
• JEF (Janome) - For Janome machines

Project Structure

easystitch/
├── src/                    # Source code
│   ├── main.py            # CLI entry point (issue #124)
│   ├── main_pipeline.py   # 5-stage pipeline orchestrator (EmbroideryPipeline)
│   ├── config.py          # Configuration models
│   ├── svg_parser/        # SVG parsing module
│   ├── embroidery_converter/ # Conversion logic
│   ├── output_generators/ # Embroidery format generators
│   └── utils/             # Utility functions
├── tests/                 # Test files
├── config/                # Configuration files
├── docs/                  # Documentation
├── data/                  # Sample data
├── requirements.txt       # Python dependencies
└── README.md             # This file

Development

To contribute to EasyStitch:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests if applicable
5. Run tests (pytest)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Supported Formats

• DST - Tajima embroidery format
• PES - Brother embroidery format
• EXP - Melco embroidery format
• JEF - Janome embroidery format

Roadmap

✅ COMPLETED PHASES

• SVG parsing with support for paths, shapes, and text
• Raster image vectorization and preprocessing
• Path optimization and reduction algorithms
• Multiple embroidery format support (DST, PES, EXP, JEF)
• Thread color mapping and Delta E matching
• Satin stitch detection and generation
• Advanced fill stitch algorithms (tatami with offset patterns)
• Semantic annotation and automatic classification
• Machine-specific optimization and constraints
• Ultra-fine detail support (0.4mm defaults)
• Complete visualization and analysis system
• Path optimization to minimize travel distance

🔄 CURRENT PHASE

• GUI interface for visual editing and preview

📋 FUTURE ENHANCEMENTS

• Advanced underlay stitch generation
• Pull compensation for satin stitches
• 3D/padding stitch support
• Advanced path planning with multiple hoop positions
• Real-time preview capabilities

License

This project is licensed under the MIT License - see the LICENSE file for details.