81 lines
4.0 KiB
Markdown
81 lines
4.0 KiB
Markdown
# 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
|
|
```
|