Feat/gauge drawing improvements

CLAUDE.md

@@ -201,6 +201,26 @@ Gradle needs JDK 17+ (Crashlytics plugin); the shell default may be JDK 11 and f
   screen, which has no setting of its own. Gauges past `PERFORMANCE_MAX_GAUGES` fall back into the grid,
   not nowhere; the gauge dialog only warns (toast), it does not block.
 
+### Gauge drawer (`renderer/gauge/`)
+* `GaugeDrawer` is shared by the Gauge, Performance, Drag Racing and Brake Boosting screens (phone + AA):
+  any dial change shows on all four. Spec: `doc/specs/gauge-drawing-improvements.md`.
+* **The dial maps values through `GaugeScale`, not `pid.min`/`pid.max`.** It extends the PID range to
+  "nice" steps; progress, labels and ticks must all use `scale.fraction()` or they drift apart.
+  Pure geometry lives in `GaugeGeometry.kt` (unit-tested); keep Canvas out of it.
+* The scale bitmap is cached, so anything that decides *what* goes into it (numbers on/off, scale,
+  zones) must be in its key. Numbers skipped for a still-`null` value were cached numberless for good.
+* End labels of a dial that ends below centre sit beside the stats row; `GaugeGeometry.statsMaxWidth`
+  keeps the row clear. Fix overlaps with draw order (numbers after ticks) before moving labels.
+* Phone dials are centred on what they draw (`GaugeGeometry.dialTopOffset` from start/sweep), not on
+  their square — a 200° arc leaves the lower circle empty.
+* Units: draw `displayUnits(pid.units)` (`renderer/Units.kt`), never `pid.units` directly. ObdMetrics'
+  PID resources spell °C as a bare `C`, and they are not ours to change (shared with exports/logs).
+* Red on the dial = the PID's `alert` thresholds. The scale bitmap cache is keyed by `GaugeScale` and
+  `GaugeRedZones` too — a cache keyed by PID id alone kept a stale scale after a PID edit.
+* Phone cards may be taller than the dial (`GaugeGeometry.cardHeight`); `borderArea` is the card, `top`
+  the dial. Captions belong to the card. `contentHeight`'s bottom pad must be excluded from the height
+  the cards share, or a filled grid scrolls by a few pixels.
+
 ### Connectors (`:datalogger/.../connectors`)
 * One `AdapterConnection` per transport, chosen by `ConnectionManager.obtain()` on
   `pref.adapter.connection.type`. Two Bluetooth transports, deliberately separate:

doc/specs/gauge-drawing-improvements.md

