Lay papercraft nets out on A4 pages, scaled to fit by default

Each piece turns to its narrowest orientation and is shelf-packed onto A4
pages (one SVG per page). Strips longer than a page are split, so the model
size is limited by band width and cap size rather than strip length. With
height_cm blank the model is the tallest whose every piece fits a page
(a cat-sized ellipsoid: 13.8 cm, was 4.8 cm before splitting long strips).
The report adds real_height_cm, max_height_cm_for_a4 and fits_a4.

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

SPEC.md

@@ -100,7 +100,7 @@ Verbs: `sat/stood/lay/rested` → `on` (ground implied), `shone/glowed` → `lig
 | `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, rings, samples → report, rung PNGs, rung GLBs, mini HTML file, mini HTML text |
-| `papercraft_rings` | ledger, item id, rings, samples, height_cm → pieces report, SVG net (mm) |
+| `papercraft_rings` | ledger, item id, rings, samples, height_cm → pieces report, one SVG per A4 page (mm) |
 
 `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.
@@ -131,8 +131,14 @@ that would curl past ~120° on paper overlaps itself, so it is split into parts
 Every joint has glue tabs on one side only, labelled with the piece they meet (band top
 edge → next band or top cap, seam end → own start or next part, bottom cap rim → band 1).
 Caps under 4 mm are dropped and the band closes to a point; tabs under 2 mm are dropped.
-Cut solid lines, fold dashed lines. Pieces are shelf-packed in 180 mm rows; a piece
-wider than that widens the sheet (use `height_cm` to print on A4).
+Cut solid lines, fold dashed lines.
+
+Output is A4 pages (190 × 277 mm inside 10 mm margins). Each piece is turned to its
+narrowest orientation and shelf-packed; strips longer than a page are split like curled
+ones. With `height_cm` blank the model is the tallest whose every piece fits a page,
+which is set by band width and cap size, not strip length. The report gives
+`real_height_cm`, `max_height_cm_for_a4` and `fits_a4`; a piece too big for A4 at a
+requested height gets a page of its own size.
 
 ### Mini HTML
 

app.py

@@ -230,8 +230,8 @@ def simplify_item(ledger_json: str, item_id: str, html: str = "url", rings: str
 
 
 def papercraft_rings(ledger_json: str, item_id: str, rings: str = "8", samples: str = "16",
-                     height_cm: str = "") -> tuple[str, str]:
-    """Make a printable papercraft net of one object from its rings rung (see simplify_item).
+                     height_cm: str = "") -> tuple[str, list]:
+    """Make a printable papercraft net of one object from its rings rung, on A4 pages (see simplify_item).
 
     Every band between two rings unrolls exactly into one paper strip; bands that would
     curl past ~120 degrees on paper are split into parts (2a, 2b, ...). Glue tabs sit on
@@ -243,10 +243,11 @@ def papercraft_rings(ledger_json: str, item_id: str, rings: str = "8", samples:
         item_id: The object item to make, e.g. "n1".
         rings: Number of horizontal sections (2-64). Fewer rings = fewer, simpler pieces.
         samples: Points around each section (3-128). Fewer samples = fewer folds.
-        height_cm: Height of the paper model in cm; blank = the object's real size.
+        height_cm: Height of the paper model in cm; blank = the largest model whose biggest
+            piece still fits one A4 page. The report gives that A4 limit either way.
 
     Returns:
-        (report JSON string with the pieces, sheet size and what glues to what, SVG net file in mm).
+        (report JSON string with the pieces, pages and what glues to what, one SVG file per A4 page in mm).
     """
     try:
         ledger = _json(ledger_json, "ledger_json")
@@ -265,17 +266,26 @@ def papercraft_rings(ledger_json: str, item_id: str, rings: str = "8", samples:
         _, profile = simplify.rings(assets.settle(item), count, n)
         if len(profile) < 2:
             raise ValueError(f"{item_id!r} has fewer than 2 sections; try more rings")
-        pieces, scale = papercraft.net(profile, n, h)
-        text, sheet = papercraft.svg(pieces, f"{item['word']}: {len(profile)} rings x {n}")
-        path = os.path.join(tempfile.mkdtemp(prefix="vli_paper_"), re.sub(r"\W+", "_", item["word"]) + "_net.svg")
-        with open(path, "w", encoding="utf-8") as f:
-            f.write(text)
+        real_cm = (profile[-1]["y"] - profile[0]["y"]) * 100
+        a4_cm = papercraft.a4_height_cm(profile, n)
+        pieces, scale = papercraft.net(profile, n, h or a4_cm)
+        work, slug = tempfile.mkdtemp(prefix="vli_paper_"), re.sub(r"\W+", "_", item["word"])
+        sheets = papercraft.pages(pieces)
+        files, page_report = [], []
+        for k, placed in enumerate(sheets, 1):
+            text, size = papercraft.svg(placed, f"{item['word']}: {len(profile)} rings x {n}, page {k}/{len(sheets)}")
+            path = os.path.join(work, f"{slug}_net_p{k}.svg")
+            with open(path, "w", encoding="utf-8") as f:
+                f.write(text)
+            files.append(path)
+            page_report.append({"page": k, "size_mm": size, "pieces": [pc["name"] for pc, _ in placed]})
         report = {"item": item_id, "word": item["word"], "rings": len(profile), "samples": n,
                   "model_height_cm": round((profile[-1]["y"] - profile[0]["y"]) * scale / 10, 1),
-                  "sheet_mm": sheet, "pieces": [{"name": pc["name"],
-                                                 "glues_to": sorted({t["label"] for t in pc["tabs"] if t["label"]})}
-                                                for pc in pieces]}
-        return json.dumps(report, indent=1), path
+                  "real_height_cm": round(real_cm, 1), "max_height_cm_for_a4": round(a4_cm, 1),
+                  "fits_a4": bool(h is None or h <= a4_cm), "pages": page_report,
+                  "pieces": [{"name": pc["name"], "glues_to": sorted({t["label"] for t in pc["tabs"] if t["label"]})}
+                             for pc in pieces]}
+        return json.dumps(report, indent=1), files
     except Exception as e:
         _fail(e)
 
@@ -315,14 +325,15 @@ def _use_primitive(primitives_json, word, shape):
     return json.dumps(prims)
 
 
-def _svg_preview(path):
-    """Show the SVG net scaled to the panel width."""
-    if not path:
-        return ""
-    with open(path, encoding="utf-8") as f:
-        text = f.read()
-    text = text.replace("<svg ", '<svg style="width:100%;height:auto" ', 1)
-    return f'<div style="background:#fff;padding:8px;border-radius:8px">{text}</div>'
+def _svg_preview(files):
+    """Show the SVG pages side by side, scaled to the panel."""
+    pages = []
+    for path in files or []:
+        with open(path, encoding="utf-8") as f:
+            text = f.read()
+        pages.append(text.replace("<svg ", '<svg style="width:100%;height:auto;border:1px solid #ccc" ', 1))
+    cells = "".join(f'<div style="flex:1 1 260px;max-width:420px">{p}</div>' for p in pages)
+    return f'<div style="display:flex;flex-wrap:wrap;gap:8px">{cells}</div>' if pages else ""
 
 
 def _html_preview(path):
@@ -393,10 +404,10 @@ with gr.Blocks(title="VisualLearningIdea") as demo:
         ladder_report = gr.Code(label="Report", language="json")
         ladder_files = gr.File(label="GLB per rung", file_count="multiple")
     with gr.Accordion("Papercraft net (rings)", open=False):
-        paper_height = gr.Textbox(label="Model height in cm (blank = real size)", value="")
+        paper_height = gr.Textbox(label="Model height in cm (blank = largest that fits A4)", value="")
         paper = gr.Button("Make net")
         paper_preview = gr.HTML()
-        paper_file = gr.File(label="Download .svg (mm)")
+        paper_file = gr.File(label="A4 pages (.svg, mm)", file_count="multiple")
         paper_report = gr.Code(label="Pieces", language="json")
 
     gr.on([sentence.change, primitives.change], check_words, [sentence, primitives], words,

vli/papercraft.py

@@ -7,13 +7,18 @@ Each joint gets glue tabs on exactly one side, labelled with the piece it meets:
   band i seam end   -> its own seam start (or the next part, when a band is split)
   bottom cap rim    -> band 1 bottom edge
 A band that would curl past ~120 degrees on paper is split into parts (2a, 2b, ...).
-Output is an SVG in millimetres, cut lines solid, fold lines dashed.
+Output is A4 pages of SVG in millimetres, cut lines solid, fold lines dashed. Each piece
+is turned to its narrowest orientation; fit_factor gives the scale at which the largest
+piece fills a page.
 """
 import numpy as np
 
 TAB_MM = 6.0
 GAP_MM = 8.0
-SHEET_MM = 180.0  # row width for laying out pieces (A4 printable width)
+PAGE_MM = (190.0, 277.0)  # A4 inside 10 mm margins
+MARGIN_MM = 10.0
+HEADER_MM = 8.0
+STRIP_MAX_MM = PAGE_MM[1] - HEADER_MM - 2 * TAB_MM  # longer strips are split
 MIN_CAP_MM = 4.0
 MIN_TAB_MM = 2.0
 LABEL_TAB_MM = 8.0
@@ -26,6 +31,12 @@ def _ring_points(p, dirs):
     return np.c_[cx + r[:, 0] * dirs[:, 0], np.full(len(dirs), p["y"]), cz + r[:, 0] * dirs[:, 1]]
 
 
+def _rings(profile, samples):
+    ang = np.linspace(0, 2 * np.pi, samples, endpoint=False)
+    dirs = np.c_[np.cos(ang), np.sin(ang)]
+    return [_ring_points(p, dirs) for p in profile]
+
+
 def _place(a2, c2, da, dc, away2):
     """The 2D point at distance da from a2 and dc from c2, on the side away from away2."""
     d = np.linalg.norm(c2 - a2)
@@ -79,15 +90,17 @@ def _tab(p, q, inside, label):
             "at": (p + q) / 2 + n * w / 2}
 
 
-def _chunks(B, max_turn_deg=120):
-    """Split a strip where its bottom edge has turned too far: a strip that curls
-    past a half circle overlaps itself on paper (bands near a pole)."""
+def _chunks(B, max_turn_deg=120, max_len=np.inf):
+    """Split a strip where its bottom edge has turned too far (a strip that curls
+    past a half circle overlaps itself on paper: bands near a pole) or has grown
+    longer than `max_len` mm (so a long band still fits a page)."""
     S = len(B) - 1
     edges = np.diff(B, axis=0)
     heading = np.unwrap(np.arctan2(edges[:, 1], edges[:, 0]))
+    length = np.r_[0, np.cumsum(np.linalg.norm(edges, axis=1))]
     cuts, start = [0], 0
     for j in range(1, S):
-        if abs(heading[j] - heading[start]) > np.radians(max_turn_deg):
+        if abs(heading[j] - heading[start]) > np.radians(max_turn_deg) or length[j + 1] - length[start] > max_len:
             cuts.append(j)
             start = j
     return list(zip(cuts, cuts[1:] + [S]))
@@ -98,18 +111,16 @@ def net(profile, samples, height_cm=None):
 
     Caps under MIN_CAP_MM across are left out: the band there closes to a point.
     """
-    ang = np.linspace(0, 2 * np.pi, samples, endpoint=False)
-    dirs = np.c_[np.cos(ang), np.sin(ang)]
     real_h = profile[-1]["y"] - profile[0]["y"]
     scale = 1000.0 if not height_cm else 10.0 * float(height_cm) / max(real_h, 1e-6)
-    rings = [_ring_points(p, dirs) * scale for p in profile]
+    rings = [r * scale for r in _rings(profile, samples)]
     caps = {k: 2 * max(profile[i]["radii"]) * scale >= MIN_CAP_MM for k, i in (("bottom", 0), ("top", -1))}
     n = len(rings) - 1
     pieces = []
     for i in range(n):
         B, T, _ = _unroll_band(rings[i], rings[i + 1])
         above = f"band {i + 2}" if i + 1 < n else ("top cap" if caps["top"] else None)
-        parts = _chunks(B)
+        parts = _chunks(B, max_len=STRIP_MAX_MM)
         names = [f"band {i + 1}" + (chr(ord("a") + k) if len(parts) > 1 else "") for k in range(len(parts))]
         for k, (j0, j1) in enumerate(parts):
             mid = (B[j0:j1 + 1].mean(axis=0) + T[j0:j1 + 1].mean(axis=0)) / 2
@@ -131,44 +142,107 @@ def net(profile, samples, height_cm=None):
     return pieces, scale
 
 
-def _bounds(piece):
-    pts = np.array(list(piece["outline"]) + [p for t in piece["tabs"] for p in t["poly"]])
-    return pts.min(axis=0), pts.max(axis=0)
+def _points(piece):
+    return np.array(list(piece["outline"]) + [p for t in piece["tabs"] for p in t["poly"]])
 
 
-def svg(pieces, title):
-    """Shelf-pack the pieces into rows and draw them. Units are millimetres."""
-    x = y = row_h = 0.0
-    width = max(SHEET_MM, max(float((hi - lo)[0]) for lo, hi in map(_bounds, pieces)))
-    placed = []
+def _upright(piece):
+    """Rotate a piece to its narrowest orientation, long side vertical (fits a portrait page)."""
+    pts = _points(piece)
+    best = None
+    for deg in range(0, 180, 3):
+        a = np.radians(deg)
+        rot = np.array([[np.cos(a), -np.sin(a)], [np.sin(a), np.cos(a)]])
+        w, h = np.ptp(pts @ rot.T, axis=0)
+        if w > h:
+            continue
+        if best is None or w < best[0]:
+            best = (w, rot)
+    rot = best[1] if best else np.eye(2)
+
+    def r(p):
+        return rot @ p
+    return {"name": piece["name"], "outline": [r(p) for p in piece["outline"]],
+            "folds": [(r(p), r(q)) for p, q in piece["folds"]],
+            "tabs": [{**t, "poly": [r(p) for p in t["poly"]], "at": r(t["at"])} for t in piece["tabs"]]}
+
+
+def fit_factor(pieces):
+    """How much the pieces can grow (or must shrink) so the largest fits an A4 page.
+    Tabs keep their size when the net is rescaled, so they are left out of the fit."""
+    f = np.inf
     for pc in pieces:
-        lo, hi = _bounds(pc)
-        w, h = hi - lo
-        if x > 0 and x + w > width:
+        w, h = np.ptp(np.array(_upright({**pc, "tabs": []})["outline"]), axis=0)
+        f = min(f, (PAGE_MM[0] - 2 * TAB_MM) / max(w, 1e-6), (PAGE_MM[1] - 2 * TAB_MM - HEADER_MM) / max(h, 1e-6))
+    return float(f)
+
+
+def a4_height_cm(profile, samples):
+    """The tallest model whose every piece fits an A4 page. Long strips are split, so
+    what limits it is how wide a band is and how big the caps are."""
+    real_cm = (profile[-1]["y"] - profile[0]["y"]) * 100
+    rings = _rings(profile, samples)
+    widest = max([np.linalg.norm(a - b, axis=1).max() for a, b in zip(rings, rings[1:])]
+                 + [2 * max(profile[i]["radii"]) for i in (0, -1)])
+    h = real_cm * min(PAGE_MM) * 0.9 / max(widest * 1000, 1e-6)
+    for _ in range(6):  # curved strips can still be wider than their band: shrink until all fit
+        f = fit_factor(net(profile, samples, h)[0])
+        if f >= 1:
+            break
+        h *= 0.98 * f
+    return h
+
+
+def pages(pieces):
+    """Shelf-pack upright pieces onto A4 pages. A piece too big for a page gets a page of its own size."""
+    out, cur, x, y, row_h = [], [], 0.0, HEADER_MM, 0.0
+    for pc in map(_upright, pieces):
+        pts = _points(pc)
+        lo = pts.min(axis=0)
+        w, h = np.ptp(pts, axis=0)
+        if x > 0 and x + w > PAGE_MM[0]:
             x, y, row_h = 0.0, y + row_h + GAP_MM, 0.0
-        placed.append((pc, np.array([x, y + 10.0]) - lo))
+        if cur and y + h > PAGE_MM[1]:
+            out.append(cur)
+            cur, x, y, row_h = [], 0.0, HEADER_MM, 0.0
+        cur.append((pc, np.array([x, y]) - lo))
         x, row_h = x + w + GAP_MM, max(row_h, h)
-    height = y + row_h + 10.0 + GAP_MM
+    if cur:
+        out.append(cur)
+    return out
+
+
+def svg(placed, title):
+    """One A4 page (millimetres, 10 mm margins) of placed pieces."""
+    pts_all = np.concatenate([_points(pc) + off for pc, off in placed])
+    width = max(PAGE_MM[0], float(pts_all[:, 0].max())) + 2 * MARGIN_MM
+    height = max(PAGE_MM[1], float(pts_all[:, 1].max())) + 2 * MARGIN_MM
 
     def pts(poly, off):
-        return " ".join(f"{p[0] + off[0]:.1f},{p[1] + off[1]:.1f}" for p in poly)
+        return " ".join(f"{p[0] + off[0] + MARGIN_MM:.1f},{p[1] + off[1] + MARGIN_MM:.1f}" for p in poly)
+
+    def xy(p, off):
+        return p[0] + off[0] + MARGIN_MM, p[1] + off[1] + MARGIN_MM
 
     out = [f'<svg xmlns="http://www.w3.org/2000/svg" width="{width:.0f}mm" height="{height:.0f}mm" '
            f'viewBox="0 0 {width:.1f} {height:.1f}" font-family="sans-serif">',
-           f'<text x="0" y="5" font-size="4">{_esc(title)}: cut solid, fold dashed, glue tabs to the named piece</text>']
+           '<rect width="100%" height="100%" fill="#fff"/>',
+           f'<text x="{MARGIN_MM}" y="{MARGIN_MM + 4}" font-size="4">{_esc(title)}: cut solid, fold dashed, '
+           f'glue tabs to the named piece</text>']
     for pc, off in placed:
         for t in pc["tabs"]:
             out.append(f'<polygon points="{pts(t["poly"], off)}" fill="#eee" stroke="#000" stroke-width="0.2"/>')
             if not t["label"]:
                 continue
-            a = t["at"] + off
+            a = xy(t["at"], off)
             out.append(f'<text x="{a[0]:.1f}" y="{a[1]:.1f}" font-size="2" text-anchor="middle" '
                        f'dominant-baseline="middle">{_esc(t["label"])}</text>')
         out.append(f'<polygon points="{pts(pc["outline"], off)}" fill="#fff" stroke="#000" stroke-width="0.3"/>')
         for p, q in pc["folds"]:
-            out.append(f'<line x1="{p[0] + off[0]:.1f}" y1="{p[1] + off[1]:.1f}" x2="{q[0] + off[0]:.1f}" '
-                       f'y2="{q[1] + off[1]:.1f}" stroke="#888" stroke-width="0.2" stroke-dasharray="1.5,1"/>')
-        c = np.mean(pc["outline"], axis=0) + off
+            (x1, y1), (x2, y2) = xy(p, off), xy(q, off)
+            out.append(f'<line x1="{x1:.1f}" y1="{y1:.1f}" x2="{x2:.1f}" y2="{y2:.1f}" '
+                       f'stroke="#888" stroke-width="0.2" stroke-dasharray="1.5,1"/>')
+        c = xy(np.mean(pc["outline"], axis=0), off)
         out.append(f'<text x="{c[0]:.1f}" y="{c[1]:.1f}" font-size="4" text-anchor="middle" '
                    f'dominant-baseline="middle">{_esc(pc["name"])}</text>')
     out.append("</svg>")