mobile-ui-comparator 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- mobile_ui_comparator-0.1.0/.claude/launch.json +11 -0
- mobile_ui_comparator-0.1.0/.dockerignore +13 -0
- mobile_ui_comparator-0.1.0/.github/workflows/publish.yml +44 -0
- mobile_ui_comparator-0.1.0/.gitignore +69 -0
- mobile_ui_comparator-0.1.0/Dockerfile +69 -0
- mobile_ui_comparator-0.1.0/FLOW.md +279 -0
- mobile_ui_comparator-0.1.0/PKG-INFO +933 -0
- mobile_ui_comparator-0.1.0/README.md +890 -0
- mobile_ui_comparator-0.1.0/docker-compose.yml +26 -0
- mobile_ui_comparator-0.1.0/mobile_ui_comparator/__init__.py +304 -0
- mobile_ui_comparator-0.1.0/mobile_ui_comparator/annotator.py +136 -0
- mobile_ui_comparator-0.1.0/mobile_ui_comparator/categorizer.py +80 -0
- mobile_ui_comparator-0.1.0/mobile_ui_comparator/cli.py +566 -0
- mobile_ui_comparator-0.1.0/mobile_ui_comparator/clip_similarity.py +109 -0
- mobile_ui_comparator-0.1.0/mobile_ui_comparator/config.py +46 -0
- mobile_ui_comparator-0.1.0/mobile_ui_comparator/dino_similarity.py +231 -0
- mobile_ui_comparator-0.1.0/mobile_ui_comparator/job_queue.py +107 -0
- mobile_ui_comparator-0.1.0/mobile_ui_comparator/logger.py +51 -0
- mobile_ui_comparator-0.1.0/mobile_ui_comparator/normalizer.py +116 -0
- mobile_ui_comparator-0.1.0/mobile_ui_comparator/ocr_diff.py +316 -0
- mobile_ui_comparator-0.1.0/mobile_ui_comparator/phash_gate.py +52 -0
- mobile_ui_comparator-0.1.0/mobile_ui_comparator/reporter.py +896 -0
- mobile_ui_comparator-0.1.0/mobile_ui_comparator/server.py +634 -0
- mobile_ui_comparator-0.1.0/mobile_ui_comparator/single_analyzer.py +803 -0
- mobile_ui_comparator-0.1.0/mobile_ui_comparator/ssim_regions.py +219 -0
- mobile_ui_comparator-0.1.0/mobile_ui_comparator/vision_llm.py +111 -0
- mobile_ui_comparator-0.1.0/pyproject.toml +67 -0
- mobile_ui_comparator-0.1.0/tests/__init__.py +0 -0
- mobile_ui_comparator-0.1.0/tests/test_clip.py +38 -0
- mobile_ui_comparator-0.1.0/tests/test_phash.py +52 -0
- mobile_ui_comparator-0.1.0/tests/test_ssim.py +55 -0
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
{
|
|
2
|
+
"version": "0.0.1",
|
|
3
|
+
"configurations": [
|
|
4
|
+
{
|
|
5
|
+
"name": "mobile-ui-comparator-server",
|
|
6
|
+
"runtimeExecutable": "/Users/subrahmanyam.m/Documents/applications/automationframework/python/mobile-ui-comparator/.venv/bin/uvicorn",
|
|
7
|
+
"runtimeArgs": ["mobile_ui_comparator.server:app", "--host", "0.0.0.0", "--port", "8765", "--workers", "1"],
|
|
8
|
+
"port": 8765
|
|
9
|
+
}
|
|
10
|
+
]
|
|
11
|
+
}
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
name: Publish to PyPI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
tags:
|
|
6
|
+
- "v*.*.*"
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
test:
|
|
10
|
+
runs-on: ubuntu-latest
|
|
11
|
+
strategy:
|
|
12
|
+
matrix:
|
|
13
|
+
python-version: ["3.9", "3.10", "3.11"]
|
|
14
|
+
steps:
|
|
15
|
+
- uses: actions/checkout@v4
|
|
16
|
+
- name: Set up Python ${{ matrix.python-version }}
|
|
17
|
+
uses: actions/setup-python@v5
|
|
18
|
+
with:
|
|
19
|
+
python-version: ${{ matrix.python-version }}
|
|
20
|
+
- name: Install dependencies
|
|
21
|
+
run: |
|
|
22
|
+
pip install -e ".[dev]"
|
|
23
|
+
- name: Run tests (excluding slow CLIP tests)
|
|
24
|
+
run: |
|
|
25
|
+
pytest -v -m "not slow"
|
|
26
|
+
|
|
27
|
+
publish:
|
|
28
|
+
needs: test
|
|
29
|
+
runs-on: ubuntu-latest
|
|
30
|
+
environment: pypi
|
|
31
|
+
permissions:
|
|
32
|
+
id-token: write
|
|
33
|
+
steps:
|
|
34
|
+
- uses: actions/checkout@v4
|
|
35
|
+
- name: Set up Python
|
|
36
|
+
uses: actions/setup-python@v5
|
|
37
|
+
with:
|
|
38
|
+
python-version: "3.11"
|
|
39
|
+
- name: Install build tools
|
|
40
|
+
run: pip install build
|
|
41
|
+
- name: Build package
|
|
42
|
+
run: python -m build
|
|
43
|
+
- name: Publish to PyPI
|
|
44
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*.pyo
|
|
5
|
+
*.pyd
|
|
6
|
+
*.egg
|
|
7
|
+
*.egg-info/
|
|
8
|
+
dist/
|
|
9
|
+
build/
|
|
10
|
+
.eggs/
|
|
11
|
+
*.whl
|
|
12
|
+
MANIFEST
|
|
13
|
+
|
|
14
|
+
# Virtual environments
|
|
15
|
+
.venv/
|
|
16
|
+
venv/
|
|
17
|
+
env/
|
|
18
|
+
.env/
|
|
19
|
+
|
|
20
|
+
# Environment / secrets
|
|
21
|
+
.env
|
|
22
|
+
.env.*
|
|
23
|
+
*.env
|
|
24
|
+
|
|
25
|
+
# Tool caches
|
|
26
|
+
.mypy_cache/
|
|
27
|
+
.ruff_cache/
|
|
28
|
+
.pytest_cache/
|
|
29
|
+
.coverage
|
|
30
|
+
htmlcov/
|
|
31
|
+
*.prof
|
|
32
|
+
|
|
33
|
+
# IDE
|
|
34
|
+
.vscode/
|
|
35
|
+
.idea/
|
|
36
|
+
*.iml
|
|
37
|
+
*.suo
|
|
38
|
+
*.user
|
|
39
|
+
|
|
40
|
+
# macOS
|
|
41
|
+
.DS_Store
|
|
42
|
+
.AppleDouble
|
|
43
|
+
.LSOverride
|
|
44
|
+
|
|
45
|
+
# Reports and run output
|
|
46
|
+
ui-diff-reports/
|
|
47
|
+
|
|
48
|
+
# Uploaded / downloaded test images
|
|
49
|
+
*.png
|
|
50
|
+
*.jpg
|
|
51
|
+
*.jpeg
|
|
52
|
+
*.webp
|
|
53
|
+
*.bmp
|
|
54
|
+
*.tiff
|
|
55
|
+
|
|
56
|
+
# DL model caches (should live in ~/.cache, not in the repo)
|
|
57
|
+
.cache/
|
|
58
|
+
models/
|
|
59
|
+
|
|
60
|
+
# Build / distribution
|
|
61
|
+
dist/
|
|
62
|
+
build/
|
|
63
|
+
|
|
64
|
+
# Logs
|
|
65
|
+
*.log
|
|
66
|
+
run.log
|
|
67
|
+
|
|
68
|
+
# Docker
|
|
69
|
+
.docker/
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Mobile UI Comparator — full build (pHash + SSIM + OCR + DINOv2-small)
|
|
2
|
+
# Expected image size: ~3.5 GB (torch + easyocr + dinov2-small weights)
|
|
3
|
+
|
|
4
|
+
FROM python:3.10-slim
|
|
5
|
+
|
|
6
|
+
# ── System libraries ──────────────────────────────────────────────────────────
|
|
7
|
+
RUN apt-get update && apt-get install -y --no-install-recommends \
|
|
8
|
+
libgl1 \
|
|
9
|
+
libglib2.0-0 \
|
|
10
|
+
libgomp1 \
|
|
11
|
+
curl \
|
|
12
|
+
&& rm -rf /var/lib/apt/lists/*
|
|
13
|
+
|
|
14
|
+
WORKDIR /app
|
|
15
|
+
|
|
16
|
+
# ── Core deps — pHash + SSIM pipeline ────────────────────────────────────────
|
|
17
|
+
RUN pip install --no-cache-dir \
|
|
18
|
+
"imagehash>=4.3.1" \
|
|
19
|
+
"scikit-image>=0.21.0" \
|
|
20
|
+
"opencv-python-headless>=4.8.0" \
|
|
21
|
+
"Pillow>=10.0.0" \
|
|
22
|
+
"numpy>=1.24.0" \
|
|
23
|
+
"click>=8.1.0" \
|
|
24
|
+
"rich>=13.0.0" \
|
|
25
|
+
"fastapi>=0.110.0" \
|
|
26
|
+
"uvicorn[standard]>=0.29.0" \
|
|
27
|
+
"python-multipart>=0.0.9" \
|
|
28
|
+
"certifi"
|
|
29
|
+
|
|
30
|
+
# ── OCR — torch + EasyOCR ────────────────────────────────────────────────────
|
|
31
|
+
RUN pip install --no-cache-dir \
|
|
32
|
+
"torch>=2.2.0,<2.3.0" \
|
|
33
|
+
--extra-index-url https://download.pytorch.org/whl/cpu && \
|
|
34
|
+
pip install --no-cache-dir "easyocr>=1.7.0"
|
|
35
|
+
|
|
36
|
+
# ── transformers (DINOv2) ─────────────────────────────────────────────────────
|
|
37
|
+
RUN pip install --no-cache-dir "transformers>=4.35.0"
|
|
38
|
+
|
|
39
|
+
# ── Application source ────────────────────────────────────────────────────────
|
|
40
|
+
COPY mobile_ui_comparator/ ./mobile_ui_comparator/
|
|
41
|
+
|
|
42
|
+
# ── Bake EasyOCR models into image ───────────────────────────────────────────
|
|
43
|
+
ENV EASYOCR_MODULE_PATH=/root/.EasyOCR
|
|
44
|
+
|
|
45
|
+
RUN python -c "import warnings; warnings.filterwarnings('ignore'); print('Caching EasyOCR English models ...'); import easyocr; easyocr.Reader(['en'], gpu=False, verbose=False); print('EasyOCR OK')"
|
|
46
|
+
|
|
47
|
+
# ── Bake DINOv2-small model into image ────────────────────────────────────────
|
|
48
|
+
ENV HF_HOME=/root/.cache/huggingface
|
|
49
|
+
ENV TRANSFORMERS_OFFLINE=0
|
|
50
|
+
# Disable HF xet protocol — forces standard HTTP download (avoids CAS decode errors)
|
|
51
|
+
ENV HF_HUB_DISABLE_XET=1
|
|
52
|
+
|
|
53
|
+
RUN python -c "import warnings; warnings.filterwarnings('ignore'); print('Caching DINOv2 facebook/dinov2-small ...'); from transformers import AutoImageProcessor, AutoModel; mid='facebook/dinov2-small'; AutoImageProcessor.from_pretrained(mid); AutoModel.from_pretrained(mid); print('DINOv2 OK')"
|
|
54
|
+
|
|
55
|
+
# Lock HF offline at runtime
|
|
56
|
+
ENV TRANSFORMERS_OFFLINE=1
|
|
57
|
+
ENV HF_HUB_OFFLINE=1
|
|
58
|
+
ENV TOKENIZERS_PARALLELISM=false
|
|
59
|
+
|
|
60
|
+
# ── Report storage ────────────────────────────────────────────────────────────
|
|
61
|
+
RUN mkdir -p /app/ui-diff-reports
|
|
62
|
+
VOLUME ["/app/ui-diff-reports"]
|
|
63
|
+
|
|
64
|
+
EXPOSE 8000
|
|
65
|
+
|
|
66
|
+
CMD ["uvicorn", "mobile_ui_comparator.server:app", \
|
|
67
|
+
"--host", "0.0.0.0", \
|
|
68
|
+
"--port", "8000", \
|
|
69
|
+
"--workers", "1"]
|
|
@@ -0,0 +1,279 @@
|
|
|
1
|
+
# Pipeline Flow
|
|
2
|
+
|
|
3
|
+
End-to-end walkthrough of what happens from the moment two screenshots are provided until the HTML report is written.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Overview
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
┌──────────────────────────────────────────────────────────────────────────┐
|
|
11
|
+
│ INPUT │
|
|
12
|
+
│ image_a (URL / local path) image_b (URL / local path) │
|
|
13
|
+
└────────────────────┬─────────────────────────┬───────────────────────────┘
|
|
14
|
+
│ download if URL │ download if URL
|
|
15
|
+
▼ ▼
|
|
16
|
+
temp_a.png (disk) temp_b.png (disk)
|
|
17
|
+
│ │
|
|
18
|
+
┌───────────▼──────────────────────────▼───────────┐
|
|
19
|
+
│ STAGE 1 · pHash Gate │
|
|
20
|
+
│ Tool: imagehash (difference hash, 8×8 DCT) │
|
|
21
|
+
│ Hamming distance of the two hashes │
|
|
22
|
+
│ distance ≤ 15 → PASS → continue │
|
|
23
|
+
│ distance > 15 → ABORT (different screens) │
|
|
24
|
+
└──────────────────────┬────────────────────────────┘
|
|
25
|
+
│ PASS
|
|
26
|
+
┌──────────────────────▼────────────────────────────┐
|
|
27
|
+
│ STAGE 2 · CLIP Semantic Similarity │
|
|
28
|
+
│ Model: openai/clip-vit-base-patch32 (~88 MB) │
|
|
29
|
+
│ Both images → 512-dim feature vectors │
|
|
30
|
+
│ Cosine similarity × 100 = score% │
|
|
31
|
+
│ ≥ 90% → PASS · 70–90% → WARNING · <70% → FAIL │
|
|
32
|
+
└──────────────────────┬────────────────────────────┘
|
|
33
|
+
│
|
|
34
|
+
┌──────────────────────▼────────────────────────────┐
|
|
35
|
+
│ STAGE 2.5 · OCR Text Diff │
|
|
36
|
+
│ Model: EasyOCR English (~50 MB) │
|
|
37
|
+
│ Extracts text blocks + bounding boxes from each │
|
|
38
|
+
│ image. Greedy best-match pairing by text │
|
|
39
|
+
│ similarity (SequenceMatcher ≥ 0.60). │
|
|
40
|
+
│ │
|
|
41
|
+
│ Issues detected: │
|
|
42
|
+
│ TEXT_TRUNCATED — text cut short on device B │
|
|
43
|
+
│ TEXT_WRAPPED — bbox height grew > 60% │
|
|
44
|
+
│ FONT_SIZE_DIFF — same text, different height │
|
|
45
|
+
│ TEXT_MOVED — position shift > 30 px │
|
|
46
|
+
│ TEXT_MISSING — text visible on one device │
|
|
47
|
+
│ │
|
|
48
|
+
│ Status bar (top 4%) and --ignore-region rects │
|
|
49
|
+
│ are excluded before OCR runs. │
|
|
50
|
+
└──────────────────────┬────────────────────────────┘
|
|
51
|
+
│
|
|
52
|
+
┌──────────────────────▼────────────────────────────┐
|
|
53
|
+
│ STAGE 3 · SSIM Region Detection │
|
|
54
|
+
│ Tool: scikit-image ssim + OpenCV findContours │
|
|
55
|
+
│ │
|
|
56
|
+
│ 1. Resize both images to 1080 × ≤ 2400 px │
|
|
57
|
+
│ 2. Convert to grayscale │
|
|
58
|
+
│ 3. Compute full SSIM map (returns per-pixel │
|
|
59
|
+
│ structural similarity score) │
|
|
60
|
+
│ 4. Threshold map → binary diff mask │
|
|
61
|
+
│ 5. findContours → bounding rects of changed │
|
|
62
|
+
│ regions (min area 50 px²) │
|
|
63
|
+
│ 6. Filter out status-bar and --ignore-region │
|
|
64
|
+
│ contours by centre-point │
|
|
65
|
+
│ 7. Compute per-region SSIM score + diff_px / │
|
|
66
|
+
│ diff_pct │
|
|
67
|
+
│ 8. Assign severity: │
|
|
68
|
+
│ CRITICAL SSIM < 0.50 │
|
|
69
|
+
│ MAJOR 0.50 – 0.69 │
|
|
70
|
+
│ MINOR 0.70 – 0.84 │
|
|
71
|
+
└──────────────────────┬────────────────────────────┘
|
|
72
|
+
│
|
|
73
|
+
┌──────────────────────▼────────────────────────────┐
|
|
74
|
+
│ CATEGORIZER │
|
|
75
|
+
│ Tool: pixel-intensity variance + edge density │
|
|
76
|
+
│ │
|
|
77
|
+
│ Each DiffRegion → category: │
|
|
78
|
+
│ SPACING — uniform low-variance diff │
|
|
79
|
+
│ POSITION — shifted edges │
|
|
80
|
+
│ TEXT — high-frequency diff pattern │
|
|
81
|
+
│ COLOR — hue shift, same shape │
|
|
82
|
+
│ PRESENCE — large solid fill │
|
|
83
|
+
└──────────────────────┬────────────────────────────┘
|
|
84
|
+
│
|
|
85
|
+
┌──────────────────────▼────────────────────────────┐
|
|
86
|
+
│ ZONE MAPPER (in reporter.py) │
|
|
87
|
+
│ │
|
|
88
|
+
│ Maps each region's vertical centre (% of canvas) │
|
|
89
|
+
│ to a screen zone and developer priority: │
|
|
90
|
+
│ │
|
|
91
|
+
│ y% Zone Priority │
|
|
92
|
+
│ 0 – 4% Status Bar P4 │
|
|
93
|
+
│ 4 – 12% App Header / Toolbar P2 │
|
|
94
|
+
│ 12 – 42% Profile / Hero P1 │
|
|
95
|
+
│ 42 – 86% Main Content Area P3 │
|
|
96
|
+
│ 86 – 94% Bottom Action Bar P3 │
|
|
97
|
+
│ 94 – 100% Bottom Navigation P1 │
|
|
98
|
+
└──────────────────────┬────────────────────────────┘
|
|
99
|
+
│
|
|
100
|
+
┌──────────────────────▼────────────────────────────┐
|
|
101
|
+
│ ANNOTATOR (annotator.py) │
|
|
102
|
+
│ │
|
|
103
|
+
│ diff_annotated.png │
|
|
104
|
+
│ Side-by-side A | B with numbered bounding │
|
|
105
|
+
│ boxes (red=CRITICAL, orange=MAJOR, yellow=MINOR)│
|
|
106
|
+
│ │
|
|
107
|
+
│ heatmap.png │
|
|
108
|
+
│ SSIM diff overlay: red = pixels that differ, │
|
|
109
|
+
│ green = pixels that match │
|
|
110
|
+
└──────────────────────┬────────────────────────────┘
|
|
111
|
+
│
|
|
112
|
+
┌──────────────────────▼────────────────────────────┐
|
|
113
|
+
│ REPORTER (reporter.py) │
|
|
114
|
+
│ │
|
|
115
|
+
│ report.json │
|
|
116
|
+
│ scores, summary, issues[], ocr_analysis, │
|
|
117
|
+
│ zone_summary, categories, mask info │
|
|
118
|
+
│ │
|
|
119
|
+
│ report.html (self-contained, no CDN) │
|
|
120
|
+
│ • Score cards (pHash / CLIP / SSIM / diff%) │
|
|
121
|
+
│ • 4-image panel (A / B / diff / heatmap) │
|
|
122
|
+
│ • "What to fix" priority action box │
|
|
123
|
+
│ • Issues grouped by zone with collapsible │
|
|
124
|
+
│ <details> per zone, SSIM + diff% per row │
|
|
125
|
+
│ • OCR text issues table │
|
|
126
|
+
│ • Mask summary (status bar / ignore regions) │
|
|
127
|
+
└──────────────────────┬────────────────────────────┘
|
|
128
|
+
│
|
|
129
|
+
┌───────────────────────────────▼──────────────────────────────────────────┐
|
|
130
|
+
│ OUTPUT (ui-diff-reports/<transid>/) │
|
|
131
|
+
│ │
|
|
132
|
+
│ report.html Open in any browser — fully self-contained │
|
|
133
|
+
│ report.json Machine-readable — use in CI or downstream │
|
|
134
|
+
│ diff_annotated.png Visual diff for PR comments │
|
|
135
|
+
│ heatmap.png Per-pixel SSIM heat map │
|
|
136
|
+
│ run.log Timestamped debug log │
|
|
137
|
+
└──────────────────────────────────────────────────────────────────────────┘
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
---
|
|
141
|
+
|
|
142
|
+
## Stage details
|
|
143
|
+
|
|
144
|
+
### Stage 1 — pHash Gate
|
|
145
|
+
|
|
146
|
+
**File:** `phash_gate.py`
|
|
147
|
+
|
|
148
|
+
| Detail | Value |
|
|
149
|
+
|--------|-------|
|
|
150
|
+
| Algorithm | Difference hash (dHash) via `imagehash` |
|
|
151
|
+
| Hash size | 8 × 8 = 64 bits |
|
|
152
|
+
| Distance metric | Hamming distance |
|
|
153
|
+
| Pass threshold | ≤ 15 bits different |
|
|
154
|
+
| Purpose | Reject unrelated screens before expensive DL inference |
|
|
155
|
+
|
|
156
|
+
If the gate fails and `--skip-phash` is not set, the run aborts immediately with an error explaining the images appear to be different screens.
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
|
|
160
|
+
### Stage 2 — CLIP Semantic Similarity
|
|
161
|
+
|
|
162
|
+
**File:** `clip_similarity.py`
|
|
163
|
+
|
|
164
|
+
| Detail | Value |
|
|
165
|
+
|--------|-------|
|
|
166
|
+
| Model | `openai/clip-vit-base-patch32` |
|
|
167
|
+
| Cache | `~/.cache/huggingface/hub/` |
|
|
168
|
+
| Input | RGB PIL image → processor → 224×224 patches |
|
|
169
|
+
| Output | 512-dim L2-normalised feature vector per image |
|
|
170
|
+
| Score | Cosine similarity × 100 (%) |
|
|
171
|
+
| Thresholds | ≥ 90 % PASS · 70–90 % WARNING · < 70 % FAIL |
|
|
172
|
+
|
|
173
|
+
CLIP is loaded once at process start (CLI) or server startup (FastAPI) and kept in memory. Subsequent runs do not reload it.
|
|
174
|
+
|
|
175
|
+
The `HF_HUB_OFFLINE=1` env var is set before loading from cache to prevent background network telemetry. Cleared in a `finally` block.
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
### Stage 2.5 — OCR Text Diff
|
|
180
|
+
|
|
181
|
+
**File:** `ocr_diff.py`
|
|
182
|
+
|
|
183
|
+
| Detail | Value |
|
|
184
|
+
|--------|-------|
|
|
185
|
+
| Engine | EasyOCR English |
|
|
186
|
+
| Cache | `~/.EasyOCR/model/` |
|
|
187
|
+
| Input | Original image (not resized) |
|
|
188
|
+
| Text pairing | Greedy SequenceMatcher, min similarity 0.60 |
|
|
189
|
+
| Min confidence | 0.30 |
|
|
190
|
+
| Min text length | 3 characters |
|
|
191
|
+
|
|
192
|
+
**Masking applied before OCR:**
|
|
193
|
+
- Status bar (top 4% of image height) — auto-excluded
|
|
194
|
+
- `--ignore-region` rects — scaled from SSIM canvas space to original image dimensions using `(raw_w / 1080, raw_h / canvas_h)` scale factors
|
|
195
|
+
|
|
196
|
+
**Issue types and thresholds:**
|
|
197
|
+
|
|
198
|
+
| Type | Trigger | Severity |
|
|
199
|
+
|------|---------|---------|
|
|
200
|
+
| TEXT_TRUNCATED | text ends with `…` or is < 75% of A's length | CRITICAL |
|
|
201
|
+
| TEXT_WRAPPED | bbox height grew > 60% | MAJOR |
|
|
202
|
+
| FONT_SIZE_DIFF | height delta > 15% | MAJOR / CRITICAL |
|
|
203
|
+
| TEXT_MOVED | Δx or Δy > 30 px | MAJOR (> 100/150 px → CRITICAL) |
|
|
204
|
+
| TEXT_MISSING | text found on only one device | MAJOR |
|
|
205
|
+
|
|
206
|
+
---
|
|
207
|
+
|
|
208
|
+
### Stage 3 — SSIM Region Detection
|
|
209
|
+
|
|
210
|
+
**File:** `ssim_regions.py`
|
|
211
|
+
|
|
212
|
+
**Resize target:** 1080 × min(raw_height, 2400) px — preserves aspect ratio, caps very tall screens.
|
|
213
|
+
|
|
214
|
+
**SSIM parameters:**
|
|
215
|
+
- `win_size=11` (11×11 Gaussian window)
|
|
216
|
+
- `data_range=255` (uint8 images)
|
|
217
|
+
- `full=True` → returns per-pixel map in [-1, 1]
|
|
218
|
+
|
|
219
|
+
**Contour pipeline:**
|
|
220
|
+
1. `binary_mask = ssim_map < threshold` (default 0.85)
|
|
221
|
+
2. `cv2.findContours(RETR_EXTERNAL, CHAIN_APPROX_SIMPLE)`
|
|
222
|
+
3. Skip contours with area < 50 px²
|
|
223
|
+
4. Skip contours whose centre falls in status bar or ignore regions
|
|
224
|
+
5. For each surviving contour: compute `region_ssim = mean(ssim_map[y:y+h, x:x+w])`
|
|
225
|
+
6. Count `diff_px = sum(binary_mask[y:y+h, x:x+w] > 0)`; `diff_pct = diff_px / (w×h) × 100`
|
|
226
|
+
|
|
227
|
+
**Canvas-level stats:**
|
|
228
|
+
- `canvas_diff_px = sum(binary_mask > 0)` (entire image)
|
|
229
|
+
- `canvas_diff_pct = canvas_diff_px / (W×H) × 100`
|
|
230
|
+
|
|
231
|
+
---
|
|
232
|
+
|
|
233
|
+
### Categorizer
|
|
234
|
+
|
|
235
|
+
**File:** `categorizer.py`
|
|
236
|
+
|
|
237
|
+
Inspects the cropped diff region pixel values and edge map to assign a visual category. All logic is local numpy / OpenCV — no model inference.
|
|
238
|
+
|
|
239
|
+
| Category | Signal |
|
|
240
|
+
|----------|--------|
|
|
241
|
+
| SPACING | Low variance in the diff mask; large contiguous changed block |
|
|
242
|
+
| POSITION | Edge gradient shifted — same shape at different coordinates |
|
|
243
|
+
| TEXT | High spatial frequency in the diff, small tall bounding box |
|
|
244
|
+
| COLOR | Diff present in colour channels but structural edges match |
|
|
245
|
+
| PRESENCE | Large solid-fill region present in one image but not the other |
|
|
246
|
+
|
|
247
|
+
---
|
|
248
|
+
|
|
249
|
+
### Zone Mapper + Reporter
|
|
250
|
+
|
|
251
|
+
**File:** `reporter.py`
|
|
252
|
+
|
|
253
|
+
Each region's vertical centre as a fraction of canvas height maps to a named zone and developer priority. The HTML report groups all zones into collapsible `<details>` blocks, sorted top → bottom.
|
|
254
|
+
|
|
255
|
+
The **"What to fix"** action box (at the top of the HTML report, before the zone tables) lists each affected zone in priority order with issue counts by severity so a developer knows where to look first without reading all 26+ rows.
|
|
256
|
+
|
|
257
|
+
---
|
|
258
|
+
|
|
259
|
+
## Model caching strategy
|
|
260
|
+
|
|
261
|
+
| Context | When loaded | Reload on next run |
|
|
262
|
+
|---------|------------|-------------------|
|
|
263
|
+
| CLI | On first `compare-ui` invocation | Yes — new process each time |
|
|
264
|
+
| FastAPI server | At startup (`lifespan`) | No — shared across all requests |
|
|
265
|
+
| Docker | Baked into image at `docker build` | Never — `HF_HUB_OFFLINE=1` |
|
|
266
|
+
|
|
267
|
+
For the FastAPI server, module-level globals (`_model`, `_processor` in `clip_similarity.py`; `_reader` in `ocr_diff.py`) hold the loaded objects. A guard at the top of each loader checks `if _model is None` before loading, making re-entrance free.
|
|
268
|
+
|
|
269
|
+
---
|
|
270
|
+
|
|
271
|
+
## Transaction isolation
|
|
272
|
+
|
|
273
|
+
Every run (CLI or API) gets a unique transaction ID:
|
|
274
|
+
|
|
275
|
+
```
|
|
276
|
+
YYYYMMDD_HHMMSS_<8 hex chars> e.g. 20260929_182511_5bb560ee
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
All output files are written under `ui-diff-reports/<transid>/`. Runs never share or overwrite each other's files.
|