@@ -0,0 +1,88 @@
+# Spec: Gauge drawing improvements
+
+2026-10-08 · branch `feat/gauge-drawing-improvements` · **Status: implemented**
+
+## Summary
+
+Readability, correctness and per-frame cost fixes for the dial gauge (`GaugeDrawer`), taken from a phone Gauge-screen screenshot.
+
+![Phone Gauge screen before](img/gauge-before.png)
+
+**Problem.** Scale labels were thirds of the PID range (`-40, -6, 26, 60 …`, `0.8, 2.7, 4.5 …`). The last part of every dial was painted red whether or not the PID has an alert. End-of-scale labels ran into the ticks and the card border. The min / avg / max row was unlabelled and spaced by fixed offsets. A long value ran past the dial. Four gauges used under half of a portrait screen. A value outside the PID's min..max drew the progress arc past the dial's end (or backwards).
+
+**Scope.** `:screen_renderer` only: `GaugeDrawer`, `GaugeSurfaceRenderer`, new pure `GaugeGeometry.kt`; `renderer/Units.kt` used by every drawer that draws units. `GaugeDrawer` is shared, so items 1–5 and 7–9 also change the gauges of Performance, Drag Racing and Brake Boosting (phone and AA). No preference, query or data changes.
+
+## Behaviour changes
+
+| # | Area | Before | After |
+| --- | --- | --- | --- |
+| 1 | Scale labels | 6 equal parts of `min..max`, rounded (`-40, -6, 26 …`) | "Nice" steps (1, 2, 2.5, 4, 5 × 10ⁿ), 4–7 intervals, the range extended to the nearest step: `-40, 0, 40 … 160`; gear `-2, 0, 2 … 10` |
+| 2 | Red zone | Last ~2 labels / ticks red on every dial (fixed divider indexes) | Red only over the PID's alert ranges (`alert.upperThreshold`..max, min..`alert.lowerThreshold`); none without thresholds |
+| 3 | Label placement | Drawn before the ticks, so the red ticks' glow covered the end labels | Drawn after the ticks; centred at 0.75 r as before, moved inward only if the label would reach past 0.85 r |
+| 4 | Stats row | Fixed offsets from the centre, no captions | Measured, centred, equal gaps; `▼` before min, `▲` before max. Scaled down to fit 90 % of the card and, when the dial ends below its centre, the space left of the end label |
+| 5 | Value text | Fixed size | Shrunk (never enlarged) to 70 % of the dial width with its unit; label / stats stay where they were |
+| 6 | Phone layout | Square cards | When the grid does not scroll, cards share the free height up to 1.5 × width; dial centred, module name / rate stay in the card's top corners |
+| 7 | Out-of-range value | Arc drawn past the end, or backwards below min | Clamped to the dial |
+| 8 | Arc angle | Truncated to whole degrees | Float |
+| 9 | Scale bitmap cache | Keyed by PID id, size, colour; numbers skipped while the value was still `null`, and that numberless dial stayed cached | Also keyed by scale, red zones and whether numbers are drawn; numbers skipped only for non-numeric values; the replaced bitmap is recycled |
+| 11 | Dial position (phone) | Dial square centred in the card; a 200° dial draws nothing below 40° under its centre, so the bottom third of each card was empty | The drawn part of the arc (from its start / sweep angles) is centred in the card (`GaugeGeometry.dialTopOffset`) |
+| 12 | Units | `C` as defined in the ObdMetrics PID resources | `°C` / `°F` on every surface-rendered screen (gauge, Giulia, Trip Info, Performance, status panel) via `displayUnits()`; the PID data, exports and logs keep `C` |
+| 10 | Per frame | New `RadialGradient` per gauge; colour parsed / resolved per frame | Gradient cached per PID and card rect; colours resolved once |
+
+## Settings / keys touched
+
+None.
+
+## Implementation
+
+* `GaugeGeometry.kt` (pure, unit-tested): `GaugeScale.of(min, max)` picks the step by least range extension, then interval count nearest 5; `fraction()` clamps. `GaugeRedZones` turns thresholds into scale fractions. `GaugeGeometry.labelCenterRadius`, `statsMaxWidth`, `fitScale`, `statsRow`, `cardHeight`.
+* Lesson from the first device run: pulling every side label inward by its width put the end label (40° below centre on a 200° dial) into the stats row, which the `▼`/`▲` captions had made wider. The original overlap was draw order (ticks over numbers), not radius.
+* `GaugeDrawer`: `pidScale(metric)` caches scale + zones per PID, invalidated when min/max/thresholds change. Progress, numbers and ticks all use the scale's fraction. Ticks: majors on the labels, minors halfway; outer gray majors outside zones; in each zone the glowing dense ticks plus a solid band over its outer half. `DrawerSettings.dividersCount`, `dividersStepAngle`, `dividerHighlightStart` removed (no caller set them).
+* `GaugeSurfaceRenderer` (phone only, not landscape single-column): `rowHeight = cardHeight + 2 × margin`; `borderRects` take the card height, the dial top is offset by half the slack. The free height excludes `CONTENT_BOTTOM_PADDING`, otherwise a filled grid scrolls by a few pixels.
+
+## Backward compatibility
+
+Visual only. Existing profiles keep their PIDs and ranges; the dial's range may extend slightly past a PID's min/max to the nearest step (gear `-1..10` → `-2..10`), so the progress arc's position for the same value can shift a little. Dials with no alert thresholds lose their decorative red end.
+
+## Tests
+
+`screen_renderer/src/test/.../gauge/GaugeGeometryTest.kt`:
+
+| Test | Pins |
+| --- | --- |
+| temperature scale uses round labels instead of thirds of the range | `-40..160` → `-40, 0, 40 … 160` |
+| gear scale has integer labels instead of 0,8 and 2,7 | `-1..10` → `-2 … 10` |
+| common ranges get round steps without extending the range | 0..100, 0..8000, 0..300, 0..3 |
+| scale always covers the PID range with 4 to 7 intervals | Invariant over assorted ranges |
+| no negative zero label / invalid range falls back to a single interval | Edge cases |
+| value outside the scale sticks to its ends | Item 7 (clamp) |
+| red zones come from the alert thresholds only / thresholds beyond the scale draw no zone | Item 2 |
+| labels keep their radius unless they would reach into the ticks | Item 3 |
+| stats row stays clear of the end label when the dial ends below its centre / uses the card when it ends at or above | Item 4 |
+| stats row is centred with equal gaps / wider than the card is scaled down | Item 4 |
+| value text is only ever shrunk | Item 5 |
+| cards fill the free height up to a limit, stay square when scrolling | Item 6 |
+| phone dial is centred on what it draws / upper half dial moves to the middle / full circle dial stays | Item 11 |
+| `UnitsTest`: bare temperature units get the degree sign / other units are drawn as defined | Item 12 |
+
+## Risks and verification checklist
+
+- [ ] Phone Gauge screen, portrait, 4 gauges: cards fill the height, no scrollbar, module name in the card corner.
+- [ ] Portrait, many gauges (scrolls): cards square as before.
+- [ ] Landscape, 1 and several gauges.
+- [ ] A PID with an upper alert threshold shows red from the threshold; one without shows no red.
+- [ ] Edit a PID's min/max: the dial redraws.
+- [ ] A gauge showing `--` (no value yet) still shows its scale numbers.
+- [ ] End label (e.g. `120`) does not touch the `▲` max value.
+- [ ] Performance, Drag Racing, Brake Boosting gauges (phone + AA DHU): labels readable, no overlap with ticks.
+- [ ] Phone, square (scrolling) cards: dial and stats sit in the middle of the card, the arc's end stays inside it.
+- [ ] Temperatures read `°C` on Gauge, Giulia, Trip Info, Performance and the AA status panel.
+- [ ] `▼` / `▲` render (font fallback) on the target devices.
+
+## Out of scope
+
+* `°C` in the `:app` views (Dashboard, graph marker, DTC details): they format units themselves; `displayUnits` would have to move to `:common` first.
+* Fixing `C` in the ObdMetrics PID resources: a separate repository, and the unit also feeds exports and logs.
+
+* Pre-rendering the progress glow: the arc changes every frame, so it cannot be cached; the `BlurMaskFilter` cost was not measured.
+* Captions in words (`min / avg / max`): would need strings in `:app`'s resources for both locales.

