simplecadapi 2.2.7

2.2.7 Update Notes

The first stable release of the C++ engine (2.2.7b1 was the beta): the geometry engine is C++ on OpenCASCADE, shipped inside
prebuilt wheels, and pip install simplecadapi needs no cadquery-ocp and no OpenCASCADE on the machine. This release makes
the editor much faster, lets Var and Expr be used like numbers, and fixes what the beta left out.

Prebuilt packages

Linux x86_64 and aarch64 (manylinux_2_28), macOS arm64 (14+) and Windows x86_64, each for Python 3.10, 3.11, 3.12 and 3.13, all
linked against the same OpenCASCADE 7.9.3. There are no wheels for macOS Intel, musl Linux or Windows on ARM; there the source
distribution builds the module and needs a C++20 toolchain and OpenCASCADE >= 7.8.

The editor is faster

Measured on the six-axis arm (sandbox-envs/desktop_arm_sources) in the editor, same machine:

	2.2.6.post2	2.2.7b1	2.2.7
cold start	64.5 s	48.8 s	34.9 s
start with nothing changed	4.1 s	2.1 s	1.6 s
a joint angle never seen before	4.4 s	5.7 s	2.7 s
a joint angle seen before	6.2 s	5.5 s	0.6 s
idle memory	1038 MB	322 MB	617 MB

• The model reaches the page sooner. The kernel publishes the model as parts identified by the content of their geometry,
  the server sends each page only the parts that page lacks, and the page builds geometry only for new parts. A joint angle
  moves 115 KB instead of 6.26 MB; from the last cell to the model on screen takes 0.36-0.41 s instead of 1.3-3.2 s. The
  model is pushed over the WebSocket in the preview event itself, with no second request.
• The kernel keeps what its cells made and what use() returned, and a saved parameter's digest follows what a cell
  reads: changing one joint angle no longer redoes the cell that builds the parts. The cost is memory: about 300 MB more at
  idle than the beta (the kernel keeps the twelve most recent cell results).
• One case is still slower than 2.2.6: a new value of OPEN_STROKE on the arm takes 5.8 s (2.2.6.post2: 4.7 s; the beta:
  6.8 s), because the assembly solve it triggers is real work.

Var and Expr behave like numbers

int(r), round(r, 2), r > 3, max(r, 3), sorted([...]), range(n), [0] * n, lst[n - 1], r // 2, r % 3,
f"{r:.2f}" and str(r) now work and read the value the variable has now; arithmetic still builds the formula that keeps
the link to the parameters. r == 5.0 is True (it was False), and a ql predicate with a value computed from a Var
(ql.prop("geom.length", ">=", 2 * math.pi * radius)) now matches, where 2.2.6 matched nothing.
Still errors: bool(var) (write if r > 0:) and json.dumps(var); numpy needs float(var). A notebook that relies on the new
behaviour does not run unchanged on 2.2.6; float(var) makes it portable.

shape.wrapped is an OCP shape

With OCP installed (pip install "simplecadapi[verify]"), shape.wrapped is an OCP shape of the class of its kind
(TopoDS_Solid, TopoDS_Face, ...), so verifier scripts written with the OCCT API run as written. It is a copy: every access
makes a new one, and a change made to it does not reach the SDK's shape. simplecadapi.verify.to_ocp / from_ocp are the
explicit forms. SCA_WRAPPED=native|ocp chooses. Without OCP it stays the SDK's own OCCT shape. The fem extra is gone.

Failures and fixes

• A failing fillet or chamfer, and a failing ql exactly(), attach their picture again (2.2.7b1 drew one for booleans only).
• The editor starts with whatever model file is on disk: a damaged or partial one is not restored and no longer leaves the
  editor "starting the kernel" for ever. A damaged preview is refused with the reason (400), not as missing parts.
