Init

README.md

@@ -0,0 +1,80 @@
+# whoshue
+
+A pixel-art color analyzer for KDE/Wayland. Capture a game/application window,
+select part of its preview, and inspect the captured colors. The analyzer is a
+normal desktop window; it does not flash calibration colors or hide itself.
+
+## Run
+
+On CachyOS/Arch with KDE, the capture backend uses `xdg-desktop-portal`,
+`xdg-desktop-portal-kde`, and PipeWire. Building needs Rust, a C toolchain,
+`pkgconf`, Clang/libclang, and PipeWire development libraries (`libpipewire`).
+
+```sh
+cargo run --release
+# Or start with a local image, without requesting screen sharing:
+cargo run --release -- /path/to/screenshot.png
+```
+
+1. Click **Choose source…**. KDE handles selecting a window, screen, or region.
+   Click it again to choose a different source.
+2. Drag a rectangle in the source preview. Capture display pauses during the
+   drag, then returns to its previous live/frozen state. The crop is stored in
+   source pixels and resets if the source dimensions change.
+3. **Freeze** holds the displayed frame and analysis; **Resume** takes the newest
+   available frame. **Stop sharing** closes capture and keeps the last image.
+4. Inspect the nearest-neighbor zoomed crop. Hover for source coordinates,
+   RGB/hex and HSV; click to copy hex. Click palette swatches to copy them too.
+5. **Save crop PNG** writes a uniquely named PNG in the system temporary directory
+   and displays its path. Drop an image or click **Open image…** to browse for a file in KDE's file picker.
+
+The HSV histogram has 36 ten-degree bins. Switch between pixel counts and equal
+weight per distinct RGB color. Colors with saturation below 5% are counted
+separately as neutrals. The palette is exact (no quantization), ordered by count,
+then RGB for deterministic ties. Fully transparent pixels are excluded; partially
+transparent pixels retain their stored RGB values and count once.
+
+Choosing a source always opens KDE's picker. The last portal token is saved at
+`$XDG_CONFIG_HOME/whoshue/config.toml` (normally `~/.config/whoshue/config.toml`)
+for the command-line capture diagnostic. No capture starts until **Choose source…**
+is clicked. Cancelling the file picker leaves the current image/capture unchanged.
+
+Portal requests share one application-lifetime async runtime. PipeWire runs on a
+separate blocking worker so restarting capture or opening another portal dialog
+cannot strand the cached D-Bus connection on a stopped executor.
+
+## Limits and next work
+
+- Window capture is preferred: screen/region capture includes overlapping windows,
+  including whoshue if placed inside the captured area.
+- Selection follows coordinates within the source, not a moving sprite.
+- Analysis uses source pixels before preview scaling, but these are rendered
+  colors, not necessarily original game-asset colors. HDR and color-profile
+  conversion have not been validated; the current path assumes ordinary SDR RGB.
+- Live analysis refreshes at most five times per second. Large selections with
+  many unique colors are more expensive; release builds are recommended.
+- Game-specific behavior on focus loss/minimization needs desktop testing.
+- Perceptual OKLCH views, color/hue highlighting, and comparing saved selections
+  are future features; this first version uses HSV.
+
+## Validation
+
+```sh
+cargo test --offline --locked
+cargo clippy --offline --locked --all-targets -- -D warnings
+cargo fmt --check
+```
+
+Tests cover hue boundaries, neutral/transparent pixel handling, weighting,
+cropping, selection coordinates, pixel-format conversion, frozen-frame behavior,
+resize handling, headless UI rendering, file-picker cancellation/reopening, and
+repeated portal requests during/after capture. The portal regression test requires
+`dbus-run-session` and permission to create a local socket; it uses its own private
+bus and does not open desktop dialogs. Actual portal capture requires a running
+Wayland desktop and permission through KDE's picker.
+
+For a capture-only diagnostic (saves the first full source frame):
+
+```sh
+cargo run -- --selftest /tmp/whoshue-selftest.png
+```