zed-playground/py_workspace/AGENTS.md

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:

uv sync
uv run python -V

Run common scripts:

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

Type-check / lint-equivalent:

uv run basedpyright

Run all 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 subset by keyword:

uv run pytest -k "depth and refine"

Useful options:

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.