189 lines
4.7 KiB
Markdown
189 lines
4.7 KiB
Markdown
# AGENTS.md — Python Workspace Guide
|
|
|
|
This file defines coding-agent guidance for:
|
|
`/workspaces/zed-playground/py_workspace`
|
|
|
|
Use this as the primary reference for Python work in this repository.
|
|
|
|
---
|
|
|
|
## 1) Scope & Environment
|
|
|
|
- Package manager: **uv**
|
|
- Python: **3.12+**
|
|
- Project file: `pyproject.toml`
|
|
- Main package/work area: top-level scripts + `aruco/` + `tests/`
|
|
- Non-primary/vendor-like areas (avoid unless explicitly asked):
|
|
- `loguru/`
|
|
- `tmp/`
|
|
- `libs/`
|
|
|
|
Core dependencies include:
|
|
- `pyzed`, `opencv-python`, `click`, `numpy`, `scipy`
|
|
- `loguru`, `awkward`, `jaxtyping`, `pyarrow`, `pandas`
|
|
|
|
Dev dependencies:
|
|
- `pytest`, `basedpyright`
|
|
|
|
---
|
|
|
|
## 2) Build / Run / Lint / Test Commands
|
|
|
|
Run commands from:
|
|
`/workspaces/zed-playground/py_workspace`
|
|
|
|
Environment sync:
|
|
```bash
|
|
uv sync
|
|
uv run python -V
|
|
```
|
|
|
|
Run common scripts:
|
|
```bash
|
|
uv run streaming_receiver.py --help
|
|
uv run recording_multi.py
|
|
uv run calibrate_extrinsics.py --help
|
|
```
|
|
|
|
Type-check / lint-equivalent:
|
|
```bash
|
|
uv run basedpyright
|
|
```
|
|
|
|
Run all tests:
|
|
```bash
|
|
uv run pytest
|
|
```
|
|
|
|
Run a single test file:
|
|
```bash
|
|
uv run pytest tests/test_depth_refine.py
|
|
```
|
|
|
|
Run a single test function:
|
|
```bash
|
|
uv run pytest tests/test_depth_refine.py::test_refine_extrinsics_with_depth_with_offset
|
|
```
|
|
|
|
Run subset by keyword:
|
|
```bash
|
|
uv run pytest -k "depth and refine"
|
|
```
|
|
|
|
Useful options:
|
|
```bash
|
|
uv run pytest -x -vv
|
|
```
|
|
|
|
Notes from `pyproject.toml`:
|
|
- `testpaths = ["tests"]`
|
|
- `norecursedirs = ["loguru", "tmp", "libs"]`
|
|
|
|
---
|
|
|
|
## 3) Rules Files (Cursor / Copilot)
|
|
|
|
Latest scan in this workspace found:
|
|
- No `.cursorrules`
|
|
- No `.cursor/rules/`
|
|
- No `.github/copilot-instructions.md`
|
|
|
|
If these files appear later, treat them as higher-priority local instructions.
|
|
|
|
---
|
|
|
|
## 4) Python Code Style Conventions
|
|
|
|
### Imports
|
|
- Group imports: standard library → third-party → local modules.
|
|
- Use ZED import style:
|
|
- `import pyzed.sl as sl`
|
|
- In package modules (`aruco/*`), prefer relative imports:
|
|
- `from .pose_math import ...`
|
|
- In top-level scripts, absolute imports are common:
|
|
- `from aruco.detector import ...`
|
|
|
|
### Formatting & structure
|
|
- 4-space indentation.
|
|
- PEP8-style layout.
|
|
- Keep functions focused and composable.
|
|
- Prefer explicit CLI options over positional ambiguity.
|
|
|
|
### Typing
|
|
- Add type hints on public and most internal functions.
|
|
- Existing code uses both:
|
|
- `typing.Optional/List/Dict/Tuple`
|
|
- modern `|` unions
|
|
Stay consistent with the surrounding file.
|
|
- When arrays/matrices are central, use `jaxtyping` shape aliases (with `TYPE_CHECKING` guards) where already established.
|
|
- Avoid broad `Any` unless unavoidable at library boundaries (OpenCV/pyzed interop).
|
|
|
|
### Naming
|
|
- `snake_case`: functions, variables, modules.
|
|
- `PascalCase`: classes.
|
|
- `UPPER_SNAKE_CASE`: constants.
|
|
|
|
### Docstrings
|
|
- Use concise purpose + `Args` / `Returns`.
|
|
- Document expected array shapes and units for geometry/math functions.
|
|
|
|
### Logging & output
|
|
- User-facing CLI output: `click.echo`.
|
|
- Diagnostic logs: `loguru` (`logger.debug/info/warning`).
|
|
- Keep verbose logs behind a `--debug` flag.
|
|
|
|
### Error handling
|
|
- Raise specific exceptions (`ValueError`, `FileNotFoundError`, etc.) with actionable messages.
|
|
- For CLI fatal paths, use `click.UsageError` or `SystemExit(1)` patterns.
|
|
- Validate early (shape/range/None) before expensive compute.
|
|
|
|
---
|
|
|
|
## 5) Testing Conventions
|
|
|
|
- Framework: `pytest`
|
|
- Numerical checks: use `numpy.testing.assert_allclose` where appropriate.
|
|
- Exception checks: `pytest.raises(..., match=...)`.
|
|
- Place/add tests under `tests/`.
|
|
- For `aruco/*` behavior changes, update related tests (`test_depth_*`, `test_alignment`, etc.).
|
|
|
|
---
|
|
|
|
## 6) Project-Specific ZED Guidance
|
|
|
|
### Streaming vs Fusion architecture
|
|
- Streaming API sends compressed video; host computes depth/tracking.
|
|
- Fusion API sends metadata; host does lightweight fusion.
|
|
- Do not assume built-in depth-map streaming parity with metadata fusion.
|
|
|
|
### Units
|
|
- Keep units explicit and consistent end-to-end.
|
|
- Marker parquet geometry is meter-based in this workspace.
|
|
- Be careful with ZED depth unit configuration and conversions.
|
|
|
|
### Threading
|
|
- OpenCV GUI (`cv2.imshow`, `cv2.waitKey`) should stay on main thread.
|
|
- Use worker thread(s) for grab/retrieve and queue handoff patterns.
|
|
|
|
### Network config
|
|
- Follow `zed_network_utils.py` and `zed_settings/inside_network.json` patterns.
|
|
|
|
---
|
|
|
|
## 7) Agent Workflow Checklist
|
|
|
|
Before editing:
|
|
1. Identify target file/module and nearest existing pattern.
|
|
2. Confirm expected command(s) from this guide.
|
|
3. Check for relevant existing tests.
|
|
|
|
After editing:
|
|
1. Run focused tests first.
|
|
2. Run broader test selection as needed.
|
|
3. Run `uv run basedpyright` on final pass.
|
|
4. Keep changes minimal and avoid unrelated churn.
|
|
|
|
If uncertain:
|
|
- Prefer small, verifiable changes.
|
|
- Document assumptions in PR/commit notes.
|