181 lines
4.3 KiB
Markdown
181 lines
4.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
uv run ruff check .
|
|
uv run ruff check . --fix
|
|
```
|
|
|
|
### Format
|
|
|
|
```bash
|
|
uv run ruff format .
|
|
```
|
|
|
|
### Tests
|
|
|
|
Full suite:
|
|
|
|
```bash
|
|
uv run pytest -q
|
|
```
|
|
|
|
Single test file (important):
|
|
|
|
```bash
|
|
uv run pytest test_cam_props.py -q
|
|
```
|
|
|
|
Single test function:
|
|
|
|
```bash
|
|
uv run pytest test_cam_props.py::test_props -q
|
|
```
|
|
|
|
Keyword filter:
|
|
|
|
```bash
|
|
uv run pytest -k "props" -q
|
|
```
|
|
|
|
### Script sanity checks
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
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.
|