Skip to content

compas_plotter.scene ¤

Plotter scene objects and their registration.

This subpackage is the "Plotter" visualisation-context backend, mirroring the structure of compas_rhino.scene and compas_blender.scene: it provides a scene object per supported COMPAS type and registers each one under the "Plotter" context.

BoxObject ¤

BoxObject(
    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,
)

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 (float, default: 1.0 ) –

    Width of the edges.

  • linestyle (str, default: 'solid' ) –

    Matplotlib line style ("solid", "dotted", "dashed", "dashdot").

  • facecolor (Color | Sequence[float], default: (0.9, 0.9, 1.0) ) –

    Color of the faces.

  • edgecolor (Color | Sequence[float], default: (0.0, 0.0, 0.0) ) –

    Color of the edges.

  • fill (bool, default: True ) –

    If True, fill the faces.

  • alpha (float, default: 0.3 ) –

    Transparency of the faces, between 0 and 1.

axes property ¤

axes: Axes

The matplotlib axes of the owning plotter.

clear ¤

clear() -> None

Remove all matplotlib artists previously created by this scene object.

redraw ¤

redraw() -> None

Redraw the object, reflecting any changes to its geometry or settings.

The default implementation clears the existing matplotlib artists and draws again. Subclasses may override this to update artists in place.

CircleObject ¤

CircleObject(
    linewidth: float = 1.0,
    linestyle: str = "solid",
    facecolor: Color | Sequence[float] = (1.0, 1.0, 1.0),
    edgecolor: Color | Sequence[float] = (0.0, 0.0, 0.0),
    fill: bool = True,
    alpha: float = 1.0,
    **kwargs,
)

Plotter scene object for :class:compas.geometry.Circle.

The circle is drawn as its projection onto the XY plane (center and radius); any out-of-plane orientation of the circle frame is ignored.

Parameters:

  • linewidth (float, default: 1.0 ) –

    Width of the circle boundary.

  • linestyle (str, default: 'solid' ) –

    Matplotlib line style ("solid", "dotted", "dashed", "dashdot").

  • facecolor (Color | Sequence[float], default: (1.0, 1.0, 1.0) ) –

    Color of the interior of the circle.

  • edgecolor (Color | Sequence[float], default: (0.0, 0.0, 0.0) ) –

    Color of the boundary of the circle.

  • fill (bool, default: True ) –

    If True, fill the interior of the circle.

  • alpha (float, default: 1.0 ) –

    Transparency of the circle, between 0 and 1.

axes property ¤

axes: Axes

The matplotlib axes of the owning plotter.

clear ¤

clear() -> None

Remove all matplotlib artists previously created by this scene object.

redraw ¤

redraw() -> None

Redraw the object, reflecting any changes to its geometry or settings.

The default implementation clears the existing matplotlib artists and draws again. Subclasses may override this to update artists in place.

EllipseObject ¤

EllipseObject(
    linewidth: float = 1.0,
    linestyle: str = "solid",
    facecolor: Color | Sequence[float] = (1.0, 1.0, 1.0),
    edgecolor: Color | Sequence[float] = (0.0, 0.0, 0.0),
    fill: bool = True,
    alpha: float = 1.0,
    **kwargs,
)

Plotter scene object for :class:compas.geometry.Ellipse.

The ellipse is drawn as its projection onto the XY plane (center, major and minor axes); any out-of-plane orientation of the ellipse frame is ignored.

Parameters:

  • linewidth (float, default: 1.0 ) –

    Width of the ellipse boundary.

  • linestyle (str, default: 'solid' ) –

    Matplotlib line style ("solid", "dotted", "dashed", "dashdot").

  • facecolor (Color | Sequence[float], default: (1.0, 1.0, 1.0) ) –

    Color of the interior of the ellipse.

  • edgecolor (Color | Sequence[float], default: (0.0, 0.0, 0.0) ) –

    Color of the boundary of the ellipse.

  • fill (bool, default: True ) –

    If True, fill the interior of the ellipse.

  • alpha (float, default: 1.0 ) –

    Transparency of the ellipse, between 0 and 1.

