DECISION: write the decision down in the repository, with the discussion it came from, so that a person who was not in the conversation can take over and trace it. WHY: the multi-body Part was a design choice made for the editor's convenience, withdrawn on 2026-11-10 after the owner and the assistant talked it through (the owner's reasons: the editor needs several solids side by side with no assembly constraint, e.g. pattern a tool and cut; but making that a property of the Part makes assembly hard and was a wrong decision; the assistant's analysis: those solids are notebook intermediates, not product items, so Part = one solid and the editor shows loose solids). The owner also asked that every decision be its own commit with its reasons. Commit messages carry the short form; this file carries the whole chain, the audit table of what was broken in 2.2.8, the rules after the decision, and the list of commits. - design-docs/part-holds-one-solid.md: new; supersedes the older document. (design-docs/ is git-ignored, but the older design document is tracked, so this one is added the same way, with -f.) - design-docs/multi-solid-design.md: a note at the top says it is superseded and where to read instead; the body is left as it was (the record of what was tried). Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
29 KiB
Multi-body parts (several solids in one part, without an assembly)
SUPERSEDED on 2026-11-10 by
part-holds-one-solid.md. The multi-body Part described here was withdrawn: a Part holds exactly one solid again. Read that document for the decision, the reasons and the discussion behind it. This one is kept only as the record of what was tried.
Status: research and spike on research/multi-solid (cut from dev). The spike is in the code and in
test/test_multi_body_part.py. Everything under "Staged plan" after stage 1 is a proposal. Section 9 records the
owner's decisions and how they are implemented; where it differs from an earlier section, section 9 wins.
1. The decision
A Part holds an ordered set of named bodies. A body is a Solid with an id that is unique within its part. A one-body Part is the special case that every existing Part already is.
make_part_rpart(part_id=..., bodies={"base": base, "lid": lid})makes a part with two bodies.make_part_rpart(part_id=..., body=solid)is unchanged.part.bodiesreturns(Body, ...)in order.part.get_body("lid")returns one body andpart.body_ids()returns the ids.part.bodykeeps returning the Solid of a one-body part. On a multi-body part it raises aTypeErrorthat names the bodies. It never silently returns the first body: a caller that readspart.bodywould otherwise export, weigh or draw only part of the part.- A Body is product geometry and nothing more. It has no placement, joint, constraint or connector of its own in stage 1. Anything that moves relative to something else is a component of an Assembly. This is the line every surveyed CAD system draws (see section 3): Fusion says it outright, and SolidWorks says "one part = one BOM line".
- Construction solids, tool solids and "kept for a later boolean" solids are not bodies. They stay plain notebook
values, as they are today. The product is exactly what the product cell puts into the Part. This one rule covers
"tool bodies that must stay hidden" with no
visibleflag in the data model: hiding is an editor view state, and being part of the product is a modelling fact.
Why not a Compound inside the Part: a Compound is a new shape root and drops the tags of the solids it is built from
(verified: scad.Compound([a, b]) of two tagged boxes has no face tags; SDK_DEFECTS.md #21). Each body therefore stays
its own Solid root, with its own tags, lineage, graph node and topology snapshot. A Compound appears only as a
geometry view (scad.part_shape(part)), for consumers that do not care which body a face belongs to (STEP, STL,
MJCF).
Why not "a part studio of several Parts" (Onshape style): that would make each body a separate product definition
with its own part_id, BOM line and package unit. That is a real feature, but it is a different one: it amounts to
"one notebook, several products". This design keeps one product per notebook.
2. The data model today (evidence)
| Piece | Where | One-solid assumption |
|---|---|---|
Part (C++) |
src/cpp/include/scad/product/part.hpp:19 (before), part.cpp |
Solid body_ field. Header comment: "exactly one Solid" |
make_part_rpart |
bindings/python/bind_product.cpp:81, src/product/ops_structure.cpp:105 |
typed<Solid>(body). Docstring: "Wrap exactly one Solid" |
| guidance | src/cpp/src/product/specs.cpp:43 |
"Union intended multiple bodies into one Solid before creating the Part." |
Solid |
src/cpp/src/topo/shape.cpp:15 |
the kind is checked, so a Solid is exactly one TopoDS_Solid |
Compound |
include/scad/topo/shape.hpp:290 |
solids(). A new root, so the tags of its parts are lost (#21) |
| solid lists | cut_rsolid_list, boolean_rsolidlist, *_pattern_rsolidlist |
list[Solid] values in the notebook. Never a product |
cut_rsolid |
src/cpp/src/ops/features/booleans.cpp:372 |
refuses a split result (since bd36d58) |
| assembly flatten | src/cpp/src/product/ops_projection.cpp:20 |
part->body() |
| session children | src/simplecadapi/_glue/session.py:53 |
yield item.body |
| cell cache | runtime/cache.py:255 (_semantic_state) |
"A Part is its body" |
| pickling | _glue/values.py _reduce |
rebuilds Part(part_id, body, ...) from attributes (#22) |
@part builder |
build/part_builder.py:43 |
"must return exactly one Solid or one Part" (still true: one Part) |
| PartDefinition | artifacts/part_definition.py:30, schema contracts/part-definition-2.schema.json |
"exactly one evaluated Solid": one solid_cache.body_ref, one topology_snapshot_ref |
| definition build | build/definition.py:169-225 |
BRep, snapshot, geometry hash and validation of part.body |
| BRep reader | artifacts/brep.py:44 read_brep_solid |
"BRep root must be exactly one Solid" |
| part archive load | artifacts/part_io.py:93 |
read_brep_solid |
| materialize | artifacts/assembly_io.py:762 |
Part(body=read_brep_solid(...)) |
| package blob roles | product/packages.py:180 |
one body and one topology blob per part |
| live preview | scene/preview.py:271 (compile_preview) |
one PreviewNode per part, entity/<part>/<kind>/<topo> |
| package scene | scene/product_scene.py:322, :822 (_camera) |
one GLB and one entity document per part |
| legacy scene | scene/compiler.py:330, 339, 697, 928 |
part.body. "a standalone Compound must contain exactly one solid" |
| prewarm | scene/prewarm.py:39 |
one body per part |
| STEP | exporter/step.py:76 |
"shape": value.body |
| STL / surface mesh | exporter/_surface_mesh.py:45 |
(value.body,) |
| MJCF | exporter/mjcf.py:680 |
part.body |
| definition kind | 20 places | "single_solid". The kind name means "a part" (#23) |
| editor features | feat/gui-modeling:src/simplecadapi/editor/features.py:677 _with_combine |
"A part holds one solid": every new solid must join, cut or intersect, or start the body |
| editor product | feat/gui-modeling:.../gui_features.py:99, 489 |
the product cell is make_part_rpart(..., body=<one slug>), re-pointed after each feature |
| editor defaults | gui_features.py:_defaults |
operation = "join" if last is not None else "new" ("do not leave a second") |
| editor-web | editor-web/src/components/NotebookList.tsx:155 |
"a notebook that builds one solid" |
The editor already tracks the "open bodies" of a notebook: solids that no later feature consumed
(gui_features.py:129). Today only one of them reaches the product. A multi-body part is the missing link between
"open bodies" and the product.
3. Other CAD systems
The research used primary documentation read in a browser. V means read on the page. I means inferred or not confirmed.
- Onshape Part Studio. One feature list "drives the shape of multiple parts" (V, cad.onshape.com/help/Content/PartStudio/part_studios.htm). Each part is its own BOM item. Features choose New / Add / Remove / Intersect with a merge scope; when several touching parts are ambiguous the user must choose, and an empty scope is an error (V, .../extrude.htm). Boolean has "Keep tools", and a merge keeps the name of the first-selected part (V, .../boolean.htm). Mass properties are additive, overlaps count twice, and parts without a material are left out (V, .../View/mass_properties_tool.htm). Several parts export to one file by default (V, .../File/exporting_files.htm). A composite part groups bodies into one BOM line (V, .../composite_part.htm).
- SolidWorks multibody part. "Part documents can contain multiple solid bodies", kept in a Solid Bodies folder, each with its own name and colour (V, help.solidworks.com/2024 .../c_Multibody_Overview.htm). "One part (multibody or not) should represent one part number in a Bill of Materials", and bodies are "not dynamic" (V, .../c_Multibody_Parts_Vs_Assemblies.htm). Material is set per part; a per-body material overrides it (V, .../c_multibody_materials.htm). Extrude has "Merge result"; without it the feature creates a distinct solid body (V, .../r_extrude_propertymanager.htm). Feature Scope limits which bodies a feature touches (V). Combine does Add / Subtract / Common (V). Mass properties exclude hidden bodies unless asked (V, .../hidd_massproperty_text_dlg.htm). Export offers all bodies or selected bodies (V); Save Bodies writes each body to its own part and can build an assembly (V, .../hidd_dve_feat_split.htm).
- Autodesk Fusion. "A Body is a single container for a contiguous 3D shape". Components hold bodies, and "you cannot create joints or motion between bodies" (V, help.autodesk.com ...GUID-C1AB4941...). Extrude operations are Join / Cut / Intersect / New Body / New Component (V, ...SLD-REF-EXTRUDE). Combine has a target, tool bodies and "Keep Tools" (V, ...SLD-COMBINE). Per-body material and appearance are inferred (I).
- FreeCAD. A PartDesign Body "is intended to hold a single contiguous solid", and 1.0 adds an experimental "Allow Compound" (V, wiki.freecad.org/PartDesign_Body). Part Compound groups shapes, and a compound whose members touch or intersect "is invalid for Boolean operations", which is not checked (V, .../Part_Compound). PartDesign Boolean pulls tool bodies into the active body and hides them (V, .../PartDesign_Boolean).
- CadQuery / build123d.
combine=Falsekeeps a new solid apart. Results are Compounds, and.Solids()lists them (V, cadquery.readthedocs.io .../workplane.html). build123d modes are ADD / SUBTRACT / INTERSECT / REPLACE / PRIVATE.BuildPart.part"may contain more than one shape" (V, build123d.readthedocs.io .../build_part.html). STEP export carries a label and colour per node, and repeated labels are numbered (V, .../import_export.html).
What this design takes from them:
- A body is named geometry inside one product item (every system).
- "New body" is an explicit per-feature choice beside join/cut/intersect, and an ambiguous target is an error, never a guess (Onshape, SolidWorks, Fusion).
- A boolean between bodies says whether it consumes its tools, and the result keeps the name of the target body (Onshape, Fusion).
- Mass is the sum over bodies, with explicit rules for overlaps and missing material (Onshape, SolidWorks).
- A multi-body part exports as one product holding several solids, with an option to split it (SolidWorks, Onshape).
- A bare compound is not a body set. It must not quietly become the input of a boolean (FreeCAD).
4. Design
4.1 Body
Body(body_id: identifier, solid: Solid, name: str | None = None)
- Identity.
body_idis unique within its part and has the same rules as apart_id(validate_identifier). In a notebook it is normally the name of the variable or feature slug that produced the solid ("base", "lid"). A one-body Part has one Body with the id"body"(kDefaultBodyId). - Order. Bodies keep the order they are given in, which is the order of the dict. Order is part of the product: it decides the STEP solid order and the order of the scene nodes.
- Names.
nameis an optional display name. - Colour (implemented,
feat/body-appearance). Optionalcolor(linear RGB in [0, 1]) andopacityon Body, an appearance only, set with the recorded opset_body_appearance_rpart(part, body_id="body", *, color=None, opacity=None, name=None, reset=False). The material colour is the default; a body colour overrides it for display. It reaches the preview (nodecolor/opacity),scene/compiler.py(base_color), the package scene (nodeproperties.color/opacity), the definition (optionalappearanceblock, profiles 2 and 3; absent when unused, so bytes are unchanged), STEP (the part colour for a one-body part; a named, coloured XCAF sub-shape per body of a multi-body part, withwrite.stepcaf.subshapes.nameon), the cell cache and replay. - Material (stage 3). The part material applies to every body. A per-body material override follows
SolidWorks' rule: the body material wins, and bodies without one inherit the part's. Mass already reads density per
body (
measure_part_mass_rmassreport), so stage 3 only changes where the density comes from. - Visibility. None in the product. See section 1: a hidden tool is not a body.
4.2 API
Stage 1, implemented:
| Name | Kind | Notes |
|---|---|---|
scad.Body(body_id, solid, name=None) |
value | C++ scad::product::Body. Pickles |
scad.make_part_rpart(part_id, body=None, name=None, *, bodies=None) |
op | exactly one of body / bodies. bodies is {id: Solid} or [Body, ...]. Recorded with one body input per body and params.bodies = [{body_id, name}]. Replays |
scad.Part(..., bodies=...) |
ctor | same rule. ValueError for no bodies, a duplicate body_id, or connectors on several bodies |
Part.bodies, Part.multi_body, Part.body_ids(), Part.get_body(id) |
read | |
Part.body |
read | the Solid of a one-body part. TypeError on a multi-body part |
scad.part_shape(part) |
helper | the Solid, or a Compound of every body (a geometry view, no tags) |
scad.measure_part_mass_rmassreport(part, *, density=None, density_unit=None) |
op (diagnostic) | per body: volume_mm3, mass_kg, centroid_mm; plus totals. Density comes from the material or from the arguments |
Stage 2, proposed (each one an SDK op, so agents and the editor call the same thing):
add_body_rpart(part, body_id, solid, name=None) -> Partandremove_body_rpart(part, body_id) -> Part: the functional edits the editor's bodies list needs, in the style ofadd_connector_rpart.split_rpart(part, body_ids=None) -> Assembly("Save Bodies"): one component per body, with identity placements and part ids<part>_<body>. This is the explicit exit from bodies to an assembly when the bodies need motion.cut_rsolid_listnaming help: pieces come out in kernel order, which is not stable across OCCT versions. Abodies_from_pieces(prefix, pieces)that orders pieces by centroid (x, then y, then z) gives stable idspiece_1..nfor "a part with disjoint pieces after a cut".
Stage 3, proposed:
combine_bodies_rpart(part, target, tools, operation="join"|"cut"|"intersect", keep_tools=False) -> Part. The result keeps the target'sbody_id(Onshape's rule). Consumed tools leave the part. It is needed only when a Part arrives without its notebook (an imported multi-solid STEP). In a notebook, bodies are still plain solids before the product cell, andunion_rsolid(base, lid)is already "combine". A part is the end of the pipeline, not a workspace.- Per-body material and colour (4.1).
- Connectors on multi-body parts: a connector anchor names
body_idplus the entity within that body. TheGeometryRefand the binding checks inbuild/definition.pythen run per body.
4.3 Booleans between named bodies
In a notebook, bodies are named before they meet the product, so booleans between them are ordinary operators on named solids. The rules the editor and the docs follow:
- Join, cut and intersect consume their inputs as they do today. A consumed solid is no longer an "open body", so it leaves the product's bodies at the next re-point (4.4).
- "Keep tools" is the default behaviour of a functional SDK anyway: the tool variable still exists. Whether it stays a body is the product cell's choice, and the editor offers that choice explicitly.
cut_rsolidkeeps refusing a split.cut_rsolid_listkeeps every piece, and those pieces become bodies throughbodies={...}(stage 2 helper above).- Overlapping bodies are allowed, as in SolidWorks and Onshape. Mass counts every body whole, which is the Onshape
rule, and the report says so. A stage-2 diagnostic
check_bodies_disjoint(pairwise common volume) can warn before export. Whethermake_part_rpartshould refuse overlaps is an open question for the owner (section 7).
4.4 Editor UX (the editor only adapts SDK ops)
- Bodies list. The product cell becomes the list.
make_part_rpart(part_id=..., bodies={"base": base, "lid": lid})is parsed like_PRODUCT_BODYtoday, with one row per entry. A notebook with one body keeps writingbody=..., so existing notebooks are untouched. - Operation choice. Each combinable feature keeps join / cut / intersect / new body. The changes:
- "New body" becomes a real choice. The feature makes a new open body, and the editor adds it to the product's
bodies with
add_body_rpartsemantics (an edit of the dict literal in the product cell). - The default stays "join" when a body exists (Onshape's default is New only for the first feature, too). The help text no longer says "a part holds one solid".
- "Combine with" stays an explicit body choice. When more than one body exists the target has no default: the form asks, which is Onshape's rule for an ambiguous merge.
- "New body" becomes a real choice. The feature makes a new open body, and the editor adds it to the product's
bodies with
- Re-pointing.
_repoint_producttoday swaps the one body name. With bodies it does the same for the dict entry whose solid the new feature consumed, and keeps thebody_id. A body keeps its id while it is joined, cut and filleted, the way a SolidWorks body keeps its name through features. - Construction solids. Open solids that are not in the bodies dict are listed under "Construction", drawn ghosted and never exported. That covers tool bodies and solids kept for a later boolean, with no flag in the product.
- Viewer. Preview nodes are
node/<part>/body:<id>, and entities areentity/<part>/body:<id>/<kind>/<topo>. The scene tree shows the part with its bodies as children (node_kind: "solid", which the scene schema andeditor-web/src/scene/scene2.ts:27already accept). Picking a face says which body it belongs to. - Assemblies stay separate. Assembly documents (
assembly_doc.py) keep placing Parts. A multi-body part is one component there. "Make components from bodies" issplit_rpart.
4.5 Export, mass, preview, package
- Live preview (
scene/preview.py, implemented): one node per body, all at the part's placement. The part key includes the body id, so two equal-shaped bodies stay two entity namespaces.entity_infounderstands thebody:segment. - Package (
PartDefinition, implemented):- A one-body part writes the same manifest bytes as before, so its content hash is unchanged.
- A multi-body part adds
solid_cache.bodies = [{body_id, name, body_ref, topology_snapshot_ref}], one BRep and one snapshot per body, so every body keeps its tags. solid_cache.body_refis then a BRep Compound of every body. That is what a geometry-only reader needs, and what a reader that expects exactly one Solid refuses (read_brep_solid), so old readers fail closed instead of dropping bodies.topology_snapshot_refrepeats the first body's snapshot, because the schema requires it.- The geometry interface hash covers
[{body_id, geometry}]. - Validation (
validate_artifact_blobs, package blob roles,part_io) covers every body blob and checks that the Compound holds as many solids as there are bodies.
- Package scene (
scene/product_scene.py, implemented): the part node has no geometry. Each body is a child node of kindsolidwith its own GLB and entity document,node_idnode/<part>/body:<id>. The camera frames every body. - STEP (implemented): one PRODUCT whose shape holds every body. The test checks one
PRODUCT(and twoMANIFOLD_SOLID_BREP. Stage 2 writes the body name and colour on each solid (an XCAF sub-shape label), as build123d does. - STL / MJCF (implemented): every body goes into the mesh. In MJCF a multi-body part is one rigid body with one mesh, which is correct because bodies never move apart.
- Mass (implemented):
measure_part_mass_rmassreport. Totals are sums; the centroid is volume-weighted. - Cell cache (implemented):
Partpickles with its bodies (_glue/values.py_ARGUMENTS), and the semantic-state guard watches every body (runtime/cache.py). - Legacy
scene/compiler.py(compile_scene/export_scene): not converted. A multi-body part raises thePart.bodyTypeError there (stage 2).
4.6 Boundary with assemblies
| Bodies of one Part | Components of an Assembly | |
|---|---|---|
| Product items / BOM lines | one | one per component |
| Placement | none (bodies share the part frame) | per component |
| Joints / constraints / motion | never | yes |
| Connectors | per part (stage 3: anchored on one body) | per part, public per assembly |
| Material | part (stage 3: per-body override) | per part |
| From one to the other | split_rpart (stage 2) |
make_compound_from_assembly_rcompound flattens (every body of every part) |
5. Staged plan
- Stage 1, done in this spike: Body,
Part.bodies,make_part_rpart(bodies=...)with recording and replay, pickling and cache, live preview, package format, package scene, STEP, STL and MJCF geometry, assembly flattening, and the mass report. One-body parts are unchanged byte for byte. - Stage 2:
- Editor: bodies list, a real "New body", construction group, re-pointing by
body_id. add_body_rpart,remove_body_rpart,split_rpart, ordered piece naming,check_bodies_disjoint.- STEP body names and colours.
scene/compiler.py.- Body colour.
- Skill docs: when to use bodies and when to use an assembly.
- Editor: bodies list, a real "New body", construction group, re-pointing by
- Stage 3:
- Per-body material.
- Connectors on a body.
combine_bodies_rpartfor parts without a notebook (STEP import with several solids becomes a multi-body Part instead of an error).- Rename the
single_soliddefinition kind at the next package schema bump.
6. Risks
- Silent partial readers. Any code still reading
part.bodyraises on a multi-body part. That is loud, not silent, but it is a runtime failure on paths no test covers, e.g.scene/compiler.py:330and the translators. Thegrep '\.body\b'list in section 2 is the checklist. - Package compatibility. A package with
solid_cache.bodiesvalidates under the samepart-definition-2profile. An old SDK reading it fails atread_brep_solid(Compound root) or at the closed schema (additionalProperties: falseonsolid_cache), which is the right failure. A profile bump topart-definition-3would make the change explicit, at the cost of every reader (open question). - Body id stability. The ids come from the notebook. If a person renames a variable, the body is renamed with it.
Pieces of
cut_rsolid_listarrive in kernel order (stage-2 helper). - Overlaps. Overlapping bodies make mass and FEM meaningless and STEP ambiguous. The policy is open (section 7).
- Editor complexity. Re-pointing a dict entry is more state than swapping one name. The bodies list must stay a parse of the product cell, never a second store.
7. Open questions for the owner
- May
make_part_rpart(bodies=...)refuse overlapping or touching bodies (FreeCAD's warning), or only warn through a diagnostic? The spike allows overlaps. - Should the package profile move to
part-definition-3, or does the additivesolid_cache.bodiesunder profile 2 stay (the spike's choice, which keeps one-body hashes)? - Should the default body id of a one-body part stay
"body", or should it be the notebook variable name? The variable name is nicer in the editor, but changing it would change ids that exist today. - Does "New body" in the editor need confirmation the first time a notebook gets a second body, given that until now a second solid was a mistake?
- (Decided, section 9: splits are kept as pieces by default.) Should
cut_rsolidkeep refusing splits?
8. The spike
- C++:
include/scad/product/part.hpp,src/product/part.cpp: Body, the bodies of a Part, thebody()TypeError.src/product/ops_structure.cpp: themake_part_rpartoverload and its record.src/product/ops_projection.cpp: assembly flattening takes every body.- Bindings:
bind_product_values.cpp,bind_product.cpp,bind_product_args.hpp(body_list).
- Python:
product/bodies.py:part_shape,measure_part_mass_rmassreport._glue/values.py,_glue/session.py,runtime/cache.py.artifacts/part_definition.py(BodyRef),artifacts/part_io.py(read_part_bodies),artifacts/assembly_io.py,artifacts/validation.py,contracts/part-definition-2.schema.json.build/definition.py,product/packages.py.scene/preview.py,scene/product_scene.py,scene/prewarm.py.exporter/step.py,exporter/_surface_mesh.py,exporter/mjcf.py.recording/serializer.py(replay and the diagnostic row).- Docs, stubs and
docstrings.json/modules.jsonregistration.
- Tests:
test/test_multi_body_part.py, 20 tests:- value rules;
- pickle and deepcopy with tags;
- connectors refused;
- assembly flattening;
- graph replay;
- mass per body and totals;
- preview nodes and entity namespaces, including two equal-shaped bodies;
- a notebook run twice, with every cell after setup cached and the same content hash;
- a package that round-trips with tags per body;
- scene solid nodes;
- STEP with one product and two solids;
- one-body definitions without
bodies.
9. Owner decisions (implemented)
-
Overlapping bodies warn, never refuse.
inspect_body_overlaps_rlist(part)is a diagnostic op. It lists pairs that share volume: a bounding-box prefilter, then the OCCT common volume. Bodies that only touch along a face, an edge or a point are not reported.- Building the definition warns once per pair with
BodyOverlapWarning. That covers a notebook run,@partand a package.make_part_rpartitself never runs the check, so the live editor loop stays cheap.
-
Multi-body definitions are profile
simplecad-part-definition-3.- The new schema
contracts/part-definition-3.schema.jsonrequiressolid_cache.bodies. part-definition-2.schema.jsonis back to its dev bytes. A profile-2 reader fails schema validation onprofile(const), so it refuses the file rather than reading it wrongly. This is tested by validating a profile-3 manifest against schema 2.- One-body parts stay profile 2, so their bytes and content hashes do not change.
validate_manifestpicks the schema by the manifest's profile.
- The new schema
-
Default body ids. A one-body part keeps
"body"; a multi-body part uses the names it was given. This is unchanged from the spike. -
Choosing "New body" is the confirmation. The editor asks nothing more.
Implicit Part (the
kind = "part"rule onfeat/gui-modeling,runtime/projection.py): every open body becomes a body of the implicit Part, named by its variable. The drop-in issimplecadapi.product.bodies.part_from_bodies(part_id, {name: solid_or_pieces}). It makes a one-body Part (id"body") for one open Solid, and otherwisemake_part_rpart(bodies=...)with the pieces of a split expanded to<name>_1..n. The exact change onfeat/gui-modeling:- in
open_bodies, also accept a non-emptylist/tupleofSolid(the pieces of a split cut) as a candidate. Use the lineage of its first element for the "made from" test, and treatid()of each piece as seen; - in
_implicit_part, drop thelen(names) > 1error and returnpart_from_bodies(config.id, {name: values[name] for name in names}); - update its docstring and the test that expected the error. Expected: two open bodies give a Part with those two body ids.
- in
-
A cut that splits the body is not refused.
cut_rsolid(..., on_split="pieces")is the default. A one-piece result is aSolid, exactly as before, with the same record, so the hashes of existing notebooks do not change. A split returns every piece aslist[Solid], ordered by centroid (x, then y, then z). It is recorded asmake_cut_rsolid_listwithparams.piece_order = "centroid", and both the C++ executor and the Python serializer replay it in that order.on_split="error"keeps the strict behaviour.- Pieces become bodies directly:
make_part_rpart(body=pieces)givesbody_1..n, andbodies={"bar": pieces}givesbar_1..n. - Default: separate bodies, not one solid with several lumps. OCCT has no valid single solid with several lumps.
A
TopoDS_Solidbuilt from the two outer shells of a split bar failsBRepCheck_Analyzer, and STEP writes it asBREP_WITH_VOIDS, with the second lump turned into a void. This was checked with a small OCCT program. Fusion ("a body is a single container for a contiguous 3D shape") and FreeCAD ("a single contiguous solid") agree that a body is one closed volume. - "Keeping the pieces together" is therefore a naming matter: they share the prefix of the value they came from
(
bar_1,bar_2), and the editor can show them as one row with two bodies. - A Body that holds several lumps would be a later, additive extension (
Body.lumps). It is not needed for valid geometry. - Downstream single-solid features (a fillet on
bar) now fail with a clear type error whenbaris a list. The editor should then offer to pick a piece or keep the pieces as bodies (stage 2).
Skill pages updated with these rules: domains/part-modeling.md (with a new "Multi-body parts" section),
domains/assembly-and-product.md, discipline/core-rules.md R5, discipline/failure-and-repair.md,
discipline/mechanical-modeling.md, discipline/notebook-cell-design.md C9, docs/core/compound.md,
docs/guides/notebook-runtime.md, workflows/single-part-modeling.md and role-4-build.md, and
workflows/drawing-reconstruction.md. The API pages are regenerated. Tags on cut pieces: a plain cut_rsolid outside
a recording session carries no input face tags, a behaviour that predates this work. Tag and ref propagation belongs to
research/stable-geometry-refs.