Deploy from GitHub commit 1d59f596c1ba09e37dee8698f4e940a2a4bd3311

app.py

@@ -332,6 +332,89 @@ def _encode_shade(relative: np.ndarray, lo: float, hi: float) -> np.ndarray:
     return np.round((np.clip(relative, lo, hi) - lo) * (255.0 / span)).clip(0, 255).astype(np.uint8)
 
 
+def _dominant_period(field: np.ndarray, axis: int) -> int:
+    """N3 — dominant repeat pitch of a (high-frequency) field along an axis,
+    or 0 if it is not strongly periodic. Mean-abs self-difference over
+    candidate lags on a <=320px decimated copy; a repeating pattern has a deep
+    minimum at its pitch (measured ~0.4x median) while aperiodic shadow fields
+    stay near 1.0x."""
+    h, w = field.shape[:2]
+    full = w if axis == 1 else h
+    scale = max(1, int(np.ceil(full / 320)))
+    ds = field[::scale, ::scale]
+    n = ds.shape[1] if axis == 1 else ds.shape[0]
+    lag_lo = max(10, int(n * 0.05))
+    lag_hi = int(n * 0.5)
+    if lag_hi - lag_lo < 4:
+        return 0
+    diffs = []
+    for lag in range(lag_lo, lag_hi):
+        if axis == 1:
+            d = np.mean(np.abs(ds[:, lag:] - ds[:, :-lag]))
+        else:
+            d = np.mean(np.abs(ds[lag:] - ds[:-lag]))
+        diffs.append(d)
+    diffs_np = np.asarray(diffs)
+    best = float(diffs_np.min())
+    med = float(np.median(diffs_np)) + 1e-6
+    if best / med > 0.55:
+        return 0
+    idx = int(np.nonzero(diffs_np <= best * 1.15)[0][0])
+    # A smooth aperiodic field (a lone shadow blob) is most self-similar at
+    # the smallest lag — a monotone profile, not periodicity. Require a true
+    # interior dip: the profile must RISE (anti-phase) before the minimum.
+    if idx == 0 or float(np.max(diffs_np[:idx])) < best * 1.5:
+        return 0
+    return (lag_lo + idx) * scale
+
+
+def _suppress_periodic_shading(field: np.ndarray) -> np.ndarray:
+    """N3 — strip repeating tile/grout shading from the lighting field.
+
+    The fine median removes thin grout lines, but tile-scale brightness washes
+    (every tile of the old floor shaded the same way) are LARGER than contact
+    shadows, so no scale-based filter can separate them — they bled through as
+    ghost diagonal banding on the replacement floor. Periodicity separates
+    them: the wash repeats at the old floor's tile pitch, real shadows don't.
+    The periodic part of the high-frequency residual is estimated by averaging
+    period-shifted copies (coherent for the pattern, diluted ~1/N for
+    shadows) and subtracted.
+    """
+    h, w = field.shape[:2]
+    sigma = max(8.0, min(h, w) / 14.0)
+    base = cv2.GaussianBlur(field, (0, 0), sigmaX=sigma, sigmaY=sigma)
+    resid = field - base
+    for axis in (1, 0):
+        period = _dominant_period(resid, axis)
+        if not period:
+            continue
+        n = w if axis == 1 else h
+        shifts = [s for s in (-2 * period, -period, period, 2 * period) if abs(s) < int(n * 0.9)]
+        if len(shifts) < 2:
+            continue
+        acc = resid.copy()
+        cnt = np.ones_like(resid)
+        for s in shifts:
+            shifted = np.roll(resid, s, axis=axis)
+            valid = np.ones_like(resid)
+            # roll wraps content across the border; mask the wrapped strip out
+            if axis == 1:
+                if s > 0:
+                    valid[:, :s] = 0
+                else:
+                    valid[:, s:] = 0
+            else:
+                if s > 0:
+                    valid[:s, :] = 0
+                else:
+                    valid[s:, :] = 0
+            acc += shifted * valid
+            cnt += valid
+        periodic = acc / cnt
+        resid = resid - periodic
+    return base + resid
+
+
 # ---------------------------------------------------------------------------
 # B1 — Shadow Map Extraction
 # Luminance-based shade map; returns (encoded_uint8, (lo, hi)) so the frontend
