Add 3D shape scene objects (XY projection)

Draw COMPAS solids as their projection onto the XY plane:

- ShapeObject: shared object for Sphere, Cylinder, Cone, Capsule, Torus and
  Polyhedron, tessellating via Shape.to_vertices_and_faces (u/v resolution) and
  drawing each face as a semi-transparent polygon with a solid outline.
- Box keeps its dedicated BoxObject (exact six-face projection).

Registers the shapes under the "Plotter" context, extends the tutorial, and adds
tests covering Box and all shape types (13 tests total).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: gonzalocasas

CHANGELOG.md

@@ -21,7 +21,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   context. Every `Plotter` now owns one, giving a hierarchical scene tree
   (parent/child transforms), serialization, and API symmetry with the Rhino,
   Blender and Viewer backends.
-* Guarded registration hook for future 3D shape / `Brep` / surface scene objects.
+* Scene object for `Box`, drawn as the exact XY projection of its six faces.
+* Shared `ShapeObject` drawing `Sphere`, `Cylinder`, `Cone`, `Capsule`, `Torus`
+  and `Polyhedron` as tessellated XY projections, with `u`/`v` resolution control.
 
 ### Changed
 

docs/tutorial.md

@@ -62,7 +62,29 @@ in points, so they do not grow or shrink when you zoom.
 
 3D shapes are drawn as their projection onto the XY plane. A `Box`, for example,
 is projected face by face, so it reads as a solid wireframe regardless of how its
-frame is oriented.
+frame is oriented. The same works for `Sphere`, `Cylinder`, `Cone`, `Capsule`,
+`Torus` and `Polyhedron`: they are tessellated into a mesh and that mesh is
+projected. Curved shapes take `u`/`v` keyword arguments to control the
+tessellation resolution.
+
+```python
+from compas.geometry import Sphere, Cylinder, Cone, Torus, Polyhedron
+from compas.geometry import Translation
+from compas_plotters import Plotter
+
+plotter = Plotter(figsize=(10, 3))
+
+plotter.add(Sphere(1.0))
+plotter.add(Cylinder(0.6, 2.0).transformed(Translation.from_vector([3, 0, 0])))
+plotter.add(Cone(0.8, 2.0).transformed(Translation.from_vector([6, 0, 0])), u=12)
+plotter.add(Torus(1.0, 0.3).transformed(Translation.from_vector([9, 0, 0])))
+plotter.add(Polyhedron.from_platonicsolid(12).transformed(Translation.from_vector([12, 0, 0])))
+
+plotter.zoom_extents()
+plotter.show()
+```
+
+The `Box` below is projected the same way.
 
 ```python
 from math import radians
@@ -116,8 +138,9 @@ def spin(frame):
 plotter.show()
 ```
 
-Each frame applies a small rotation about the Z axis; the six faces are
-re-projected onto the XY plane, so the wireframe appears to turn in 3D.
+Each frame applies a small rotation; the six faces are re-projected onto the XY
+plane, so the wireframe appears to turn in 3D. Any of the shapes above can be
+animated the same way.
 
 ## Meshes
 

src/compas_plotters/scene/__init__.py

@@ -11,13 +11,19 @@
 from compas.datastructures import Graph
 from compas.datastructures import Mesh
 from compas.geometry import Box
+from compas.geometry import Capsule
 from compas.geometry import Circle
+from compas.geometry import Cone
+from compas.geometry import Cylinder
 from compas.geometry import Ellipse
 from compas.geometry import Frame
 from compas.geometry import Line
 from compas.geometry import Point
 from compas.geometry import Polygon
+from compas.geometry import Polyhedron
 from compas.geometry import Polyline
+from compas.geometry import Sphere
+from compas.geometry import Torus
 from compas.geometry import Vector
 from compas.plugins import plugin
 from compas.scene import register
@@ -34,6 +40,7 @@
 from .pointobject import PointObject
 from .polygonobject import PolygonObject
 from .polylineobject import PolylineObject
