zed-playground/AGENTS.md

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

uv sync
uv run python -V

Run scripts:

uv run streaming_receiver.py --help
uv run recording_multi.py
uv run calibrate_extrinsics.py --help

Type checking / lint-equivalent:

uv run basedpyright

Tests:

uv run pytest

Run a single test file:

uv run pytest tests/test_depth_refine.py

Run a single test function:

uv run pytest tests/test_depth_refine.py::test_refine_extrinsics_with_depth_with_offset

Run by keyword:

uv run pytest -k "depth and refine"

Useful verbosity / fail-fast options:

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

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.