scene + exporters: a Part is drawn, exported and measured from its one body (no per-body branches)

DECISION: every consumer of a Part reads `part.body` again. The code that treated a multi-body Part as a
set of child solid nodes, a Compound view or a list of named / coloured STEP solids is removed.

WHY - THE DISCUSSION (owner and assistant, 2026-11-10; full account in design-docs/part-holds-one-solid.md)
The multi-body Part was judged a wrong design (it was made so the editor could hold several solids
with no assembly constraint, and it makes assembly hard); the agreed fix is Part = one solid, and the
editor's several solids become loose preview values (commit "runtime + preview"). The audit of 2.2.8
showed what a second code path per consumer costs: each consumer had to branch on `multi_body`, and some
did not (explode, the legacy scene compiler), which is how the release came to have crashes. With the
invariant enforced in the Part constructor these branches can never run, so they are deleted rather than
kept as dead code.

WHAT CHANGES
- scene/product_scene.py: the package scene has one GLB and one entity document per Part again;
  _body_geometries and the `node/<part>/body:<id>` child solid nodes are removed; _part_geometry no
  longer refuses; _appearance_properties reads the part's one appearance row.
  (The package-scene node tree of a one-body part is what it always was.)
- exporter/step.py: the STEP product's shape is `part.body`; the body colour overrides the material colour
  as before; the `bodies` list of named / coloured solids is no longer built for a Part. The STEP writer's
  generic support for named solids (io::StepBody in C++) is left in place: it is the writer's ability, it
  has its own tests, and removing it would be a separate decision.
- exporter/mjcf.py: the collision / visual mesh of a Part is `part.body`.
- scene/prewarm.py, exporter/_surface_mesh.py, build/definition.py: only the comments that said "every
  body of a multi-body part" (the loops over `part.bodies` stay: it has one element).

