constructelligence's picture
Update code: real-machine G-code adapter, commissioning gate, machine_job runner, pump watchdog firmware, twin completion gate, realism and masking modules (card and weights unchanged)
4eecd03 verified
Raw History Blame Contribute Delete
11.4 kB
"""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}