Integrate compas.scene.Scene via PlotterScene

Follow the compas_viewer ViewerScene pattern: Plotter now owns a
PlotterScene(compas.scene.Scene) bound to the "Plotter" context, instead of
managing its own object list. This gives a hierarchical scene tree (parent/child
with composed world transformations), serialization, and API symmetry with the
Rhino/Blender/Viewer backends.

- add/find/zoom_extents/redraw/sceneobjects delegate to the scene tree.
- PlotterScene.add injects the owning plotter and draws the object; remove clears
  its matplotlib artists.
- SceneObject.draw() now returns the created artists (SceneObject contract), so
  Scene.draw() works; drawing is still managed by the Plotter (like the viewer).
- Guarded registration hook for future 3D shape / Brep scene objects.
- Docs: tutorial "Scenes and hierarchy" section; 4 new tests (11 total).

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

Author: gonzalocasas

.gitignore

@@ -50,3 +50,6 @@ ENV/
 # COMPAS / temp
 temp/
 *.gif
+
+# uv
+uv.lock

CHANGELOG.md

@@ -17,6 +17,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `Ellipse` and `Frame`.
 * Scene objects for the `Mesh` and `Graph` data structures, with vertex/edge/face
   and node/edge labels.
+* `PlotterScene`, a `compas.scene.Scene` subclass bound to the `"Plotter"`
+  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.
 
 ### Changed
 

docs/tutorial.md

@@ -105,6 +105,36 @@ plotter.zoom_extents()
 plotter.show()
 ```
 
+## Scenes and hierarchy
+
+Every `Plotter` owns a [`PlotterScene`][compas_plotters.scene.PlotterScene], a
+subclass of [`compas.scene.Scene`](https://compas.dev/compas/latest/) bound to
+the `"Plotter"` context. `Plotter.add` delegates to it, so you get the full
+COMPAS scene tree: parent/child relationships, composed world transformations,
+and serialization — the same model used by the Rhino, Blender and Viewer
+backends.
+
+```python
+from compas.geometry import Point, Translation
+from compas_plotters import Plotter
+
+plotter = Plotter()
+
+parent = plotter.add(Point(0, 0, 0))
+child = plotter.add(Point(1, 0, 0), parent=parent)
+
+# Transforming the parent moves the child with it.
+parent.transformation = Translation.from_vector([5, 0, 0])
+assert child.worldtransformation[0, 3] == 5.0
+
+plotter.scene  # -> the underlying PlotterScene
+plotter.sceneobjects  # -> the plotter scene objects in the tree
+```
+
+Drawing is managed by the `Plotter` (objects are drawn when added, and
+`Plotter.redraw` refreshes them), so you normally do not call `Scene.draw`
+yourself.
+
 ## Saving
 
 ```python

src/compas_plotters/plotter.py

@@ -9,13 +9,14 @@
 import matplotlib.pyplot as plt
 from compas.geometry import allclose
 
+from compas_plotters.scene.plotterobject import PlotterSceneObject
+from compas_plotters.scene.plotterscene import PlotterScene
+
 if TYPE_CHECKING:
     from compas.data import Data
     from matplotlib.axes import Axes
     from matplotlib.figure import Figure
 
-    from compas_plotters.scene.plotterobject import PlotterSceneObject
-
 Viewbox = tuple[tuple[float, float], tuple[float, float]]
 
 