+from .shapeobject import ShapeObject
 from .vectorobject import VectorObject
 
 
@@ -52,24 +59,13 @@ def register_scene_objects():
     register(Mesh, MeshObject, context="Plotter")
     register(Graph, GraphObject, context="Plotter")
 
-    # Roadmap: 3D shapes, Breps and surfaces are drawn via XY projection once
-    # their scene objects are implemented. Registration is guarded so the package
-    # keeps working until then, and lights up automatically when the objects (and
-    # any optional dependencies, e.g. compas_occ for Breps) become available.
-    try:
-        from compas.geometry import Capsule
-        from compas.geometry import Cone
-        from compas.geometry import Cylinder
-        from compas.geometry import Polyhedron
-        from compas.geometry import Sphere
-        from compas.geometry import Torus
+    # 3D shapes are drawn as their projection onto the XY plane, tessellated by
+    # a shared ShapeObject. Box keeps its own object (exact 6-face projection).
+    for shape_cls in (Sphere, Cylinder, Cone, Capsule, Torus, Polyhedron):
+        register(shape_cls, ShapeObject, context="Plotter")
 
-        from .shapeobject import ShapeObject
-
-        for shape_cls in (Sphere, Cylinder, Cone, Capsule, Torus, Polyhedron):
-            register(shape_cls, ShapeObject, context="Plotter")
-    except ImportError:
-        pass
+    # Roadmap: Breps and surfaces are drawn via XY projection once their scene
+    # objects are implemented (Breps additionally need e.g. compas_occ).
 
 
 # Eager registration so that the Plotter works in editable / non-installed setups
@@ -89,6 +85,7 @@ def register_scene_objects():
     "EllipseObject",
     "FrameObject",
     "BoxObject",
+    "ShapeObject",
     "MeshObject",
     "GraphObject",
 ]

src/compas_plotters/scene/shapeobject.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from typing import Sequence
+
+from compas.colors import Color
+from compas.geometry import Shape
+from compas.scene import GeometryObject
+from matplotlib.patches import Polygon as PolygonPatch
+
+from .plotterobject import PlotterSceneObject
+from .plotterobject import to_rgb
+
+
+class ShapeObject(PlotterSceneObject, GeometryObject):
+    """Plotter scene object for :class:`compas.geometry.Shape`.
+
+    Handles all COMPAS solids (Sphere, Cylinder, Cone, Capsule, Torus,
+    Polyhedron, ...). The shape is tessellated with
+    :meth:`compas.geometry.Shape.to_vertices_and_faces` and drawn as the
+    projection of that mesh onto the XY plane: each face becomes a
+    semi-transparent polygon with a solid outline, so the shape reads as a solid
+    wireframe regardless of its orientation.
+
+    Parameters
+    ----------
+    u
+        Number of faces around curved shapes (longitude). Ignored by shapes
+        without a resolution, such as :class:`compas.geometry.Polyhedron`.
+    v
+        Number of faces along curved shapes (latitude), where applicable.
+    linewidth
+        Width of the edges.
+    linestyle
+        Matplotlib line style (``"solid"``, ``"dotted"``, ``"dashed"``, ``"dashdot"``).
+    facecolor
+        Color of the faces.
+    edgecolor
+        Color of the edges.
+    fill
+        If True, fill the faces.
+    alpha
+        Transparency of the faces, between 0 and 1.
+    """
+
+    def __init__(
+        self,
+        u: int = 16,
+        v: int = 16,
+        linewidth: float = 0.5,
+        linestyle: str = "solid",
+        facecolor: Color | Sequence[float] = (0.9, 0.9, 1.0),
+        edgecolor: Color | Sequence[float] = (0.0, 0.0, 0.0),
+        fill: bool = True,
+        alpha: float = 0.2,
+        **kwargs,
+    ) -> None:
+        super().__init__(zorder=1000, **kwargs)
+        self.u = u
+        self.v = v
+        self.linewidth = linewidth
+        self.linestyle = linestyle
+        self.facecolor = facecolor
+        self.edgecolor = edgecolor
+        self.fill = fill
+        self.alpha = alpha
+
+    @property
+    def shape(self) -> Shape:
+        return self.geometry  # type: ignore[return-value]
+
+    def _vertices_and_faces(self) -> tuple[list, list]:
+        try:
+            return self.shape.to_vertices_and_faces(u=self.u, v=self.v)
+        except TypeError:
+            # Shapes without a resolution (e.g. Polyhedron) take no u/v.
+            return self.shape.to_vertices_and_faces()
+
+    def viewdata(self) -> list[list[float]]:
+        vertices, _ = self._vertices_and_faces()
+        return [list(vertex[:2]) for vertex in vertices]
+
+    def draw(self) -> list:
+        vertices, faces = self._vertices_and_faces()
+        # Bake the transparency into the face color only, so the edges stay solid
+        # even where projected faces overlap.
+        facecolor = (*to_rgb(self.facecolor), self.alpha) if self.fill else "none"
+        self._mpl_objects = []
+        for face in faces:
+            polygon = PolygonPatch(
+                [list(vertices[index][:2]) for index in face],
+                linewidth=self.linewidth,
+                linestyle=self.linestyle,
+                facecolor=facecolor,
+                edgecolor=to_rgb(self.edgecolor),
+                fill=self.fill,
+                zorder=self.zorder,
+            )
+            self._mpl_objects.append(self.axes.add_patch(polygon))
+        return self._mpl_objects

