mobile-ui-comparator 0.1.0__py3-none-any.whl

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.
@@ -0,0 +1,304 @@
1
+ from importlib.metadata import version, PackageNotFoundError
2
+ from dataclasses import dataclass, field
3
+ from pathlib import Path
4
+ from typing import List, Optional
5
+ import uuid
6
+ from datetime import datetime
7
+
8
+ try:
9
+ __version__ = version("mobile-ui-comparator")
10
+ except PackageNotFoundError:
11
+ __version__ = "0.1.0"
12
+
13
+
14
+ # ── Result types ──────────────────────────────────────────────────────────────
15
+
16
+ @dataclass
17
+ class AnalyzeResult:
18
+ """Result of a single-image UI audit."""
19
+ status: str # PASS | WARNING | FAIL
20
+ critical: int
21
+ major: int
22
+ minor: int
23
+ total_issues: int
24
+ issues: List[dict]
25
+ ocr_blocks: int
26
+ checks_run: List[str]
27
+ annotated: Optional[Path] = None # numbered bounding-box overlay
28
+ report_json: Optional[Path] = None
29
+ report_html: Optional[Path] = None
30
+ run_dir: Optional[Path] = None
31
+
32
+ def __bool__(self) -> bool:
33
+ return self.status == "PASS"
34
+
35
+
36
+ @dataclass
37
+ class CompareResult:
38
+ """Result of a two-image UI comparison."""
39
+ status: str # PASS | WARNING | FAIL
40
+ critical: int
41
+ major: int
42
+ minor: int
43
+ total_issues: int
44
+ issues: List[dict]
45
+ overall_ssim: float
46
+ canvas_diff_pct: float
47
+ dino_similarity: float
48
+ annotated: Optional[Path] = None # diff_annotated.png
49
+ heatmap: Optional[Path] = None
50
+ report_json: Optional[Path] = None
51
+ report_html: Optional[Path] = None
52
+ run_dir: Optional[Path] = None
53
+
54
+ def __bool__(self) -> bool:
55
+ return self.status == "PASS"
56
+
57
+
58
+ # ── Public API ────────────────────────────────────────────────────────────────
59
+
60
+ def analyze(
61
+ image: str,
62
+ *,
63
+ device: str = "Device",
64
+ output_dir: str = "ui-diff-reports",
65
+ ) -> AnalyzeResult:
66
+ """Audit a single screenshot for UI quality issues.
67
+
68
+ Parameters
69
+ ----------
70
+ image: Local file path or https:// URL to the screenshot.
71
+ device: Label shown in the report (e.g. "Pixel 8 Pro", "Build 42").
72
+ output_dir: Directory where report files are written.
73
+
74
+ Returns
75
+ -------
76
+ AnalyzeResult with `.status`, `.issues`, `.annotated`, `.report_html`, etc.
77
+
78
+ Examples
79
+ --------
80
+ >>> from mobile_ui_comparator import analyze
81
+ >>> result = analyze("screenshot.png", device="Pixel 8 Pro")
82
+ >>> print(result.status, result.critical)
83
+ WARNING 0
84
+ >>> for issue in result.issues:
85
+ ... print(issue["id"], issue["severity"], issue["description"])
86
+ """
87
+ from . import single_analyzer
88
+ from .config import DEFAULT_CONFIG
89
+
90
+ image_path = _resolve(image)
91
+
92
+ transid = _make_transid()
93
+ run_dir = Path(output_dir) / f"analyze_{transid}"
94
+ run_dir.mkdir(parents=True, exist_ok=True)
95
+
96
+ raw = single_analyzer.run(image_path, device_label=device)
97
+
98
+ annotated = single_analyzer.generate_annotated(raw, image_path, run_dir, device_label=device)
99
+ report_json = single_analyzer.save_json(raw, image_path, run_dir)
100
+ report_html = single_analyzer.save_html(raw, image_path, run_dir,
101
+ device_label=device, annotated_path=annotated)
102
+
103
+ return AnalyzeResult(
104
+ status=raw.status,
105
+ critical=raw.critical,
106
+ major=raw.major,
107
+ minor=raw.minor,
108
+ total_issues=raw.total_issues,
109
+ issues=raw.issues,
110
+ ocr_blocks=raw.ocr_blocks,
111
+ checks_run=raw.checks_run,
112
+ annotated=annotated,
113
+ report_json=report_json,
114
+ report_html=report_html,
115
+ run_dir=run_dir,
116
+ )
117
+
118
+
119
+ def compare(
120
+ image_a: str,
121
+ image_b: str,
122
+ *,
123
+ device_a: str = "Device A",
124
+ device_b: str = "Device B",
125
+ screen: str = "Unknown",
126
+ output_dir: str = "ui-diff-reports",
127
+ threshold: float = 0.85,
128
+ ignore_regions: Optional[List] = None,
129
+ mask_status_bar: bool = True,
130
+ ) -> CompareResult:
131
+ """Compare two mobile screenshots for UI regressions.
132
+
133
+ Parameters
134
+ ----------
135
+ image_a: Local path or https:// URL — the reference / baseline image.
136
+ image_b: Local path or https:// URL — the candidate / build image.
137
+ device_a: Label for the reference image.
138
+ device_b: Label for the candidate image.
139
+ screen: Screen name shown in the report.
140
+ output_dir: Directory where report files are written.
141
+ threshold: SSIM pass threshold 0.0–1.0 (default 0.85).
142
+ ignore_regions: List of (x, y, w, h) tuples to exclude from analysis.
143
+ mask_status_bar: Exclude the OS status bar from analysis (default True).
144
+
145
+ Returns
146
+ -------
147
+ CompareResult with `.status`, `.issues`, `.annotated`, `.report_html`, etc.
148
+
149
+ Examples
150
+ --------
151
+ >>> from mobile_ui_comparator import compare
152
+ >>> result = compare("baseline.png", "build.png",
153
+ ... device_a="Baseline", device_b="Build 123",
154
+ ... screen="Home Screen")
155
+ >>> if not result:
156
+ ... for issue in result.issues:
157
+ ... print(issue["severity"], issue["description"])
158
+ """
159
+ import concurrent.futures as _cf
160
+ from . import (
161
+ phash_gate, dino_similarity, ocr_diff,
162
+ ssim_regions, categorizer, annotator, reporter, normalizer,
163
+ )
164
+ from .config import DEFAULT_CONFIG
165
+ from .reporter import _overall_status
166
+
167
+ ignore_regions = ignore_regions or []
168
+ path_a = _resolve(image_a)
169
+ path_b = _resolve(image_b)
170
+
171
+ transid = _make_transid()
172
+ run_dir = Path(output_dir) / transid
173
+ run_dir.mkdir(parents=True, exist_ok=True)
174
+
175
+ status_bar_ratio = DEFAULT_CONFIG.get("status_bar_ratio", 0.04) if mask_status_bar else 0.0
176
+
177
+ norm = normalizer.run(path_a, path_b, status_bar_ratio=status_bar_ratio)
178
+
179
+ from PIL import Image as _PIL
180
+ _raw_w, _raw_h = _PIL.open(path_a).size
181
+ _sb_px = int(_raw_h * status_bar_ratio)
182
+ _sx, _sy = _raw_w / norm.canvas_w, _raw_h / (norm.canvas_h or 1)
183
+ _ignore_ocr = [(int(x * _sx), int(y * _sy), int(w * _sx), int(h * _sy))
184
+ for x, y, w, h in ignore_regions]
185
+
186
+ with _cf.ThreadPoolExecutor(max_workers=3) as pool:
187
+ f_dino = pool.submit(dino_similarity.run, norm.img_a, norm.img_b,
188
+ canvas_size=(norm.canvas_w, norm.canvas_h))
189
+ f_ocr = pool.submit(ocr_diff.run, path_a, path_b,
190
+ status_bar_px=_sb_px, ignore_regions=_ignore_ocr)
191
+ f_ssim = pool.submit(ssim_regions.run, path_a, path_b,
192
+ img_a_array=norm.img_a, img_b_array=norm.img_b,
193
+ ssim_threshold=threshold, status_bar_ratio=0.0,
194
+ ignore_regions=ignore_regions)
195
+ dino_r = f_dino.result()
196
+ ocr_r = f_ocr.result()
197
+ ssim_r = f_ssim.result()
198
+
199
+ regions = dino_r.regions if dino_r.status != dino_similarity.SKIPPED and dino_r.regions \
200
+ else ssim_r.regions
201
+ diff_map = dino_r.diff_map if dino_r.status != dino_similarity.SKIPPED \
202
+ else ssim_r.diff_map
203
+
204
+ categorizer.classify(regions, img_a_path=path_a, img_b_path=path_b,
205
+ canvas_size=(norm.canvas_w, norm.canvas_h))
206
+
207
+ diff_path, heatmap_path = annotator.generate(
208
+ image_a=path_a, image_b=path_b,
209
+ img_a_array=norm.img_a, img_b_array=norm.img_b,
210
+ regions=regions, diff_map=diff_map,
211
+ output_dir=run_dir,
212
+ device_a=device_a, device_b=device_b, screen=screen,
213
+ clip_similarity=dino_r.similarity,
214
+ dl_similarity_label="DINOv2 Similarity",
215
+ )
216
+
217
+ _clip_sim = getattr(dino_r, "similarity", 0.0)
218
+ _phash_r = phash_gate.run(path_a, path_b)
219
+ result_obj = reporter.AnalysisResult(
220
+ device_a=device_a, device_b=device_b, screen=screen,
221
+ image_a=image_a, image_b=image_b,
222
+ phash_distance=_phash_r.distance,
223
+ phash_passed=_phash_r.passed,
224
+ clip_similarity=_clip_sim,
225
+ clip_status=dino_r.status,
226
+ overall_ssim=ssim_r.overall_ssim,
227
+ regions=regions,
228
+ diff_image_path=str(diff_path) if diff_path else None,
229
+ heatmap_path=str(heatmap_path) if heatmap_path else None,
230
+ canvas_height=norm.canvas_h,
231
+ transid=transid,
232
+ ocr_result=ocr_r,
233
+ status_bar_px=norm.crop_top_a,
234
+ masked_ssim_regions=ssim_r.masked_status_bar,
235
+ ignore_regions=ignore_regions or None,
236
+ masked_ignore_ssim=ssim_r.masked_ignore,
237
+ masked_ignore_ocr=0,
238
+ canvas_diff_px=ssim_r.canvas_diff_px,
239
+ canvas_diff_pct=ssim_r.canvas_diff_pct,
240
+ dino_similarity=dino_r.similarity if dino_r.status != dino_similarity.SKIPPED else 0.0,
241
+ dino_status=dino_r.status,
242
+ )
243
+
244
+ json_path = reporter.save_json(result_obj, run_dir)
245
+ html_path = reporter.save_html(result_obj, run_dir, image_a_path=path_a, image_b_path=path_b)
246
+
247
+ final_status = _overall_status(result_obj)
248
+ critical = sum(1 for r in regions if r.severity == "CRITICAL")
249
+ major = sum(1 for r in regions if r.severity == "MAJOR")
250
+ minor = sum(1 for r in regions if r.severity == "MINOR")
251
+
252
+ issues = [
253
+ {
254
+ "id": i + 1,
255
+ "severity": r.severity,
256
+ "category": r.category,
257
+ "zone": r.zone,
258
+ "description": r.description,
259
+ "fix_hint": r.fix_hint,
260
+ "region": {"x": r.x, "y": r.y, "w": r.w, "h": r.h},
261
+ }
262
+ for i, r in enumerate(regions)
263
+ ]
264
+
265
+ return CompareResult(
266
+ status=final_status,
267
+ critical=critical,
268
+ major=major,
269
+ minor=minor,
270
+ total_issues=len(regions),
271
+ issues=issues,
272
+ overall_ssim=ssim_r.overall_ssim,
273
+ canvas_diff_pct=ssim_r.canvas_diff_pct,
274
+ dino_similarity=dino_r.similarity if dino_r.status != dino_similarity.SKIPPED else 0.0,
275
+ annotated=diff_path,
276
+ heatmap=heatmap_path,
277
+ report_json=json_path,
278
+ report_html=html_path,
279
+ run_dir=run_dir,
280
+ )
281
+
282
+
283
+ # ── Helpers ───────────────────────────────────────────────────────────────────
284
+
285
+ def _make_transid() -> str:
286
+ return datetime.now().strftime("%Y%m%d_%H%M%S") + "_" + uuid.uuid4().hex[:8]
287
+
288
+
289
+ def _resolve(value: str) -> Path:
290
+ """Download a URL to a temp file or return a local Path."""
291
+ if value.startswith("http://") or value.startswith("https://"):
292
+ import tempfile, urllib.request, urllib.error
293
+ suffix = Path(value.split("?")[0]).suffix or ".png"
294
+ tmp = tempfile.NamedTemporaryFile(suffix=suffix, delete=False)
295
+ try:
296
+ with urllib.request.urlopen(value, timeout=30) as resp:
297
+ tmp.write(resp.read())
298
+ finally:
299
+ tmp.close()
300
+ return Path(tmp.name)
301
+ p = Path(value)
302
+ if not p.exists():
303
+ raise FileNotFoundError(f"Image not found: {value}")
304
+ return p
@@ -0,0 +1,136 @@
1
+ from pathlib import Path
2
+ from typing import List, Optional, Tuple
3
+
4
+ import cv2
5
+ import numpy as np
6
+ from PIL import Image, ImageDraw, ImageFont
7
+
8
+ from .ssim_regions import DiffRegion
9
+
10
+ SEVERITY_COLORS = {
11
+ "CRITICAL": (220, 38, 38),
12
+ "MAJOR": (234, 115, 22),
13
+ "MINOR": (234, 179, 8),
14
+ }
15
+
16
+ HEADER_HEIGHT = 80
17
+ FOOTER_HEIGHT = 50
18
+ LABEL_FONT_SIZE = 18
19
+ PADDING = 10
20
+
21
+
22
+ def _pil_font(size: int):
23
+ try:
24
+ return ImageFont.truetype("/System/Library/Fonts/Helvetica.ttc", size)
25
+ except Exception:
26
+ return ImageFont.load_default()
27
+
28
+
29
+ def _draw_regions_on_image(
30
+ img: np.ndarray,
31
+ regions: List[DiffRegion],
32
+ scale_x: float = 1.0,
33
+ scale_y: float = 1.0,
34
+ ) -> np.ndarray:
35
+ out = img.copy()
36
+ for r in regions:
37
+ color = SEVERITY_COLORS.get(r.severity, (255, 0, 0))
38
+ bgr = (color[2], color[1], color[0])
39
+ x1 = int(r.x * scale_x)
40
+ y1 = int(r.y * scale_y)
41
+ x2 = int((r.x + r.w) * scale_x)
42
+ y2 = int((r.y + r.h) * scale_y)
43
+ cv2.rectangle(out, (x1, y1), (x2, y2), bgr, 2)
44
+ label = f"#{r.id}"
45
+ (tw, th), _ = cv2.getTextSize(label, cv2.FONT_HERSHEY_SIMPLEX, 0.55, 1)
46
+ cv2.rectangle(out, (x1, y1 - th - 4), (x1 + tw + 4, y1), bgr, -1)
47
+ cv2.putText(out, label, (x1 + 2, y1 - 2), cv2.FONT_HERSHEY_SIMPLEX, 0.55, (255, 255, 255), 1)
48
+ return out
49
+
50
+
51
+ def generate(
52
+ image_a: Path,
53
+ image_b: Path,
54
+ regions: List[DiffRegion],
55
+ diff_map: np.ndarray,
56
+ output_dir: Path,
57
+ device_a: str = "Device A",
58
+ device_b: str = "Device B",
59
+ screen: str = "",
60
+ clip_similarity: float = 0.0,
61
+ no_heatmap: bool = False,
62
+ img_a_array: Optional[np.ndarray] = None,
63
+ img_b_array: Optional[np.ndarray] = None,
64
+ dl_similarity_label: str = "DL Similarity",
65
+ ) -> Tuple[Path, Path]:
66
+ output_dir = Path(output_dir)
67
+ output_dir.mkdir(parents=True, exist_ok=True)
68
+
69
+ # Prefer pre-normalized arrays: regions are in normalized canvas coords so
70
+ # using the normalized images ensures boxes align correctly with app content
71
+ # and the OS status bar / nav bar (already cropped) never appear in the diff.
72
+ img_a_orig = img_a_array if img_a_array is not None else np.array(Image.open(image_a).convert("RGB"))
73
+ img_b_orig = img_b_array if img_b_array is not None else np.array(Image.open(image_b).convert("RGB"))
74
+
75
+ # Resize both to same height for side-by-side
76
+ target_h = min(img_a_orig.shape[0], img_b_orig.shape[0])
77
+ scale_a = target_h / img_a_orig.shape[0]
78
+ scale_b = target_h / img_b_orig.shape[0]
79
+
80
+ img_a_disp = cv2.resize(img_a_orig, (int(img_a_orig.shape[1] * scale_a), target_h))
81
+ img_b_disp = cv2.resize(img_b_orig, (int(img_b_orig.shape[1] * scale_b), target_h))
82
+
83
+ # Scale regions to display size (regions are in normalized canvas coords)
84
+ img_a_annotated = _draw_regions_on_image(img_a_disp, regions, scale_a, scale_a)
85
+ img_b_annotated = _draw_regions_on_image(img_b_disp, regions, scale_b, scale_b)
86
+
87
+ sep = np.ones((target_h, 4, 3), dtype=np.uint8) * 80
88
+ canvas = np.hstack([img_a_annotated, sep, img_b_annotated])
89
+
90
+ # Convert to PIL for text overlay
91
+ pil = Image.fromarray(canvas)
92
+ cw, ch = pil.size
93
+ total_h = HEADER_HEIGHT + ch + FOOTER_HEIGHT
94
+ final = Image.new("RGB", (cw, total_h), (30, 30, 30))
95
+ final.paste(pil, (0, HEADER_HEIGHT))
96
+
97
+ draw = ImageDraw.Draw(final)
98
+ font_lg = _pil_font(22)
99
+ font_sm = _pil_font(14)
100
+
101
+ # Header
102
+ title = f"MOBILE UI COMPARATOR | {screen}" if screen else "MOBILE UI COMPARATOR"
103
+ draw.text((PADDING, 8), title, fill=(255, 255, 255), font=font_lg)
104
+ draw.text((PADDING, 36), f"A: {device_a}", fill=(180, 180, 180), font=font_sm)
105
+ draw.text((PADDING + 200, 36), f"B: {device_b}", fill=(180, 180, 180), font=font_sm)
106
+ similarity_str = f"{dl_similarity_label}: {clip_similarity:.1f}%"
107
+ draw.text((cw - 220, 36), similarity_str, fill=(180, 180, 180), font=font_sm)
108
+
109
+ # Footer — category counts
110
+ from collections import Counter
111
+ cats = Counter(getattr(r, "category", "SPACING") for r in regions)
112
+ footer_text = " ".join(f"{k}:{v}" for k, v in cats.items())
113
+ total_issues = len(regions)
114
+ critical = sum(1 for r in regions if r.severity == "CRITICAL")
115
+ major = sum(1 for r in regions if r.severity == "MAJOR")
116
+ minor = sum(1 for r in regions if r.severity == "MINOR")
117
+ footer = f"Issues: {total_issues} CRITICAL:{critical} MAJOR:{major} MINOR:{minor} {footer_text}"
118
+ draw.text((PADDING, HEADER_HEIGHT + ch + 10), footer, fill=(200, 200, 200), font=font_sm)
119
+
120
+ diff_path = output_dir / "diff_annotated.png"
121
+ final.save(diff_path)
122
+
123
+ # Heatmap
124
+ heatmap_path = None
125
+ if not no_heatmap and diff_map is not None:
126
+ diff_uint8 = (np.clip(1.0 - diff_map, 0, 1) * 255).astype(np.uint8)
127
+ heatmap = cv2.applyColorMap(diff_uint8, cv2.COLORMAP_JET)
128
+ heatmap_rgb = cv2.cvtColor(heatmap, cv2.COLOR_BGR2RGB)
129
+
130
+ # Overlay on Image A at 50% opacity
131
+ base = cv2.resize(img_a_orig, (diff_map.shape[1], diff_map.shape[0]))
132
+ overlay = cv2.addWeighted(base, 0.5, heatmap_rgb, 0.5, 0)
133
+ heatmap_path = output_dir / "heatmap.png"
134
+ Image.fromarray(overlay).save(heatmap_path)
135
+
136
+ return diff_path, heatmap_path
@@ -0,0 +1,80 @@
1
+ from typing import List
2
+
3
+ import cv2
4
+ import numpy as np
5
+ from PIL import Image
6
+
7
+ from .ssim_regions import DiffRegion
8
+ from .logger import get
9
+
10
+ log = get("categorizer")
11
+
12
+
13
+ def _detect_color_diff(region: DiffRegion, img_a: np.ndarray, img_b: np.ndarray) -> bool:
14
+ """Returns True if the region differs in color but not in grayscale structure."""
15
+ x, y, w, h = region.x, region.y, region.w, region.h
16
+ patch_a = img_a[y : y + h, x : x + w]
17
+ patch_b = img_b[y : y + h, x : x + w]
18
+
19
+ if patch_a.size == 0 or patch_b.size == 0:
20
+ return False
21
+
22
+ # Compare color channels vs grayscale
23
+ color_diff = np.mean(np.abs(patch_a.astype(float) - patch_b.astype(float)))
24
+ gray_a = cv2.cvtColor(patch_a, cv2.COLOR_RGB2GRAY).astype(float)
25
+ gray_b = cv2.cvtColor(patch_b, cv2.COLOR_RGB2GRAY).astype(float)
26
+ gray_diff = np.mean(np.abs(gray_a - gray_b))
27
+
28
+ return color_diff > 30 and gray_diff < 20
29
+
30
+
31
+ def classify(
32
+ regions: List[DiffRegion],
33
+ img_a_path=None,
34
+ img_b_path=None,
35
+ canvas_size=None,
36
+ ) -> List[DiffRegion]:
37
+ """Assign a category to each DiffRegion using heuristic rules."""
38
+ img_a = np.array(Image.open(img_a_path).convert("RGB")) if img_a_path else None
39
+ img_b = np.array(Image.open(img_b_path).convert("RGB")) if img_b_path else None
40
+
41
+ if canvas_size is not None:
42
+ cw, ch = canvas_size
43
+ if img_a is not None:
44
+ img_a = cv2.resize(img_a, (cw, ch))
45
+ if img_b is not None:
46
+ img_b = cv2.resize(img_b, (cw, ch))
47
+
48
+ screen_height = canvas_size[1] if canvas_size else None
49
+
50
+ log.debug("Categorizing %d regions (canvas=%s)", len(regions), canvas_size)
51
+
52
+ for r in regions:
53
+ # COLOR — low color diff, high grayscale similarity
54
+ if img_a is not None and img_b is not None and _detect_color_diff(r, img_a, img_b):
55
+ r.category = "COLOR"
56
+ log.debug(" #%d [%d,%d,%d,%d] → COLOR (color diff detected)", r.id, r.x, r.y, r.w, r.h)
57
+ continue
58
+
59
+ aspect = r.w / r.h if r.h > 0 else 1.0
60
+ is_thin = r.h < 30 or r.w < 30
61
+ is_wide_short = aspect > 5.0
62
+ is_top = screen_height is not None and (r.y + r.h / 2) < screen_height * 0.25
63
+
64
+ if is_thin:
65
+ r.category = "SPACING"
66
+ elif is_wide_short and is_top:
67
+ r.category = "TEXT"
68
+ elif r.w > 50 and r.h > 50:
69
+ r.category = "POSITION"
70
+ else:
71
+ r.category = "SPACING"
72
+
73
+ log.debug(" #%d [%d,%d,%d,%d] aspect=%.1f thin=%s wide_short=%s top=%s → %s",
74
+ r.id, r.x, r.y, r.w, r.h, aspect, is_thin, is_wide_short, is_top, r.category)
75
+
76
+ from collections import Counter
77
+ cat_counts = Counter(getattr(r, "category", "?") for r in regions)
78
+ log.info("Categorizer: %s", dict(cat_counts))
79
+
80
+ return regions