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:
@@ -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.
|
||||
|
||||
@@ -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`
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user