axes property ¤

axes: Axes

The matplotlib axes of the owning plotter.

clear ¤

clear() -> None

Remove all matplotlib artists previously created by this scene object.

redraw ¤

redraw() -> None

Redraw the object, reflecting any changes to its geometry or settings.

The default implementation clears the existing matplotlib artists and draws again. Subclasses may override this to update artists in place.

FrameObject ¤

FrameObject(
    size: float = 1.0,
    xcolor: tuple[float, float, float] = (1.0, 0.0, 0.0),
    ycolor: tuple[float, float, float] = (0.0, 1.0, 0.0),
    pointsize: float = 5,
    pointcolor: tuple[float, float, float] = (0.0, 0.0, 0.0),
    **kwargs,
)

Plotter scene object for :class:compas.geometry.Frame.

The frame is drawn as its projection onto the XY plane: a red arrow for the X axis and a green arrow for the Y axis, both starting at the frame origin, with a disc marking the origin in between the two arrows.

Parameters:

  • size (float, default: 1.0 ) –

    Length of the axis arrows, in data units.

  • xcolor (tuple[float, float, float], default: (1.0, 0.0, 0.0) ) –

    Color of the X-axis arrow.

  • ycolor (tuple[float, float, float], default: (0.0, 1.0, 0.0) ) –

    Color of the Y-axis arrow.

  • pointsize (float, default: 5 ) –

    Size of the origin marker, in points.

  • pointcolor (tuple[float, float, float], default: (0.0, 0.0, 0.0) ) –

    Color of the origin marker.

axes property ¤

axes: Axes

The matplotlib axes of the owning plotter.

clear ¤

clear() -> None

Remove all matplotlib artists previously created by this scene object.

redraw ¤

redraw() -> None

Redraw the object, reflecting any changes to its geometry or settings.

The default implementation clears the existing matplotlib artists and draws again. Subclasses may override this to update artists in place.

GraphObject ¤

GraphObject(
    nodesize: float = 5,
    edgewidth: float = 1.0,
    nodecolor=(1.0, 1.0, 1.0),
    edgecolor=(0.0, 0.0, 0.0),
    sizepolicy: str = "absolute",
    nodetext: dict | None = None,
    edgetext: dict | None = None,
    **kwargs,
)

Plotter scene object for :class:compas.datastructures.Graph.

Reuses the data layer of the COMPAS 2.x base graph scene object (the show_nodes/edges flags and the per-element color/size settings, and the node_xyz coordinate map) and provides the matplotlib drawing backend, including optional labels.

Parameters:

  • nodesize (float, default: 5 ) –

    Size of the node markers.

  • edgewidth (float, default: 1.0 ) –

    Width of the edges.

  • nodecolor –

    Color of the nodes. A single color, or a dict mapping nodes to colors.

  • edgecolor –

    Color of the edges. A single color, or a dict mapping edges to colors.

  • sizepolicy (str, default: 'absolute' ) –

    If "absolute", nodesize is scaled by the plotter resolution, giving nodes a constant on-screen size (the default). If "relative", nodesize is scaled by the number of nodes.

  • nodetext (dict | None, default: None ) –

    A dict mapping nodes to label strings.

  • edgetext (dict | None, default: None ) –

    A dict mapping edges to label strings.

axes property ¤

axes: Axes

The matplotlib axes of the owning plotter.

node_xyz property writable ¤

node_xyz: dict

Mapping of nodes to their view coordinates.

clear ¤

clear() -> None

Remove all matplotlib artists previously created by this scene object.

redraw ¤

redraw() -> None

Redraw the object, reflecting any changes to its geometry or settings.

The default implementation clears the existing matplotlib artists and draws again. Subclasses may override this to update artists in place.

LineObject ¤

LineObject(
    draw_points: bool = False,
    draw_as_segment: bool = False,
    linewidth: float = 1.0,
    linestyle: str = "solid",
    color: Color | Sequence[float] = (0.0, 0.0, 0.0),
    **kwargs,
)

