#!/usr/bin/env python3 """Measure how far an object sits above its own shadow. python3 Tools/shadow_gap.py --image Screenshots/demo/review-demo-spawn-view.png \ --object-box 0.52,0.55,0.60,0.75 --out /tmp/gigline/shadow-gap.json Why a measurement instead of another opinion: a still cannot distinguish "the object floats" from "the object stands on a raised kerb and its shadow falls past it onto the road", and a vision model asked to arbitrate gives a different answer each run. The vertical pixel gap between the lowest object pixel and the top of its shadow is objective. Method, deliberately simple and stated so it can be argued with: 1. Crop the region of interest (the object box, fractions of the frame). 2. The object is the set of pixels that differ from the local background - the median colour of the crop's border. 3. The shadow is the darkest connected region *below* the object. 4. Report the gap in pixels between the object's lowest row and the shadow's top row, and the object's height in pixels, so the gap can be read as a fraction of the object. A large gap relative to the object's height is the floating signal; a small gap is contact. The thresholds are arguments, not constants, because the right values depend on the camera. """ from __future__ import annotations import argparse import json import os import sys from PIL import Image DEFAULT_GAP_FRACTION = 0.12 # gap > 12 % of the object's pixel height reads as floating SHADOW_DELTA = 38 # how much darker than the background a pixel must be to be shadow def border_median(image: Image.Image): """Median colour of the crop's border, used as the local background.""" pixels = image.load() width, height = image.size samples = [] step = max(1, width // 60) for x in range(0, width, step): samples.append(pixels[x, 1]) samples.append(pixels[x, height - 2]) for y in range(0, height, max(1, height // 60)): samples.append(pixels[1, y]) samples.append(pixels[width - 2, y]) if not samples: return (128, 128, 128) channels = list(zip(*samples)) return tuple(sorted(channel)[len(channel) // 2] for channel in channels) def classify_pixels(image: Image.Image, background, object_delta=18): """Return two masks: the object (differs from background) and the shadow (darker).""" pixels = image.load() width, height = image.size object_rows = [0] * height shadow_rows = [0] * height for y in range(height): for x in range(width): r, g, b = pixels[x, y] delta = max(abs(r - background[0]), abs(g - background[1]), abs(b - background[2])) luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b background_luminance = (0.2126 * background[0] + 0.7152 * background[1] + 0.0722 * background[2]) # A shadow is a darkened version of the surface; an object is much darker or a # different colour. Classifying by absolute delta alone put every shadow in the # object mask, which is why the first runs reported "no shadow found". ratio = luminance / max(1.0, background_luminance) # A shadow darkens every channel by the same proportion; an object does not. # Comparing the per-channel scale factors is what separates them - an absolute # delta cannot, because a shadow's delta is as large as a dark object's. scales = [rgb / max(1.0, base) for rgb, base in zip((r, g, b), background)] spread = max(scales) - min(scales) if 0.45 <= ratio < 0.90 and spread < 0.15: shadow_rows[y] += 1 elif ratio < 0.45 or delta > object_delta: object_rows[y] += 1 return object_rows, shadow_rows def measure(image_path: str, box, gap_fraction=DEFAULT_GAP_FRACTION) -> dict: image = Image.open(image_path).convert("RGB") width, height = image.size x0, y0, x1, y1 = (int(box[0] * width), int(box[1] * height), int(box[2] * width), int(box[3] * height)) crop = image.crop((x0, y0, x1, y1)) background = border_median(crop) object_rows, shadow_rows = classify_pixels(crop, background) object_rows_nonzero = [y for y, count in enumerate(object_rows) if count > 4] if not object_rows_nonzero: return {"error": "no object found in the box", "background": background} object_top, object_bottom = object_rows_nonzero[0], object_rows_nonzero[-1] object_height = max(1, object_bottom - object_top) # Shadow rows below the object's lowest row. shadow_below = [y for y, count in enumerate(shadow_rows) if y > object_bottom and count > 4] shadow_top = shadow_below[0] if shadow_below else None gap = None if shadow_top is None else shadow_top - object_bottom verdict = "unknown" if gap is not None: verdict = "floating" if gap > object_height * gap_fraction else "contact" return { "image": os.path.abspath(image_path), "box_pixels": [x0, y0, x1, y1], "background": list(background), "object_top_row": object_top, "object_bottom_row": object_bottom, "object_height_px": object_height, "shadow_top_row": shadow_top, "gap_px": gap, "gap_fraction_of_object": None if gap is None else round(gap / object_height, 3), "threshold_fraction": gap_fraction, "verdict": verdict, } def main(argv=None): ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) ap.add_argument("--image", required=True) ap.add_argument("--object-box", required=True, help="x0,y0,x1,y1 as fractions of the frame around the object and its shadow") ap.add_argument("--gap-fraction", type=float, default=DEFAULT_GAP_FRACTION, help="gap/height above this reads as floating (default 0.12)") ap.add_argument("--out", default="/tmp/gigline/shadow-gap.json") args = ap.parse_args(argv) box = [float(v) for v in args.object_box.split(",")] if len(box) != 4: print("error: --object-box needs four comma-separated fractions", file=sys.stderr) return 2 if not os.path.exists(args.image): print(f"error: no such image: {args.image}", file=sys.stderr) return 2 result = measure(args.image, box, args.gap_fraction) os.makedirs(os.path.dirname(os.path.abspath(args.out)) or ".", exist_ok=True) with open(args.out, "w") as handle: json.dump(result, handle, indent=2) print(json.dumps(result, indent=2)) return 0 if result.get("verdict") != "unknown" else 1 if __name__ == "__main__": raise SystemExit(main())