Add a rings rung to the ladder: planar sections sampled at a fixed count

A second simplification path aimed at papercraft and easy debugging:
N horizontal sections of the mesh, each outline sampled at S angles from
its centre, joined into bands with flat caps. Each band is one paper strip
and each vertex is (ring, angle); the report lists every ring's height,
centre and radii. simplify_item takes rings (default 8) and samples
(default 16), also in the UI.

Checked by hand: a 0.1 m cylinder gives radius 0.1 at every sample, a cone
gives linearly shrinking radii. Limit: one stack per object, so branching
shapes like a lamp merge into one envelope; it sits beside decimation,
not in place of it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

SPEC.md

@@ -99,7 +99,7 @@ Verbs: `sat/stood/lay/rested` → `on` (ground implied), `shone/glowed` → `lig
 | `check_words` | sentence, primitives → per-word status, missing words, completions |
 | `translate_to_scene` | sentence, primitives, seed, html → ledger, PNG, GLB, mini HTML file, mini HTML text |
 | `refine_scene` | ledger, changes, seed, html → ledger, PNG, GLB, mini HTML file, mini HTML text |
-| `simplify_item` | ledger, item id, html → report, rung PNGs, rung GLBs, mini HTML file, mini HTML text |
+| `simplify_item` | ledger, item id, html, rings, samples → report, rung PNGs, rung GLBs, mini HTML file, mini HTML text |
 
 `check_words` also returns `maps_to` per noun (the asset it would get), so a word
 that exists but maps to the wrong thing shows up before submitting.
@@ -113,6 +113,14 @@ thin parts. Rungs are
 labelled with the faces they actually have, and the ladder stops descending when
 a rung doesn't reduce, so a stalled mesh never shows as several identical rungs.
 
+**Rings rung (second path, for papercraft).** `rings` horizontal sections, each
+outline sampled at `samples` evenly spaced angles from the section's centre (the
+farthest crossing per ray), joined into bands with flat caps. Every band is one
+paper strip and every vertex is (ring, angle); the report lists each ring's height,
+centre and radii, so it can be checked by hand. One stack per object: branching or
+overhanging parts (a lamp's arm and shade) merge into one envelope, and heights with
+no section are skipped.
+
 ### Mini HTML
 
 A self-contained page: Three.js (`three@0.160.0` from unpkg) plus one inline `D`

app.py

@@ -48,6 +48,17 @@ def _seed(value):
         raise ValueError(f"seed must be a whole number, got {value!r}")
 
 
+def _count(value, name, lo, hi):
+    """A whole number in [lo, hi], sent as a string like seeds."""
+    try:
+        n = int(float(str(value).strip()))
+    except ValueError:
+        raise ValueError(f"{name} must be a whole number, got {value!r}")
+    if not lo <= n <= hi:
+        raise ValueError(f"{name} must be between {lo} and {hi}, got {n}")
+    return n
+
+
 HTML_MODES = ["url", "inline", "skip"]
 
 
@@ -168,18 +179,25 @@ def refine_scene(ledger_json: str, changes_json: str = "[]", seed: str = "0",
         _fail(e)
 
 
-def simplify_item(ledger_json: str, item_id: str, html: str = "url") -> tuple[str, list, list, str, str]:
-    """Build the simplification ladder for one object: full asset -> fewer faces -> convex hull -> box.
+def simplify_item(ledger_json: str, item_id: str, html: str = "url", rings: str = "8",
+                  samples: str = "16") -> tuple[str, list, list, str, str]:
+    """Build the simplification ladder for one object: full asset -> fewer faces -> rings -> convex hull -> box.
 
     Look at where the object stops reading as its word: that rung is the least geometry
     that still carries the meaning, and the low rungs are the ones that can be made
     physically (fewer faces = fewer papercraft pieces).
 
+    The rings rung is a second path: `rings` horizontal sections, each outline sampled at
+    `samples` angles, joined into bands (one paper strip per band). The report lists every
+    ring's height, centre and radii, so each vertex can be checked by hand.
+
     Args:
         ledger_json: Ledger JSON from translate_to_scene or refine_scene.
         item_id: The object item to simplify, e.g. "n1".
         html: "url" (default), "inline" or "skip", as in translate_to_scene. The ladder page
             holds several rungs of up to 1000 faces each, so inline is especially large.
+        rings: Number of horizontal sections for the rings rung (2-64).
+        samples: Points sampled around each section (3-128).
 
     Returns:
         (report JSON string, gallery of rung pictures, GLB file per rung,
@@ -192,14 +210,17 @@ def simplify_item(ledger_json: str, item_id: str, html: str = "url") -> tuple[st
             raise ValueError(f"{item_id!r} is not an object item in this ledger")
         mesh = assets.settle(item)
         work = tempfile.mkdtemp(prefix="vli_ladder_")
-        rungs = simplify.ladder(mesh)
+        rungs = simplify.ladder(mesh, _count(rings, "rings", 2, 64), _count(samples, "samples", 3, 128))
         report, gallery, files = {"item": item_id, "word": item["word"], "rungs": []}, [], []
         for k, (label, rung) in enumerate(rungs):
             png = scene.render({item_id: rung}, os.path.join(work, f"{k}.png"), title=label)
             slug = re.sub(r"\W+", "_", label)
             glb = os.path.join(work, f"{k}_{slug}.glb")
             rung.export(glb)
-            report["rungs"].append({"rung": label, **simplify.stats(rung)})
+            entry = {"rung": label, **simplify.stats(rung)}
+            if "rings" in rung.metadata:
+                entry["rings"] = rung.metadata["rings"]
+            report["rungs"].append(entry)
             gallery.append((png, label))
             files.append(glb)
         return (json.dumps(report, indent=1), gallery, files,
@@ -299,7 +320,10 @@ with gr.Blocks(title="VisualLearningIdea") as demo:
         changes = gr.Code(label="Changes", language="json", value=EXAMPLE_CHANGES, interactive=True)
         refine = gr.Button("Refine")
     with gr.Accordion("Simplification ladder", open=False):
-        item_id = gr.Textbox(label="Object item id", value="n1")
+        with gr.Row():
+            item_id = gr.Textbox(label="Object item id", value="n1")
+            ring_count = gr.Textbox(label="Rings", value="8")
+            ring_samples = gr.Textbox(label="Samples per ring", value="16")
         simp = gr.Button("Simplify")
         ladder_pics = gr.Gallery(label="Rungs", columns=4)
         ladder_preview = gr.HTML()
@@ -319,7 +343,7 @@ with gr.Blocks(title="VisualLearningIdea") as demo:
     refine.click(refine_scene, [ledger, changes, seed, html_mode],
                  [ledger, picture, model, scene_file, scene_html], api_name="refine_scene") \
         .then(_html_preview, scene_file, scene_preview, api_visibility="private")
-    simp.click(simplify_item, [ledger, item_id, html_mode],
+    simp.click(simplify_item, [ledger, item_id, html_mode, ring_count, ring_samples],
                [ladder_report, ladder_pics, ladder_files, ladder_file, ladder_html], api_name="simplify_item") \
         .then(_html_preview, ladder_file, ladder_preview, api_visibility="private")
 

vli/simplify.py

@@ -85,7 +85,64 @@ def _recolor(mesh, color):
     return mesh
 
 
-def ladder(mesh):
+def _ray_hits(center, dirs, a, b):
+    """Farthest hit of each 2D ray (center + t*dir) on segments a->b; nan where a ray misses."""
+    e, w = b - a, a - center
+    denom = dirs[:, None, 0] * e[None, :, 1] - dirs[:, None, 1] * e[None, :, 0]
+    with np.errstate(divide="ignore", invalid="ignore"):
+        t = (w[:, 0] * e[:, 1] - w[:, 1] * e[:, 0])[None] / denom
+        s = (w[:, 0] * dirs[:, None, 1] - w[:, 1] * dirs[:, None, 0]) / denom
+    far = np.where((np.abs(denom) > 1e-12) & (t >= 0) & (s >= 0) & (s <= 1), t, -np.inf).max(axis=1)
+    return np.where(np.isfinite(far), far, np.nan)
+
+
+def rings(mesh, count=8, samples=16):
+    """Planar circumferences: `count` horizontal sections, each sampled at `samples` angles.
+
+    Each ring is the section's outer outline seen from its own centre: the farthest
+    crossing along `samples` evenly spaced rays. Neighbouring rings join into bands,
+    so every band is one paper strip and every vertex is (ring, angle). Cruder than
+    decimation, but each number can be checked by hand. Returns (mesh, profile).
+    """
+    lo, hi = mesh.bounds[:, 1]
+    inset = 0.01 * (hi - lo)
+    ang = np.linspace(0, 2 * np.pi, samples, endpoint=False)
+    dirs = np.c_[np.cos(ang), np.sin(ang)]  # in the (x, z) plane
+    profile = []
+    for y in np.linspace(lo + inset, hi - inset, count):
+        seg = trimesh.intersections.mesh_plane(mesh, [0, 1, 0], [0, y, 0])
+        if len(seg) == 0:
+            continue  # a gap between parts at this height
+        a, b = seg[:, 0][:, [0, 2]], seg[:, 1][:, [0, 2]]
+        pts = np.r_[a, b]
+        center = (pts.min(axis=0) + pts.max(axis=0)) / 2
+        r = _ray_hits(center, dirs, a, b)
+        hit = ~np.isnan(r)
+        if not hit.any():
+            continue
+        r = np.interp(ang, ang[hit], r[hit], period=2 * np.pi)  # fill rays that found nothing
+        profile.append({"y": round(float(y), 3), "center": [round(float(c), 3) for c in center],
+                        "radii": [round(float(x), 3) for x in r]})
+    if len(profile) < 2:
+        return None, profile
+    verts = [[p["center"][0] + rr * dx, p["y"], p["center"][1] + rr * dz]
+             for p in profile for rr, (dx, dz) in zip(p["radii"], dirs)]
+    n, faces = len(profile), []
+    for i in range(n - 1):
+        for j in range(samples):
+            v00, v01 = i * samples + j, i * samples + (j + 1) % samples
+            faces += [[v00, v00 + samples, v01 + samples], [v00, v01 + samples, v01]]
+    for k, p in ((0, profile[0]), (n - 1, profile[-1])):  # flat caps: fan to the ring centre
+        c = len(verts)
+        verts.append([p["center"][0], p["y"], p["center"][1]])
+        faces += [[c, k * samples + (j + 1) % samples, k * samples + j] for j in range(samples)]
+    out = trimesh.Trimesh(np.array(verts), np.array(faces), process=False)
+    if out.volume < 0:
+        out.invert()
+    return out, profile
+
+
+def ladder(mesh, ring_count=8, ring_samples=16):
     color = base_color(mesh)
     rungs = [("original", mesh)]
     for n in FACE_LEVELS:
@@ -96,6 +153,10 @@ def ladder(mesh):
         if len(rung.faces) > 0.8 * prev:
             break  # decimation stalled: lower levels would repeat this mesh
         rungs.append((f"{len(rung.faces)} faces", rung))
+    ringed, profile = rings(mesh, ring_count, ring_samples)
+    if ringed is not None:
+        ringed.metadata["rings"] = profile
+        rungs.append((f"rings {len(profile)}x{ring_samples}", _recolor(ringed, color)))
     rungs.append(("convex hull", _recolor(mesh.convex_hull, color)))
     box = mesh.bounding_box_oriented
     rungs.append(("bounding box", _recolor(trimesh.Trimesh(box.vertices, box.faces), color)))