# dpg-gauges

Dear PyGui gauge widgets for dashboards and telemetry displays.

## Install

```bash
uv add dpg-gauges
```

For local development from another project:

```bash
uv add --editable ../dpg-gauges
```

## Minimal Example

```python
import dearpygui.dearpygui as dpg
import dpg_gauges as dpgg

dpg.create_context()
with dpg.window(label="Dashboard"):
    dpgg.analog_gauge(tag="rpm", label="RPM", value=3200, max_value=8000, width=220, height=220)
    dpgg.digital_gauge(tag="speed", label="Speed", value=88, unit="km/h", width=220, height=90)

dpg.create_viewport(title="gauges", width=520, height=340)
dpg.setup_dearpygui()
dpg.show_viewport()
dpg.start_dearpygui()
dpg.destroy_context()
```

## Dashboard Example

```python
with dpg.window(label="Engine"):
    with dpgg.gauge_panel(label="Powertrain", width=-1, height=260):
        with dpgg.gauge_grid(columns=3, min_column_width=180):
            dpgg.analog_gauge(tag="rpm", label="RPM", max_value=8000, redline_start=6500)
            dpgg.bar_gauge(tag="boost", label="Boost", max_value=30, unit="psi")
            dpgg.status_light(tag="ecu", label="ECU", state=True)
```

`gauge_grid` is a wrapping, table-backed layout. `columns` is a maximum; if the parent is too
narrow for `columns * min_column_width`, the grid uses fewer columns and continues on the next row
instead of creating a horizontal scrollbar. Gauges with `width=0` or `width=-1` fill their grid cell.

Gauges also accept Dear PyGui's usual `parent` argument for adding a gauge to an
existing container after that container has already been created:

```python
dpg.add_window(tag="data_input", label="Data Input")
dpgg.analog_gauge(tag="rpm", parent="data_input", label="RPM")
```

The `parent` is applied to the gauge's outer group. The gauge's internal drawlist
is then parented to that group.

## GUI-Thread Contract

Dear PyGui item operations must happen on the GUI thread. Gauge creation and runtime updates such as
`set_value`, `update_gauge`, `set_thresholds`, and `delete_gauge` are GUI-thread functions. Worker
threads may produce data, but applications should marshal the latest values to a Dear PyGui frame
callback before calling dpg-gauges APIs.

## Animation And Smoothing

Animation changes the displayed value over a short duration without changing the raw target value.
Smoothing improves readability during high-rate updates.

```python
dpgg.digital_gauge(
    tag="speed",
    animation=dpgg.AnimationConfig(enabled=True, duration=0.15),
    smoothing=dpgg.SmoothingConfig(enabled=True, alpha=0.25, max_step=5),
)
```

Disable animation with `animation=False` for immediate response.

## Thresholds And Markers

Thresholds and markers are visual only; they do not trigger callbacks or alarms.

```python
dpgg.bar_gauge(
    tag="coolant",
    min_value=40,
    max_value=120,
    thresholds=[dpgg.ThresholdBand(100, 120, (255, 45, 45, 150))],
    markers=[dpgg.GaugeMarker(110, (255, 255, 255, 255), thickness=3)],
)
```

Implemented gauge types: analog, digital, bar, level, status light, segmented, compass,
thermometer, battery, and multi-value.