@@ -70,7 +71,7 @@ def __init__(
         self._show_axes = show_axes
         self._viewbox: Viewbox | None = None
         self._axes: Axes | None = None
-        self._sceneobjects: list[PlotterSceneObject] = []
+        self.scene = PlotterScene(plotter=self)
         self.viewbox = view
         self.figsize = figsize
         self.dpi = dpi
@@ -125,7 +126,12 @@ def figure(self) -> Figure:
     @property
     def sceneobjects(self) -> list[PlotterSceneObject]:
         """The scene objects currently included in the plot."""
-        return self._sceneobjects
+        return [obj for obj in self.scene.objects if isinstance(obj, PlotterSceneObject)]
+
+    @property
+    def is_live(self) -> bool:
+        """Whether the matplotlib figure has been created yet."""
+        return self._axes is not None
 
     @property
     def title(self) -> str:
@@ -163,7 +169,7 @@ def zoom_extents(self, padding: float | None = None) -> None:
         fig_aspect = width / height
 
         data: list[list[float]] = []
-        for obj in self._sceneobjects:
+        for obj in self.sceneobjects:
             data += obj.viewdata()
         if not data:
             return
@@ -226,17 +232,7 @@ def add(self, item: Data, **kwargs) -> PlotterSceneObject:
         -------
         The scene object created for the item.
         """
-        # Imported lazily to avoid a circular import at module load time.
-        from compas.scene import SceneObject
-
-        if self.zstack == "natural":
-            zorder = 1000 + len(self._sceneobjects) * 100
-            kwargs.setdefault("zorder", zorder)
-
-        sceneobject: PlotterSceneObject = SceneObject(item=item, context="Plotter", plotter=self, **kwargs)  # type: ignore[assignment]
-        sceneobject.draw()
-        self._sceneobjects.append(sceneobject)
-        return sceneobject
+        return self.scene.add(item, **kwargs)  # type: ignore[return-value]
 
     def add_from_list(self, items: Iterable[Data], **kwargs) -> list[PlotterSceneObject]:
         """Add multiple COMPAS objects, all with the same options.
@@ -266,7 +262,7 @@ def find(self, item: Data) -> PlotterSceneObject | None:
         -------
         The matching scene object, or None if the item is not in the plot.
         """
-        for obj in self._sceneobjects:
+        for obj in self.sceneobjects:
             if item is obj.item:
                 return obj
         return None
@@ -302,7 +298,7 @@ def redraw(self, pause: float | None = None) -> None:
         pause
             If provided, pause for this many seconds after redrawing.
         """
-        for obj in self._sceneobjects:
+        for obj in self.sceneobjects:
             obj.redraw()
         self.figure.canvas.draw()
         self.figure.canvas.flush_events()

src/compas_plotters/scene/__init__.py

@@ -28,6 +28,7 @@
 from .lineobject import LineObject
 from .meshobject import MeshObject
 from .plotterobject import PlotterSceneObject
+from .plotterscene import PlotterScene
 from .pointobject import PointObject
 from .polygonobject import PolygonObject
 from .polylineobject import PolylineObject
@@ -48,13 +49,34 @@ 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 Box
+        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
+
+        from .shapeobject import ShapeObject
+
+        for shape_cls in (Box, Sphere, Cylinder, Cone, Capsule, Torus, Polyhedron):
+            register(shape_cls, ShapeObject, context="Plotter")
+    except ImportError:
+        pass
+
 
 # Eager registration so that the Plotter works in editable / non-installed setups
 # (where the entry-point-based plugin discovery does not run).
 register_scene_objects()
 
 
 __all__ = [
+    "PlotterScene",
     "PlotterSceneObject",
     "PointObject",
     "VectorObject",

src/compas_plotters/scene/circleobject.py

@@ -60,7 +60,7 @@ def viewdata(self) -> list[list[float]]:
         r = self.circle.radius
         return [[cx - r, cy], [cx + r, cy], [cx, cy - r], [cx, cy + r]]
 
-    def draw(self) -> None:
+    def draw(self) -> list:
         circle = CirclePatch(
             self.circle.center[:2],
             radius=self.circle.radius,
@@ -73,3 +73,4 @@ def draw(self) -> None:
             zorder=self.zorder,
         )
         self._mpl_objects = [self.axes.add_artist(circle)]
+        return self._mpl_objects

src/compas_plotters/scene/ellipseobject.py

@@ -61,7 +61,7 @@ def viewdata(self) -> list[list[float]]:
         b = self.ellipse.minor
         return [[cx - a, cy], [cx + a, cy], [cx, cy - b], [cx, cy + b]]
 
-    def draw(self) -> None:
+    def draw(self) -> list:
         ellipse = EllipsePatch(
             self.ellipse.center[:2],
             width=2 * self.ellipse.major,
@@ -75,3 +75,4 @@ def draw(self) -> None:
             zorder=self.zorder,
         )
         self._mpl_objects = [self.axes.add_artist(ellipse)]
+        return self._mpl_objects

src/compas_plotters/scene/frameobject.py

@@ -58,11 +58,12 @@ def _arrow(self, end, color) -> FancyArrowPatch:
             mutation_scale=100,
         )
 
-    def draw(self) -> None:
+    def draw(self) -> list:
         origin = self.frame.point
         ex = origin + self.frame.xaxis.scaled(self.size)
         ey = origin + self.frame.yaxis.scaled(self.size)
         self._mpl_objects = [
             self.axes.add_patch(self._arrow(ex, self.xcolor)),
             self.axes.add_patch(self._arrow(ey, self.ycolor)),
         ]
+        return self._mpl_objects

src/compas_plotters/scene/graphobject.py

@@ -68,13 +68,14 @@ def _node_radius(self) -> float:
     def viewdata(self) -> list[list[float]]:
         return [xyz[:2] for xyz in self.node_xyz.values()]
 
-    def draw(self) -> None:
+    def draw(self) -> list:
         node_xyz = self.node_xyz
         if self.show_edges:
             self._draw_edges(node_xyz)
         if self.show_nodes:
             self._draw_nodes(node_xyz)
         self._draw_labels(node_xyz)
+        return self._mpl_objects
 
     def _draw_nodes(self, node_xyz: dict) -> None:
         radius = self._node_radius()

src/compas_plotters/scene/lineobject.py

@@ -71,15 +71,16 @@ def clip(self) -> list | None:
         box = [[xmin, ymin], [xmax, ymin], [xmax, ymax], [xmin, ymax]]
         return intersection_line_box_xy(self.line, box)
 
-    def draw(self) -> None:
+    def draw(self) -> list:
         color = to_rgb(self.color)
         if self.draw_as_segment:
             x0, y0 = self.line.start[:2]
             x1, y1 = self.line.end[:2]
         else:
             points = self.clip()
             if not points:
-                return
+                self._mpl_objects = []
+                return self._mpl_objects
             (x0, y0), (x1, y1) = points[0][:2], points[1][:2]
 
         line2d = Line2D(
@@ -96,3 +97,4 @@ def draw(self) -> None:
                 self.plotter.add(self.line.start, edgecolor=color),
                 self.plotter.add(self.line.end, edgecolor=color),
             ]
+        return self._mpl_objects