• Cache entries written by an older build that name classes which no longer exist are replaced; a notebook with such entries
  (a child run through use, the arm's gripper) takes 0.8 s instead of 3-6 s.
• An OCCT failure while reading a geometry type or closedness makes the property absent, as in 2.2.6.
• A failure that is handled and used to leave no trace prints a [sca] line on stderr.

Upgrading

• Notebooks with saved parameter values rebuild once after the upgrade (their cells' digests changed).
• shape.wrapped is a copy when OCP is installed (above).
• New switches are listed in docs/environment.md.

The skill

discipline/notebook-cell-design.md states where the cell boundaries go, when a number is a scad.var, and why, with the error
you get when a rule is broken.

For contributors

The C++ tree is formatted (.clang-format, checked in CI), has a CONTRIBUTING.md, a reading order and a landing plan under
src/cpp/, named tolerances (scad::tol), no swallowed exceptions or unchecked optionals that clang-tidy reports, and its
doctest executables run in CI in Release and under ASan and UBSan. The old tests that do not apply to the soft renderer are
listed in src/cpp/docs/DEVIATIONS.md.

---

中文说明：docs/updates/2.2.7.zh-CN.md

simplecadapi 2.2.7b1

2.2.7b1 Update Notes (beta)

The geometry engine is now C++ on OpenCASCADE, shipped inside the wheel. pip install simplecadapi
needs no cadquery-ocp and no OpenCASCADE on the machine. Models, graphs, packages and the public
API behave as before: the whole previous test suite passes on the new engine.

Prebuilt packages

platform	wheels
Linux x86_64 (manylinux_2_28)	Python 3.10, 3.11, 3.12, 3.13
Linux aarch64 (manylinux_2_28)	Python 3.10, 3.11, 3.12, 3.13
macOS arm64 (macOS 14+)	Python 3.10, 3.11, 3.12, 3.13
Windows x86_64	Python 3.10, 3.11, 3.12, 3.13

Every wheel links the same OpenCASCADE 7.9.3, built from source, so a model computes the same on
every platform. There are no wheels for macOS Intel, musl Linux or Windows on ARM; there the source
distribution builds the module and needs a C++20 toolchain and OpenCASCADE >= 7.8.

This is the first release with prebuilt wheels: please report a platform that does not install or
import.

Faster and smaller

On the six-axis arm (sandbox-envs/desktop_arm_sources), same sources, same machine, Python runtime:

	2.2.6.post2	2.2.7b1
cold build	43.8 s	29.1 s
nothing changed	12.8 s	6.0 s
edit one joint	9.9 s	6.1 s
peak memory, cold build (process tree)	2690 MB	2043 MB
import simplecadapi	1.6 s, 360 MB	0.2 s, 68 MB

The models computed are the same (volumes agree to 1e-12 relative).

One package

• The compiled module is simplecadapi._cpp; simplecadapi.core, simplecadapi.operators.*,
  simplecadapi.ql, simplecadapi.std.* and the other modules keep their import paths as
  forwarding modules, and each says in its docstring which C++ source defines its names.
• Removed dependencies: cadquery-ocp, ocp-gordon, py-slvs. The OpenCASCADE view of a shape
  (shape.wrapped) is now the module's own binding, simplecadapi._cpp.occt, laid out like OCP.
• SCA_BACKEND is gone: there is one backend.
• simplecadapi.inspect.brep is part of the default install and renders with the same software renderer as
  render_screenshot_rpath: no VTK, no GPU, no display server (no xvfb). matplotlib is now a core dependency; the
  inspect extra stays as an empty alias so older install commands keep working. Only simplecadapi.inspect.drawing
  still needs an extra (drawing).

Booleans that split a body

• New cut_rsolid_list(base, *tools) returns every piece of a cut: a slot through a bar gives both halves, a tool that
  encloses the whole body gives an empty list. It is recorded as make_cut_rsolid_list and replays.
• cut_rsolid used to return only the first piece when a cut split the body, silently losing the rest (a slot through a
  100x20x10 bar reported half the volume). It now raises and names cut_rsolid_list. A tool that only touches a wall
  tangentially also leaves a separate sliver, so a script that relied on the dropped sliver needs a tool that does not
  touch the wall, or cut_rsolid_list.

Errors

• Every message the library writes is English.
• The tag-validation and semantic-query errors render in full, like every operator error: what
  happened, possible causes, how to fix.

Python 3.10 to 3.13

Built and tested on all four.

---

中文说明：docs/updates/2.2.7b1.zh-CN.md

simplecadapi 2.2.6.post2

2.2.6.post2 Update Notes

No change in what the SDK computes. Eight operators moved to the module of their family, and
the API reference they are documented in is now generated for all of them.

Operators live with their family

operator	now in
scale_rsolid, transform_rsolid	operators/transform.py (next to translate_shape, rotate_shape)
boolean_rsolidlist	operators/boolean.py (next to union_rsolid, cut_rsolid)
offset_rsolid, draft_rsolid, extrude_taper_rsolid, extrude_until_rsolid, sweep_multisection_rsolid	operators/features.py (next to extrude_rsolid, shell_rsolid, sweep_rsolid)

from simplecadapi import scale_rsolid (and every other name) works as before. Code that
imported them from the modules they were first written in, simplecadapi.operators.deformation,
draft, section_features or limited_extrusion, still works and gets a DeprecationWarning
naming the new place; import from simplecadapi instead.

The API reference is generated for every operator

The documentation generator kept its own hand-written list of source files and public
functions, and nobody had added those four modules to it. The docs of the eight operators above
were therefore written by hand, and the generator deleted them whenever it ran, while
boolean_rsolidlist had none. Now operators/ is discovered, a function the package exports is
public, and what the hand-written docs said (examples, error conditions, how the operation is
replayed) is in the docstrings, so it is in the generated docs. Tests fail if a public operator
has no doc, or if the committed docs differ from what the generator writes.

simplecadapi 2.2.6.post1

2.2.6.post1 Update Notes

A hotfix for the editor's parameter panel, and a round of speed work on the notebook cache
and on use, measured on the desktop six-axis arm.

scad.var(name=..., default=...) is a parameter again

The editor found a parameter's default only as the second positional argument of
scad.var. A declaration written with keywords —

J1 = scad.var(name="j1", default=0.0, comment="Joint 1")

— was skipped: no slider, no commit back to the file. Both forms are read now, and
committing a value rewrites the right argument in either.

What a cached run costs

desktop arm	before	now
cold run	80.5 s	34.6 s
nothing changed	23.6 s	4.0 s
one joint angle edited	18.2 s	3.0 s
a link length edited	35.1 s	19 s
cache on disk	1.7 GB	96 MB

• Restoring is cheaper. A restored shape is built when something first uses it, so a
  cached value no running cell reads costs nothing; the tag caches are rebuilt once, not
  once per ancestor. The cache no longer stores a cell's private (_name) values and
  compresses what it writes; entries from before are still read.
• Parameters are keyed by value. A cell that reads one scad.var is not redone because a
  neighbour defined in the same cell changed.
• A name, not a file. from lib.dims import A depends on the definition of A.
• use is followed one call at a time. A cell that uses a notebook by a literal path
  depends on that notebook (its text, the modules it imports, the notebooks it uses): editing
  one child redoes the cell that uses it, not its siblings. The editor kernel caches such
  cells too.
• use calls run side by side. The use calls a cell is about to make are started in
  worker processes (threads would not help: OpenCASCADE keeps the interpreter lock) and the
  cell finds them built. SCA_JOBS sets the number (default: the smaller of 4 and the
  cores; 1 turns it off). Workers are started only when that saves more than they take to
  start, and a notebook is locked between processes while it runs.
• Editor sliders. A drag is sent when it pauses (250 ms) or ends, not step by step.

v2.2.6

What's Changed

• release: 2.2.6 by @NiJingzhe in #52
• release: 2.2.6 by @NiJingzhe in #53

Full Changelog: v2.2.5...v2.2.6

2.2.5

2.2.5 Update Notes

From a container agent's field report: the editor now works the way agents actually use it,
and says what happened instead of leaving silence.

sca cell works behind container proxies

Before, a container's http_proxy swallowed the editor's health check and sca cell
answered "no editor is running" while one was. Now the editor's discovery record always
carries a loopback url (--host 0.0.0.0 included), the checks bypass the proxy environment,
and a record whose server does not answer is reported with its path and url instead of being
skipped quietly. A record whose pid is gone says "stale record … delete it or restart the
editor". When sca cell ls/get fall back to reading the file, they say so on stderr.

Cell feedback carries the chain

sca cell put/insert/run now return the console output and every cell left unhealthy by the
change, and the dependents a write made stale are run instead of waiting. A failing cell's
report names its upstream cells (the failing ones first), so the error you see can be traced
to its cause. A write whose rerun takes longer than the call now answers "the edit was
applied and the rerun is still going; check sca cell ls" instead of a raw socket error
(SCA_EDITOR_CALL_TIMEOUT raises the wait, default 300s).

Validate a stage headlessly

sca run stage.py --through 3 --no-product    # the first 3 cells, no product needed
sca run stage.py --timeout 600               # a wall clock for heavy fillets

--through N runs the first N cells, numbered the way the editor numbers them; --no-product
runs a work-in-progress notebook that has no product yet; --timeout fails a run that takes
longer (off by default).

Quieter output, shorter prints

The cache loaders' degraded-state warnings (unsigned entries, a value restored as a stub) no
longer print at WARNING, and the render paths switch VTK's warning display off process-wide —
this also hides VTK chatter from code you run in the same process. A real failure is still
raised and named. Printing a BRepInspection shows a one-line summary; the per-face records
are to_dict() / .faces / .edges.

Skill

While an editor runs, sca cell is the only way to change a regular cell — the file only when
no editor runs, or for the setup / @app.function cells sca cell refuses. dof=0 says the
constraint system closed, not that the shape is right (angle constraints can solve to the
mirror solution): verify by measurement. And a modeling project is managed like software:
git from the first file, commits at verified milestones.

See the changelog for the complete list.

2.2.4

2.2.4 Update Notes

The editor now tells you why no model is coming, instead of showing "building the model" until
its fallback clears.

A failed build is reported every time you ask for one

Before, a publish error was reported once per identical message. When the same failure repeated —
you press "run all" again, an agent edits a cell, the notebook file changes on disk — the editor
stayed silent: no model arrived, no error was shown, and the page waited out its three-minute
fallback. Now every run someone asks for reports its outcome afresh, and the veil lifts with the
reason (for example, a notebook whose top-level Part does not carry the notebook id; the message
ends with the Parts and Assemblies that were found instead). Reports during a slider drag are
still collapsed to one per identical state.

A page that opens or refreshes after the failure learns the reason at once, from the end of the
connection handshake.

The marimo button

The header's button that opened the raw marimo editor is gone.

See the changelog for the complete list.

simplecadapi 2.2.3

2.2.3 Update Notes

The editor (sca edit) and an agent can now work on the same notebook without overwriting each other.

The editor takes in edits made to the file

Before, the editor held the open notebook in memory and rewrote the file on each edit, so a change
an agent saved was overwritten by the editor's next save and never shown. Now the file is watched:
a saved change is compared with the editor's cells and applied cell by cell. Changed cells are
updated and run again, added or removed cells appear or go away, and the page does not reload or
flicker. A change to the setup cell or an @app.function cell restarts the kernel instead; a file
that does not parse is ignored until the next save that does.

If a cell was edited in both places, the file's version is kept and the text you had not saved
goes to the log at the bottom. Notebooks added to or removed from the workspace appear in the list
by themselves.

sca cell and sca new

sca cell ls [--code]                 # numbered cells with status, errors and output
sca cell get 3
echo 'L = 90' | sca cell put 3       # replace a cell's code and run it
sca cell insert --after 3 -f new.py
sca cell rm 4
sca cell run [CELL ...]
sca new bracket --kind part          # a new notebook, listed by the running editor

These go through the running editor, found by <workspace>/.sca-editor/server.json: the page shows
the change live and each write prints the touched cell's status, errors and output. With no editor
running, or another notebook open, ls and get read the file and the write commands refuse: edit
the file directly then.

The skill (editor-collaboration) and landing.md now tell agents to work this way.

See the changelog for the complete list.

v2.2.2

2.2.2 Update Notes

Two additions to the code-first editor (sca edit), and a fix that made one of them usable.

Code completion from the SDK

scad. (and scad.ql., scad.std.gear., ql., Q.) lists the real functions with their
signatures; the side panel shows every parameter with its default and the docstring.

• Accepting a function, or typing ( after a known name, writes the call with every
  required parameter as name=: scad.make_box_rsolid(width=, height=, depth=).
  Tab moves to the next parameter.
• Inside a call, the parameters not given yet complete as name=, required ones first.
• The names come from the running package (GET /api/sdk), so they cannot drift from the code.

Create a notebook from the workspace tab

A new action in the notebooks header starts a notebook from the SDK's template: a part, or an
assembly that uses the first two parts of the workspace. The name is checked as you type. An empty
workspace opens on that form, so sca edit on an empty directory is usable.

Fixed

The cell editors rebuilt their configuration on every render, which dropped a snippet in progress
and could disturb typing; the editor's onChange and options are stable now.

See the changelog for the complete list.

v2.2.1

2.2.1 Update Notes

The first stable release of the 2.2 line. It brings the code-first editor, the
notebook runtime of 2.2.0b1 and the agent landing path to a stable version.

Editor: sca edit

• A web editor over a directory of notebooks, part of the SDK
  (pip install "simplecadapi[editor]"). It runs the notebooks in a marimo
  kernel with the SDK's own cell executor, previews the live model straight
  from the solids, and shares one per-cell cache with sca run.
• Parameters from # ---- params ---- cells (an optional # ui: comment picks
  the control); local modules (shared dimensions) have their own view.
• Picking a solid, face, edge or vertex writes a scad.ql selection cell
  (selected_<kind>, selected_item) into the notebook; edits autosave; a cell
  reference can be copied for a coding agent; sca snapshot shows an agent what
  the person sees. A log dock reports what ran and what failed.
• Light and dark themes (follows the system, with a manual switch).
• Re-Studio is removed: the reverse-engineering studio (Re-mode of the
  standalone sca-web-editor) is gone; sca edit replaces the standalone editor.

Landing path for agents

docs/landing.md is the script an agent follows to install the SDK and its
skill and to open an example in the editor. sca example u_link copies the
bundled workspace; sca skill where shows where the skill is installed. The
wheel now carries the built editor UI, the skill sources and the example.

Modeling

scale, affine transform, signed offset, draft, tapered and
until-limited extrusion and multisection sweep are recorded features. Volumes
and centres of mass integrate NURBS by knot spans, which is exact for rational
patches. A build123d to FTC converter is included under
tools/research/build123dftc (research tooling).

See the changelog for the complete list.