Add box

Author: gonzalocasas

docs/tutorial.md

@@ -58,6 +58,67 @@ between `line.start` and `line.end`.
 Points (and mesh vertices and graph nodes) are drawn with a fixed on-screen size
 in points, so they do not grow or shrink when you zoom.
 
+## 3D shapes
+
+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.
+
+```python
+from math import radians
+from compas.geometry import Box, Frame
+from compas_plotters import Plotter
+
+plotter = Plotter(figsize=(8, 5))
+
+# an axis-aligned box projects to a rectangle
+plotter.add(Box(3, 2, 1))
+
+# a rotated box keeps its 3D silhouette
+frame = Frame([6, 0, 0]).rotated(radians(35), [1, 1, 1], point=[6, 0, 0])
+plotter.add(Box(2, 2, 2, frame=frame), facecolor=(0.9, 0.9, 1.0), alpha=0.3)
+
+plotter.zoom_extents()
+plotter.show()
+```
+
+Pass `fill=False` for a pure wireframe, or tune `alpha` and `facecolor` to shade
+the faces. Because a projection has no depth sorting, faces are not hidden behind
+one another — every edge stays visible.
+
+### Rotating box animation
+
+A good way to confirm the projection is spinning the box and watching the
+silhouette update every frame. Rotate the geometry inside a
+[`Plotter.on`][compas_plotters.Plotter.on] callback (see
+[Dynamic plots and animations](#dynamic-plots-and-animations)) and the plotter
+reprojects and redraws it:
+
+```python
+from math import radians
+from compas.geometry import Box, Frame, Rotation
+from compas_plotters import Plotter
+
+plotter = Plotter(figsize=(6, 6))
+
+box = Box(2, 2, 2, frame=Frame([0, 0, 0]).rotated(radians(35), [1, 1, 1]))
+plotter.add(box, facecolor=(0.9, 0.9, 1.0), alpha=0.3)
+
+# keep the view fixed so the box is seen to rotate, not the camera
+plotter.zoom_extents()
+
+rotation = Rotation.from_axis_and_angle([0, 1, 0], radians(6), point=[0, 0, 0])
+
+@plotter.on(interval=0.05, frames=60, record=True, recording="box.gif")
+def spin(frame):
+    box.transform(rotation)
+
+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.
+
 ## Meshes
 
 Meshes reuse the data layer of the COMPAS scene system, so the `show_vertices`,

src/compas_plotters/scene/__init__.py

@@ -10,6 +10,7 @@
 
 from compas.datastructures import Graph
 from compas.datastructures import Mesh
+from compas.geometry import Box
 from compas.geometry import Circle
 from compas.geometry import Ellipse
 from compas.geometry import Frame
@@ -21,6 +22,7 @@
 from compas.plugins import plugin
 from compas.scene import register
 
+from .boxobject import BoxObject
 from .circleobject import CircleObject
 from .ellipseobject import EllipseObject
 from .frameobject import FrameObject
@@ -46,6 +48,7 @@ def register_scene_objects():
     register(Circle, CircleObject, context="Plotter")
     register(Ellipse, EllipseObject, context="Plotter")
     register(Frame, FrameObject, context="Plotter")
+    register(Box, BoxObject, context="Plotter")
     register(Mesh, MeshObject, context="Plotter")
     register(Graph, GraphObject, context="Plotter")
 
@@ -54,7 +57,6 @@ def register_scene_objects():
     # 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
@@ -64,7 +66,7 @@ def register_scene_objects():
 
         from .shapeobject import ShapeObject
 
-        for shape_cls in (Box, Sphere, Cylinder, Cone, Capsule, Torus, Polyhedron):
+        for shape_cls in (Sphere, Cylinder, Cone, Capsule, Torus, Polyhedron):
             register(shape_cls, ShapeObject, context="Plotter")
     except ImportError:
         pass
@@ -86,6 +88,7 @@ def register_scene_objects():
     "CircleObject",
     "EllipseObject",
     "FrameObject",
+    "BoxObject",
     "MeshObject",
     "GraphObject",
 ]

src/compas_plotters/scene/boxobject.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from typing import Sequence
+
+from compas.colors import Color
+from compas.geometry import Box
+from compas.scene import GeometryObject
+from matplotlib.patches import Polygon as PolygonPatch
+
+from .plotterobject import PlotterSceneObject
+from .plotterobject import to_rgb
+
+
+class BoxObject(PlotterSceneObject, GeometryObject):
+    """Plotter scene object for :class:`compas.geometry.Box`.
+
+    The box is drawn as its projection onto the XY plane: each of the six faces
+    is projected to a semi-transparent polygon and the twelve edges are drawn on
+    top, so the box reads as a solid regardless of its orientation.
+
+    Parameters
+    ----------
+    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,
+        linewidth: float = 1.0,
+        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.3,
+        **kwargs,
+    ) -> None:
+        super().__init__(zorder=1000, **kwargs)
+        self.linewidth = linewidth
+        self.linestyle = linestyle
+        self.facecolor = facecolor
+        self.edgecolor = edgecolor
+        self.fill = fill
+        self.alpha = alpha
+
+    @property
+    def box(self) -> Box:
+        return self.geometry  # type: ignore[return-value]
+
+    def viewdata(self) -> list[list[float]]:
+        return [list(point[:2]) for point in self.box.points]
+
+    def draw(self) -> list:
+        points = self.box.points
+        # 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 self.box.faces:
+            polygon = PolygonPatch(
+                [list(points[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