"""How much independent evidence supports a wall measurement, as a score from 0 to 100 -- and what would raise it. from evidence import assess result = assess({"views": 3, "scale": "measured_height", "wall_complete": True, "drawing": "matched", "depth": "validated_known_focal"}) WHAT THE NUMBER IS. An evidence score, not a probability. 80 means strong, independent evidence supports the measurement (the wall is whole in view, the scale is anchored by something real, other sources agree). It does not mean "80 % likely to be right". Next to it the result gives the expected size of the dimension error for the evidence on hand, taken from ``evidence_study.json`` (a simulation: see ``evidence_study.py``), with a floor so a perfect-mask simulation never reads as a promise. WHERE THE POINTS COME FROM (40 + 25 + 15 + 12 + 8 = 100). Each part answers a failure the study measured or that the geometry makes certain: scale anchor, 40 what fixes millimetres. An ASSUMED ceiling height is worth little (about +-9 % typical, 17 % at the 90th percentile: every dimension scales with the guess). A measured wall height or width, a drawing the photo matches, or depth with known camera intrinsics are worth a lot. Depth with an assumed focal length is only as good as the assumed height. Two independent anchors that agree add a little; two that disagree are a conflict and cost points. coverage, 25 is the whole wall in view? A single photo that cuts the wall off under-reports its width by about a quarter (the study), and no other evidence repairs that. More views fixes it by fusing them. independent views, 15 registered photos / video keyframes of the SAME wall. Beyond completeness these cross-check each other; that benefit is plausible but not yet measured on real walls, so it is a modest credit with diminishing returns (video keyframes count half). drawings, 12 a calibrated drawing, and more if the photo's openings match it (drawing_match.py). depth plane, 8 a depth/LiDAR map whose wall plane agrees with the vision mask (depth_validation.py): an independent check of the geometry. CAPS AND CONFLICTS. More photos cannot fix a wrong scale, so while the best scale anchor is only an assumed height or an assumed focal length the total is capped at 45. A scale conflict (two anchors differing by more than 8 %) is reported and subtracts 10. Nothing is ever added for an unregistered photo: a view that does not register to the wall is listed and ignored. Pure functions, standard library only. """ from __future__ import annotations import json import pathlib HERE = pathlib.Path(__file__).resolve().parent ASSUMED_CAP = 45 CONFLICT_PENALTY = 10 DISCLAIMER = ("An evidence score, not a probability. It rises with independent evidence that supports the measurement; it does not say the " "number is right. Expected errors come from a simulation with perfect masks and are a floor on the real error.") FLOOR_PCT = 3.0 # never display an expected error below this: the study assumes a perfect segmentation mask # What the study found, used if evidence_study.json is not beside this file (kept in step by tests/test_evidence.py) _DEFAULT_STUDY = {"height_assumed": {"median_pct": 8.87, "p90_pct": 16.49}, "height_measured_full": {"median_pct": 0.0, "p90_pct": 0.5}, "clipped_single": {"median_pct": 23.86, "p90_pct": 33.38}, "mosaic_3views": {"median_pct": 0.08, "p90_pct": 0.19}, "depth_known_focal": {"median_pct": 1.09, "p90_pct": 2.91}, "depth_assumed_focal": {"median_pct": 7.17, "p90_pct": 17.78}} def study() -> dict: p = HERE / "evidence_study.json" try: return json.loads(p.read_text()) except (OSError, ValueError): return dict(_DEFAULT_STUDY) SCALE_POINTS = { # what each way of fixing the scale is worth (out of 40) "assumed": 6, # an assumed ceiling height "assumed_focal": 8, # depth scale with a focal length guessed from a default field of view "measured_height": 28, "measured_width": 28, "drawing": 30, # the photo's openings matched to a calibrated drawing "depth": 38, # depth/LiDAR scale with known camera intrinsics "laser": 36, # laser distance meter: width and height of the wall read directly (a few mm) "laser_scan": 40, # a laser-scan point cloud: the wall's plane, size and relief to millimetres } AGREE_BONUS = 6 def _scale_anchor(facts): """(points, label, assumed_only, conflict_note). ``facts["anchors"]`` may list several with their mm-per-pixel for the agreement check.""" anchors = facts.get("anchors") or [] kinds = [a["kind"] for a in anchors] if anchors else [facts.get("scale", "assumed")] pts = {k: SCALE_POINTS.get(k, 0) for k in kinds} best_kind = max(pts, key=pts.get) best = pts[best_kind] conflict = None real = [a for a in anchors if a["kind"] not in ("assumed", "assumed_focal") and a.get("mm_per_px")] if len(real) >= 2: vals = [a["mm_per_px"] for a in real] spread = (max(vals) - min(vals)) / min(vals) if spread > 0.08: conflict = f"scale anchors disagree by {spread:.0%} ({', '.join(a['kind'] for a in real)}): resolve before trusting dimensions" else: best = min(40, best + AGREE_BONUS) assumed_only = all(k in ("assumed", "assumed_focal") for k in kinds) return best, best_kind, assumed_only, conflict def views_points(n_registered, n_video_keyframes=0): n = n_registered + 0.5 * n_video_keyframes table = [0, 3, 8, 11, 13, 15] i = int(n) base = table[min(i, 5)] return min(15, base + (table[min(i + 1, 5)] - base) * (n - i) if i < 5 else 15) def band(label: str) -> dict: s = study().get(label, _DEFAULT_STUDY.get(label, {"median_pct": 10, "p90_pct": 20})) return {"typical_pct": round(max(s["median_pct"], FLOOR_PCT), 1), "high_pct": round(max(s["p90_pct"], FLOOR_PCT), 1)} def expected_error(facts, anchor_kind, coverage_complete): """(text, typical_pct, high_pct) for the evidence on hand.""" if not coverage_complete and anchor_kind in ("laser", "laser_scan"): b = band("height_measured_full") return ("the wall's SIZE is fixed by the laser, but only part of the wall has been seen: the state (painted or not) of the rest is unknown until more of it is in view", b["typical_pct"], b["high_pct"]) if not coverage_complete: b = band("clipped_single") return (f"the wall runs out of frame: its width is likely under-reported by about {b['typical_pct']:.0f}% (up to {b['high_pct']:.0f}%) until more of it is in view", b["typical_pct"], b["high_pct"]) key = {"assumed": "height_assumed", "assumed_focal": "depth_assumed_focal", "measured_height": "height_measured_full", "measured_width": "height_measured_full", "drawing": "height_measured_full", "depth": "depth_known_focal", "laser": "height_measured_full", "laser_scan": "height_measured_full"}[anchor_kind] b = band(key) if anchor_kind == "assumed": return (f"dimensions scale with an assumed ceiling height: typically off by about {b['typical_pct']:.0f}%, up to {b['high_pct']:.0f}% or more", b["typical_pct"], b["high_pct"]) if anchor_kind == "assumed_focal": return (f"depth scale with a guessed camera focal length: about {b['typical_pct']:.0f}% typical, up to {b['high_pct']:.0f}%", b["typical_pct"], b["high_pct"]) return (f"about {b['typical_pct']:.0f}% or better in simulation (up to {b['high_pct']:.0f}% at worst); real masks add error on top", b["typical_pct"], b["high_pct"]) def label_of(score): return "High" if score >= 80 else "Good" if score >= 60 else "Fair" if score >= 40 else "Rough" def _raw(facts): anchor, anchor_kind, assumed_only, conflict = _scale_anchor(facts) complete = bool(facts.get("wall_complete")) mosaic = facts.get("views", 1) >= 2 coverage = 25 if complete else (10 if mosaic else 5) views = views_points(int(facts.get("views", 1)), int(facts.get("video_keyframes", 0))) d = facts.get("drawing") # None | "calibrated" | "matched" drawing = {"calibrated": 4, "matched": 12}.get(d, 0) depth_plane = 8 if facts.get("depth_plane_ok") else 0 parts = [("Scale anchor", anchor, 40), ("Wall coverage", coverage, 25), ("Independent views", views, 15), ("Drawings", drawing, 12), ("Depth plane check", depth_plane, 8)] total = sum(p for _, p, _ in parts) - (CONFLICT_PENALTY if conflict else 0) cap = None if assumed_only and total > ASSUMED_CAP: total, cap = ASSUMED_CAP, "capped: the scale is only an assumption, and more photos cannot fix a wrong scale" return max(0, min(100, round(total))), parts, anchor_kind, assumed_only, conflict, complete, cap def assess(facts: dict) -> dict: """``facts``: views (registered photos of this wall, >= 1), video_keyframes (registered keyframes), wall_complete (whole wall in one view or in the fused mosaic), scale (assumed | assumed_focal | measured_height | measured_width | drawing | depth) or anchors [{kind, mm_per_px}], drawing (None | calibrated | matched), depth_plane_ok (a depth map's wall plane agrees with the mask).""" score, parts, anchor_kind, assumed_only, conflict, complete, cap = _raw(facts) text, typ, high = expected_error(facts, anchor_kind, complete) # what each possible addition would be worth right now, honestly computed with the same rules kinds = [a["kind"] for a in (facts.get("anchors") or [])] or [facts.get("scale", "assumed")] ideas = [] for title, change in ( ("Enter the wall's real height (or width)", {"scale": "measured_height"} if assumed_only else None), ("Add a depth / LiDAR scan with the camera's intrinsics", {"scale": "depth", "depth_plane_ok": True} if "depth" not in kinds else None), ("Photograph the rest of the wall (the whole wall in view)", {"wall_complete": True, "views": max(2, facts.get("views", 1) + 1)} if not complete else None), ("Add another overlapping photo or a video of this wall", {"views": facts.get("views", 1) + 1} if facts.get("views", 1) < 5 else None), ("Add a drawing and match it to the photo", {"drawing": "matched"} if facts.get("drawing") != "matched" else None), ("Run a depth plane check", {"depth_plane_ok": True} if not facts.get("depth_plane_ok") else None), ): if change is None: continue new = dict(facts); new.update(change) if "scale" in change: new.pop("anchors", None) gain = _raw(new)[0] - score if gain > 0: ideas.append({"do": title, "gain": gain, "to": score + gain}) ideas.sort(key=lambda x: -x["gain"]) return {"score": score, "label": label_of(score), "parts": [{"name": n, "points": round(p, 1), "max": m} for n, p, m in parts], "penalty": CONFLICT_PENALTY if conflict else 0, "conflict": conflict, "cap": cap, "scale_anchor": anchor_kind, "expected_error": text, "typical_error_pct": typ, "high_error_pct": high, "next": ideas[:4], "disclaimer": DISCLAIMER}