146 lines
7.3 KiB
Markdown
146 lines
7.3 KiB
Markdown
# AGENTS.md
|
|
|
|
## Current status
|
|
|
|
Step 5 completed and verified with automated checks. Step 5 commit is pending.
|
|
|
|
## Completed steps
|
|
|
|
Initial setup before Step 1:
|
|
|
|
- `uv` package metadata exists.
|
|
- Runtime dependency `dearpygui` is installed.
|
|
- Dev dependencies `pytest`, `ruff`, and `pyright` are installed.
|
|
- Required package skeleton exists under `src/dpg_gauges/`.
|
|
- `examples/`, `tests/`, and `docs/` directories exist.
|
|
- `pyproject.toml` is configured for Python 3.11+, Ruff, and Pyright.
|
|
|
|
Step 1 - Public API contract and pure core:
|
|
|
|
- Public API exports are defined in `src/dpg_gauges/__init__.py`.
|
|
- Public exceptions are defined in `src/dpg_gauges/exceptions.py`.
|
|
- Shared public dataclasses and type aliases are defined in `src/dpg_gauges/types.py`.
|
|
- Pure gauge configuration dataclasses are defined in `src/dpg_gauges/gauges.py`.
|
|
- Pure scale helpers are defined in `src/dpg_gauges/scales.py`.
|
|
- Lightweight theme/style presets are defined in `src/dpg_gauges/themes.py`.
|
|
- GUI-dependent public functions are import-safe stubs for Step 1.
|
|
- Step 1 tests cover public imports, dataclass construction, clamp/normalize math, tick generation, threshold validation, formatting, and missing-gauge stubs.
|
|
|
|
## Current step
|
|
|
|
Step 6 - High-rate updates, animation, and stress examples.
|
|
|
|
Step 5 - Analog, segmented, compass, thermometer, battery, and multi-value gauges:
|
|
|
|
Implemented during Step 5:
|
|
|
|
- Added analog and compass dial rendering with arcs, ticks, tick labels, needles, redline bands, and markers.
|
|
- Added compass heading wraparound for runtime values.
|
|
- Added segmented gauge rendering with active segment calculation.
|
|
- Added thermometer and battery-specific drawlist rendering.
|
|
- Added multi-value gauge rendering.
|
|
- Added Step 5 examples and tests for angle math, tick generation, compass wraparound, segment activation, battery clamp, and multi-value rendering.
|
|
|
|
Step 4 - Digital, bar, level, and status gauges:
|
|
|
|
Implemented during Step 4:
|
|
|
|
- Added digital gauge drawlist rendering with formatted value text.
|
|
- Added bar and level gauge rendering with horizontal/vertical fill geometry.
|
|
- Added threshold band and marker drawing for bar/level gauges.
|
|
- Added status light rendering with configured status state colors and text.
|
|
- Added Dear PyGui item callback wiring for gauges with `callback=`.
|
|
- Added Step 4 examples and tests for geometry, runtime updates, thresholds, markers, and status states.
|
|
|
|
Step 3 - Widget shell and renderer foundation:
|
|
|
|
Implemented during Step 3:
|
|
|
|
- Added Dear PyGui widget shell creation for gauge context managers when a DPG context is active.
|
|
- Kept pure registration behavior when no DPG context has been created.
|
|
- Added a renderer foundation that measures drawlist size, redraws stable placeholder background/frame/value text, schedules animation frames, and exposes renderer debug fields.
|
|
- Added draw layer bookkeeping.
|
|
- Added lightweight `gauge_panel` and `gauge_grid` containers.
|
|
- Added Step 3 examples and smoke tests.
|
|
|
|
Step 2 - State, sizing, animation, and smoothing model:
|
|
|
|
Implemented during Step 2:
|
|
|
|
- Added `DpgGaugesConfig`, `configure(...)` wiring, `GaugeState`, `DirtyFlags`, and the global gauge registry.
|
|
- Runtime API functions now mutate logical state for values, config updates, thresholds, markers, visibility, and deletion without Dear PyGui calls.
|
|
- Added pure sizing helpers for requested/measured size, last non-zero size preservation, square rects, and stretch rects.
|
|
- Added pure animation interpolation helpers and smoothing progression helpers.
|
|
- Added debug state reporting for registered gauges.
|
|
- Added Step 2 tests for registry behaviour, clamped/displayed separation, dirty flags, sizing, animation, smoothing, and invalid values.
|
|
|
|
## Design decisions
|
|
|
|
- Package is managed with uv.
|
|
- Public import is `import dpg_gauges as dpgg`.
|
|
- Package target is Python 3.11+.
|
|
- The package is Dear PyGui-only, but pure configuration/state helpers should avoid Dear PyGui imports where practical.
|
|
- Widget creation and Dear PyGui item operations are GUI-thread-only.
|
|
- Runtime value/configuration updates are intended to be called from the GUI thread.
|
|
- High-frequency updates should be smoothed/coalesced so gauges remain readable and flicker-free.
|
|
- Out-of-range values clamp to min/max and display the clamped value.
|
|
- Gauges are display-only for the first release.
|
|
- Thresholds and redline zones are visual only; they do not trigger events.
|
|
- The public API should feel like normal Dear PyGui context-manager usage.
|
|
- Each completed build step must be checked, documented in this file, and committed before starting the next step.
|
|
|
|
## Known issues
|
|
|
|
Manual visual example checks for Steps 3, 4, and 5 were not run in this headless session.
|
|
|
|
## Commands used
|
|
|
|
- Read `codex-old/README.md`, `codex-old/FEATURES.md`, `codex-old/ARCHITECTURE.md`, `codex-old/STEPS.md`, and `codex-old/AGENTS.md`.
|
|
- Inspected `/home/hector/projects/dpg-map` package, examples, tests, docs, and pyproject structure.
|
|
- Created the initial `codex/` instruction documents for `dpg-gauges`.
|
|
- Read `codex/README.md`, `codex/FEATURES.md`, `codex/ARCHITECTURE.md`, `codex/STEPS.md`, and `codex/AGENTS.md`.
|
|
- Completed missing pre-Step-1 skeleton files and directories.
|
|
- Ran `uv run python -c "import dpg_gauges; print(dpg_gauges.__name__)"`.
|
|
- Ran `uv run ruff check .`.
|
|
- Ran `uv run ruff format .`.
|
|
- Read all files under `codex/`.
|
|
- Implemented Step 1 public API exports and pure core modules.
|
|
- Added `tests/test_step1_core.py`.
|
|
- Ran `uv run pytest`.
|
|
- Ran `uv run ruff check .`.
|
|
- Ran `uv run ruff format --check .`.
|
|
- Ran `uv run pyright`.
|
|
- Committed Step 4 with `git commit -m "step 4: add digital bar level and status gauges"` before starting Step 5.
|
|
- Read `codex/FEATURES.md`, `codex/ARCHITECTURE.md`, `codex/STEPS.md`, and `codex/AGENTS.md` before Step 5 changes.
|
|
- Implemented Step 5 first catalogue rendering, compass wraparound, examples, README status update, and tests.
|
|
- Ran `uv run pytest`.
|
|
- Ran `uv run ruff check .`.
|
|
- Ran `uv run ruff format .`.
|
|
- Ran `uv run ruff format --check .`.
|
|
- Ran `uv run pyright`.
|
|
- Read `codex/FEATURES.md`, `codex/ARCHITECTURE.md`, `codex/STEPS.md`, and `codex/AGENTS.md` before Step 2 changes.
|
|
- Implemented Step 2 state, sizing, animation, smoothing, runtime API, diagnostics, tests, and README status update.
|
|
- Ran `uv run pytest`.
|
|
- Ran `uv run ruff check .`.
|
|
- Ran `uv run ruff format --check .`.
|
|
- Ran `uv run pyright`.
|
|
- Updated instructions to require a commit after each completed step.
|
|
- Read `codex/FEATURES.md`, `codex/ARCHITECTURE.md`, `codex/STEPS.md`, and `codex/AGENTS.md` before Step 3 changes.
|
|
- Implemented Step 3 widget shells, renderer foundation, draw layer bookkeeping, layout helpers, examples, smoke tests, README status update, and diagnostics renderer fields.
|
|
- Ran `uv run pytest`.
|
|
- Ran `uv run ruff check .`.
|
|
- Ran `uv run ruff format .`.
|
|
- Ran `uv run ruff format --check .`.
|
|
- Ran `uv run pyright`.
|
|
- Committed Step 3 with `git commit -m "step 3: add widget shell and renderer foundation"` before starting Step 4.
|
|
- Read `codex/FEATURES.md`, `codex/ARCHITECTURE.md`, `codex/STEPS.md`, and `codex/AGENTS.md` before Step 4 changes.
|
|
- Implemented Step 4 digital, bar, level, and status rendering, threshold/marker drawing, callback wiring, examples, README status update, and tests.
|
|
- Ran `uv run pytest`.
|
|
- Ran `uv run ruff check .`.
|
|
- Ran `uv run ruff format --check .`.
|
|
- Ran `uv run pyright`.
|
|
|
|
## Next action
|
|
|
|
Commit Step 5, then implement Step 6.
|