screen_renderer/src/main/java/org/obd/graphs/renderer/AbstractDrawer.kt

@@ -318,7 +318,7 @@ internal abstract class AbstractDrawer(
                     marginLeft += getTextWidth(currentStatusText, statusPaint) + 4F
                     drawText(
                         canvas,
-                        "${it.source.format(castToInt = false)}${it.pid.units ?: ""}",
+                        "${it.source.format(castToInt = false)}${displayUnits(it.pid.units) ?: ""}",
                         marginLeft,
                         top,
                         Color.WHITE,
@@ -343,7 +343,7 @@ internal abstract class AbstractDrawer(
                     marginLeft += getTextWidth(currentStatusText, statusPaint) + 4F
                     drawText(
                         canvas,
-                        "${it.source.format(castToInt = false)}${it.pid.units ?: ""}",
+                        "${it.source.format(castToInt = false)}${displayUnits(it.pid.units) ?: ""}",
                         marginLeft,
                         top,
                         Color.WHITE,

screen_renderer/src/main/java/org/obd/graphs/renderer/Units.kt

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2019-2026, Tomasz Żebrowski
+ *
+ * <p>Licensed to the Apache Software Foundation (ASF) under one or more contributor license
+ * agreements. See the NOTICE file distributed with this work for additional information regarding
+ * copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the License. You may obtain a
+ * copy of the License at
+ *
+ * <p>http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * <p>Unless required by applicable law or agreed to in writing, software distributed under the
+ * License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.obd.graphs.renderer
+
+// The PID definitions (ObdMetrics resources) spell temperatures as a bare "C"; they are shared with
+// exports and logs, so the degree sign is added only where the unit is drawn.
+private val DISPLAY_UNITS =
+    mapOf(
+        "C" to "°C",
+        "F" to "°F"
+    )
+
+/** [units] as drawn on screen. */
+internal fun displayUnits(units: String?): String? = units?.let { DISPLAY_UNITS[it.trim()] ?: it }