Plotter scene object for :class:compas.geometry.Line.

By default the line is treated as infinite and clipped to the current view box. Set draw_as_segment to draw only the segment between start and end.

Parameters:

  • draw_points (bool, default: False ) –

    If True, also draw the start and end points of the line.

  • draw_as_segment (bool, default: False ) –

    If True, draw only the segment between start and end instead of the infinite line clipped to the view box.

  • linewidth (float, default: 1.0 ) –

    Width of the line.

  • linestyle (str, default: 'solid' ) –

    Matplotlib line style ("solid", "dotted", "dashed", "dashdot").

  • color (Color | Sequence[float], default: (0.0, 0.0, 0.0) ) –

    Color of the line.

axes property ¤

axes: Axes

The matplotlib axes of the owning plotter.

clear ¤

clear() -> None

Remove all matplotlib artists previously created by this scene object.

clip ¤

clip() -> list | None

Compute the intersection of the (infinite) line with the current view box.

Returns:

  • The two clipping points, or None if the line does not cross the view box. –

redraw ¤

redraw() -> None

Redraw the object, reflecting any changes to its geometry or settings.

The default implementation clears the existing matplotlib artists and draws again. Subclasses may override this to update artists in place.

MeshObject ¤

MeshObject(
    vertexsize: float = 5,
    edgewidth: float = 1.0,
    facecolor=(0.9, 0.9, 0.9),
    edgecolor=(0.0, 0.0, 0.0),
    vertexcolor=(1.0, 1.0, 1.0),
    vertextext: dict | None = None,
    edgetext: dict | None = None,
    facetext: dict | None = None,
    **kwargs,
)

Plotter scene object for :class:compas.datastructures.Mesh.

Reuses the data layer of the COMPAS 2.x base mesh scene object (the show_vertices/edges/faces flags and the per-element color/size settings) and provides the matplotlib drawing backend, including optional labels.

Parameters:

  • vertexsize (float, default: 5 ) –

    On-screen size of the vertex markers, in points.

  • edgewidth (float, default: 1.0 ) –

    Width of the edges.

  • facecolor –

    Color of the faces. A single color, or a dict mapping faces to colors.

  • edgecolor –

    Color of the edges. A single color, or a dict mapping edges to colors.

  • vertexcolor –

    Color of the vertices. A single color, or a dict mapping vertices to colors.

  • vertextext (dict | None, default: None ) –

    A dict mapping vertices to label strings.

  • edgetext (dict | None, default: None ) –

    A dict mapping edges to label strings.

  • facetext (dict | None, default: None ) –

    A dict mapping faces to label strings.

axes property ¤

axes: Axes

The matplotlib axes of the owning plotter.

vertex_xyz property writable ¤

vertex_xyz: dict

Mapping of vertices to their view coordinates.

clear ¤

clear() -> None

Remove all matplotlib artists previously created by this scene object.

redraw ¤

redraw() -> None

Redraw the object, reflecting any changes to its geometry or settings.

The default implementation clears the existing matplotlib artists and draws again. Subclasses may override this to update artists in place.

PlotterScene ¤

PlotterScene(
    plotter: Plotter | None = None, name: str = "PlotterScene", context: str = "Plotter"
)

A :class:compas.scene.Scene bound to the "Plotter" visualisation context.

This is the container behind a :class:compas_plotter.Plotter, mirroring the way compas_viewer wraps :class:compas.scene.Scene in a ViewerScene. It stores a back-reference to the owning plotter and injects it into every scene object it creates, so the objects can draw onto the plotter axes.

Parameters:

  • plotter (Plotter | None, default: None ) –

    The plotter that owns this scene.

  • name (str, default: 'PlotterScene' ) –

    The name of the scene.

  • context (str, default: 'Plotter' ) –

    The visualisation context. Fixed to "Plotter"; overriding it would prevent the plotter scene objects from being resolved.

add ¤

add(item: Data | SceneObject, parent=None, **kwargs) -> SceneObject

Add an item to the scene and draw it on the plotter canvas.

