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 |
 
 <!-- TODO: Add screenshot of Nautilus showing PES thumbnails -->
 
@@ -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)

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 <nils@narl.io>"]
+keywords = ["embroidery", "pes", "thumbnail", "stitch"]
+categories = ["graphics", "parser-implementations"]
+readme = "README.md"
 
 [dependencies]
 thiserror = "2"

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

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 <nils@narl.io>"]
+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"

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