Actuators/agent.md

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:

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

Run And Verify

client/bin/python main.py

For Wayland:

QT_QPA_PLATFORM=xcb client/bin/python main.py

Smoke-test GUI initialization without a display:

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.