OneCAD-Draft/docs/cadkernel-body-path.md

Scripting ACIS bodies through opencadkernel: findings and plan

Investigation of the blocker on Solid3D, Body, Region and Surface (docs/plugin-host-model-coverage-ledger.md). The blocker said a script can neither produce a valid ACIS payload nor edit one, and that the handover forbids rewriting an opaque payload without a proven lossless path. This note records what OCS's own kernel path can already do, measured with two spike tests (spike_kernel_body_round_trip, spike_kernel_timings in src/app/plugin_host.rs, both #[ignore] because they are slow in a debug build). Measured on opencadcodec 5b682ed / opencadkernel 6f046af, debug build.

Conclusion: the blocker was overstated. OCS already owns a kernel-backed create/transform/boolean pipeline whose output is verified lossless before it is accepted. The missing piece is not geometry but an operation channel from a script to that pipeline. Solid3D and Body are then straightforward; Region and Surface need a little more; the one real cost is boolean speed.

What exists

Capability	Where	Notes
Primitives: box, wedge, cylinder, cone/frustum, elliptical cylinder, sphere, torus, pyramid, pyramid frustum	scene/model/solid_model.rs (box_solid, ...)	return a kernel Body
Transforms: place, turn about an axis, mirror, column-major 4x4	placed, turned, mirrored, by_matrix	analytic surfaces move with their frames, no point rewriting
Booleans: union, subtract, intersect	boolean_result	refuses with a reason instead of returning a broken solid
Body to entity payload	acis_export::solid_to_sat	self-verifying: it lifts its own SAT text and SAB binary back and returns None unless both are lossless (loss.is_empty()) and validate
Entity payload to body	solid3d_tess::kernel_body / kernel_region_body / kernel_surface_body / kernel_acis_body	returns None when the lift is lossy or has more than one body
Regenerating derived data	app/model_ops.rs::entity_with_boolean_body	rewrites acis_data, wires, clears silhouettes and history_handle for Solid3D, Region and Surface
Volume, extent, edge wires	volume, extent, edge_wires	used as oracles below

kernel_acis_body is exactly the "proven lossless path" the handover asked for: a payload is edited only if it lifts with no loss, otherwise it is left alone.

Spike results

Everything below passed, with the kernel's own volume as the oracle.

Test	Result
Box 10x6x4 to Solid3D	volume 240, 12 edge wires, lifts back
DWG save/reopen	lifts back, volume 240, 12 wires kept. acis_data changes from SAT text to SAB binary (same solid, different bytes)
DXF save/reopen	lifts back, volume 240. Cached wires are dropped (0) and are regenerated on demand; silhouettes were already empty
Translate by (5,5,5)	volume 240, extent shifted exactly, lifts back
Rotate 45 degrees about Z	volume 240, extent -5.657..5.657, lifts back
Mirror in X	volume 240, lifts back
Box union cylinder	volume 315.277, 16 wires, lifts back
Box subtract cylinder	volume 189.815, 14 wires, lifts back
Box intersect cylinder	volume 50.185, 2 wires, lifts back
Sphere, torus, wedge, pyramid	volumes 112.696, 98.415, 12.000, 28.532; all lift back
Same payload in a Body entity	lifts back; still lifts back after DWG and after DXF

Timings (debug build): primitive, transform, solid_to_sat and edge_wires are effectively instant (under 0.05 s). Each boolean took about 23 s, most likely a debug-build artifact for a kernel doing heavy numeric work, but it has not been measured in release and must be before booleans are exposed.

Two things to understand about "lossless":

• DWG rewrites SAT text as SAB binary. The solid is identical (same volume, topology, faces) but the bytes are not, so the honest oracle is "lifts back with no loss and the same volume", not byte equality. An untouched body that a script never edits is written exactly as OCS writes any other body.
• DXF does not carry the cached wires; they are derived data.

Design

The obstacle is the channel. The generic entity path moves an opencadcodec EntityType from the plugin to the host; the plugin has no kernel and must never see or rewrite ACIS bytes. Three ways to give a script the operations:

A. Host-side normalization with a request carrier (no ABI change). A hand-written converter (as for Dimension) turns create_entity('Solid3D', primitive='box', ...) into a Solid3D that carries the request in an otherwise unused field, and the host's normalize_scripted_entity replaces it with the real payload, exactly as it already does for MLine geometry, Helix splines and image definitions. It works inside today's v7 protocol, but the carrier field is a hack.

B. New host operation (recommended). Add one additive operation to HostApi and the v4 IPC protocol, for example solid_operation(op) -> Result<Handle, String>, with op one of: create primitive, transform, boolean, and (later) region from curves. The host runs it through the pipeline above inside an undo step and returns the new or updated handle. Because it is a new method with a default "unsupported" implementation it is backward compatible; bump the minor/negotiate by capability rather than the major version. Python side:

box  = doc.solids.box(center=(0, 0, 0), size=(10, 6, 4))
cyl  = doc.solids.cylinder(base=(0, 0, -3), radius=2, height=10)
hole = box.subtract(cyl)            # new Solid3D; operands untouched
box.transform(translate=(5, 5, 5))  # in-place, transactional, undoable

C. Do nothing but layer edits (the current state).

Recommended: B, with solid_operation covering create, transform and boolean. Every operation goes through solid_to_sat (self-verifying) and the kernel's own refusal path, so a failure is an error before any mutation, and an untouched payload is never rewritten. In-place edits of an existing entity are gated by kernel_acis_body returning Some: a payload the kernel cannot lift losslessly is refused with a clear message instead of being rewritten.

Per-kind feasibility

