179 lines
5.0 KiB
Markdown
179 lines
5.0 KiB
Markdown
# AGENTS.md — Repository Guide for Coding Agents
|
|
|
|
This file is for autonomous/agentic coding in `/workspaces/zed-playground`.
|
|
Primary active Python workspace: `/workspaces/zed-playground/py_workspace`.
|
|
|
|
---
|
|
|
|
## 1) Environment & Scope
|
|
|
|
- Python package manager: **uv**
|
|
- Python version: **3.12+**
|
|
- Core deps (py_workspace): `pyzed`, `opencv-python`, `click`, `numpy`, `scipy`, `loguru`, `awkward`, `jaxtyping`
|
|
- Dev deps: `pytest`, `basedpyright`
|
|
- Treat `py_workspace/loguru/` and `py_workspace/tmp/` as non-primary project areas unless explicitly asked.
|
|
|
|
---
|
|
|
|
## 2) Build / Run / Lint / Test Commands
|
|
|
|
### Python (py_workspace)
|
|
|
|
Run from: `/workspaces/zed-playground/py_workspace`
|
|
|
|
```bash
|
|
uv sync
|
|
uv run python -V
|
|
```
|
|
|
|
Run scripts:
|
|
```bash
|
|
uv run streaming_receiver.py --help
|
|
uv run recording_multi.py
|
|
uv run calibrate_extrinsics.py --help
|
|
```
|
|
|
|
Type checking / lint-equivalent:
|
|
```bash
|
|
uv run basedpyright
|
|
```
|
|
|
|
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 by keyword:
|
|
```bash
|
|
uv run pytest -k "depth and refine"
|
|
```
|
|
|
|
Useful verbosity / fail-fast options:
|
|
```bash
|
|
uv run pytest -x -vv
|
|
```
|
|
|
|
Notes:
|
|
- `pyproject.toml` sets `testpaths = ["tests"]`
|
|
- `norecursedirs = ["loguru", "tmp", "libs"]`
|
|
|
|
### C++ sample project (body tracking)
|
|
|
|
Run from:
|
|
`/workspaces/zed-playground/playground/body tracking/multi-camera/cpp/build`
|
|
|
|
```bash
|
|
cmake ..
|
|
make -j4
|
|
./ZED_BodyFusion <config_file.json>
|
|
```
|
|
|
|
---
|
|
|
|
## 3) Rules Files Scan (Cursor / Copilot)
|
|
|
|
As of latest scan:
|
|
- No `.cursorrules` found
|
|
- No `.cursor/rules/` found
|
|
- No `.github/copilot-instructions.md` found
|
|
|
|
If these files are later added, treat them as higher-priority local policy and update this guide.
|
|
|
|
---
|
|
|
|
## 4) Code Style Conventions (Python)
|
|
|
|
### Imports
|
|
- Prefer grouping: stdlib → third-party → local modules.
|
|
- ZED imports use `import pyzed.sl as sl`.
|
|
- In package modules (`aruco/*`), use relative imports (`from .pose_math import ...`).
|
|
- In top-level scripts, absolute package imports are common (`from aruco... import ...`).
|
|
|
|
### Formatting & structure
|
|
- 4-space indentation, PEP8-style layout.
|
|
- Keep functions focused; isolate heavy logic into helper functions.
|
|
- Favor explicit CLI options via `click.option` rather than positional ambiguity.
|
|
|
|
### Typing
|
|
- Type hints are expected on public and most internal functions.
|
|
- Existing code uses both `typing.Optional/List/Dict` and modern `|` syntax; stay consistent with surrounding file.
|
|
- Use `jaxtyping` shape hints when already used in module (`TYPE_CHECKING` guard pattern).
|
|
- Avoid `Any` unless unavoidable (OpenCV / pyzed boundaries).
|
|
|
|
### Naming
|
|
- `snake_case`: functions, variables, modules.
|
|
- `PascalCase`: classes.
|
|
- `UPPER_SNAKE_CASE`: constants (e.g., dictionary maps).
|
|
|
|
### Docstrings
|
|
- Include concise purpose + `Args` / `Returns` where helpful.
|
|
- For matrix/array-heavy functions, document expected shape and units.
|
|
|
|
### Logging & user output
|
|
- CLI-facing messaging: use `click.echo`.
|
|
- Diagnostic/internal logs: use `loguru` (`logger.debug/info/warning`).
|
|
- Keep debug noise behind `--debug` style flag where possible.
|
|
|
|
### Error handling
|
|
- Raise specific exceptions (`ValueError`, `FileNotFoundError`, etc.) with actionable messages.
|
|
- For CLI fatal paths, use `click.UsageError` / `SystemExit(1)` patterns found in project.
|
|
- Validate early (shape/range/None checks) before expensive operations.
|
|
|
|
---
|
|
|
|
## 5) Testing Conventions
|
|
|
|
- Framework: `pytest`
|
|
- Numeric assertions: prefer `numpy.testing.assert_allclose` where appropriate.
|
|
- Exception checks: `pytest.raises(..., match=...)`.
|
|
- Add tests under `py_workspace/tests/`.
|
|
- If adding behavior in `aruco/*`, add or update corresponding tests (`test_depth_*`, `test_alignment`, etc.).
|
|
|
|
---
|
|
|
|
## 6) ZED-Specific Project Guidance
|
|
|
|
### Architecture reminder: Streaming vs Fusion
|
|
- Streaming API: send compressed video, compute depth/tracking on host.
|
|
- Fusion API: publish metadata (bodies/poses), lightweight host fusion.
|
|
- There is no built-in “stream depth map” mode in the same way as metadata fusion.
|
|
|
|
### Depth units
|
|
- Be explicit with coordinate units and keep units consistent end-to-end.
|
|
- Marker geometry/parquet conventions in this repo are meter-based; do not mix mm/m silently.
|
|
|
|
### Threading
|
|
- OpenCV GUI (`cv2.imshow`, `cv2.waitKey`) belongs on main thread.
|
|
- Capture/grab work in worker threads with queue handoff.
|
|
|
|
### Network config
|
|
- Use `zed_network_utils.py` and `zed_settings/inside_network.json` conventions.
|
|
|
|
---
|
|
|
|
## 7) Agent Execution Checklist
|
|
|
|
Before editing:
|
|
1. Identify target workspace (`py_workspace` vs playground C++).
|
|
2. Confirm commands from this file and nearby module docs.
|
|
3. Search for existing tests covering the area.
|
|
|
|
After editing:
|
|
1. Run focused test(s) first, then broader test run as needed.
|
|
2. Run `uv run basedpyright` for type regressions.
|
|
3. Keep diffs minimal and avoid unrelated file churn.
|
|
|
|
If uncertain:
|
|
- Prefer small, verifiable changes.
|
|
- Document assumptions in commit/PR notes.
|