98e24b6aad
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
336 lines
15 KiB
Python
336 lines
15 KiB
Python
"""``scad.ref``: stable references as public API (design-docs/stable-refs-design.md, sections 3.2, 4, 7).
|
|
|
|
A reference is written as plain keyword data (``scad.ref.face("base", "make_box_rsolid", role="box.top")``), resolves
|
|
through the recorded history of the shape it is resolved in, says how it went (ok / split / merged / lost), and is
|
|
used as a ``ql`` predicate or as the selection an operation takes. A split or a lost reference is an error that
|
|
carries the candidates, through any operation; a choice is written back into the reference.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
import math
|
|
import pickle
|
|
import subprocess
|
|
import sys
|
|
import textwrap
|
|
|
|
import pytest
|
|
|
|
import simplecadapi as scad
|
|
from simplecadapi import ql
|
|
|
|
|
|
def _top(shape, z=10.0):
|
|
return ql.faces().where(ql.prop("geom.center.z", ">=", z - 1e-6)).where(ql.prop("geom.center.z", "<=", z + 1e-6)).resolve(shape)
|
|
|
|
|
|
def _rim_edges(shape, z=10.0):
|
|
return ql.edges().where(ql.prop("geom.center.z", ">=", z - 1e-6)).where(ql.prop("geom.center.z", "<=", z + 1e-6)).resolve(shape)
|
|
|
|
|
|
TOP = scad.ref.face("base", "make_box_rsolid", role="box.top")
|
|
|
|
|
|
def _tool(namespace: str, make):
|
|
"""A tool made in a feature of its own (another cell), on the graph the next session shares."""
|
|
from simplecadapi._glue.session import GraphSession
|
|
|
|
with GraphSession(graph_id="refs", namespace=namespace, shared_lineage=True):
|
|
return make()
|
|
|
|
|
|
def _session():
|
|
from simplecadapi._glue.session import GraphSession
|
|
|
|
return GraphSession(graph_id="refs", namespace="base", shared_lineage=True)
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# The spelling
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
|
def test_a_reference_reads_as_code_and_parses_back():
|
|
with scad.GraphSession(namespace="base"):
|
|
box = scad.make_box_rsolid(40, 20, 10)
|
|
(top,) = _top(box)
|
|
ref = scad.ref.of(top, box)
|
|
assert repr(ref) == "scad.ref.face('base', 'make_box_rsolid', role='box.top', guard=('PLANE', (0, 0, 10), 800, (0, 0, 1)))"
|
|
assert scad.ref.parse(repr(ref)) == ref
|
|
assert scad.ref.ElementRef.from_dict(json.loads(json.dumps(ref.to_dict()))) == ref
|
|
assert pickle.loads(pickle.dumps(ref)) == ref
|
|
# An edge is named by the two faces it lies between: readable, and found again after booleans.
|
|
rim = scad.ref.of(_rim_edges(box)[0], box)
|
|
assert rim.between is not None and rim.code().startswith("scad.ref.edge('base', 'make_box_rsolid', between=('box.")
|
|
assert scad.ref.parse(rim.code()) == rim
|
|
# The written forms, with every optional field.
|
|
text = "scad.ref.face('hole', 'make_cut_rsolid', topo='face_7', occurrence=1, slot=2, piece=0, digest='ab12', guard=('PLANE', (0, 1.5, 8), 28.96), naming=2)"
|
|
assert scad.ref.parse(text).code() == text
|
|
nested = "scad.ref.edge(between=(scad.ref.face('base', 'make_box_rsolid', role='box.top'), scad.ref.face('bore', 'make_cylinder_rsolid', role='cylinder.side')))"
|
|
assert scad.ref.parse(nested).code() == nested
|
|
kind, refs = scad.ref.parse_selection(__import__("ast").parse("scad.ref.faces(" + text + ", " + repr(TOP) + ")", mode="eval").body)
|
|
assert kind == "face" and refs == [scad.ref.parse(text), TOP]
|
|
|
|
|
|
@pytest.mark.parametrize(
|
|
"text, message",
|
|
[
|
|
("scad.ref.face('base', 'make_box_rsolid')", "role=, by topo="),
|
|
("scad.ref.face('base', 'make_box_rsolid', role='box.top', topo='face_1')", "exactly one"),
|
|
("scad.ref.face('base', 'make_box_rsolid', between=('a', 'b'))", "between= names an edge"),
|
|
("scad.ref.edge('base', 'make_box_rsolid', role='x', piece=-1)", "piece"),
|
|
("scad.ref.face('base', 'make_box_rsolid', role=__import__('os').name)", "literal values only"),
|
|
("scad.ref.face('base', 'make_box_rsolid', role='box.top', guard=('PLANE', (0, 0), 1))", "guard"),
|
|
("scad.ref.solid('base', 'make_box_rsolid', role='box')", "a solid has no kernel role"),
|
|
("scad.ref.shell('base', 'make_box_rsolid', topo='shell_0')", "not a reference"),
|
|
],
|
|
)
|
|
def test_a_malformed_reference_is_refused(text, message):
|
|
with pytest.raises(ValueError, match=message):
|
|
scad.ref.parse(text)
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Statuses: ok, split, merged, lost
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
|
def test_ok_through_a_boolean_as_a_query_predicate_and_an_operation_selection():
|
|
with scad.GraphSession(namespace="base"):
|
|
box = scad.make_box_rsolid(40, 20, 10)
|
|
cut = scad.cut_rsolid(box, scad.make_cylinder_rsolid(3, 30))
|
|
resolution = TOP.resolve(cut)
|
|
assert resolution.status == "ok" and resolution.bodies == [0]
|
|
assert TOP.one(cut).get_area() == pytest.approx(800 - 9 * math.pi)
|
|
(face,) = ql.faces().where(ql.ref(TOP)).exactly(1).resolve(cut)
|
|
assert face == TOP.one(cut)
|
|
# The edges picked on the box are found after the cut through the faces they lie between.
|
|
rims = [scad.ref.of(e, box) for e in _rim_edges(box)]
|
|
rounded = scad.fillet_rsolid(cut, scad.ref.edges(rims), 1.0)
|
|
assert rounded.get_volume() < cut.get_volume()
|
|
assert TOP.one(rounded).get_area() == pytest.approx(38 * 18 - 9 * math.pi, rel=1e-6)
|
|
# The record travels in the selector (to_dict) and with it when pickled.
|
|
selector = scad.ref.faces(TOP)
|
|
assert selector.to_dict()["predicate"]["kind"] == "ref"
|
|
assert pickle.loads(pickle.dumps(selector)) == selector
|
|
|
|
|
|
def test_a_split_is_an_error_with_the_pieces_through_any_operation_and_a_choice_writes_piece():
|
|
slot = _tool("groove", lambda: scad.make_box_rsolid(4, 30, 4, (0, 0, 8)))
|
|
with _session():
|
|
box = scad.make_box_rsolid(40, 20, 10)
|
|
cut = scad.cut_rsolid(box, slot)
|
|
with pytest.raises(scad.ElementRefError) as caught:
|
|
TOP.one(cut)
|
|
assert caught.value.status == "split"
|
|
assert [round(c.center[0], 6) for c in caught.value.candidates] == [-11.0, 11.0]
|
|
# The same error, with its candidates, reaches the caller of a C++ operation that resolved the reference.
|
|
with pytest.raises(scad.ElementRefError) as through:
|
|
scad.shell_rsolid(cut, scad.ref.faces(TOP), 1.0)
|
|
assert through.value.status == "split" and len(through.value.candidates) == 2
|
|
with pytest.raises(scad.ElementRefError):
|
|
ql.faces().where(ql.ref(TOP)).resolve(cut)
|
|
|
|
chosen = TOP.choose(1, cut)
|
|
assert chosen.piece == 1 and chosen.code().endswith("role='box.top', piece=1)")
|
|
assert chosen.one(cut).get_center().x == pytest.approx(11.0)
|
|
shelled = scad.shell_rsolid(cut, scad.ref.faces(chosen), 1.0)
|
|
assert shelled.get_volume() < cut.get_volume()
|
|
|
|
|
|
def test_a_coplanar_union_is_merged_and_still_one_face():
|
|
wing = _tool("wing", lambda: scad.make_box_rsolid(20, 20, 10, (25, 0, 0)))
|
|
with _session():
|
|
box = scad.make_box_rsolid(40, 20, 10)
|
|
joined = scad.union_rsolid(box, wing)
|
|
resolution = TOP.resolve(joined)
|
|
assert resolution.status == "merged"
|
|
assert TOP.one(joined).get_area() == pytest.approx(1100.0)
|
|
|
|
|
|
def test_a_lost_reference_offers_look_alikes_and_accepting_one_writes_a_new_reference():
|
|
cutter = _tool("trim", lambda: scad.make_box_rsolid(50, 30, 5, (0, 0, 6)))
|
|
with _session():
|
|
box = scad.make_box_rsolid(40, 20, 10)
|
|
top = scad.ref.of(_top(box)[0], box) # with its guard
|
|
trimmed = scad.cut_rsolid(box, cutter)
|
|
resolution = top.resolve(trimmed)
|
|
assert resolution.status == "lost" and resolution.reason == "deleted"
|
|
assert resolution.candidates and resolution.candidates[0].center[2] == pytest.approx(6.0)
|
|
described = resolution.describe()
|
|
assert described["status"] == "lost" and described["candidates"][0]["geom_type"] == "PLANE"
|
|
with pytest.raises(scad.ElementRefError) as caught:
|
|
ql.faces().where(ql.ref(top)).resolve(trimmed)
|
|
assert caught.value.status == "lost" and caught.value.candidates
|
|
accepted = top.choose(0, trimmed)
|
|
assert accepted != top
|
|
assert accepted.one(trimmed).get_center().z == pytest.approx(6.0)
|
|
with pytest.raises(ValueError, match="nothing to choose"):
|
|
accepted.choose(0, trimmed)
|
|
|
|
|
|
def test_an_edge_between_faces_that_no_longer_meet_is_lost():
|
|
with scad.GraphSession(namespace="base"):
|
|
box = scad.make_box_rsolid(40, 20, 10)
|
|
rim = scad.ref.of(_rim_edges(box)[0], box)
|
|
rounded = scad.fillet_rsolid(box, scad.ref.edges(rim), 2.0) # the faces now meet through the fillet patch
|
|
resolution = rim.resolve(rounded)
|
|
assert resolution.status == "lost" and resolution.reason == "not_adjacent"
|
|
assert resolution.candidates # look-alikes by its guard
|
|
|
|
|
|
def test_a_pick_made_by_a_later_cell_does_not_hide_the_history_of_the_value_it_read():
|
|
# Cell "cup" picks the top of base (recording the pick re-stamps the shared face, SDK_DEFECTS 56); cell "groove"
|
|
# cuts base afterwards: its history names the pick as the parent, and the reference still follows the face.
|
|
from simplecadapi._glue.session import GraphSession
|
|
|
|
with GraphSession(graph_id="picks", namespace="base.c1", shared_lineage=True):
|
|
base = scad.make_box_rsolid(40, 20, 10)
|
|
with GraphSession(graph_id="picks", namespace="cup.c2", shared_lineage=True):
|
|
scad.apply_tag_rselection(base, scad.ref.faces(TOP), "lid")
|
|
with GraphSession(graph_id="picks", namespace="groove.c3", shared_lineage=True):
|
|
groove = scad.cut_rsolid(base, scad.make_box_rsolid(4, 30, 4, (0, 0, 8)))
|
|
resolution = TOP.resolve(groove)
|
|
assert resolution.status == "split", (resolution.reason, resolution.lost_at)
|
|
|
|
|
|
def test_multi_body_results_say_which_body():
|
|
saw = _tool("saw", lambda: scad.make_box_rsolid(4, 30, 30, (0, 0, -10)))
|
|
with _session():
|
|
box = scad.make_box_rsolid(40, 20, 10)
|
|
pieces = scad.cut_rsolid_list(box, saw)
|
|
assert len(pieces) == 2
|
|
halves = [TOP.resolve(piece) for piece in pieces]
|
|
assert [r.status for r in halves] == ["ok", "ok"]
|
|
assert all(r.bodies == [0] for r in halves)
|
|
assert sorted(round(TOP.one(piece).get_center().x, 6) for piece in pieces) == [-11.0, 11.0]
|
|
|
|
|
|
def test_a_reference_predicate_needs_a_shape_to_resolve_in():
|
|
with scad.GraphSession(namespace="base"):
|
|
box = scad.make_box_rsolid(40, 20, 10)
|
|
predicate = ql.ref(TOP)
|
|
assert predicate.kind == "ref" and predicate.data["ref"]["role"] == "box.top"
|
|
with pytest.raises(ValueError, match="resolves in one shape"):
|
|
predicate(_top(box)[0])
|
|
with pytest.raises(ValueError, match="takes face references"):
|
|
scad.ref.faces(scad.ref.edge("base", "make_box_rsolid", between=("box.top", "box.front")))
|
|
|
|
|
|
def test_a_feature_cell_namespace_names_the_feature_by_its_slug():
|
|
# A feature cell's key is "<slug>.<code digest>" (runtime/cells.py): references name the slug, so an edit of the
|
|
# cell's code (another key) keeps them.
|
|
from simplecadapi.runtime.cells import cell_keys, feature_of_key
|
|
|
|
(key,) = cell_keys(["# ---- feature: base (build) ----\nbase = scad.make_box_rsolid(40, 20, 10)"])
|
|
assert key.startswith("base.c") and feature_of_key(key) == "base"
|
|
for code in ("base = scad.make_box_rsolid(40, 20, 10)", "base = scad.make_box_rsolid(55, 20, 10)"):
|
|
with scad.GraphSession(namespace=cell_keys([f"# ---- feature: base (build) ----\n{code}"])[0]):
|
|
box = scad.make_box_rsolid(40 if "40" in code else 55, 20, 10)
|
|
assert scad.ref.of(_top(box)[0], box, guard=False) == TOP
|
|
assert TOP.one(box).get_area() == pytest.approx(box.get_volume() / 10)
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Persistence: model JSON replay, the cell cache in a fresh process
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
|
def test_a_model_with_references_replays_from_its_json():
|
|
with scad.GraphSession(namespace="base") as session:
|
|
box = scad.make_box_rsolid(40, 20, 10)
|
|
rims = [scad.ref.of(e, box) for e in _rim_edges(box)]
|
|
cut = scad.cut_rsolid(box, scad.make_cylinder_rsolid(3, 30))
|
|
rounded = scad.fillet_rsolid(cut, scad.ref.edges(rims), 1.0)
|
|
tagged = scad.apply_tag_rselection(rounded, scad.ref.faces(TOP), "mount.face")
|
|
payload = scad.export_model_json(session)
|
|
replayed = scad.replay_model_json(payload)[-1]
|
|
assert replayed.get_volume() == pytest.approx(tagged.get_volume())
|
|
(face,) = ql.faces().where(ql.tag("mount.face")).resolve(replayed)
|
|
assert face.get_area() == pytest.approx(TOP.one(tagged).get_area())
|
|
|
|
|
|
NOTEBOOK = '''\
|
|
# /// script
|
|
# [tool.simplecadapi]
|
|
# id = "refs"
|
|
# kind = "part"
|
|
# ///
|
|
import marimo
|
|
|
|
app = marimo.App()
|
|
|
|
with app.setup:
|
|
import simplecadapi as scad
|
|
|
|
|
|
@app.cell
|
|
def _():
|
|
# ---- feature: base (build) ----
|
|
base = scad.make_box_rsolid(WIDTH, 20.0, 10.0)
|
|
return (base,)
|
|
|
|
|
|
@app.cell
|
|
def _(base):
|
|
# ---- feature: bore (subtract) ----
|
|
_tool = scad.make_cylinder_rsolid(3.0, 30.0)
|
|
bore = scad.cut_rsolid(base, _tool)
|
|
return (bore,)
|
|
|
|
|
|
@app.cell
|
|
def _(bore):
|
|
# ---- feature: rounded (modifier) ----
|
|
_edges = scad.ref.edges(scad.ref.edge("base", "make_box_rsolid", between=("box.front", "box.top")))
|
|
rounded = scad.fillet_rsolid(solid=bore, edges=_edges, radius=1.0)
|
|
return (rounded,)
|
|
|
|
|
|
@app.cell
|
|
def _(rounded):
|
|
# ---- feature: cup (modifier) ----
|
|
top = scad.ref.face("base", "make_box_rsolid", role="box.top")
|
|
cup = scad.apply_tag_rselection(rounded, scad.ref.faces(top), "mount.face")
|
|
return (cup, top)
|
|
|
|
|
|
if __name__ == "__main__":
|
|
app.run()
|
|
'''
|
|
|
|
|
|
def test_references_resolve_through_the_cell_cache_in_a_fresh_process(tmp_path):
|
|
path = tmp_path / "refs.py"
|
|
script = textwrap.dedent(
|
|
"""
|
|
import json, sys
|
|
import simplecadapi as scad
|
|
from simplecadapi.runtime import run_notebook
|
|
run = run_notebook(sys.argv[1])
|
|
top = run.values["top"]
|
|
print(json.dumps({"statuses": [c.status for c in run.cells], "volume": run.values["cup"].get_volume(),
|
|
"tagged": [f.get_area() for f in scad.ql.faces().where(scad.ql.tag("mount.face")).resolve(run.values["cup"])],
|
|
"top": repr(top),
|
|
"status": top.resolve(run.values["rounded"]).status}))
|
|
"""
|
|
)
|
|
|
|
def run() -> dict:
|
|
done = subprocess.run([sys.executable, "-c", script, str(path)], capture_output=True, text=True, timeout=600, cwd=tmp_path)
|
|
assert done.returncode == 0, done.stderr[-2000:]
|
|
return json.loads(done.stdout.strip().splitlines()[-1])
|
|
|
|
path.write_text(NOTEBOOK.replace("WIDTH", "40.0"), encoding="utf-8")
|
|
first = run()
|
|
second = run() # a fresh process: every cell comes from the cache, the references resolve on restored values
|
|
assert "cached" in second["statuses"] and second["statuses"].count("cached") >= 3
|
|
assert second["volume"] == pytest.approx(first["volume"])
|
|
assert second["status"] == "ok" and second["top"] == "scad.ref.face('base', 'make_box_rsolid', role='box.top')"
|
|
assert len(second["tagged"]) == 1 and second["tagged"] == pytest.approx(first["tagged"])
|
|
# An edit of the base cell's code (another key) keeps every reference into it: they name the feature's slug.
|
|
path.write_text(NOTEBOOK.replace("WIDTH", "55.0"), encoding="utf-8")
|
|
edited = run()
|
|
assert edited["status"] == "ok" and edited["volume"] > first["volume"]
|