pixelcoords 0.1.0

Every screen tool that measures pixels ends at a human's eyeball: a ruler shows you a number, a screenshot app draws an arrow, a mouse tracker prints a position you copy by hand. pixelcoords starts from a different premise — the real consumer of a coordinate is a machine.

It freezes your screen so nothing moves while you measure, then lets you mark regions with real shapes — rectangles, ellipses, triangles, N-gons, freehand — rotated, labeled, and placed to the exact pixel with a loupe and arrow-key nudging. What you mark becomes data, not a picture: versioned JSON in physical pixels with per-monitor DPI scale, labeled crops and frame-sized cutouts, ready-to-paste click code for your automation stack, point verification with exit codes for CI and computer-use agents, and self-healing re-location when the UI drifts out from under your coordinates. Sessions reopen and edit like documents.

No account, no network, no toolkit — one small native binary for macOS, Windows, and Linux. MIT-licensed, because the aim was to build the best tool in this category and give it away.

Install

Prebuilt binaries for macOS, Windows, and Linux are on the releases page — download, unpack, run. Or build it with cargo:

cargo install pixelcoords

Rust 1.88+ for the cargo route. On Linux it needs build dependencies first:

sudo apt-get install -y libxcb1-dev libxcb-randr0-dev libpipewire-0.3-dev \
  libclang-dev libegl1-mesa-dev libgbm-dev pkg-config

macOS asks for Screen Recording permission on first run — docs/TROUBLESHOOTING.md covers it.

Sixty seconds

pixelcoords                      # screen freezes; drag shapes, A labels, S saves
# → Downloads/pixelcoords-captures/<timestamp>/
#   session.json  screenshot-0.png  cutout-primary-0.png  cutout-inverse-0.png  crop-0-submit.png

pixelcoords assert --session <dir> --point 812,440 --label submit
# exit 0: that point is inside the region you labeled "submit"

pixelcoords emit --session <dir> --format pyautogui
# ready-to-paste click code, coordinate conventions already handled

pixelcoords find --session <dir>
# the UI moved? every region re-located by its saved crop, deltas included

pixelcoords resume                # pick any saved session, keep editing it

Window-relative marking: --target "Title" on macOS/Windows/X11, or --pick on Wayland. Every command speaks exit codes and JSON where a script would care — the complete reference with every flag is docs/CLI.md.

Controls

Drag draws; the on-screen panel teaches everything else. The six that matter: W cycles the tool, A labels, S saves, Z undoes, hold M for a pixel loupe, Esc backs out / quits. Full table in docs/CLI.md; every key is rebindable via docs/CONFIGURATION.md.

Platform status

Multi-monitor and mixed-DPI layouts are exercised by tests but not yet verified on real hardware. This table is kept honest — claims match runs.

Non-goals

Knowing what a tool is means knowing what it isn't. These are settled:

• OCR — text extraction is a different product; platform tools and Shottr own it.
• Live (unfrozen) measurement — the freeze is the thesis: nothing moves between look and click.
• Annotation — arrows, blur, and highlights are a screenshot editor's job; labels here exist for machines, not slides.
• Recording / GIF capture — the product is the frozen instant, not the timeline; ShareX exists.
• Cloud upload, sharing, accounts — offline by design, permanently.

Documentation

• docs/CLI.md — every command, flag, control, and exit code
• docs/OUTPUT.md — session.json schema, crops, cutouts, jq recipes
• docs/CONFIGURATION.md — colors, key bindings, config file
• docs/TROUBLESHOOTING.md — fixes, behaviors, FAQ
• docs/DEVELOPMENT.md — building from source, CI gates, tests, releases
• CHANGELOG.md — what changed and why
• CONTRIBUTING.md — bug reports and pull requests

License

MIT — see LICENSE. Bundled: JetBrains Mono (OFL 1.1).