← back to Wallco Ai
seamless-detector: half-drop + ISOLATED_MOTIF + scenic-skip refinements
d8f36834e4ecc89717bfc7b49aa1710d823d2380 · 2026-05-24 08:09:53 -0700 · Steve Abrams
Ground-truth pass via graphic-designer subagent on 12 sample designs
revealed three systematic failure modes in the basic edge-pixel diff:
1. **Half-drop repeats** — designs where adjacent rows are offset by 50%
horizontally. Straight pixel-edge diff fails them, but they ARE tileable.
Fix: compute a second diff with np.roll(opposite_edge, dim/2). Verdict
is SEAMLESS_HALFDROP if straight fails but half-drop passes.
2. **Isolated motif on solid background** — centered medallion / spot
illustration on a uniform field. Edge pixels are all background color,
so straight diff is ~0 → falsely passes as seamless. The design isn't
actually a wallpaper repeat.
Fix: compute per-channel variance on each of the 4 edges. If all 4
edges have variance < 25 (tuned on validation sample), emit
ISOLATED_MOTIF verdict regardless of edge-diff. Solid-red-medallion
landed at variance ~0.4; busy edges 200-20000.
3. **Scenic murals** — cactus-pine-scenic, designer-scenic, panoramic etc.
are single-image compositions with intentional non-repeating content
(horizon, atmospheric perspective). Tile-edge tests don't apply.
Fix: SCENIC_CATEGORIES set in lib/seamless-detector.js, mirrors the
set in lib/ghost-detector.js. isScenicCategory() strips colorway
suffix ("designer-scenic · stone-pewter" → "designer-scenic") before
matching. verifySeamless() short-circuits with SKIPPED_SCENIC.
Wired through to:
- scripts/scan-seamless.js: skips scenic categories during the sweep,
emits SKIPPED_SCENIC entries.
- scripts/generate_designs.js: passes opt.category to verifySeamless()
so scenic kind=seamless_tile (yes, that combo exists) skips the gate.
Validation match rate: 9/12 in raw (75%), 7/9 = 78% on non-scenic
(3 correctly identified as scenic and not tested). Remaining mismatches
are dense designs where designer eye and pixel math reasonably disagree.
Also re-implemented seamless-check.py in numpy (vectorized) — same logic,
~10x faster.
Files touched
M lib/seamless-detector.jsM scripts/generate_designs.jsM scripts/scan-seamless.jsM scripts/seamless-check.py
Diff
commit d8f36834e4ecc89717bfc7b49aa1710d823d2380
Author: Steve Abrams <steve@designerwallcoverings.com>
Date: Sun May 24 08:09:53 2026 -0700
seamless-detector: half-drop + ISOLATED_MOTIF + scenic-skip refinements
Ground-truth pass via graphic-designer subagent on 12 sample designs
revealed three systematic failure modes in the basic edge-pixel diff:
1. **Half-drop repeats** — designs where adjacent rows are offset by 50%
horizontally. Straight pixel-edge diff fails them, but they ARE tileable.
Fix: compute a second diff with np.roll(opposite_edge, dim/2). Verdict
is SEAMLESS_HALFDROP if straight fails but half-drop passes.
2. **Isolated motif on solid background** — centered medallion / spot
illustration on a uniform field. Edge pixels are all background color,
so straight diff is ~0 → falsely passes as seamless. The design isn't
actually a wallpaper repeat.
Fix: compute per-channel variance on each of the 4 edges. If all 4
edges have variance < 25 (tuned on validation sample), emit
ISOLATED_MOTIF verdict regardless of edge-diff. Solid-red-medallion
landed at variance ~0.4; busy edges 200-20000.
3. **Scenic murals** — cactus-pine-scenic, designer-scenic, panoramic etc.
are single-image compositions with intentional non-repeating content
(horizon, atmospheric perspective). Tile-edge tests don't apply.
Fix: SCENIC_CATEGORIES set in lib/seamless-detector.js, mirrors the
set in lib/ghost-detector.js. isScenicCategory() strips colorway
suffix ("designer-scenic · stone-pewter" → "designer-scenic") before
matching. verifySeamless() short-circuits with SKIPPED_SCENIC.
Wired through to:
- scripts/scan-seamless.js: skips scenic categories during the sweep,
emits SKIPPED_SCENIC entries.
- scripts/generate_designs.js: passes opt.category to verifySeamless()
so scenic kind=seamless_tile (yes, that combo exists) skips the gate.
Validation match rate: 9/12 in raw (75%), 7/9 = 78% on non-scenic
(3 correctly identified as scenic and not tested). Remaining mismatches
are dense designs where designer eye and pixel math reasonably disagree.
Also re-implemented seamless-check.py in numpy (vectorized) — same logic,
~10x faster.
---
lib/seamless-detector.js | 47 ++++++++++++---
scripts/generate_designs.js | 4 +-
scripts/scan-seamless.js | 8 ++-
scripts/seamless-check.py | 144 ++++++++++++++++++++++++++++++--------------
4 files changed, 147 insertions(+), 56 deletions(-)
diff --git a/lib/seamless-detector.js b/lib/seamless-detector.js
index 6446b18..11369d1 100644
--- a/lib/seamless-detector.js
+++ b/lib/seamless-detector.js
@@ -29,6 +29,23 @@ const path = require('path');
const SCRIPT = path.join(__dirname, '..', 'scripts', 'seamless-check.py');
+// Scenic / mural categories — these are single-image compositions with
+// intentional non-repeating content (sky stripes, atmospheric perspective,
+// panoramic landscape). Pixel-edge tileability tests don't apply.
+// Mirrors SCENIC_CATEGORIES in lib/ghost-detector.js — keep in sync.
+const SCENIC_CATEGORIES = new Set([
+ 'cactus-pine-scenic', 'cactus-11ft-mural', 'tree-mural',
+ 'mural', 'scenic', 'panoramic', 'desert-flora', 'mural-animal',
+ 'mural-scenic', 'designer-scenic',
+]);
+
+function isScenicCategory(category) {
+ if (!category) return false;
+ // category may be "designer-scenic · stone-pewter" — strip colorway suffix
+ const base = category.split(' · ')[0].toLowerCase();
+ return SCENIC_CATEGORIES.has(base);
+}
+
function checkSeamless(imagePath, opts = {}) {
const tolerance = opts.tolerance ?? 12;
const r = spawnSync('python3', [SCRIPT, imagePath], {
@@ -44,22 +61,38 @@ function checkSeamless(imagePath, opts = {}) {
let parsed;
try { parsed = JSON.parse(r.stdout.trim()); }
catch (e) { throw new Error(`seamless-check non-JSON: ${r.stdout.slice(0, 200)}`); }
- const tbFail = parsed.top_bottom_diff > parsed.tolerance;
- const lrFail = parsed.left_right_diff > parsed.tolerance;
- let code = 'SEAMLESS_OK';
- if (tbFail && lrFail) code = 'SEAMLESS_FAIL_BOTH';
- else if (tbFail) code = 'SEAMLESS_FAIL_TB';
- else if (lrFail) code = 'SEAMLESS_FAIL_LR';
+ // The script now returns its own `code` field — pass through. Fall back
+ // to deriving from diffs if an older script version is on PATH.
+ let code = parsed.code;
+ if (!code) {
+ const tbFail = parsed.top_bottom_diff > parsed.tolerance;
+ const lrFail = parsed.left_right_diff > parsed.tolerance;
+ if (parsed.ok) code = 'SEAMLESS';
+ else if (tbFail && lrFail) code = 'SEAMLESS_FAIL_BOTH';
+ else if (tbFail) code = 'SEAMLESS_FAIL_TB';
+ else if (lrFail) code = 'SEAMLESS_FAIL_LR';
+ else code = 'SEAMLESS_FAIL';
+ }
return {
ok: parsed.ok,
top_bottom_diff: parsed.top_bottom_diff,
left_right_diff: parsed.left_right_diff,
+ top_bottom_diff_halfdrop: parsed.top_bottom_diff_halfdrop,
+ left_right_diff_halfdrop: parsed.left_right_diff_halfdrop,
+ top_var: parsed.top_var,
+ bottom_var: parsed.bottom_var,
+ left_var: parsed.left_var,
+ right_var: parsed.right_var,
tolerance: parsed.tolerance,
code,
};
}
async function verifySeamless(imagePath, opts = {}) {
+ // Scenic murals are not tiles — gate trivially passes them.
+ if (isScenicCategory(opts.category)) {
+ return { ok: true, code: 'SKIPPED_SCENIC', scenic: true };
+ }
const r = checkSeamless(imagePath, opts);
if (!r.ok) {
const e = new Error(`tile not seamless: ${r.code} tb=${r.top_bottom_diff} lr=${r.left_right_diff} tol=${r.tolerance}`);
@@ -70,4 +103,4 @@ async function verifySeamless(imagePath, opts = {}) {
return r;
}
-module.exports = { checkSeamless, verifySeamless };
+module.exports = { checkSeamless, verifySeamless, isScenicCategory };
diff --git a/scripts/generate_designs.js b/scripts/generate_designs.js
index db43231..a8f503c 100644
--- a/scripts/generate_designs.js
+++ b/scripts/generate_designs.js
@@ -583,14 +583,14 @@ async function main() {
if (opt.kind === 'seamless_tile' && process.env.WALLCO_SEAMLESS_GATE !== '0') {
const tolerance = parseFloat(process.env.WALLCO_SEAMLESS_TOLERANCE || '12');
try {
- await verifySeamless(outPath, { tolerance });
+ await verifySeamless(outPath, { tolerance, category: opt.category });
} catch (serr) {
if (serr.code === 'SEAMLESS_DEFECT') {
const dr = serr.detector_result;
console.warn(` ⚠ not seamless (${dr.code} tb=${dr.top_bottom_diff} lr=${dr.left_right_diff}) — regenerating once`);
const retryPrompt = prompt + '\n\nABSOLUTE RULE — SEAMLESSLY TILEABLE. Every motif that touches the right edge MUST continue on the left edge at the same height. Every motif that touches the top edge MUST continue on the bottom edge at the same x. No half-elements at the boundary that float without a wrap-around match. The image will be rejected if the seam is visible when tiled.';
generate(retryPrompt, seed + 1, outPath, { kind: opt.kind, category: opt.category });
- const r2 = await verifySeamless(outPath, { tolerance }).catch(e => e);
+ const r2 = await verifySeamless(outPath, { tolerance, category: opt.category }).catch(e => e);
if (r2 && r2.code === 'SEAMLESS_DEFECT') {
console.warn(` ✗ still not seamless after retry — skipping #${seed}`);
continue;
diff --git a/scripts/scan-seamless.js b/scripts/scan-seamless.js
index 6818aec..8e69280 100755
--- a/scripts/scan-seamless.js
+++ b/scripts/scan-seamless.js
@@ -24,7 +24,7 @@
const fs = require('fs');
const path = require('path');
const { spawnSync } = require('child_process');
-const { checkSeamless } = require('../lib/seamless-detector');
+const { checkSeamless, isScenicCategory } = require('../lib/seamless-detector');
const ARGS = process.argv.slice(2);
function arg(name, def) { const i = ARGS.indexOf('--' + name); return i >= 0 ? ARGS[i + 1] : def; }
@@ -121,6 +121,10 @@ function fetchTargets() {
}
async function processOne(row) {
+ // Scenic / mural categories are not tiles — skip the gate entirely.
+ if (isScenicCategory(row.category)) {
+ return { id: row.id, ts: new Date().toISOString(), ok: true, code: 'SKIPPED_SCENIC', category: row.category, source: row.source };
+ }
if (!row.local_path || !fs.existsSync(row.local_path)) {
return { id: row.id, ts: new Date().toISOString(), error: 'file_missing', category: row.category, source: row.source };
}
@@ -131,6 +135,8 @@ async function processOne(row) {
ok: r.ok,
top_bottom_diff: r.top_bottom_diff,
left_right_diff: r.left_right_diff,
+ top_bottom_diff_halfdrop: r.top_bottom_diff_halfdrop,
+ left_right_diff_halfdrop: r.left_right_diff_halfdrop,
code: r.code,
tolerance: r.tolerance,
category: row.category,
diff --git a/scripts/seamless-check.py b/scripts/seamless-check.py
index 1e645c4..5dc27ce 100644
--- a/scripts/seamless-check.py
+++ b/scripts/seamless-check.py
@@ -1,70 +1,122 @@
#!/usr/bin/env python3
"""
-Seamlessness check for wallco.ai pattern PNGs. Compares the top edge to the
-bottom edge and the left edge to the right edge — pure pixel-difference at a
-small downscaled resolution so it's fast. If both edge-pairs match within the
-tolerance, the tile is seamless. If either fails, the image will visibly seam
-when tiled — that violates Steve's standing rule "all patterns must match all
-the way around seamlessly" (2026-05-13).
+Seamlessness check for wallco.ai pattern PNGs.
-Output: prints a JSON line and exits 0 (seamless) or 1 (NOT seamless).
+Three signals (2026-05-24 — refined after ground-truth pass via graphic-designer):
- { "ok": true|false, "top_bottom_diff": <float>, "left_right_diff": <float>,
- "tolerance": <float>, "image": <path> }
+ 1. Straight edge-pixel diff (top↔bottom, left↔right) — basic tileability.
+ 2. Half-drop edge-pixel diff (top↔bottom shifted w/2, left↔right shifted h/2)
+ — half-drop repeats fail signal #1 but pass signal #2; both count as
+ seamless. This was the dominant false-positive on designer-zoo-calm
+ and tropical damask: parrots on the right edge wrap to the LEFT edge
+ of the NEXT ROW DOWN, not the same row.
+ 3. Edge variance — if top AND bottom edges are near-uniform color (variance
+ ~0), the design is a centered spot motif on solid background, not a
+ wallpaper repeat. Signal #1 trivially passes (background ≈ background)
+ but the design isn't actually tileable as a repeat — mark as
+ ISOLATED_MOTIF. Same for left and right edges.
-Tolerance: average per-channel diff in 0–255 space across the edge row/col.
-Default 12 — perceptually clean tiles land under 4; honest soft repeats land
-under 8; visible seams land 15+. Override via SEAMLESS_TOLERANCE env var.
+Verdict precedence (most specific wins):
+ ISOLATED_MOTIF → both axis edges are near-uniform; not a true tile
+ SEAMLESS_HALFDROP → straight fails but half-drop passes; valid repeat
+ SEAMLESS → straight passes; valid repeat
+ SEAMLESS_FAIL_* → straight fails on TB / LR / BOTH and half-drop also fails
+
+Tolerance: average per-channel diff in 0–255 space. Default 12 — perceptually
+clean tiles land under 4; honest soft repeats land under 8; visible seams
+land 15+. Override via SEAMLESS_TOLERANCE env.
+
+Output (backward-compatible: keeps `ok`, `top_bottom_diff`, `left_right_diff`,
+`tolerance`, `image` keys that callers expect):
+
+ { ok, top_bottom_diff, left_right_diff,
+ top_bottom_diff_halfdrop, left_right_diff_halfdrop,
+ top_var, bottom_var, left_var, right_var,
+ tolerance, code, image }
+
+Exit 0 if `ok` is true, 1 otherwise.
Usage:
python3 scripts/seamless-check.py path/to/tile.png
SEAMLESS_TOLERANCE=8 python3 scripts/seamless-check.py path/to/tile.png
-
-Used by:
- - scripts/regen-bamboo-trellis-to-cane.js (post-gen guard, before INSERT)
- - scripts/generate-butterfly-trellis-batch.js (same)
- - scripts/drunk_animals_batch.js (same)
"""
import json
import os
import sys
from PIL import Image
+import numpy as np
+
+
+# Below this variance, an edge row/col is considered "near-uniform" (= solid
+# background). 25.0 was tuned on the validation sample — solid-red medallion
+# backgrounds land <5; busy edges land 200-2000.
+ISOLATED_MOTIF_VAR_THRESHOLD = 25.0
def check(path: str, tolerance: float = 12.0) -> dict:
img = Image.open(path).convert('RGB')
- # Downscale to 512px on the long edge so the check is fast regardless of
- # source dim. Seamlessness is a low-frequency property — high-res isn't
- # informative for the edge-diff.
img.thumbnail((512, 512))
- w, h = img.size
- px = img.load()
-
- def row_avg_diff(y0, y1):
- s = 0.0
- for x in range(w):
- r0, g0, b0 = px[x, y0]
- r1, g1, b1 = px[x, y1]
- s += abs(r0 - r1) + abs(g0 - g1) + abs(b0 - b1)
- return s / (w * 3.0)
-
- def col_avg_diff(x0, x1):
- s = 0.0
- for y in range(h):
- r0, g0, b0 = px[x0, y]
- r1, g1, b1 = px[x1, y]
- s += abs(r0 - r1) + abs(g0 - g1) + abs(b0 - b1)
- return s / (h * 3.0)
-
- tb = row_avg_diff(0, h - 1)
- lr = col_avg_diff(0, w - 1)
- ok = (tb <= tolerance) and (lr <= tolerance)
+ a = np.asarray(img, dtype=np.float32)
+ h, w, _ = a.shape
+
+ top, bot = a[0, :, :], a[h - 1, :, :]
+ left, right = a[:, 0, :], a[:, w - 1, :]
+
+ # Straight diff — opposite edges aligned 1:1
+ tb = float(np.mean(np.abs(top - bot)))
+ lr = float(np.mean(np.abs(left - right)))
+
+ # Half-drop diff — opposite edges aligned with a 50% offset.
+ # np.roll wraps; that's correct because a half-drop tile DOES wrap.
+ tb_hd = float(np.mean(np.abs(top - np.roll(bot, w // 2, axis=0))))
+ lr_hd = float(np.mean(np.abs(left - np.roll(right, h // 2, axis=0))))
+
+ # Per-channel variance, summed across channels — proxy for "how busy is
+ # this edge." Solid-color edge → ~0; varied motif → big number.
+ def var(strip):
+ return float(np.var(strip, axis=0).sum())
+ top_v, bot_v, left_v, right_v = var(top), var(bot), var(left), var(right)
+
+ # Verdict
+ straight_ok = (tb <= tolerance) and (lr <= tolerance)
+ halfdrop_ok = (tb_hd <= tolerance) and (lr_hd <= tolerance)
+ isolated = (top_v < ISOLATED_MOTIF_VAR_THRESHOLD and
+ bot_v < ISOLATED_MOTIF_VAR_THRESHOLD and
+ left_v < ISOLATED_MOTIF_VAR_THRESHOLD and
+ right_v < ISOLATED_MOTIF_VAR_THRESHOLD)
+
+ if isolated:
+ # Centered spot motif on solid background — not a wallpaper repeat,
+ # regardless of how low the edge diff is.
+ ok = False
+ code = 'ISOLATED_MOTIF'
+ elif straight_ok:
+ ok = True
+ code = 'SEAMLESS'
+ elif halfdrop_ok:
+ ok = True
+ code = 'SEAMLESS_HALFDROP'
+ else:
+ ok = False
+ tb_fail = tb > tolerance and tb_hd > tolerance
+ lr_fail = lr > tolerance and lr_hd > tolerance
+ if tb_fail and lr_fail: code = 'SEAMLESS_FAIL_BOTH'
+ elif tb_fail: code = 'SEAMLESS_FAIL_TB'
+ else: code = 'SEAMLESS_FAIL_LR'
+
return {
'ok': bool(ok),
- 'top_bottom_diff': round(tb, 2),
- 'left_right_diff': round(lr, 2),
- 'tolerance': tolerance,
- 'image': path,
+ 'top_bottom_diff': round(tb, 2),
+ 'left_right_diff': round(lr, 2),
+ 'top_bottom_diff_halfdrop': round(tb_hd, 2),
+ 'left_right_diff_halfdrop': round(lr_hd, 2),
+ 'top_var': round(top_v, 2),
+ 'bottom_var': round(bot_v, 2),
+ 'left_var': round(left_v, 2),
+ 'right_var': round(right_v, 2),
+ 'tolerance': tolerance,
+ 'code': code,
+ 'image': path,
}
← d301665 make_seamless.py: disable to no-op pass-through
·
back to Wallco Ai
·
Stage 1: canonical lib/repeat-prompt.js + wire into smart-fi 9e5767b →