rustitch 0.2.2

PES embroidery file parser and thumbnail renderer
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

# rustitch

[![crates.io](https://img.shields.io/crates/v/rustitch)](https://crates.io/crates/rustitch)
[![docs.rs](https://img.shields.io/docsrs/rustitch)](https://docs.rs/rustitch)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](../LICENSE)

A Rust library for parsing **embroidery files** and rendering stitch data to images.

Supported formats: **PES**, **DST**, **EXP**, **JEF**, **VP3**

Part of the [stitch-peek-rs](https://git.narl.io/nvrl/stitch-peek-rs) project.

## Usage

Add `rustitch` to your `Cargo.toml`:

```toml
[dependencies]
rustitch = "0.2"
```

### Generate a thumbnail

```rust
// PES files (backward-compatible API)
let pes_data = std::fs::read("design.pes")?;
let png_bytes = rustitch::thumbnail(&pes_data, 256)?;
std::fs::write("preview.png", &png_bytes)?;

// Any supported format
let dst_data = std::fs::read("pattern.dst")?;
let png_bytes = rustitch::thumbnail_format(&dst_data, 256, rustitch::Format::Dst)?;
std::fs::write("preview.png", &png_bytes)?;
```

### Parse and inspect a PES design

```rust
use rustitch::pes::{self, StitchCommand};

let data = std::fs::read("design.pes")?;
let design = pes::parse(&data)?;

println!("PES version: {}", std::str::from_utf8(&design.header.version).unwrap());
println!("Label: {}", design.pec_header.label);
println!("Colors: {}", design.pec_header.color_count);

let stitch_count = design.commands.iter()
    .filter(|c| matches!(c, StitchCommand::Stitch { .. }))
    .count();
println!("Stitches: {stitch_count}");
```

### Resolve and render manually

```rust
use rustitch::pes;

let data = std::fs::read("design.pes")?;
let design = pes::parse(&data)?;
let resolved = pes::resolve(&design)?;

println!("Segments: {}", resolved.segments.len());
println!("Bounding box: ({}, {}) to ({}, {})",
    resolved.bounds.min_x, resolved.bounds.min_y,
    resolved.bounds.max_x, resolved.bounds.max_y);

let png_bytes = rustitch::render_thumbnail(&resolved, 512)?;
std::fs::write("large_preview.png", &png_bytes)?;
```

### Format detection

```rust
use rustitch::format::{self, Format};
use std::path::Path;

// Detect from file extension
let fmt = format::detect_from_extension(Path::new("design.jef"));
assert_eq!(fmt, Some(Format::Jef));

// Detect from file content (magic bytes)
let data = std::fs::read("design.pes")?;
let fmt = format::detect_from_bytes(&data);
assert_eq!(fmt, Some(Format::Pes));
```

## Supported formats

| Format | Manufacturer | Colors | Notes |
|--------|-------------|--------|-------|
| **PES** | Brother PE-Design | Embedded (PEC palette) | Versions 1-10 |
| **DST** | Tajima | Default palette | 3-byte bit-packed records |
| **EXP** | Melco/Bernina | Default palette | Simple 2-byte encoding |
| **JEF** | Janome | Embedded (Janome palette) | Structured header with color table |
| **VP3** | Pfaff/Viking | Embedded (RGB) | Hierarchical format with per-section colors |

Formats without embedded color info (DST, EXP) use a default palette of 12 high-contrast colors, cycling on each color change.

## How it works

1. **Detect** the file format from magic bytes or extension
2. **Parse** the format-specific binary encoding into a common `StitchCommand` stream (stitch, jump, trim, color change, end)
3. **Resolve** relative movements into absolute coordinate segments grouped by thread color
4. **Render** anti-aliased line segments with [tiny-skia](https://github.com/nickel-org/tiny-skia), scaled to fit the requested size
5. **Encode** as PNG with proper alpha handling

## License

MIT