docs/api: the API pages say a Part holds exactly one solid (drop bodies=, multi-body wording and inspect_body_overlaps_rlist)

DECISION: the generated-style API reference pages follow the code decision of the commit "part: a Part holds
exactly one solid (the constructor refuses several; make_part_rpart and Part lose `bodies=`)".

WHY - THE DISCUSSION (owner and assistant, 2026-11-10; full account in design-docs/part-holds-one-solid.md)
The editor must let several solids exist in one notebook with no assembly constraint (pattern a tool, then cut:
for a moment there are several tools and the body). The multi-body Part was made to hold them; the owner judged
that a wrong decision because it makes assembly hard. The agreed analysis: those solids are intermediate values
of a notebook, not product items, so a Part is one solid and the editor shows loose solids. These pages are what
a model author (and the skill) reads, so they must not keep promising `bodies=`, a multi-body Part, per-body
overlap checks or "connectors are not supported on multi-body parts yet".

WHAT CHANGES
- make_part_rpart.md, Part.md: signature `make_part_rpart(part_id, body, name=None)` / `Part(part_id, body, name,
  material, connectors)`; body is a Solid, a Body, or a list of exactly one piece; several solids raise
  ValueError that says what to do (one Part per solid in an Assembly, or union / cut to one solid);
  Part.bodies is a one-element tuple (Body carries display name, colour, opacity).
- set_body_appearance_rpart.md: it paints the Part's one body (body id "body"); the read-back is
  part.bodies[0].
- cut_rsolid.md: pieces of a splitting cut are a notebook value; more than one piece cannot be one Part.
- ref.face.md: "a multi-body result has one per body" -> an operation that makes several solids.
- core/compound.md: a Part is one Solid; part_shape is gone; a Compound is not a way to hold several solids as one
  Part.
- core/part_assembly_development_plan.md: "multi-body part authoring" removed from the out-of-scope list (it is
  not a planned lake any more).