tests/test_plotter.py

@@ -4,16 +4,24 @@
 
 from compas.datastructures import Graph
 from compas.datastructures import Mesh
+from compas.geometry import Box
+from compas.geometry import Capsule
 from compas.geometry import Circle
+from compas.geometry import Cone
+from compas.geometry import Cylinder
 from compas.geometry import Ellipse
 from compas.geometry import Frame
 from compas.geometry import Line
 from compas.geometry import Point
 from compas.geometry import Polygon
+from compas.geometry import Polyhedron
 from compas.geometry import Polyline
+from compas.geometry import Sphere
+from compas.geometry import Torus
 from compas.geometry import Vector
 
 from compas_plotters import Plotter
+from compas_plotters.scene import BoxObject
 from compas_plotters.scene import CircleObject
 from compas_plotters.scene import EllipseObject
 from compas_plotters.scene import FrameObject
@@ -23,6 +31,7 @@
 from compas_plotters.scene import PointObject
 from compas_plotters.scene import PolygonObject
 from compas_plotters.scene import PolylineObject
+from compas_plotters.scene import ShapeObject
 from compas_plotters.scene import VectorObject
 
 
@@ -50,6 +59,33 @@ def test_add_all_geometry_types():
     assert len(plotter.sceneobjects) >= len(pairs)
 
 
+def test_add_box_returns_boxobject():
+    plotter = Plotter()
+    obj = plotter.add(Box(1, 2, 3))
+    assert isinstance(obj, BoxObject)
+    # one patch per face
+    assert len(obj._mpl_objects) == 6
+    assert len(obj.viewdata()) == 8
+
+
+def test_add_all_shape_types():
+    plotter = Plotter()
+    shapes = [
+        Sphere(1.0),
+        Cylinder(0.5, 2.0),
+        Cone(0.5, 2.0),
+        Capsule(0.3, 1.5),
+        Torus(1.0, 0.3),
+        Polyhedron.from_platonicsolid(12),
+    ]
+    for shape in shapes:
+        obj = plotter.add(shape)
+        assert isinstance(obj, ShapeObject)
+        # every tessellated face is drawn
+        _, faces = obj._vertices_and_faces()
+        assert len(obj._mpl_objects) == len(faces) > 0
+
+
 def test_add_mesh_and_graph():
     plotter = Plotter()
     mesh = Mesh.from_vertices_and_faces(