Kind	Create	Edit	Notes
Solid3D	9 primitives, boolean of two solids	transform, boolean	Straightforward. Regenerate wires; clear silhouettes; history_handle is cleared by entity_with_boolean_body, so a history-carrying solid needs a decision (refuse, or accept losing parametric history).
Body	same payload container	transform	Same pipeline, kernel_acis_body works on a Body payload (spike). A true non-solid (sheet or wire) body may not lift; those stay layer-only.
Region	from closed curve entities (the REGION command's add_region_model)	transform	Needs a "region from these curve handles" operation and planar-face construction.
Surface	plane, extruded, revolved from a profile	transform	The most involved: surface kinds carry surface_data besides acis_data, and only Plane keeps its kind on regeneration (SurfaceKind::Generic otherwise).

Risks and open questions

1. Boolean speed. Measured in release, see "Boolean timings" below: about 1 to 2.2 s for a box and a cylinder, 0.2 s for two spheres and 1 to 2 ms for planar-only operands, against 23 s in a debug build. The kernel also refuses many curved cases, which matters more than speed.
2. Interoperability cannot be verified here. solid_to_sat is verified by OCS's own lifter. Whether AutoCAD accepts the SAT/SAB that OCS writes is not testable without AutoCAD, so completion should be scoped as "OCS round trip", as for RasterImage.
3. Parametric history. Regenerating a payload clears history_handle.
4. Frames. Some solids carry a body-to-world transform in the SAT (body_transform in kernel_acis_body); the lift already applies it, and the spike's translated/rotated bodies confirm it, but a foreign DWG with a scaled or sheared body transform should be added as a fixture.
5. API surface. solid_operation is a protocol addition; decide whether it is one generic operation enum or separate methods before starting.

Suggested phases

1. solid_operation protocol and host executor for create primitive and transform on Solid3D, with the full lifecycle test through the real runner (volume oracle, DWG and DXF reopen, undo, refusal of a lossy payload).
2. Booleans (after release-build timing) and the Body container.
3. Region from curve handles.
4. Surface (plane first).

Phase 1 alone would move Solid3D from blocked to complete-in-OCS.

Status (2026-09-20): phase 1 is done. HostApi::solid_operation (create primitive and rigid transform), the doc.solids Python API and audit_python_solid3d_lifecycle_over_real_ipc are in; Solid3D is complete, Body moves through the same channel. Design B was implemented as recommended. Region creation from a closed profile followed (RegionFromProfile). Plane surfaces and extrusions (SurfaceFromProfile, Extrude) followed. Only booleans remain, plus lofted, revolved, swept and NURBS surfaces.

Boolean timings (release build)

Measured 2026-09-20 in a scratch crate built with --release (opt-level 3) against the same opencadkernel revision OCS pins (6f046af, features acis and offset), calling exactly what OCS's solid_model::boolean_result calls: brep::operation_tolerance then brep::combine. A debug build of OCS is about 22 times slower, so booleans must never be exercised in a debug test run. The scratch program is not in the repository; to repeat it, depend on opencadkernel at that revision and time brep::combine on brep::make::{cuboid, cylinder, sphere, torus} operands.

Operation	Time	Result
box union / subtract / intersect cylinder (10x6x4 box, r=2 cylinder)	1.05 to 1.08 s each, identical on repeat runs	ok
same, operands scaled 10x and 100x	2.21 s and 2.21 s	ok
box union / subtract box (planar only)	0.001 to 0.002 s	ok
sphere union sphere (overlapping)	0.22 s	ok
sphere subtract sphere (overlapping)	0.23 s	refused CutRefused
box subtract sphere (sphere cutting the box faces)	1.28 s	refused Coincident
sphere union torus (disjoint)	under 1 ms	refused NoClosedForm
torus subtract cylinder through the ring	under 1 ms	refused NoClosedForm
drill a first cylinder hole in a box	0.03 s	ok
drill a second hole in the drilled box	under 1 ms	refused CutRefused

What this means:

• Speed is acceptable. A curved boolean costs 0.2 to 2.2 s, the same cost as the GUI BOOLEAN command, and planar work is instant. The 23 s seen earlier was a debug-build artifact.
• It blocks the host thread. The plugin's PY_RUN is a synchronous dispatch and nested host requests run inline, so a script freezes the UI while a boolean runs. One to two seconds per operation is tolerable; a script with dozens is not.
• The whole script has a budget. A Dispatch call uses the 30 s default timeout (OCS_PLUGIN_CALL_TIMEOUT_SECS, with a 10 s floor), and nested host work counts against one deadline. Roughly fifteen curved booleans in a single script would exceed it.
• Refusals are the real limit. The kernel says no often: coincident faces, a cut it has no closed form for, torus operands, and, surprisingly, a second cut in a body that was already drilled. Refusals are fast and leave the inputs intact, which is the behavior the API already relies on, but it means booleans will be a partial feature that fails with a reason, not a general one.
• Timing is not proportional to size. Scaling the operands 10x doubled the time, 100x changed nothing more, so the cost is dominated by the surface intersection setup rather than the geometry size.

Recommendation

Add SolidOperation::Boolean { first, second, operation, layer } and run it synchronously on the host thread, surfacing the kernel's refusal (Coincident, CutRefused, NoClosedForm, ...) verbatim in the error and leaving both operands untouched on failure. Build the result with the existing entity_with_boolean_body path so it inherits the lossless verification. Test it with planar operands (millisecond cost, safe in debug) plus one #[ignore] curved case that documents the release-only runtime. Document the 30 s script budget and that chained cuts on a drilled body are often refused. Do not move booleans to a background thread yet: it would need cancellation and undo coordination for a cost that is one to two seconds.

Status (2026-09-20): implemented. SolidOperation::Boolean and doc.solids.union, subtract and intersect follow the recommendation above, with planar-operand lifecycle testing and an ignored curved refusal test. Every operation this note proposed is now built.