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