anti-prestige-tool/README.md

# Anti Prestige Tool v0.9.0

Queue-position reader for Arma Reforger on Linux Wayland.

The tool captures a user-selected Reforger window through xdg-desktop-portal/PipeWire, crops the queue-number region, and reads the orange UI digits with bundled real-game digit templates. Normal use does not require external OCR libraries, desktop-specific screenshot hooks, or a specific installed font.

## Install

Install system dependencies:

```bash
# Arch example
sudo pacman -S --needed base-devel uv qt6-base gstreamer gst-plugins-base gst-plugin-pipewire imagemagick xdg-desktop-portal
```

Install the portal backend for your desktop:

```text
KDE:   xdg-desktop-portal-kde
GNOME: xdg-desktop-portal-gnome
wlr:   xdg-desktop-portal-wlr
```

Set up the Python environment and build the portal helper:

```bash
uv sync
make
```

No sudo install step is required.

## Standard Run

Watch the selected Reforger window and alert when the queue position reaches `5` or lower:

```bash
uv run reforger_queue_read.py --watch --portal-window
```

On first run, your desktop should show a window-sharing picker. Select the Arma Reforger window. Later runs try to reuse that selection.

Read the queue once:

```bash
uv run reforger_queue_read.py --portal-window
```

Force the window picker again if the saved selection is stale or wrong:

```bash
uv run reforger_queue_read.py --portal-window --portal-reselect
```

Run once with crop and OCR details while tuning or checking accuracy:

```bash
uv run reforger_queue_read.py --portal-window --show-crop --debug
```

The saved portal restore token lives here:

```text
~/.local/state/anti-prestige-tool/portal-window-restore-token
```

## Watch Behavior

Default watch mode:

```text
poll interval: 15 seconds
alert threshold: 5, inclusive
alerts: once per newly detected position
notification urgency: critical
```

Each poll prints a timestamp, the detected queue number, and whether an alert fired:

```text
2026-05-01T14:44:05+01:00 number=5 alert=yes
2026-05-01T14:44:20+01:00 number=5 alert=no
```

If no digits are found, the watcher logs that and keeps running.

## Optional Flags

Common flags:

```text
--watch                      keep polling instead of reading once
--watch-interval SECONDS     poll delay; default 15
--alert-threshold N          alert when position is <= N; default 5
--portal-reselect            ignore the saved portal selection and pick again
--show-crop                  print the resolved crop
--debug                      print OCR match details
--save-input PATH            save the captured portal frame
--notify-command COMMAND     notification command; default notify-send
```

Input and test flags:

```text
--image PATH                 read an existing screenshot
--dataset DIR                read every image in a dataset directory
--expect-filenames           compare dataset results to numeric filenames
--font FONT                  debug with synthetic font templates
--crop X,Y,W,H               override the crop
--cropped                    treat input image as already cropped
```

## Examples

Alert at queue position `10` or lower:

```bash
uv run reforger_queue_read.py --watch --portal-window --alert-threshold 10
```

Poll every 5 seconds:

```bash
uv run reforger_queue_read.py --watch --portal-window --watch-interval 5
```

Save the captured input image while debugging:

```bash
uv run reforger_queue_read.py --portal-window --save-input /tmp/apt-portal-window.png --show-crop --debug
```

Test watcher alerting against a fixture without sending a real notification:

```bash
uv run reforger_queue_read.py --watch --image datasets/regression-test-set/3.png --watch-interval 1 --notify-command true
```

Read an existing screenshot:

```bash
uv run reforger_queue_read.py --image /path/to/screenshot.png --show-crop --debug
```

## Validation

Run the regression set:

```bash
uv run reforger_queue_read.py --dataset datasets/regression-test-set --expect-filenames
```

Expected result:

```text
summary: 21 passed, 0 failed
```

Run the smaller smoke dataset:

```bash
uv run reforger_queue_read.py --dataset datasets/scootz-dataset --show-crop
```

Expected output:

```text
datasets/scootz-dataset/1920x1080.png	crop=788,465,75,45
datasets/scootz-dataset/1920x1080.png	22
datasets/scootz-dataset/2160x1440.png	crop=1050,620,100,60
datasets/scootz-dataset/2160x1440.png	24
```

## Debug Options

The default matcher uses bundled templates from:

```text
templates/reforger_digits.json
```

Font mode is only for debugging. Known-good overrides:

```bash
uv run reforger_queue_read.py --portal-window --font Roboto-Condensed --show-crop --debug
uv run reforger_queue_read.py --portal-window --font Adwaita-Sans --show-crop --debug
```

Default crop reference:

```text
reference-size: 2560x1440
reference-crop: 1050,620,100,60
scale-mode: width
```

Portal restore behavior depends on the desktop portal. If the selected window disappears after an Arma restart, the portal may show the picker again.