compas_plotter.Plotter

Plotter(
    view: Viewbox = ((-8.0, 16.0), (-5.0, 10.0)),
    figsize: tuple[float, float] = (8.0, 5.0),
    dpi: float = 100,
    bgcolor: str = "#ffffff",
    show_axes: bool = False,
    zstack: str = "zorder",
)

Plotter for the 2D visualisation of COMPAS geometry and data structures.

The plotter wraps a matplotlib figure and axes. COMPAS objects added to the plotter are dispatched through the :mod:compas.scene system to their registered "Plotter" scene object, which draws them with matplotlib.

Parameters:

• view (Viewbox, default: ((-8.0, 16.0), (-5.0, 10.0)) ) –

  The ((xmin, xmax), (ymin, ymax)) area zoomed into view.

• figsize (tuple[float, float], default: (8.0, 5.0) ) –

  Size of the figure in inches.

• dpi (float, default: 100 ) –

  Resolution of the figure in dots per inch.

• bgcolor (str, default: '#ffffff' ) –

  Background color of the figure canvas, as a matplotlib color.

• show_axes (bool, default: False ) –

  If True, show the matplotlib axes.

• zstack (str, default: 'zorder' ) –

  If "natural", objects are stacked in the order they are added. If "zorder", objects are stacked by their zorder.

Attributes:

• fontsize (int) –

  Default font size used for labels.

Examples:

>>> from compas.geometry import Point
>>> from compas_plotter import Plotter
>>> plotter = Plotter()
>>> obj = plotter.add(Point(0, 0, 0))
>>> plotter.zoom_extents()

axes property

axes: Axes

The matplotlib axes used by the plotter (created lazily).

figure property

figure: Figure

The matplotlib figure used by the plotter.

is_live property

is_live: bool

Whether the matplotlib figure has been created yet.

sceneobjects property

sceneobjects: list[PlotterSceneObject]

The scene objects currently included in the plot.

add

add(item: Data, **kwargs) -> PlotterSceneObject

Add a COMPAS object to the plot.

Parameters:

• item (Data) –

  A COMPAS geometry object or data structure.

• **kwargs –

  Visualisation options forwarded to the corresponding scene object.

Returns:

• The scene object created for the item. –

add_from_list

add_from_list(items: Iterable[Data], **kwargs) -> list[PlotterSceneObject]

Add multiple COMPAS objects, all with the same options.

Parameters:

• items (Iterable[Data]) –

  The COMPAS objects to add.

• **kwargs –

  Visualisation options forwarded to each scene object.

Returns:

• The scene objects created for the items. –

draw

draw(pause: float | None = None) -> None

Draw all objects included in the plot.

Parameters:

• pause (float | None, default: None ) –

  If provided, pause for this many seconds after drawing.

find

find(item: Data) -> PlotterSceneObject | None

Find the scene object associated with a given COMPAS object.

Parameters:

• item (Data) –

  The COMPAS object to look for.

Returns:

• The matching scene object, or None if the item is not in the plot. –

on

on(
    interval: float | None = None,
    frames: int | None = None,
    record: bool = False,
    recording: str | None = None,
    dpi: int = 150,
) -> Callable

Decorate a per-frame callback to create a dynamic (animated) plot.

The decorated function is called once per frame with the frame index as its only argument, and the canvas is redrawn after each call.

Parameters:

• interval (float | None, default: None ) –

  Time between frames, in seconds.

• frames (int | None, default: None ) –

  Number of frames to render.

• record (bool, default: False ) –

  If True, save the animation as a GIF to recording.

• recording (str | None, default: None ) –

  Output path for the GIF (required when record is True).

• dpi (int, default: 150 ) –

  Resolution of the recorded frames.

Returns:

• The decorator to apply to the per-frame callback. –

pause

pause(pause: float) -> None

Pause plotting for the given interval.

Parameters:

• pause (float) –

  The duration of the pause, in seconds.

redraw

redraw(pause: float | None = None) -> None

Redraw all objects and refresh the canvas.

Parameters:

• pause (float | None, default: None ) –

  If provided, pause for this many seconds after redrawing.

register_listener

register_listener(listener: Callable) -> None

Register a listener for matplotlib pick events.

Parameters:

• listener (Callable) –

  The handler called on every pick_event.

save

save(filepath: str, **kwargs) -> None

Save the plot to an image file.

Parameters:

• filepath (str) –

  Full path of the output file.

• **kwargs –

  Additional keyword arguments passed to matplotlib.pyplot.savefig.

show

show() -> None

Draw all objects and display the plot in an interactive window.

zoom_extents

zoom_extents(padding: float | None = None) -> None

Zoom the view to the bounding box of all drawn objects.

Parameters:

• padding (float | None, default: None ) –

  Extra padding around the bounding box of all objects, in data units.