Checked: test_product_exporter, test_product_packages, test_scene_preview, test_scene_compiler and
test_notebook_runtime pass. test_body_appearance fails on its multi-body fixtures; the tests are updated in a
later commit of the series.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Ni Jingzhe
2026-11-10 03:53:50 +08:00
parent 90fe84ad38
commit 2029beedea
6 changed files with 19 additions and 108 deletions
+1 -1
View File
@@ -255,7 +255,7 @@ def _attach_feature_graph_result(
raise ArtifactValidationError(
"result_invalid", "/result_node_ids/0", "result node does not exist"
)
for item in part.bodies: # one Solid, or every body of a multi-body part
for item in part.bodies: # the Part's one body
attach_graph_node(item.solid, node, graph_id=session.graph.graph_id)
attach_semantic_graph_node(part, node, graph_id=session.graph.graph_id)
session._captured_values.append(part)
+1 -1
View File
@@ -42,7 +42,7 @@ class TessellatedSurfaceMesh:
def _product_solids(value: Part | Assembly) -> tuple[Any, ...]:
if isinstance(value, Part):
return tuple(body.solid for body in value.bodies) # every body of a multi-body part
return tuple(body.solid for body in value.bodies) # the Part's one body
projection = make_compound_from_assembly_rcompound(assembly=value)
solids = tuple(projection.solids())
if not solids:
+1 -2
View File
@@ -18,7 +18,6 @@ from ..artifacts.assembly_io import materialize_definition
from ..artifacts.canonical import parse_canonical_json
from ..artifacts.part_definition import PartDefinition
from simplecadapi._cpp import Assembly, Part
from ..product.bodies import part_shape
from ..product.placement import Placement, relative_placement
from ..translator.package_units import (
ProductPackageInput,
@@ -678,7 +677,7 @@ def export_product_package_to_mjcf(
mesh_path = mesh_root / f"{mesh_name}.obj"
_write_obj(
mesh_path,
part_shape(part),
part.body,
linear_deflection=float(linear_deflection),
angular_deflection_degrees=float(angular_deflection_degrees),
)
+4 -20
View File
@@ -12,7 +12,6 @@ from typing import Any
from ..artifacts import materialize_definition
from simplecadapi._cpp import Assembly, Part
from ..product.bodies import part_shape
from ..translator.package_units import (
ProductPackageInput,
read_product_package_translation_units,
@@ -74,8 +73,7 @@ def _native_definitions(root_value: Part | Assembly, units: Any) -> list[dict[st
"id": definition_id,
"kind": kind,
"name": value.name or value.part_id,
# a multi-body part is one STEP product whose shape holds every body
"shape": part_shape(value),
"shape": value.body,
"metadata": {
"record_kind": "definition",
"definition_id": value.part_id,
@@ -97,23 +95,9 @@ def _native_definitions(root_value: Part | Assembly, units: Any) -> list[dict[st
}
if material.color is not None:
entry["color"] = tuple(float(c) for c in material.color)
if not value.multi_body:
own = value.bodies[0].color # a body colour overrides the material colour
if own is not None:
entry["color"] = tuple(float(c) for c in own)
else:
# each body with a name or a colour of its own is a named / coloured solid of the product's shape
shape = entry["shape"]
solids = shape.solids()
entry["bodies"] = [
{
"shape": solid,
"name": body.name,
"color": None if body.color is None else tuple(float(c) for c in body.color),
}
for body, solid in zip(value.bodies, solids)
if body.name is not None or body.color is not None
]
own = value.bodies[0].color # a body colour overrides the material colour
if own is not None:
entry["color"] = tuple(float(c) for c in own)
out[key] = entry
return definition_id
entry = {
+1 -1
View File
@@ -36,7 +36,7 @@ def solids_of(values: Iterable[Any]) -> Iterator[Solid]:
return
seen.add(id(item))
if isinstance(item, Part):
for body in item.bodies: # every body of a multi-body part
for body in item.bodies: # the Part's one body
if isinstance(body.solid, Solid):
yield body.solid
elif isinstance(item, Assembly):
+11 -83
View File
@@ -319,8 +319,6 @@ def _part_geometry(
str,
]:
runtime = materialize_definition(definition)
if runtime.multi_body:
raise ProductSceneError(f"part {definition.definition_id!r} has several bodies: use _body_geometries")
body = runtime.body
if not isinstance(body, Solid):
raise ProductSceneError(f"part {definition.definition_id!r} has no solid body")
@@ -342,40 +340,6 @@ def _part_geometry(
)
def _body_geometries(
definition: PartDefinition,
*,
linear_tolerance: float,
angular_tolerance: float,
) -> list[tuple[str, str | None, tuple[list[dict[str, Any]], dict[str, Any], dict[str, bytes], str, str]]]:
"""The geometry of every body of a multi-body part: ``(body_id, name, the _solid_geometry tuple)`` in body order.
Each body has its own GLB and entity document; its entities are ``entity/<part>/body:<body_id>/<kind>/<topo>``.
"""
runtime = materialize_definition(definition)
mark_part_definition_validated(definition, body=runtime.bodies, feature_graph=_feature_graph(definition))
refs = {item.body_id: item for item in definition.bodies}
out = []
for body in runtime.bodies:
snapshot = parse_artifact_json(definition.blobs[refs[body.body_id].topology_snapshot_ref.path])
out.append(
(
body.body_id,
body.name,
_solid_geometry(
definition.definition_id,
f"{definition.definition_id}/body:{body.body_id}",
body.solid,
snapshot,
linear_tolerance=linear_tolerance,
angular_tolerance=angular_tolerance,
),
)
)
return out
def _solid_geometry(
definition_id: str,
namespace: str,
@@ -602,20 +566,19 @@ def _node_id(path: tuple[str, ...]) -> str:
return "node/" + "/".join(path)
def _appearance_properties(definition: PartDefinition, body_id: str | None) -> dict[str, Any]:
"""``color`` / ``opacity`` of a body that has its own (``body_id`` None: the body of a one-body part), else ``{}``.
def _appearance_properties(definition: PartDefinition) -> dict[str, Any]:
"""``color`` / ``opacity`` of the part's body when it has its own (``set_body_appearance_rpart``), else ``{}``.
A viewer draws a node with ``properties.color`` in that colour; without one, the material's (``material_id``).
"""
for row in definition.appearance:
if body_id is None or row.body_id == body_id:
out: dict[str, Any] = {}
if row.color is not None:
out["color"] = list(row.color)
if row.opacity is not None:
out["opacity"] = row.opacity
return out
out: dict[str, Any] = {}
if row.color is not None:
out["color"] = list(row.color)
if row.opacity is not None:
out["opacity"] = row.opacity
return out
return {}
@@ -624,7 +587,6 @@ def _build_nodes(
definitions: Mapping[str, Definition],
geometry_ids: Mapping[str, str],
entity_ids: Mapping[str, str],
body_assets: Mapping[str, list[tuple[str, str | None, str, str]]] = {},
) -> tuple[
list[dict[str, Any]],
dict[str, list[str]],
@@ -667,31 +629,11 @@ def _build_nodes(
"properties": {
"content_hash": definition.content_hash,
"revision": definition.revision,
# a one-body part's body colour / opacity (set_body_appearance_rpart), when it has one
**(_appearance_properties(definition, None) if is_part and not definition.bodies else {}),
# the part's body colour / opacity (set_body_appearance_rpart), when it has one
**(_appearance_properties(definition) if is_part else {}),
},
}
)
part_node = nodes[-1]
for body_id, body_name, geometry_id, entity_id in body_assets.get(definition.definition_id, ()):
# a body of a multi-body part: a solid node under the part node, at the part's origin
nodes.append(
{
"node_id": f"{node_id}/body:{body_id}",
"parent_node_id": node_id,
"display_name": body_name or body_id,
"node_kind": "solid",
"definition_id": definition.definition_id,
"definition_kind": definition.definition_kind,
"component_id": None,
"instance_id": None,
"transform": identity_placement().to_dict(),
"geometry_asset_id": geometry_id,
"entity_asset_id": entity_id,
"material_id": part_node["material_id"],
"properties": {"body_id": body_id, **_appearance_properties(definition, body_id)},
}
)
if isinstance(definition, AssemblyDefinition):
for instance in definition.instances:
child = definitions[instance.definition_id]
@@ -1057,21 +999,7 @@ def compile_product_scene(
for definition in definitions.values()
if isinstance(definition, PartDefinition)
]
body_assets: dict[str, list[tuple[str, str | None, str, str]]] = {}
for definition in sorted(part_definitions, key=lambda item: item.definition_id):
if definition.bodies: # a multi-body part: one GLB and entity document per body, drawn by child nodes
rows = []
for body_id, body_name, (records, entity_record, part_blobs, geometry_id, entity_id) in _body_geometries(
definition, linear_tolerance=linear_tolerance, angular_tolerance=angular_tolerance
):
for record in records:
geometry_assets_by_id.setdefault(record["asset_id"], record)
if all(item["asset_id"] != entity_record["asset_id"] for item in entity_assets):
entity_assets.append(entity_record)
blobs.update(part_blobs)
rows.append((body_id, body_name, geometry_id, entity_id))
body_assets[definition.definition_id] = rows
continue
geometry_records, entity_record, part_blobs, geometry_id, entity_id = (
_part_geometry(
definition,
@@ -1087,7 +1015,7 @@ def compile_product_scene(
entity_ids[definition.definition_id] = entity_id
nodes, occurrences, children = _build_nodes(
root, definitions, geometry_ids, entity_ids, body_assets
root, definitions, geometry_ids, entity_ids
)
connectors, connector_index = _connectors(
definitions, feature_graphs, occurrences