# Actuator Agent Guide

## Project

- Python/PyQt6 desktop tool for reading actuator angles from video frames.
- Application entry point: `main.py`.
- Core modules: `actuator/angle_calc.py`, `actuator/video_reader.py`, and `actuator/automation.py`.

## Environment

- Use the project-local `uv` virtual environment: `client/`.
- Python version: 3.10.
- Install or refresh dependencies:

```bash
uv pip install --python client/bin/python -r requirements.txt
```

## Run And Verify

```bash
client/bin/python main.py
```

For Wayland:

```bash
QT_QPA_PLATFORM=xcb client/bin/python main.py
```

Smoke-test GUI initialization without a display:

```bash
QT_QPA_PLATFORM=offscreen timeout 5s client/bin/python main.py
```

An exit status caused by `timeout` is expected when the GUI initializes and remains open.

## Frame Navigation

- Set the "跳帧数" control to choose a frame-jump step (1-10000).
- `A`: move backward by the selected step.
- `D`: move forward by the selected step.
- During measurement, `A`/`D` only navigate and do not create measurements for skipped frames.
- During measurement, `Right` skips the current frame and records angle `0`; if M2 is selected, it records the measurement and advances one frame.

## Change Guidelines

- Keep GUI text in Chinese to match the existing application.
- Run `client/bin/python -m py_compile main.py actuator/*.py` after Python changes.
- Do not commit the local `client/` environment; it is ignored by Git.