From ad8738e6ddc39f7693d3dddbfa24d970a8e55bba Mon Sep 17 00:00:00 2001 From: Nils Pukropp Date: Mon, 30 Mar 2026 00:58:48 +0200 Subject: [PATCH] added publishing metadata and seperated project readmes --- README.md | 47 +++++++++++++++++---------- rustitch/Cargo.toml | 7 ++++ rustitch/README.md | 74 ++++++++++++++++++++++++++++++++++++++++++ stitch-peek/Cargo.toml | 9 ++++- stitch-peek/README.md | 69 +++++++++++++++++++++++++++++++++++++++ 5 files changed, 187 insertions(+), 19 deletions(-) create mode 100644 rustitch/README.md create mode 100644 stitch-peek/README.md diff --git a/README.md b/README.md index a3c4787..0cee194 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,13 @@ -# stitch-peek +# stitch-peek-rs 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 +| Crate | Description | +|-------|-------------| +| [**rustitch**](rustitch/) | Library for parsing PES files and rendering stitch data to images | +| [**stitch-peek**](stitch-peek/) | CLI thumbnailer that integrates with GNOME/Nautilus | @@ -13,7 +15,7 @@ Built as two crates: ### From .deb (Debian/Ubuntu) -Download the latest `.deb` from the [Releases](../../releases) page: +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 @@ -25,12 +27,27 @@ This installs the binary, thumbnailer entry, and MIME type definition. Restart N nautilus -q ``` -### From source - -Requires Rust 1.70+. +### From crates.io ```sh -git clone https://github.com/YOUR_USER/stitch-peek-rs.git +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 @@ -67,7 +84,7 @@ Add `rustitch` to your project: ```toml [dependencies] -rustitch = { git = "https://github.com/YOUR_USER/stitch-peek-rs.git" } +rustitch = "0.1" ``` ```rust @@ -76,17 +93,11 @@ 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](https://github.com/nickel-org/tiny-skia), scaled to fit the requested thumbnail size -5. **Encode** the result as a PNG image +See the [rustitch README](rustitch/README.md) for more API examples. ## 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. +**PES** (Brother PE-Design) embroidery files, versions 1 through 10. The PEC section containing stitch data is consistent across versions. ## Project structure @@ -128,4 +139,4 @@ Pull requests must bump the version in `stitch-peek/Cargo.toml` -- CI will rejec ## License -This project is licensed under the MIT License. See [LICENSE](LICENSE) for details. +[MIT](LICENSE) diff --git a/rustitch/Cargo.toml b/rustitch/Cargo.toml index af4d1d0..c4d3c0e 100644 --- a/rustitch/Cargo.toml +++ b/rustitch/Cargo.toml @@ -2,6 +2,13 @@ name = "rustitch" version = "0.1.1" edition = "2024" +description = "PES embroidery file parser and thumbnail renderer" +license = "MIT" +repository = "https://git.narl.io/nvrl/stitch-peek-rs" +authors = ["Nils Pukropp "] +keywords = ["embroidery", "pes", "thumbnail", "stitch"] +categories = ["graphics", "parser-implementations"] +readme = "README.md" [dependencies] thiserror = "2" diff --git a/rustitch/README.md b/rustitch/README.md new file mode 100644 index 0000000..affe157 --- /dev/null +++ b/rustitch/README.md @@ -0,0 +1,74 @@ +# rustitch + +A Rust library for parsing **PES embroidery files** and rendering stitch data to images. + +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.1" +``` + +### Generate a thumbnail + +```rust +let pes_data = std::fs::read("design.pes")?; +let png_bytes = rustitch::thumbnail(&pes_data, 256)?; +std::fs::write("preview.png", &png_bytes)?; +``` + +### Parse and inspect a 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)?; +``` + +## Supported formats + +**PES** (Brother PE-Design) embroidery files, versions 1 through 10. The PEC section containing stitch data is consistent across versions. + +## How it works + +1. **Parse** the PES binary header to locate the PEC section +2. **Decode** the PEC stitch byte stream (7-bit and 12-bit encoded relative movements, jumps, trims, color changes) +3. **Resolve** relative movements into absolute coordinate segments grouped by thread color, using the 65-color Brother PEC palette +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 diff --git a/stitch-peek/Cargo.toml b/stitch-peek/Cargo.toml index 8885085..2673c2a 100644 --- a/stitch-peek/Cargo.toml +++ b/stitch-peek/Cargo.toml @@ -2,8 +2,15 @@ name = "stitch-peek" version = "0.1.1" edition = "2024" +description = "Nautilus thumbnail generator for PES embroidery files" +license = "MIT" +repository = "https://git.narl.io/nvrl/stitch-peek-rs" +authors = ["Nils Pukropp "] +keywords = ["embroidery", "pes", "thumbnailer", "nautilus"] +categories = ["graphics", "command-line-utilities"] +readme = "README.md" [dependencies] -rustitch = { path = "../rustitch" } +rustitch = { version = "0.1.1", path = "../rustitch" } clap = { version = "4", features = ["derive"] } anyhow = "1" diff --git a/stitch-peek/README.md b/stitch-peek/README.md new file mode 100644 index 0000000..a2961ca --- /dev/null +++ b/stitch-peek/README.md @@ -0,0 +1,69 @@ +# stitch-peek + +A CLI tool and **Nautilus/GNOME thumbnailer** for PES embroidery files. Generates PNG previews of embroidery designs directly in your file manager. + +Part of the [stitch-peek-rs](https://git.narl.io/nvrl/stitch-peek-rs) project. Uses [rustitch](https://crates.io/crates/rustitch) for PES parsing and rendering. + +## 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 +``` + +### From crates.io + +```sh +cargo install stitch-peek +``` + +Then install the thumbnailer and MIME type files manually: + +```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 +``` + +### From source + +```sh +git clone https://git.narl.io/nvrl/stitch-peek-rs.git +cd stitch-peek-rs +cargo install --path stitch-peek +``` + +After installing, restart Nautilus to pick up the thumbnailer: + +```sh +nautilus -q +``` + +## Usage + +### As a thumbnailer + +Once installed with the `.thumbnailer` file in place, Nautilus automatically generates thumbnails for `.pes` files. No manual action needed. + +### Standalone CLI + +```sh +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 | + +## How it works + +The tool follows the [freedesktop thumbnail specification](https://specifications.freedesktop.org/thumbnail/latest/). Nautilus calls it with an input file, output path, and requested size. It parses the PES file, renders the stitch pattern as anti-aliased colored lines on a transparent background, and writes a PNG. + +## License + +MIT -- 2.49.1