fix(perception): reconcile points/pixels scale and stale overlay screenshot
Tests / Test tests.test_device_config.test_device_config_store_settings_get_set_and_defaults failed

Host-agent console showed OCR/UI-tree overlay boxes misaligned with the
displayed screenshot. Two independent causes, both confirmed with real
task data and pixel-level measurement of a user-provided screenshot:

1. perception/ui_parser.py parses XCUITest UI-tree bounds as iOS logical
   points, while scene_builder.py's Scene.width/height (via infer_png_size)
   and OCR bounds are in screenshot pixels, never reconciled (2.0x on
   Retina devices). build_scene() now detects the scale from the first
   x==0,y==0 UI element and rescales OCR bounds down to points-space,
   reporting Scene.width/height in points too. No-op for Android, where
   UiAutomator2 bounds already match pixels 1:1. This also fixes tap()
   landing at the wrong location for OCR-matched text, and lets the IOU
   fusion between UI-tree and OCR elements actually fire on iOS.

2. runtime/task.py captured `scene` (OCR/UI-tree data) before the LLM
   planning call, but re-captured `before_screenshot` for each step
   afterward - a real time gap during which on-screen content (e.g. a
   keyboard) could shift, producing a directional drift between the
   overlay and the displayed image. The first step of each plan batch
   now reuses the screenshot already taken for planning instead of
   capturing a new one; later steps in a multi-step batch still take a
   fresh capture (left unresolved, scoped out by request).

Regression tests added for both the scale reconciliation (using real
828x1792 vs 414x896 numbers) and the screenshot reuse behavior.
This commit is contained in:
2026-07-15 16:12:53 +08:00
parent c50ce1faec
commit 7f439f0db5
4 changed files with 200 additions and 6 deletions
+45 -2
View File
@@ -17,6 +17,14 @@ def build_scene(
) -> Scene:
ui_elements = ui_elements or []
ocr_elements = ocr_elements or []
scale = _detect_pixel_scale(ui_elements, screen_width)
report_width, report_height = screen_width, screen_height
if abs(scale - 1.0) > 1e-6:
ocr_elements = [_scale_element(element, 1.0 / scale) for element in ocr_elements]
report_width = round(screen_width / scale)
report_height = round(screen_height / scale)
merged: list[SceneElement] = []
used_ocr: set[int] = set()
@@ -48,8 +56,8 @@ def build_scene(
merged.append(_with_id(ocr_element, f"ocr-{ocr_index:03d}"))
return Scene(
width=screen_width,
height=screen_height,
width=report_width,
height=report_height,
elements=merged,
ocr_elements=list(ocr_elements),
)
@@ -82,6 +90,41 @@ def infer_png_size(image: bytes | str | Path | None) -> tuple[int, int]:
return (0, 0)
def _detect_pixel_scale(ui_elements: list[SceneElement], screen_width: int) -> float:
"""Detect the ratio between screenshot pixels and the UI tree's own unit (e.g. iOS points).
XCUITest reports UI tree bounds in logical points, which are half (or a
third, on some devices) of the screenshot's pixel dimensions on Retina
displays. Android's UiAutomator2 bounds already match screenshot pixels
1:1, so this returns 1.0 (no-op) for it. The first element rooted at
(0, 0) is used as the reference frame rather than the largest element,
since some system overlay elements report bounds that extend past the
visible screen.
"""
if screen_width <= 0:
return 1.0
for element in ui_elements:
bounds = element.bounds
if bounds.x == 0 and bounds.y == 0 and bounds.width > 0:
scale = screen_width / bounds.width
if scale > 0:
return scale
return 1.0
def _scale_element(element: SceneElement, factor: float) -> SceneElement:
bounds = element.bounds
return replace(
element,
bounds=Bounds(
x=bounds.x * factor,
y=bounds.y * factor,
width=bounds.width * factor,
height=bounds.height * factor,
),
)
def _with_id(element: SceneElement, fallback_id: str) -> SceneElement:
if element.id:
return element