@@ -379,10 +462,17 @@ def build_shade_map(
     # large lighting gradients survive untouched.
     med_k = max(9, int(min(h, w) / 40)) | 1
     filled = cv2.medianBlur(np.clip(filled, 0, 255).astype(np.uint8), med_k).astype(np.float32)
+    # N3 — tile-pitch washes survive the median (they are larger than it);
+    # remove them by periodicity instead of scale.
+    filled = _suppress_periodic_shading(filled)
     sigma = max(8.0, min(h, w) / 28.0)
     smooth = cv2.GaussianBlur(filled, (0, 0), sigmaX=sigma, sigmaY=sigma)
     relative = smooth / median_lum
     relative[mask == 0] = 1.0
+    # N3 — soften shadow depth slightly: reflection sheens and residual
+    # extraction noise read as stains on light replacement floors; a mild
+    # gamma keeps shadow placement while taking the "dirt" edge off.
+    relative = np.where(relative < 1.0, np.power(relative, 0.85), relative)
     lo, hi = _adaptive_shade_range(relative, mask)
     return _encode_shade(relative, lo, hi), (lo, hi)
 
@@ -559,18 +649,31 @@ def fill_enclosed_islands(
     """
     h, w = mask.shape[:2]
     inv = (mask == 0).astype(np.uint8)
-    count, labels, stats, _ = cv2.connectedComponentsWithStats(inv, connectivity=8)
+    kern = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (3, 3))
+    # N2 — sever hairline bridges before labelling: segmentation noise often
+    # connects a small island to a large neighbouring hole (e.g. the blue
+    # accent tile to the doormat in the room-4 reference photo) through a
+    # 1-2px chain, making it inherit that hole's area and protection and
+    # escape the fill.
+    inv_open = cv2.morphologyEx(inv, cv2.MORPH_OPEN, kern)
+    count, labels, stats, _ = cv2.connectedComponentsWithStats(inv_open, connectivity=8)
     out = mask.copy()
     for comp_id in range(1, count):
         x, y, cw, ch, area = stats[comp_id]
         if area > max_area:
             continue
-        if x == 0 or y == 0 or x + cw >= w or y + ch >= h:
+        if x <= 1 or y <= 1 or x + cw >= w - 1 or y + ch >= h - 1:
             continue
-        comp = labels == comp_id
-        if protect is not None and protect[comp].any():
-            continue
-        out[comp] = 1
+        comp = (labels == comp_id).astype(np.uint8)
+        # restore the 1px ring the opening ate, staying inside the real hole
+        comp_full = cv2.bitwise_and(cv2.dilate(comp, kern), inv).astype(bool)
+        if protect is not None and comp_full.any():
+            # N2 — veto only when a meaningful share of the island is a
+            # protected class; a couple of stray protected pixels from a noisy
+            # boundary must not rescue an accent tile from the fill.
+            if float(protect[comp_full].mean()) > 0.10:
+                continue
+        out[comp_full] = 1
     return out
 
 

verify_n1_sim.py

@@ -0,0 +1,422 @@
+"""N1 — horizontal band seams on periodic (geometric) tile assets.
+
+Reproduces the canvas-engine texture path on a steep look-down floor
+(rooms 4/5 of the June-10 test set) for three texture preparations:
+
+  raw       : tile the source as-is (what "wrap" mode does)
+  committed : makeSeamless v2 masked-shift (current organic path)
+  snapped   : proposed period-snap crop — detect the pattern's x/y period by
+              autocorrelation, crop to an integer number of periods, and let
+              it wrap exactly. Falls back to masked-shift when no strong
+              period exists (wood, stone), so organic sources are untouched.
+
+Pass criteria:
+  1. checkered.jpeg classifies "organic" (it is — 2.5 x 1.65 periods).
+  2. Period-snap finds a period; the cropped tile re-classifies as "wrap".
+  3. Seam-spike score (max row-to-row jump / median) of the snapped render
+     is at or below the committed render's, and shows no spike rows.
+  4. rustic-wood.jpg (organic) finds NO period -> falls back unchanged.
+"""
+
+import os
+import numpy as np
+from PIL import Image
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+TILES = os.path.join(HERE, "..", "..", "frontend", "viz2d-demo", "src", "assets", "tiles")
+OUT = os.path.join(HERE, "verify_out")
+os.makedirs(OUT, exist_ok=True)
+
+
+# ---------------------------------------------------------------- engine ports
+def detect_wrap_mode(img):
+    """Exact port of detectWrapMode (canvas-engine.ts)."""
+    h, w, _ = img.shape
+    if w < 4 or h < 4:
+        return "organic", np.inf, np.inf
+
+    def col_diff(xa, xb):
+        return float(np.mean(np.abs(img[:, xa].astype(np.float64) - img[:, xb].astype(np.float64))))
+
+    def row_diff(ya, yb):
+        return float(np.mean(np.abs(img[ya].astype(np.float64) - img[yb].astype(np.float64))))
+
+    mid_x, mid_y = w >> 1, h >> 1
+    internal = max((col_diff(mid_x, mid_x + 1) + row_diff(mid_y, mid_y + 1)) / 2, 1.5)
+    seam_x = col_diff(w - 1, 0) / internal
+    seam_y = row_diff(h - 1, 0) / internal
+    mode = "wrap" if (seam_x < 3 and seam_y < 3) else "organic"
+    return mode, seam_x, seam_y
+
+
+def make_seamless(img):
+    """Exact port of makeSeamless v2 (masked shift)."""
+    h, w, _ = img.shape
+    half_w, half_h = w >> 1, h >> 1
+    band_x = max(2, round(w * 0.12))
+    band_y = max(2, round(h * 0.12))
+
+    def edge(n, band):
+        i = np.arange(n, dtype=np.float64)
+        t = np.minimum(np.minimum(i, n - 1 - i) / band, 1.0)
+        return t * t * (3 - 2 * t)
+
+    m = np.outer(edge(h, band_y), edge(w, band_x))[..., None]
+    shifted = np.roll(img, (-half_h, -half_w), axis=(0, 1)).astype(np.float64)
+    return (img.astype(np.float64) * m + shifted * (1 - m)).astype(np.uint8)
+
+
+def find_period(img, axis):
+    """Proposed: dominant pattern period along an axis (x: axis=1, y: axis=0).
+
+    Mean-abs-diff between the image and itself shifted by each candidate lag;
+    a strongly periodic texture has a deep minimum at the period. Searches a
+    <=320px downsample, then refines at full resolution. Returns the full-res
+    period or None.
+    """
+    raw = np.mean(img.astype(np.float64), axis=2)
+    h, w = raw.shape
+    # High-pass: subtract a 16px low-pass reconstruction so the photo's
+    # lighting gradient doesn't put a floor under the diff at true alignment.
+    lp = np.asarray(Image.fromarray(raw).resize((16, 16), Image.BILINEAR).resize((w, h), Image.BILINEAR))
+    gray = raw - lp
+    full = gray.shape[1] if axis == 1 else gray.shape[0]
+    scale = max(1, int(np.ceil(full / 320)))
+    ds = gray[::scale, ::scale]
+    n = ds.shape[1] if axis == 1 else ds.shape[0]
+
+    lags = np.arange(max(12, int(n * 0.18)), int(n * 0.80))
+    if len(lags) < 4:
+        return None
+    diffs = []
+    for lag in lags:
+        if axis == 1:
+            d = np.mean(np.abs(ds[:, lag:] - ds[:, :-lag]))
+        else:
+            d = np.mean(np.abs(ds[lag:] - ds[:-lag]))
+        diffs.append(d)
+    diffs = np.asarray(diffs)
+
+    med = np.median(diffs) + 1e-6
+    best = diffs.min()
+    # Generous gate: the post-crop wrap re-classification is the real safety
+    # net; this only needs to exclude clearly aperiodic textures (wood ~0.85+,
+    # stone ~0.96 vs checker ~0.46).
+    if best / med > 0.65:
+        return None
+    # fundamental period: smallest lag within 15% of the global minimum
+    idx = np.nonzero(diffs <= best * 1.15)[0][0]
+    coarse = int(lags[idx]) * scale
+
+    # refine at full resolution
+    lo = max(8, coarse - scale - 2)
+    hi = min(full - 1, coarse + scale + 2)
+    best_lag, best_d = None, np.inf
+    for lag in range(lo, hi + 1):
+        if axis == 1:
+            d = np.mean(np.abs(gray[:, lag:] - gray[:, :-lag]))
+        else:
+            d = np.mean(np.abs(gray[lag:] - gray[:-lag]))
+        if d < best_d:
+            best_d, best_lag = d, lag
+    return best_lag
+
+
+def best_crop(img, k_periods, period, axis):
+    """Micro-search +/-5px around k*period for the crop length L that tiles
+    best. The crop [0, L) wraps perfectly iff line L (the true continuation
+    in the source) matches line 0 — so that is the diff to minimize."""
+    n = img.shape[1] if axis == 1 else img.shape[0]
+    target = k_periods * period
+    win = max(4, min(16, period // 4))  # window beats flat-cell degeneracy
+    cands = []
+    for cand in range(max(8, target - 5), min(n - win, target + 5) + 1):
+        if axis == 1:
+            d = np.mean(np.abs(img[:, cand:cand + win].astype(np.float64)
+                               - img[:, 0:win].astype(np.float64)))
+        else:
+            d = np.mean(np.abs(img[cand:cand + win].astype(np.float64)
+                               - img[0:win].astype(np.float64)))
+        cands.append((cand, d))
+    if not cands:
+        return target
+    dmin = min(d for _, d in cands)
+    # among near-ties, prefer the length closest to exactly k periods
+    near = [c for c, d in cands if d <= dmin * 1.15 + 1e-6]
+    return min(near, key=lambda c: abs(c - target))
+
+
+def seam_vs_period_pair(img, crop_len, k, period, axis):
+    """Wrap-seam diff relative to the texture's own k-period-pair diff.
+
+    The wrap seam joins content k periods apart, so the fair yardstick is two
+    interior lines k periods apart in the ORIGINAL image: they match in
+    structure (grout geometry) but differ by per-tile surface noise and
+    accumulated photo-perspective drift — the achievable floor for this seam.
+    """
+    a = img.astype(np.float64)
+    if axis == 0:
+        a = a.transpose(1, 0, 2)  # treat rows as columns; jog becomes vertical
+    n = a.shape[1]
+    dist = min(k * period, n - 1)
+    a0 = max(0, (n - 1 - dist) // 2)  # internal pair, centered, same distance
+    win = max(2, min(8, period // 8))
+    jog = max(2, round(period * 0.04))  # photo-perspective drift tolerance
+
+    def pair_diff(xa, xb):
+        # min over a small perpendicular jog: a slightly skewed lattice still
+        # tiles acceptably (the jog reads as installation tolerance, not a seam)
+        best = np.inf
+        pa = a[:, xa:xa + win]
+        for dy in range(-jog, jog + 1):
+            if dy >= 0:
+                d = np.mean(np.abs(pa[dy:] - a[: a.shape[0] - dy, xb:xb + win]))
+            else:
+                d = np.mean(np.abs(pa[:dy] - a[-dy:, xb:xb + win]))
+            best = min(best, d)
+        return best
+
+    seam = pair_diff(crop_len, 0)
+    # floor = median over several internal pairs at the same distance — a
+    # single pair can land in unrepresentatively flat or busy content
+    starts = range(0, n - dist - win, max(1, (n - dist - win) // 8 or 1))
+    floors = [pair_diff(s + dist, s) for s in starts] or [pair_diff(a0 + dist, a0)]
+    floor_ = float(np.median(floors))
+    return seam / max(floor_, 1e-6)
+
+
+def period_snap(img):
+    """Proposed prepare step: crop to integer periods if strongly periodic and
+    the seam is no worse than the texture's own period-pair noise floor;
+    otherwise fall back to masked shift."""
+    h, w, _ = img.shape
+    px = find_period(img, axis=1)
+    py = find_period(img, axis=0)
+    if px and py:
+        kx, ky = w // px, h // py
+        # the continuation line (k*period) must exist in the source to verify
+        # the wrap; an exact-multiple image keeps one period fewer
+        while kx > 1 and kx * px >= w:
+            kx -= 1
+        while ky > 1 and ky * py >= h:
+            ky -= 1
+        if kx * px < w and ky * py < h \
+                and kx >= 1 and ky >= 1 and kx * px >= 0.4 * w and ky * py >= 0.4 * h:
+            cw = best_crop(img, kx, px, axis=1)
+            ch = best_crop(img, ky, py, axis=0)
+            rx = seam_vs_period_pair(img, cw, kx, px, axis=1)
+            ry = seam_vs_period_pair(img, ch, ky, py, axis=0)
+            if rx < 1.5 and ry < 1.5:
+                return img[:ch, :cw], ("snap", px, py, rx, ry)
+    return make_seamless(img), ("fallback", px, py, None, None)
+
+
+def build_mips(img):
+    mips = [img.astype(np.float64)]
+    cur = img.astype(np.float64)
+    while cur.shape[0] > 1 or cur.shape[1] > 1:
+        h, w, _ = cur.shape
+        nh, nw = max(1, h >> 1), max(1, w >> 1)
+        y0 = np.minimum(2 * np.arange(nh), h - 1)
+        y1 = np.minimum(2 * np.arange(nh) + 1, h - 1)
+        x0 = np.minimum(2 * np.arange(nw), w - 1)
+        x1 = np.minimum(2 * np.arange(nw) + 1, w - 1)
+        cur = (cur[y0][:, x0] + cur[y0][:, x1] + cur[y1][:, x0] + cur[y1][:, x1]) / 4
+        mips.append(cur)
+    return mips
+
+
+def sample_bilinear_wrap(level, x, y):
+    h, w, _ = level.shape
+    x0 = np.clip(np.floor(x), 0, w - 1).astype(np.int64)
+    y0 = np.clip(np.floor(y), 0, h - 1).astype(np.int64)
+    x1 = (x0 + 1) % w
+    y1 = (y0 + 1) % h
+    fx = (x - np.floor(x))[..., None]
+    fy = (y - np.floor(y))[..., None]
+    p00, p10 = level[y0, x0], level[y0, x1]
+    p01, p11 = level[y1, x0], level[y1, x1]
+    return (p00 * (1 - fx) * (1 - fy) + p10 * fx * (1 - fy)
+            + p01 * (1 - fx) * fy + p11 * fx * fy)
+
+
+def render_floor(tex, img_w=900, img_h=700, repeat_w=180.0):
+    """Steep look-down floor like rooms 4/5: asymmetric trapezoid -> deep plane."""
+    th, tw, _ = tex.shape
+    repeat_h = repeat_w * (th / tw)
+    plane_w, plane_h = 900.0, 1600.0
+
+    # image trapezoid (slight asymmetry = synthetic-VP shear) -> plane rect
+    src = np.array([[260, 120], [610, 120], [900, 700], [0, 700]], np.float64)
+    dst = np.array([[0, 0], [plane_w, 0], [plane_w, plane_h], [0, plane_h]], np.float64)
+    A = []
+    for (sx, sy), (dx_, dy_) in zip(src, dst):
+        A.append([sx, sy, 1, 0, 0, 0, -dx_ * sx, -dx_ * sy])
+        A.append([0, 0, 0, sx, sy, 1, -dy_ * sx, -dy_ * sy])
+    b = dst.reshape(-1)
+    hvec = np.linalg.solve(np.asarray(A), b)
+    H = np.append(hvec, 1).reshape(3, 3)
+
+    xs, ys = np.meshgrid(np.arange(img_w, dtype=np.float64), np.arange(img_h, dtype=np.float64))
+
+    def to_plane(px, py):
+        zz = H[2, 0] * px + H[2, 1] * py + H[2, 2]
+        return ((H[0, 0] * px + H[0, 1] * py + H[0, 2]) / zz,
+                (H[1, 0] * px + H[1, 1] * py + H[1, 2]) / zz)
+
+    fx, fy = to_plane(xs, ys)
+    fx1, fy1 = to_plane(xs + 1, ys)
+    fx2, fy2 = to_plane(xs, ys + 1)
+
+    # floor mask: inside the plane rect
+    mask = (fx >= 0) & (fx < plane_w) & (fy >= 0) & (fy < plane_h)
+
+    u = np.mod(fx / repeat_w, 1.0)
+    v = np.mod(fy / repeat_h, 1.0)
+    tcx, tcy = (fx / repeat_w) * tw, (fy / repeat_h) * th
+    du = np.hypot((fx1 / repeat_w) * tw - tcx, (fy1 / repeat_h) * th - tcy)
+    dv = np.hypot((fx2 / repeat_w) * tw - tcx, (fy2 / repeat_h) * th - tcy)
+    footprint = np.maximum(np.maximum(du, dv), 1e-3)
+    lod = np.log2(footprint) + 0.5
+
+    mips = build_mips(tex)
+    max_l = len(mips) - 1
+    l0 = np.clip(np.floor(lod), 0, max_l).astype(np.int64)
+    f = np.clip(lod - l0, 0, 1)
+
+    out = np.zeros((img_h, img_w, 3), np.float64)
+    for lev in range(max_l + 1):
+        sel = mask & (l0 == lev)
+        if not sel.any():
+            continue
+        a = mips[lev]
+        sa = sample_bilinear_wrap(a, u[sel] * a.shape[1], v[sel] * a.shape[0])
+        fb = f[sel][..., None]
+        if lev < max_l:
+            bl = mips[lev + 1]
+            sb = sample_bilinear_wrap(bl, u[sel] * bl.shape[1], v[sel] * bl.shape[0])
+            out[sel] = sa + (sb - sa) * fb
+        else:
+            out[sel] = sa
+    return out.astype(np.uint8), mask
+
+
+def sharpness_profile(render, mask):
+    """Per-row mean |horizontal gradient| inside the floor. Crossfade ghost
+    bands collapse local contrast, so they show up as dips in this profile.
+    Comparing per-row against the raw render cancels the natural LOD falloff."""
+    g = np.mean(render.astype(np.float64), axis=2)
+    grad = np.abs(np.diff(g, axis=1))
+    both = mask[:, :-1] & mask[:, 1:]
+    rows = np.nonzero(both.sum(axis=1) > 200)[0]
+    prof = np.array([np.mean(grad[y, both[y]]) for y in rows])
+    return rows, prof
+
+
+# -------------------------------------------------------------------- run
+def load(name):
+    return np.asarray(Image.open(os.path.join(TILES, name)).convert("RGB"))
+
+
+def main():
+    ok = True
+
+    checker = load("checkered.jpeg")
+    mode, sx, sy = detect_wrap_mode(checker)
+    print(f"checkered.jpeg  : {checker.shape[1]}x{checker.shape[0]}  mode={mode}  "
+          f"seamX={sx:.1f}x  seamY={sy:.1f}x  (threshold 3x)")
+    if mode != "organic":
+        print("  !! expected organic"); ok = False
+
+    snapped, info = period_snap(checker)
+    tag, px, py, csx, csy = info
+    print(f"period-snap     : {tag}  periodX={px} periodY={py}  "
+          f"crop={snapped.shape[1]}x{snapped.shape[0]}  "
+          f"crop-seamX={csx if csx is None else f'{csx:.1f}x'} "
+          f"crop-seamY={csy if csy is None else f'{csy:.1f}x'}")
+    if tag != "snap":
+        print("  !! period-snap did not engage on the checker"); ok = False
+
+    healed = make_seamless(checker)
+
+    # Real-photo renders: saved for visual / golden-image comparison (the
+    # photo's per-tile texture variance defeats simple numeric seam metrics).
+    base_repeat = 180.0
+    snap_repeat = base_repeat * (snapped.shape[1] / checker.shape[1])
+    for name, tex, rep in [("raw", checker, base_repeat),
+                           ("committed", healed, base_repeat),
+                           ("snapped", snapped, snap_repeat)]:
+        render, _ = render_floor(tex, repeat_w=rep)
+        Image.fromarray(render).save(os.path.join(OUT, f"n1_{name}.png"))
+    print(f"photo renders saved to verify_out/n1_*.png (visual check)")
+
+    # ---- synthetic certification: ground truth is known exactly ----------
+    # Perfect checker, period 64, sized to a NON-integer period count so it
+    # classifies organic. The ideal result is the exact 5-period crop tiled
+    # raw; the snapped pipeline must reproduce it pixel-for-pixel.
+    per = 64
+    sw, sh = per * 5 + 37, per * 4 + 21
+    yy, xx = np.mgrid[0:sh, 0:sw]
+    cells = ((xx // (per // 2)) + (yy // (per // 2))) % 2
+    rng = np.random.default_rng(7)
+    noise = rng.normal(0, 4, (sh, sw))
+    synth = np.stack([np.where(cells, 205, 120) + noise,
+                      np.where(cells, 200, 90) + noise,
+                      np.where(cells, 190, 60) + noise], axis=2).clip(0, 255).astype(np.uint8)
+
+    smode, ssx, ssy = detect_wrap_mode(synth)
+    print(f"synthetic checker: {sw}x{sh} period={per}  mode={smode}  "
+          f"seam=({ssx:.1f}x,{ssy:.1f}x)")
+    if smode != "organic":
+        print("  !! synthetic checker should classify organic"); ok = False
+
+    s_snap, s_info = period_snap(synth)
+    print(f"synthetic snap   : {s_info[0]}  periodX={s_info[1]} periodY={s_info[2]}  "
+          f"crop={s_snap.shape[1]}x{s_snap.shape[0]}")
+    if s_info[0] != "snap":
+        print("  !! period-snap did not engage on synthetic checker"); ok = False
+    else:
+        if s_info[1] % per != 0 or s_info[2] % per != 0:
+            print(f"  !! found period not a multiple of {per}"); ok = False
+
+        ideal = synth[:(sh // per) * per, :(sw // per) * per]
+        rep_snap = 180.0 * (s_snap.shape[1] / sw)
+        rep_ideal = 180.0 * (ideal.shape[1] / sw)
+        r_snap, m1 = render_floor(s_snap, repeat_w=rep_snap)
+        r_ideal, m2 = render_floor(ideal, repeat_w=rep_ideal)
+        r_healed, _ = render_floor(make_seamless(synth), repeat_w=180.0)
+        Image.fromarray(r_snap).save(os.path.join(OUT, "n1_synth_snapped.png"))
+        Image.fromarray(r_ideal).save(os.path.join(OUT, "n1_synth_ideal.png"))
+        Image.fromarray(r_healed).save(os.path.join(OUT, "n1_synth_committed.png"))
+
+        m = m1 & m2
+        d_snap = float(np.mean(np.abs(r_snap[m].astype(float) - r_ideal[m].astype(float))))
+        d_healed = float(np.mean(np.abs(r_healed[m].astype(float) - r_ideal[m].astype(float))))
+        print(f"synthetic render : snapped-vs-ideal={d_snap:.2f}  "
+              f"committed-vs-ideal={d_healed:.2f}  (mean abs px)")
+        if d_snap > 3.0:
+            print("  !! snapped render deviates from ideal"); ok = False
+        if d_healed < d_snap:
+            print("  !! masked-shift unexpectedly beats period-snap"); ok = False
+
+    # no-regression: organic wood must NOT engage period-snap
+    wood = load("rustic-wood.jpg")
+    _, winfo = period_snap(wood)
+    print(f"rustic-wood.jpg : period-snap -> {winfo[0]}  "
+          f"(periodX={winfo[1]} periodY={winfo[2]})")
+    if winfo[0] != "fallback":
+        print("  !! wood should fall back to masked-shift"); ok = False
+
+    # informational: how do the other catalog tiles classify?
+    for name in ["floor-natural-stone.jpg", "basalt-outside-wal.jpg", "mosaic-tile.jpg"]:
+        t = load(name)
+        m, a, b = detect_wrap_mode(t)
+        _, i2 = period_snap(t)
+        print(f"{name:24s}: mode={m:7s} seam=({a:.1f}x,{b:.1f}x) snap={i2[0]} px={i2[1]} py={i2[2]}")
+
+    print("\n" + ("ALL N1 CHECKS PASSED" if ok else "N1 CHECKS FAILED"))
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

verify_n2_sim.py

@@ -0,0 +1,76 @@
+"""N2 — fill_enclosed_islands must absorb accent-tile islands even when
+segmentation noise bridges them to a large protected hole or sprinkles a few
+protected pixels over them (the room-4 blue accent tile escaped both ways).
+
+Cases:
+  1. plain enclosed island                          -> filled   (regression)
+  2. island bridged (1px chain) to big mat hole     -> filled   (N2 fix)
+  3. island 30% covered by protect (chair leg)      -> kept     (guard)
+  4. island with 2 stray protected pixels (~1%)     -> filled   (N2 fix)
+  5. hole touching the image border                 -> kept     (guard)
+  6. large hole (over max_area)                     -> kept     (guard)
+"""
+
+import cv2
+import numpy as np
+
+# --- extract the real implementation from app.py ---------------------------
+src = open("app.py").read()
+ns = {"np": np, "cv2": cv2}
+start = src.index("def fill_enclosed_islands")
+end = src.index("\ndef ", start + 10)
+exec(compile(src[start:end], "app.py", "exec"), ns)
+fill_enclosed_islands = ns["fill_enclosed_islands"]
+
+
+def main():
+    h, w = 400, 600
+    mask = np.ones((h, w), np.uint8)
+    protect = np.zeros((h, w), np.uint8)
+
+    # 1. plain island, 20x20
+    mask[50:70, 50:70] = 0
+
+    # 2. island 16x16 + 1px bridge to a big protected mat hole (90x40)
+    mask[200:240, 150:240] = 0          # mat hole
+    protect[200:240, 150:240] = 1       # mat is occluder-protected
+    mask[210:226, 260:276] = 0          # accent island nearby
+    mask[217, 240:260] = 0              # 1px bridge connecting them
+
+    # 3. island 20x20 with 30% protect coverage (a real object remnant)
+    mask[300:320, 60:80] = 0
+    protect[300:320, 60:66] = 1         # 6/20 columns = 30%
+
+    # 4. island 20x20 with 2 stray protected pixels
+    mask[80:100, 400:420] = 0
+    protect[85, 405] = 1
+    protect[92, 412] = 1
+
+    # 5. border-touching hole
+    mask[0:30, 500:540] = 0
+
+    # 6. big hole, over max_area
+    mask[280:360, 380:560] = 0          # 80x180 = 14400
+
+    out = fill_enclosed_islands(mask, protect, max_area=2000)
+
+    checks = [
+        ("1 plain island filled", bool((out[52:68, 52:68] == 1).all())),
+        ("2 bridged island filled", bool((out[212:224, 262:274] == 1).all())),
+        ("2 mat hole kept", bool((out[205:235, 155:235] == 0).all())),
+        ("3 protected island kept", bool((out[302:318, 62:78] == 0).all())),
+        ("4 stray-pixel island filled", bool((out[82:98, 402:418] == 1).all())),
+        ("5 border hole kept", bool((out[2:28, 502:538] == 0).all())),
+        ("6 big hole kept", bool((out[285:355, 385:555] == 0).all())),
+    ]
+    ok = True
+    for name, passed in checks:
+        print(f"  [{'PASS' if passed else 'FAIL'}] {name}")
+        ok &= passed
+
+    print("\n" + ("ALL N2 CHECKS PASSED" if ok else "N2 CHECKS FAILED"))
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

verify_n3_sim.py

@@ -0,0 +1,120 @@
+"""N3 — shade map must drop the old floor's repeating tile wash (ghost
+diagonal banding, room 4) while keeping real lighting: gradients and contact
+shadows. Runs the REAL build_shade_map from app.py on a synthetic floor whose
+components are known exactly, and compares against the pre-N3 pipeline.
+
+Floor luminance = gradient * shadow * periodic tile wash * grout lines.
+  - wash leakage  : correlation of the decoded shade with the wash component
+                    -> must drop >= 60% vs the pre-N3 pipeline
+  - shadow keep   : correlation with the shadow component
+                    -> must stay >= 75% of the pre-N3 pipeline's
+  - gradient keep : decoded left/right brightness ratio within 15% of truth
+"""
+
+import cv2
+import numpy as np
+
+# --- extract the real implementations from app.py ---------------------------
+src = open("app.py").read()
+ns = {"np": np, "cv2": cv2}
+for fn in ["_adaptive_shade_range", "_encode_shade", "_dominant_period",
+           "_suppress_periodic_shading", "build_shade_map"]:
+    start = src.index(f"def {fn}")
+    end = src.index("\ndef ", start + 10)
+    # build_shade_map is followed by another def inside the same block scan
+    exec(compile(src[start:end], "app.py", "exec"), ns)
+
+build_shade_map = ns["build_shade_map"]
+
+
+def build_shade_map_pre_n3(img_np, surface_mask):
+    """The pre-N3 pipeline (median + Gaussian only), for the baseline."""
+    mask = surface_mask.astype(np.uint8)
+    luminance = (img_np[:, :, 0].astype(np.float32) * 0.299
+                 + img_np[:, :, 1].astype(np.float32) * 0.587
+                 + img_np[:, :, 2].astype(np.float32) * 0.114)
+    h, w = mask.shape[:2]
+    median_lum = float(np.median(luminance[mask > 0]))
+    filled = luminance.copy()
+    filled[mask == 0] = median_lum
+    med_k = max(9, int(min(h, w) / 40)) | 1
+    filled = cv2.medianBlur(np.clip(filled, 0, 255).astype(np.uint8), med_k).astype(np.float32)
+    sigma = max(8.0, min(h, w) / 28.0)
+    smooth = cv2.GaussianBlur(filled, (0, 0), sigmaX=sigma, sigmaY=sigma)
+    relative = smooth / median_lum
+    relative[mask == 0] = 1.0
+    lo, hi = ns["_adaptive_shade_range"](relative, mask)
+    return ns["_encode_shade"](relative, lo, hi), (lo, hi)
+
+
+def decode(shade, rng):
+    lo, hi = rng
+    return lo + shade.astype(np.float32) / 255.0 * (hi - lo)
+
+
+def masked_corr(a, b, m):
+    av = a[m] - a[m].mean()
+    bv = b[m] - b[m].mean()
+    den = np.sqrt((av ** 2).sum() * (bv ** 2).sum()) + 1e-9
+    return float((av * bv).sum() / den)
+
+
+def main():
+    H, W = 700, 900
+    yy, xx = np.mgrid[0:H, 0:W].astype(np.float32)
+
+    # known components
+    gradient = 0.85 + 0.5 * (xx / W)                       # window on the right
+    shadow = 1.0 - 0.35 * np.exp(-(((xx - 250) / 90) ** 2 + ((yy - 420) / 60) ** 2))
+    period = 200
+    wash = 1.0 + 0.16 * np.sign(np.sin(2 * np.pi * (xx + yy) / period)
+                                * np.sin(2 * np.pi * (xx - yy) / period))
+    wash = cv2.GaussianBlur(wash, (0, 0), 9)               # soft tile shading
+    grout = np.where((np.mod(xx + yy, period) < 6) | (np.mod(xx - yy, period) < 6), 0.75, 1.0)
+
+    lum = 150.0 * gradient * shadow * wash * grout
+    img = np.repeat(np.clip(lum, 0, 255)[..., None], 3, axis=2).astype(np.uint8)
+    mask = np.ones((H, W), np.uint8)
+    mask[: H // 6] = 0                                     # a wall strip, exercises inpaint
+
+    ok = True
+    res = {}
+    for name, fn in [("pre-N3", build_shade_map_pre_n3), ("N3", build_shade_map)]:
+        shade, rng = fn(img, mask)
+        rel = decode(shade, rng)
+        m = mask.astype(bool)
+        wash_c = masked_corr(rel, wash, m)
+        shadow_c = masked_corr(rel, shadow, m)
+        left = rel[m & (xx < W * 0.25)].mean()
+        right = rel[m & (xx > W * 0.75)].mean()
+        grad_ratio = left / right
+        true_ratio = gradient[m & (xx < W * 0.25)].mean() / gradient[m & (xx > W * 0.75)].mean()
+        res[name] = (wash_c, shadow_c, grad_ratio)
+        print(f"[{name:6s}] wash-corr={wash_c:.3f}  shadow-corr={shadow_c:.3f}  "
+              f"gradient L/R={grad_ratio:.3f} (truth {true_ratio:.3f})")
+
+    wash_drop = 1 - abs(res["N3"][0]) / max(abs(res["pre-N3"][0]), 1e-6)
+    shadow_keep = abs(res["N3"][1]) / max(abs(res["pre-N3"][1]), 1e-6)
+    print(f"wash leakage drop = {wash_drop * 100:.0f}%  (need >= 60%)")
+    print(f"shadow retention  = {shadow_keep * 100:.0f}%  (need >= 75%)")
+    if wash_drop < 0.60:
+        print("  !! periodic wash still leaking"); ok = False
+    if shadow_keep < 0.75:
+        print("  !! real shadow lost"); ok = False
+    true_ratio = gradient[mask.astype(bool) & (xx < W * 0.25)].mean() / \
+        gradient[mask.astype(bool) & (xx > W * 0.75)].mean()
+    if abs(res["N3"][2] - true_ratio) > 0.15 * true_ratio:
+        print("  !! lighting gradient distorted"); ok = False
+
+    # period detector sanity on aperiodic field: pure shadow must NOT register
+    aper = cv2.GaussianBlur((shadow * 40).astype(np.float32), (0, 0), 3)
+    aper_hp = aper - cv2.GaussianBlur(aper, (0, 0), 50)
+    if ns["_dominant_period"](aper_hp, 1) or ns["_dominant_period"](aper_hp, 0):
+        print("  !! aperiodic shadow field misdetected as periodic"); ok = False
+
+    print("\n" + ("ALL N3 CHECKS PASSED" if ok else "N3 CHECKS FAILED"))
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())