Extends :meth:compas.scene.Scene.add by injecting the owning plotter into the created scene object and drawing it immediately, so that adding an object to a live plot shows it right away.

Parameters:

  • item (Data | SceneObject) –

    The COMPAS object (or ready-made scene object) to add.

  • parent –

    The parent scene object in the scene tree.

  • **kwargs –

    Visualisation options forwarded to the scene object.

Returns:

  • The scene object created for the item. –

remove ¤

remove(sceneobject: SceneObject) -> None

Remove a scene object, clearing its matplotlib artists first.

Parameters:

  • sceneobject (SceneObject) –

    The scene object to remove.

PlotterSceneObject ¤

PlotterSceneObject(plotter: Plotter | None = None, zorder: int = 1000, **kwargs)

Base class for all scene objects drawn by a :class:compas_plotter.Plotter.

This is the COMPAS 2.x replacement for the 1.x PlotterArtist. It stores a back-reference to the owning plotter so concrete objects can draw onto its matplotlib axes, and provides shared bookkeeping for the matplotlib artists created during drawing.

Parameters:

  • plotter (Plotter | None, default: None ) –

    The plotter that owns this scene object. Injected by :meth:Plotter.add.

  • zorder (int, default: 1000 ) –

    The stacking order of this object on the canvas.

axes property ¤

axes: Axes

The matplotlib axes of the owning plotter.

clear ¤

clear() -> None

Remove all matplotlib artists previously created by this scene object.

draw ¤

draw() -> list

Draw the object on the plotter canvas. Implemented by subclasses.

Returns:

  • The matplotlib artists created for this object (also stored on –
  • ``self._mpl_objects``), matching the :class:`compas.scene.SceneObject` –
  • contract that ``draw`` returns the created visualisation handles. –

redraw ¤

redraw() -> None

Redraw the object, reflecting any changes to its geometry or settings.

The default implementation clears the existing matplotlib artists and draws again. Subclasses may override this to update artists in place.

viewdata ¤

viewdata() -> list[list[float]]

Return the 2D points bounding this object, used by :meth:Plotter.zoom_extents.

Returns:

  • A list of ``[x, y]`` points. –

PointObject ¤

PointObject(
    size: float = 5,
    facecolor: Color | Sequence[float] = (1.0, 1.0, 1.0),
    edgecolor: Color | Sequence[float] = (0.0, 0.0, 0.0),
    **kwargs,
)

Plotter scene object for :class:compas.geometry.Point.

The point is drawn as a disc with a fixed on-screen size (in points), so it keeps a constant size regardless of the zoom level.

Parameters:

  • size (float, default: 5 ) –

    The size of the point marker, in points.

  • facecolor (Color | Sequence[float], default: (1.0, 1.0, 1.0) ) –

    Color of the interior of the marker.

  • edgecolor (Color | Sequence[float], default: (0.0, 0.0, 0.0) ) –

    Color of the boundary of the marker.

axes property ¤

axes: Axes

The matplotlib axes of the owning plotter.

clear ¤

clear() -> None

Remove all matplotlib artists previously created by this scene object.

redraw ¤

redraw() -> None

Redraw the object, reflecting any changes to its geometry or settings.

The default implementation clears the existing matplotlib artists and draws again. Subclasses may override this to update artists in place.

PolygonObject ¤

PolygonObject(
    linewidth: float = 1.0,
    linestyle: str = "solid",
    facecolor: Color | Sequence[float] = (1.0, 1.0, 1.0),
    edgecolor: Color | Sequence[float] = (0.0, 0.0, 0.0),
    fill: bool = True,
    alpha: float = 1.0,
    **kwargs,
)

Plotter scene object for :class:compas.geometry.Polygon.