- README.md (API index) and inspect_body_overlaps_rlist.md: the operation was removed (commit "api: remove the
  helpers that only existed for a Part of several bodies"), so its page and index entry are deleted.

NOT REGENERATED: tools/auto_docs_gen.py builds these pages from the docstrings in src/. Those docstrings (the
C++ bindings' make_part_rpart / Part text and the cut_rsolid, ref and set_body_appearance_rpart docstrings) are
owned by the code side of the series; until they say the same, a regeneration would bring the old text back, so
the pages were edited by hand to the same words.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Ni Jingzhe
2026-11-10 04:06:25 +08:00
parent ba19f430ad
commit 6441107ed3
9 changed files with 33 additions and 86 deletions
+8 -8
View File
@@ -3,7 +3,7 @@
## Class Definition
```python
class Part(part_id, body=None, name=None, material=None, connectors=(), bodies=None)
class Part(part_id, body, name=None, material=None, connectors=())
```
*Source: product/part.py*
@@ -14,11 +14,11 @@ class Part(part_id, body=None, name=None, material=None, connectors=(), bodies=N
## Description
Product item holding one Solid (``body``) or several named bodies (``bodies``).
Product item holding exactly one Solid (``body``).
A one-body Part is the common case: ``part.body`` is its Solid. A multi-body
Part keeps several solids apart inside one product item (a case and its lid
modelled side by side, the pieces of a split cut): ``part.bodies`` lists them
as ``Body`` values in order, ``part.get_body(body_id)`` finds one, and
``part.body`` raises ``TypeError``. Bodies of one Part are never placed
relative to each other and carry no joints; use an Assembly for that.
A Part is the unit an Assembly places, mates and gives connectors to, so it is one
solid. ``part.body`` is its Solid; ``part.bodies`` is that body as a one-element tuple
of ``Body`` values (a ``Body`` carries the display name, colour and opacity,
``set_body_appearance_rpart``). ``body`` also takes a ``Body``. Several solids are
refused (ValueError): make one Part per solid in an Assembly, or union / cut them
into one solid first.
-1
View File
@@ -416,7 +416,6 @@ This index includes generated docs for the public SimpleCAD API surface, includi
- [insert_surface_knot_rface](insert_surface_knot_rface.md) *(from operators/geometry.py)* `top-level`
- [inset_face_rsolid](inset_face_rsolid.md) *(from operators/features.py)* `top-level`
- [inspect_assembly_constraints_rconstraintreport](inspect_assembly_constraints_rconstraintreport.md) *(from operators/product.py)* `top-level`
- [inspect_body_overlaps_rlist](inspect_body_overlaps_rlist.md) *(from operators/product.py)* `top-level`
- [inspect_curve_rcurvedata](inspect_curve_rcurvedata.md) *(from operators/geometry.py)* `top-level`
- [inspect_sketch_rsketchcrossings](inspect_sketch_rsketchcrossings.md) *(from operators/sketch.py)* `top-level`
- [inspect_sketch_rsketchprofiles](inspect_sketch_rsketchprofiles.md) *(from operators/sketch.py)* `top-level`
+3 -2
View File
@@ -52,8 +52,9 @@ Solid: The cut result solid, when the result is one piece.
list[Solid]: The pieces (a ``scad.Pieces``), when the cut split the body
(``on_split="pieces"``). Operations that take one shape run on every piece
(``cut_rsolid(pieces, tool)``, ``translate_shape(pieces, ...)``) and return
``Pieces``; a selector's cardinality is checked over all pieces. Pass them on as bodies: ``make_part_rpart(part_id=..., body=pieces)`` makes the
bodies ``body_1 .. body_n``, ``bodies={"bar": pieces}`` makes ``bar_1 .. bar_n``.
``Pieces``; a selector's cardinality is checked over all pieces. A Part holds one solid, so
``make_part_rpart(part_id=..., body=pieces)`` with several pieces is an error: make one
Part per piece and put them in an Assembly, or union the pieces if they are one body.
## Raises
@@ -1,43 +0,0 @@
# inspect_body_overlaps_rlist
## API Definition
```python
def inspect_body_overlaps_rlist(part: 'Part', *, min_volume_mm3: 'float' = 1e-06) -> 'list[BodyOverlap]'
```
*Source: operators/product.py*
## Import Surface
- top-level: `from simplecadapi import inspect_body_overlaps_rlist`
## Description
List the pairs of bodies of a Part that share volume.
Overlapping bodies are allowed (a Part does not fuse them), but mass counts the
shared volume once per body and STEP holds both copies. Bodies that only touch
(a face, an edge or a point in common) do not overlap.
``scad.inspect_body_overlaps_rlist(case)`` before export. Building the part's
definition (a notebook run, ``@part``, a package) warns with ``BodyOverlapWarning``
for the same pairs.
## Parameters
### part
- **Description**: The Part to inspect; a one-body Part has no overlaps.
### min_volume_mm3
- **Description**: Shared volume below which a pair is not reported.
## Returns
list[BodyOverlap]: ``(first, second, volume_mm3)`` per overlapping pair, in body order.
## Raises
- **SimpleCADError**: The value is not a Part.
@@ -3,7 +3,7 @@
## API Definition
```python
def make_part_rpart(part_id, body=None, name=None, bodies=None)
def make_part_rpart(part_id, body, name=None)
```
*Source: operators/product.py*
@@ -14,13 +14,13 @@ def make_part_rpart(part_id, body=None, name=None, bodies=None)
## Description
Wrap one Solid, or several named solids, as a semantic Part.
Wrap one Solid as a semantic Part. A Part holds exactly one solid.
``scad.make_part_rpart(part_id=scad.notebook_id(), body=bracket)`` for one solid;
``scad.make_part_rpart(part_id=scad.notebook_id(), bodies={"case": case, "lid": lid})``
for a case and its lid kept as two bodies of one part. Material applies to every
body. Connectors are not supported on multi-body parts yet. Union the solids
first when they must become one body.
``scad.make_part_rpart(part_id=scad.notebook_id(), body=bracket)``. Several solids
are not one Part: make one Part per solid and put them in an Assembly (identity
placements when they only sit together), or union / cut them into one solid first.
Solids that sit side by side while a model is built (a tool next to the body it will
cut) are ordinary notebook values, not a Part.
## Parameters
@@ -30,25 +30,17 @@ first when they must become one body.
### body
- **Description**: The Solid of a one-body Part. The pieces of a split cut (a list of Solids) become the bodies ``body_1 .. body_n``.
- **Description**: The Solid of the Part. A ``Body`` (a solid with a display name, colour and opacity) and a list of exactly one piece of a split cut are also taken. Several solids, or a list of several pieces, are refused.
### name
- **Description**: Optional display name.
### bodies
- **Description**: Instead of ``body``: several solids kept apart in one Part, as a mapping ``body_id -> Solid`` (in its order) or a sequence of ``Body`` values. A mapping value may be the pieces of a split cut (a list of
### Solids)
- **Description**: they become ``<body_id>_1 .. <body_id>_n``. Body ids are identifiers, unique within the part. Overlapping bodies are allowed; building the definition warns (``BodyOverlapWarning``).
## Returns
Part: The new Part. ``part.bodies`` lists its bodies; ``part.body`` is the
Solid of a one-body Part.
Part: The new Part. ``part.body`` is its Solid; ``part.bodies`` is that body as a
one-element tuple.
## Raises
- **SimpleCADError**: Neither or both of ``body`` and ``bodies`` were given, a body is not a Solid, a body id is malformed or repeated, or the part_id is already used.
- **SimpleCADError**: The body is not a Solid, more than one solid was given (a ValueError that says to make one Part per solid in an Assembly, or to union / cut them to one solid), or the part_id is already used.
+1 -1
View File
@@ -44,7 +44,7 @@ A reference to a face born in *feature* by *op*.
### slot
- **Description**: The output of that operation (a multi-body result has one per body).
- **Description**: The output of that operation (an operation that makes several solids has one per solid).
### piece
@@ -14,7 +14,7 @@ def set_body_appearance_rpart(part, body_id='body', *, color=None, opacity=None,
## Description
Set the display colour, opacity and display name of one body of a Part.
Set the display colour, opacity and display name of the body of a Part.
A Part is a value: the result is a new Part, the input is unchanged. The colour is an
appearance only. A body without a colour shows its Part's material colour
@@ -22,9 +22,8 @@ appearance only. A body without a colour shows its Part's material colour
overrides the material colour for display (the live preview, the package scene, the STEP
surface colour of that solid). Mass, density and geometry never read it.
``case = scad.set_body_appearance_rpart(case, "lid", color=(0.9, 0.3, 0.2), name="Lid")``
paints the lid body of a multi-body part; ``scad.set_body_appearance_rpart(part,
color=(0.2, 0.4, 0.8))`` paints a one-body part. Recorded and replayed like
``lid = scad.set_body_appearance_rpart(lid, color=(0.9, 0.3, 0.2), name="Lid")``
paints the part's body (a Part holds one solid, whose body id is ``"body"``). Recorded and replayed like
``assign_material_rpart``. To name a face or an edge for people, tag it
(``scad.apply_tag_rselection`` / ``ql.tag``): a tag is the name.
@@ -32,11 +31,11 @@ color=(0.2, 0.4, 0.8))`` paints a one-body part. Recorded and replayed like
### part
- **Description**: The Part (one body or several).
- **Description**: The Part.
### body_id
- **Description**: The body to change: an id from ``part.body_ids()``. A one-body Part has the one body ``"body"`` (the default).
- **Description**: The body to change: the Part's one body, ``"body"`` (the default).
### color
@@ -56,7 +55,7 @@ color=(0.2, 0.4, 0.8))`` paints a one-body part. Recorded and replayed like
## Returns
Part: The Part with that body's appearance changed; ``part.get_body(body_id).color``,
Part: The Part with that body's appearance changed; ``part.bodies[0].color``,
``.opacity`` and ``.name`` read it back.
## Raises
+3 -4
View File
@@ -19,7 +19,6 @@ Use `Compound` when a workflow intentionally needs a flattened geometry
projection. Do not use it as a substitute for `Assembly` product structure.
For normal part modeling, keep using `Solid` as the body-level geometry. A
`Part` wraps one `Solid`, or several named bodies (`Part.bodies`), each its own
`Solid`. A `Compound` built from solids does not keep their tags, so it is not
a way to hold the bodies of a part (`scad.part_shape(part)` gives that view for
geometry-only use).
`Part` wraps exactly one `Solid`. A `Compound` built from solids does not keep
their tags, so it is not a way to hold several solids as one Part: make one Part
per solid and an Assembly of them.
@@ -32,7 +32,7 @@ code. If the remaining work is inside the Part/Assembly MVP lake, boil it in the
same implementation pass.
The ocean boundary is different: full assembly mate solving, full physical
simulation, multi-body part authoring, editable feature trees, or rewriting the
simulation, editable feature trees, or rewriting the
kernel around XCAF/OCAF are out of scope for this MVP and should be handled as
separate future lakes.