stitch-peek

A Nautilus/GNOME thumbnailer for PES embroidery files. Browse your embroidery designs in the file manager with automatic thumbnail previews.

Built as two crates:

• rustitch -- library for parsing PES files and rendering stitch data to images
• stitch-peek -- CLI thumbnailer that integrates with GNOME/Nautilus via the freedesktop thumbnail spec

Installation

From .deb (Debian/Ubuntu)

Download the latest .deb from the Releases page:

sudo dpkg -i stitch-peek_*_amd64.deb

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

nautilus -q

From source

Requires Rust 1.70+.

git clone https://github.com/YOUR_USER/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 .pes files. No manual action needed -- just open a folder containing PES files.

Standalone CLI

Generate a thumbnail manually:

stitch-peek -i design.pes -o preview.png -s 256

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

As a library

Add rustitch to your project:

[dependencies]
rustitch = { git = "https://github.com/YOUR_USER/stitch-peek-rs.git" }

let pes_data = std::fs::read("design.pes")?;
let png_bytes = rustitch::thumbnail(&pes_data, 256)?;
std::fs::write("preview.png", &png_bytes)?;

How it works

1. Parse the PES binary format -- extract the PEC section containing stitch commands and thread color indices
2. Decode the stitch byte stream into movement commands (stitches, jumps, trims, color changes)
3. Resolve relative movements into absolute coordinates grouped by thread color
4. Render anti-aliased line segments onto a transparent canvas using tiny-skia, scaled to fit the requested thumbnail size
5. Encode the result as a PNG image

Supported formats

Currently supports PES (Brother PE-Design) embroidery files, versions 1 through 6. The PEC section -- which contains the actual stitch data -- is consistent across versions.

Project structure

stitch-peek-rs/
├── rustitch/              # Library crate
│   └── src/
│       ├── lib.rs         # Public API
│       ├── pes/           # PES format parser
│       │   ├── header.rs  # File header (#PES magic, version, PEC offset)
│       │   ├── pec.rs     # PEC section (colors, stitch decoding)
│       │   └── palette.rs # Brother 65-color thread palette
│       └── render.rs      # tiny-skia renderer
├── stitch-peek/           # Binary crate (CLI thumbnailer)
│   └── src/main.rs
└── data/
    ├── stitch-peek.thumbnailer  # Nautilus integration
    └── pes.xml                  # MIME type definition

Development

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

This project is licensed under the MIT License. See LICENSE for details.