Parameters:

  • linewidth (float, default: 1.0 ) –

    Width of the polygon boundary.

  • linestyle (str, default: 'solid' ) –

    Matplotlib line style ("solid", "dotted", "dashed", "dashdot").

  • facecolor (Color | Sequence[float], default: (1.0, 1.0, 1.0) ) –

    Color of the interior of the polygon.

  • edgecolor (Color | Sequence[float], default: (0.0, 0.0, 0.0) ) –

    Color of the boundary of the polygon.

  • fill (bool, default: True ) –

    If True, fill the interior of the polygon.

  • alpha (float, default: 1.0 ) –

    Transparency of the polygon, between 0 and 1.

axes property ¤

axes: Axes

The matplotlib axes of the owning plotter.

clear ¤

clear() -> None

Remove all matplotlib artists previously created by this scene object.

redraw ¤

redraw() -> None

Redraw the object, reflecting any changes to its geometry or settings.

The default implementation clears the existing matplotlib artists and draws again. Subclasses may override this to update artists in place.

PolylineObject ¤

PolylineObject(
    draw_points: bool = True,
    linewidth: float = 1.0,
    linestyle: str = "solid",
    color: Color | Sequence[float] = (0.0, 0.0, 0.0),
    **kwargs,
)

Plotter scene object for :class:compas.geometry.Polyline.

Parameters:

  • draw_points (bool, default: True ) –

    If True, also draw the points of the polyline.

  • linewidth (float, default: 1.0 ) –

    Width of the polyline.

  • linestyle (str, default: 'solid' ) –

    Matplotlib line style ("solid", "dotted", "dashed", "dashdot").

  • color (Color | Sequence[float], default: (0.0, 0.0, 0.0) ) –

    Color of the polyline.

axes property ¤

axes: Axes

The matplotlib axes of the owning plotter.

clear ¤

clear() -> None

Remove all matplotlib artists previously created by this scene object.

redraw ¤

redraw() -> None

Redraw the object, reflecting any changes to its geometry or settings.

The default implementation clears the existing matplotlib artists and draws again. Subclasses may override this to update artists in place.

ShapeObject ¤

ShapeObject(
    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,
)

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 (int, default: 16 ) –

    Number of faces around curved shapes (longitude). Ignored by shapes without a resolution, such as :class:compas.geometry.Polyhedron.

  • v (int, default: 16 ) –

    Number of faces along curved shapes (latitude), where applicable.

  • linewidth (float, default: 0.5 ) –

    Width of the edges.

  • linestyle (str, default: 'solid' ) –

    Matplotlib line style ("solid", "dotted", "dashed", "dashdot").

  • facecolor (Color | Sequence[float], default: (0.9, 0.9, 1.0) ) –

    Color of the faces.

  • edgecolor (Color | Sequence[float], default: (0.0, 0.0, 0.0) ) –

    Color of the edges.

  • fill (bool, default: True ) –

    If True, fill the faces.

  • alpha (float, default: 0.2 ) –

    Transparency of the faces, between 0 and 1.

axes property ¤

axes: Axes

The matplotlib axes of the owning plotter.

clear ¤

clear() -> None

Remove all matplotlib artists previously created by this scene object.

redraw ¤

redraw() -> None

Redraw the object, reflecting any changes to its geometry or settings.

The default implementation clears the existing matplotlib artists and draws again. Subclasses may override this to update artists in place.

VectorObject ¤

VectorObject(
    point: Point | None = None,
    draw_point: bool = False,
    color: Color | Sequence[float] = (0.0, 0.0, 0.0),
    **kwargs,
)

Plotter scene object for :class:compas.geometry.Vector.

The vector is drawn as an arrow, by default starting at the world origin.

Parameters:

  • point (Point | None, default: None ) –

    The base point of the vector. Defaults to the world origin.

  • draw_point (bool, default: False ) –

    If True, also draw the base point of the vector.

  • color (Color | Sequence[float], default: (0.0, 0.0, 0.0) ) –

    Color of the arrow.

axes property ¤

axes: Axes

The matplotlib axes of the owning plotter.

clear ¤

clear() -> None

Remove all matplotlib artists previously created by this scene object.

redraw ¤

redraw() -> None

Redraw the object, reflecting any changes to its geometry or settings.

The default implementation clears the existing matplotlib artists and draws again. Subclasses may override this to update artists in place.