# stitch-peek-rs

[![CI](https://git.narl.io/nvrl/stitch-peek-rs/actions/workflows/ci.yml/badge.svg)](https://git.narl.io/nvrl/stitch-peek-rs/actions?workflow=ci.yml)
[![rustitch on crates.io](https://img.shields.io/crates/v/rustitch)](https://crates.io/crates/rustitch)
[![stitch-peek on crates.io](https://img.shields.io/crates/v/stitch-peek)](https://crates.io/crates/stitch-peek)
[![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 Nautilus/GNOME thumbnailer for **embroidery files**. Browse your embroidery designs in the file manager with automatic thumbnail previews.

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

Built as two crates:

| Crate | Description |
|-------|-------------|
| [**rustitch**](rustitch/) | Library for parsing embroidery files and rendering stitch data to images |
| [**stitch-peek**](stitch-peek/) | CLI thumbnailer that integrates with GNOME/Nautilus |

<!-- TODO: Add screenshot of Nautilus showing PES thumbnails -->

## Installation

### From .deb (Debian/Ubuntu)

Download the latest `.deb` from the [Releases](https://git.narl.io/nvrl/stitch-peek-rs/releases) page:

```sh
sudo dpkg -i stitch-peek_*_amd64.deb
```

This installs the binary, thumbnailer entry, and MIME type definition. Restart Nautilus to pick up the changes:

```sh
nautilus -q
```

### From crates.io

```sh
cargo install stitch-peek
```

Then install the data files:

```sh
sudo install -Dm644 data/stitch-peek.thumbnailer /usr/share/thumbnailers/stitch-peek.thumbnailer
sudo install -Dm644 data/pes.xml /usr/share/mime/packages/pes.xml
sudo update-mime-database /usr/share/mime
nautilus -q
```

### From source

Requires Rust 1.85+.

```sh
git clone https://git.narl.io/nvrl/stitch-peek-rs.git
cd stitch-peek-rs
cargo build --release

sudo install -Dm755 target/release/stitch-peek /usr/local/bin/stitch-peek
sudo install -Dm644 data/stitch-peek.thumbnailer /usr/share/thumbnailers/stitch-peek.thumbnailer
sudo install -Dm644 data/pes.xml /usr/share/mime/packages/pes.xml
sudo update-mime-database /usr/share/mime
nautilus -q
```

## Usage

### As a thumbnailer

Once installed, Nautilus will automatically generate thumbnails for embroidery files. No manual action needed -- just open a folder containing `.pes`, `.dst`, `.exp`, `.jef`, or `.vp3` files.

### Standalone CLI

Generate a thumbnail manually:

```sh
stitch-peek -i design.pes -o preview.png -s 256
stitch-peek -i pattern.dst -o preview.png -s 256
```

| Flag | Description | Default |
|------|-------------|---------|
| `-i` | Input embroidery file | required |
| `-o` | Output PNG path | required |
| `-s` | Thumbnail size (pixels) | 128 |

### As a library

Add `rustitch` to your project:

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

```rust
// PES (auto-detected)
let pes_data = std::fs::read("design.pes")?;
let png_bytes = rustitch::thumbnail(&pes_data, 256)?;

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

See the [rustitch README](rustitch/README.md) for more API examples.

## 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 |

## Project structure

```
stitch-peek-rs/
├── rustitch/              # Library crate
│   └── src/
│       ├── lib.rs         # Public API
│       ├── types.rs       # Shared types (StitchCommand, ResolvedDesign, ...)
│       ├── error.rs       # Error types
│       ├── format.rs      # Format detection (magic bytes, extension)
│       ├── palette.rs     # Thread color palettes (PEC, default)
│       ├── resolve.rs     # Stitch command to segment resolver
│       ├── render.rs      # tiny-skia renderer
│       ├── pes/           # PES (Brother) parser
│       ├── dst/           # DST (Tajima) parser
│       ├── exp.rs         # EXP (Melco) parser
│       ├── jef/           # JEF (Janome) parser
│       └── vp3.rs         # VP3 (Pfaff/Viking) parser
├── stitch-peek/           # Binary crate (CLI thumbnailer)
│   └── src/main.rs
└── data/
    ├── stitch-peek.thumbnailer  # Nautilus integration
    └── pes.xml                  # MIME type definitions
```

## Development

```sh
cargo test          # run all tests
cargo clippy        # lint
cargo fmt --check   # check formatting
```

Pull requests must bump the version in `stitch-peek/Cargo.toml` -- CI will reject merges without a version bump.

## Contributing

1. Fork the repo
2. Create a feature branch (`git checkout -b feature/my-change`)
3. Make your changes and add tests where appropriate
4. Ensure `cargo test && cargo clippy && cargo fmt --check` pass
5. Bump the version in `stitch-peek/Cargo.toml`
6. Open a pull request

## License

[MIT](LICENSE)