pixelcoords 0.7.7

Useful? A star is how other developers find it — ★ GitHub · pixelcoords.dev

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.

Freeze the screen so nothing moves while you measure, mark regions with real shapes, and what you marked becomes data, not a picture: versioned JSON in physical pixels with per-monitor DPI scale, labeled crops, and ready-to-paste click code for your automation stack.

Install

Building on Linux needs the capture stack 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.

Sixty seconds

pixelcoords                        # freeze every screen; drag to mark, A labels, S saves
pixelcoords resolve --session ~/Downloads/pixelcoords-captures/<stamp>

resolve prints the click point for every label you marked, in the space and units your automation API speaks:

{ "label": "submit", "monitor": 0, "scale": 2.0, "units": "logical",
  "point": { "x": 812, "y": 440 } }

That is the whole loop: mark once, resolve forever. The session is a directory of JSON and PNGs you can commit.

Commands

Full reference with every flag: docs/CLI.md

Things worth knowing early

Coordinates are physical pixels, and --units is the knob. A session records what the display actually has. --units auto converts to what your platform's input API expects — logical points on macOS, physical pixels on Windows and X11. Guessing wrong on a Retina display puts every click at half the intended position.

Exit codes are the API. Scripts branch on them:

Wayland withholds window geometry. windows and --target refuse there and point you at --pick instead. That refusal is deliberate; a guessed window position would be worse than no answer.

--min-score and --tolerance are different quantities. The first is a correlation score in 0..=1; the second is a percentage of pixels in 0..=100. Both are bounds-checked, so a swapped value is refused rather than silently matching nothing.

Configure it

Colors, key bindings, snapping, and overlay behavior live in a config file you can also override per run:

pixelcoords --bind u=undo --config ./my-config.toml

Every setting and every bindable action: docs/CONFIGURATION.md

Platform support

Fractional scaling is unverified everywhere. Claims here match runs — where a run has not happened it says so, and CONTRIBUTING.md carries the full record.

Performance

Measured on an Apple M5 Pro, --release, at 0.5.3. Reproduce with:

cargo run --release -p pixelcoords-core --example bench   # the math
scripts/bench-cli.sh <session-dir>                        # the round trip

Resolving is free; matching is the expensive part, and it scales with crop area rather than screen size. Method and caveats: docs/PERFORMANCE.md

Testing

659 tests. CI runs fmt, clippy pedantic (-D warnings), the suite, MSRV, cargo audit, and a policy job that fails on any inline #[allow].

Non-goals

Not a screen recorder, not an OCR tool, not a UI-testing framework, and not an executor — pixelcoords never moves your mouse. It answers where, and stops. pixelactions is the other half of that loop.

Documentation

• pixelcoords.dev — demo, comparisons, how-to
• 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/PERFORMANCE.md — measured timings, and what this tool is not
• docs/DEVELOPMENT.md — building, CI gates, tests, releases
• CHANGELOG.md — what changed and why

Also by nolindnaidoo

Rust

• pixelactions - Perform the interaction and confirm it landed · pixelactions.dev

VS Code Extensions — every tool in the family, one page: letools.dev

• String-LE - Extract string values for i18n from JSON, YAML, CSV, TOML, INI, and .env
• Numbers-LE - Extract numeric values from JSON, YAML, CSV, TOML, INI, and .env
• EnvSync-LE - Spot missing keys across your .env files, with a markdown report
• Paths-LE - Extract file paths from JS/TS imports, JSON, HTML, CSS, TOML, CSV, and .env
• Secrets-LE - Detect and sanitize credentials locally, before you commit
• Scrape-LE - Check whether a page is scrapeable before you write the scraper
• Colors-LE - Extract and analyze colors from CSS, SCSS, LESS, Stylus, HTML, JS/TS, and SVG
• URLs-LE - Extract URLs from documentation, configs, and code
• Regex-LE - Find, test, and validate the regex patterns in the current file
• Dates-LE - Extract and analyze dates from logs, configs, and code

Contact Developer — GitHub · LinkedIn

License

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