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.
Files changed (31) hide show
  1. mobile_ui_comparator-0.1.0/.claude/launch.json +11 -0
  2. mobile_ui_comparator-0.1.0/.dockerignore +13 -0
  3. mobile_ui_comparator-0.1.0/.github/workflows/publish.yml +44 -0
  4. mobile_ui_comparator-0.1.0/.gitignore +69 -0
  5. mobile_ui_comparator-0.1.0/Dockerfile +69 -0
  6. mobile_ui_comparator-0.1.0/FLOW.md +279 -0
  7. mobile_ui_comparator-0.1.0/PKG-INFO +933 -0
  8. mobile_ui_comparator-0.1.0/README.md +890 -0
  9. mobile_ui_comparator-0.1.0/docker-compose.yml +26 -0
  10. mobile_ui_comparator-0.1.0/mobile_ui_comparator/__init__.py +304 -0
  11. mobile_ui_comparator-0.1.0/mobile_ui_comparator/annotator.py +136 -0
  12. mobile_ui_comparator-0.1.0/mobile_ui_comparator/categorizer.py +80 -0
  13. mobile_ui_comparator-0.1.0/mobile_ui_comparator/cli.py +566 -0
  14. mobile_ui_comparator-0.1.0/mobile_ui_comparator/clip_similarity.py +109 -0
  15. mobile_ui_comparator-0.1.0/mobile_ui_comparator/config.py +46 -0
  16. mobile_ui_comparator-0.1.0/mobile_ui_comparator/dino_similarity.py +231 -0
  17. mobile_ui_comparator-0.1.0/mobile_ui_comparator/job_queue.py +107 -0
  18. mobile_ui_comparator-0.1.0/mobile_ui_comparator/logger.py +51 -0
  19. mobile_ui_comparator-0.1.0/mobile_ui_comparator/normalizer.py +116 -0
  20. mobile_ui_comparator-0.1.0/mobile_ui_comparator/ocr_diff.py +316 -0
  21. mobile_ui_comparator-0.1.0/mobile_ui_comparator/phash_gate.py +52 -0
  22. mobile_ui_comparator-0.1.0/mobile_ui_comparator/reporter.py +896 -0
  23. mobile_ui_comparator-0.1.0/mobile_ui_comparator/server.py +634 -0
  24. mobile_ui_comparator-0.1.0/mobile_ui_comparator/single_analyzer.py +803 -0
  25. mobile_ui_comparator-0.1.0/mobile_ui_comparator/ssim_regions.py +219 -0
  26. mobile_ui_comparator-0.1.0/mobile_ui_comparator/vision_llm.py +111 -0
  27. mobile_ui_comparator-0.1.0/pyproject.toml +67 -0
  28. mobile_ui_comparator-0.1.0/tests/__init__.py +0 -0
  29. mobile_ui_comparator-0.1.0/tests/test_clip.py +38 -0
  30. mobile_ui_comparator-0.1.0/tests/test_phash.py +52 -0
  31. 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,13 @@
1
+ __pycache__
2
+ **/__pycache__
3
+ *.pyc
4
+ *.pyo
5
+ .git
6
+ .gitignore
7
+ *.md
8
+ tests/
9
+ ui-diff-reports/
10
+ *.png
11
+ *.jpg
12
+ *.jpeg
13
+ .DS_Store
@@ -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.