ChArUcoBoardExp/AGENTS.md

AGENTS.md

Guide for coding agents working in this repository.

Project Overview

• Domain: Computer vision experiments with ArUco / ChArUco and camera calibration
• Language: Python
• Python version: 3.13+ (see .python-version, pyproject.toml)
• Env/deps manager: uv
• Test runner: pytest
• Lint/format: ruff
• Packaging mode: workspace scripts ([tool.uv] package = false)

High-Signal Files

• find_aruco_points.py: live marker detection + frame overlays
• find_extrinsic_object.py: pose estimation with known object points
• cali.py: charuco calibration and parquet output
• capture.py: webcam frame capture helper
• run_capture.py: multi-port gstreamer recorder CLI (click)
• scripts/uv_to_object_points.py: UV -> 3D conversion script
• test_cam_props.py: camera property probe test/script
• Shell helpers: gen.sh, cvt_all_pdfs.sh, dump_and_play.sh

Setup

uv sync

Creates .venv and installs dependencies from pyproject.toml.

Build / Lint / Test Commands

No compile step. “Build” usually means running generation/util scripts.

Lint

uv run ruff check .
uv run ruff check . --fix

Format

uv run ruff format .

Tests

Full suite:

uv run pytest -q

Single test file (important):

uv run pytest test_cam_props.py -q

Single test function:

uv run pytest test_cam_props.py::test_props -q

Keyword filter:

uv run pytest -k "props" -q

Script sanity checks

uv run python -m py_compile *.py scripts/*.py
uv run python run_capture.py --help
uv run python scripts/uv_to_object_points.py --help

Runtime/Tooling Notes

• Prefer uv run python <script>.py for all local execution.
• scripts/uv_to_object_points.py also supports script-mode execution directly.
• Shell scripts require system tools:
  • gen.sh: expects MarkerPrinter.py from OpenCV contrib generator context
  • cvt_all_pdfs.sh: needs ImageMagick (magick)
  • dump_and_play.sh: needs gst-launch-1.0

Code Style (Observed Conventions)

Follow existing style in touched files; keep edits narrow.

Imports

• Keep imports at top of module.
• Common pattern: stdlib + third-party; ordering is not perfectly strict.
• Do not do broad import reordering unless asked.

Formatting

• 4-space indentation
• Predominantly double quotes
• Script-oriented functions; avoid unnecessary abstractions

Types

• Type hints are common in core numeric/geometry scripts.
• Existing usage includes:
  • builtin generics (list[int], tuple[float, float])
  • TypedDict
  • typing.cast
  • numpy.typing and jaxtyping aliases
• Preserve/improve types when touching typed code.

Naming

• snake_case: functions, variables
• PascalCase: classes
• UPPER_SNAKE_CASE: constants/config

Error Handling / Logging

• loguru is the preferred logger.
• Use logger.warning(...) for recoverable detection/runtime issues.
• Raise explicit exceptions for invalid inputs in utility code.

CLI / Entrypoints

• click is used for CLI scripts.
• Use if __name__ == "__main__": entrypoints.
• Keep side effects in main() when possible.

CV / Numeric Practices

• Be explicit about array shapes where relevant.
• Normalize/reshape OpenCV outputs before downstream operations.
• Keep calibration/dictionary constants near top-level config.

Testing Guidance

• Repo is hardware-heavy; avoid adding camera-dependent tests unless requested.
• Prefer extracting pure logic and testing that logic.
• Use pytest naming: test_*.py, test_*.

Dependency Management (uv)

uv add <package>
uv add --dev <package>
uv remove <package>
uv sync

Prefer checking in both pyproject.toml and uv.lock for reproducibility.

Cursor / Copilot Rules Check

• .cursor/rules/: not present
• .cursorrules: not present
• .github/copilot-instructions.md: not present

No repository-specific Cursor/Copilot rule files currently exist.

Agent Workflow Checklist

Before coding:

1. Read this file and target scripts.
2. Run uv sync if env may be stale.
3. Check whether task depends on camera/hardware.

After coding:

1. Run focused checks first.
2. Run uv run ruff check ..
3. Run uv run pytest -q (or explain hardware-related skips).
4. Keep edits minimal and task-scoped.