graphics

Graphics Module.

This module provides various utilities for 3D plotting and visualization based on matplotlib. It includes functions for visualizing Cartesian trajectories, path points, coordinate systems, and more. These utilities are designed to aid in robot trajectory visualization and analysis.

robotblockset.graphics.plotucs(x: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...], UCS_length: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...] = array([1.0000, 1.0000, 1.0000]), UCS_linewidth: float = 1, UCS_labels: Sequence[str] | None = None, UCS_handles: List[Any] | None = None, ax: Axes | None = None) → Tuple[List[Any], Axes][source]

Plot coordinate frame UCS (User Coordinate System).

Draw or update a 3D coordinate frame at a pose given as a position, quaternion, homogeneous transform, or rotation matrix. Axis labels can be added, and existing plot handles can be reused to refresh an already drawn frame.

Parameters:

  • x (ArrayLike) – Frame pose (position and/or orientation) in form (7,), (4, 4), (3,), (4,) or (3, 3).

  • UCS_length (ArrayLike, optional) – Length of UCS axes, by default np.ones(3).

  • UCS_linewidth (float, optional) – Line width of UCS axes, by default 1.

  • UCS_labels (Sequence[str], optional) – Labels for UCS axes, by default None.

  • UCS_handles (List[Any], optional) – Handles used for updating UCS, by default None.

  • ax (plt.Axes, optional) – Axes used to plot UCS, by default None.

Returns:

  • hx (list) – Handles of drawn objects (lines and labels).

  • ax (plt.Axes) – Axes where UCS has been plotted.

Raises:

ValueError – If the input parameter shapes are incorrect.

robotblockset.graphics.plotspheregrid(radius: float = 1.0, alpha: float = 1.0, pos: ndarray = array([0, 0, 0]), N: int = 36, ax: Axes | None = None) → Tuple[List[Any], Axes][source]

Plot a sphere grid in 3D space.

Create a spherical reference surface that helps visualize orientation trajectories or provides spatial context for 3D plots. The radius, position, transparency, and mesh density can be adjusted.

Parameters:

  • radius (float, optional) – Sphere radius, by default 1.0.

  • alpha (float, optional) – Sphere transparency, by default 1.0.

  • pos (Vector3DType, optional) – Sphere origin position, by default np.array([0, 0, 0]).

  • N (int, optional) – Number of sphere grid lines, by default 36.

  • ax (plt.Axes, optional) – Axes used to plot the sphere, by default None.

Returns:

  • hx (list) – Handles of drawn objects (the sphere).

  • ax (plt.Axes) – Axes where the sphere has been plotted.

Raises:

ValueError – If the input parameters are incorrect.

robotblockset.graphics.plotarrow(p1: ndarray, p2: ndarray, radius: float = 0.02, head_length: float = 0.12, head_radius: float = 0.04, color: str = 'k', ax: Axes | None = None) → Tuple[List[Any], Axes][source]

Plot an arrow from point p1 to point p2.

Draw a lightweight 3D arrow between two points using Matplotlib line primitives. The shaft width, head geometry, and color can be tuned to annotate positions and directions in trajectory plots.

Parameters:

  • p1 (Vector3DType) – Initial arrow position (3,).

  • p2 (Vector3DType) – Final arrow position (3,).

  • radius (float, optional) – Arrow line width, by default 0.02.

  • head_length (float, optional) – Relative arrow head length, by default 0.12.

  • head_radius (float, optional) – Relative arrow head width, by default 0.04.

  • color (str, optional) – Arrow color, by default “k” (black).

  • ax (plt.Axes, optional) – Axes to be used for plotting the arrow, by default None.

Returns:

  • hx (list) – Handles of drawn objects (the arrow).

  • ax (plt.Axes) – Axes where the arrow has been plotted.

Raises:

ValueError – If input parameters are incorrect.

robotblockset.graphics.plotcpos_ori(t: ndarray, x: ndarray | None = None, T: ndarray | None = None, p: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...] | None = None, R: ndarray | None = None, Q: ndarray | None = None, typ: str = 'Pos', graph: str = 'Time', grid: bool = True, UCS: bool = False, label: bool = False, alpha: float = 0.1, ori_sel: List[int] = [1, 2], fig_num: str | int = 'Cartesian poses', ax: Axes | None = None) → Tuple[List[Any], Axes][source]

Plot positions or orientations of Cartesian trajecotry

Visualize a Cartesian trajectory either as time-domain signals or as a 3D curve. Position mode shows translational motion, while orientation mode shows quaternion components over time or projected orientation paths on a sphere.

Trajectory is defined by one representation x, t, p, R, Q

Parameters:

  • t (TimesType) – time (n,)

  • x (Poses3DType, optional) – Cartesian trajectory (n, 7), by default None

  • T (HomogeneousMatricesType, optional) – Cartesian trajectory (n, 4, 4), by default None

  • p (ArrayLike, optional) – Cartesian positions (n, 3), by default None

  • R (RotationMatricesType, optional) – Cartesian rotations (n, 3, 3), by default None

  • Q (QuaternionsType, optional) – quaternions (n, 4), by default None

  • typ (str, optional) – Plot signal selection: positions (“Pos”) or orientations (“Ori”), by default “Pos”

  • graph (str, optional) – Plot type selection: time signals (“Time”) or 3D plots (“3D”), by default “Time”

  • grid (bool, optional) – Grid flag, by default True

  • UCS (bool, optional) – Plot UCS flag, by default False

  • label (bool, optional) – Plot labels for points in 3D, by default False

  • alpha (float, optional) – Transparency of sphere grid for orientations, by default 0.1

  • ori_sel (List[int], optional) – Selection of two quaternions rotations for 3D plot (1, 2 or 3), by default [1, 2]

  • fig_num (str, optional) – Figure identifier, by default 1

  • ax (plt.Axes, optional) – Axes to be used for plot, by default None

Returns:

  • hx (list) – handles of drawn objects

  • ax (plt.Axes) – axes where UCS has been ploted

Raises:

ValueError – If the input parameters are invalid.

robotblockset.graphics.plotcpath(s: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...], path: ndarray, points: ndarray | None = None, auxpoints: ndarray | None = None, grid: bool = True, UCS: bool = True, label: bool = True, ori_sel: List[int] = [0, 1], normscale: float = 1, fig_num: str | int = 'Cartesian path', **kwargs) → Tuple[List[Any], List[Axes]][source]

Plot positions, orientations, velocities, and accelerations for a Cartesian path vs path parameter.

Generate a combined overview of a Cartesian path, including 3D position, orientation evolution, and derivative signals with respect to the path parameter. Optional waypoints, auxiliary points, labels, and UCS frames can be overlaid for path debugging.

Parameters:

  • s (ArrayLike) – Path parameter (n,).

  • path (Poses3DType) – Cartesian path (n, 7).

  • points (Poses3DType, optional) – Cartesian points used to generate path (m, 7), by default None.

  • auxpoints (Poses3DType, optional) – Auxiliary Cartesian points, by default None.

  • grid (bool, optional) – Grid flag, by default True.

  • UCS (bool, optional) – Plot UCS axes, by default True.

  • label (bool, optional) – Label points, by default True.

  • ori_sel (List[int], optional) – Selection of quaternion rotations for 3D plot, by default [1, 2].

  • normscale (float, optional) – Scale factor for normalizing the path, by default 1.

  • fig_num (str, optional) – Figure identifier, by default “Cartesian path”.

  • ax (plt.Axes, optional) – Axes to be used for plot, by default None.

Returns:

  • hx (list) – Handles of drawn objects (path points, labels, etc.).

  • ax (list) – Axes where the plot was drawn.

robotblockset.graphics.plotctraj(t: ndarray, xt: ndarray, *args: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...], grid: bool = True, fig_num: str | int = 'Cartesian trajectory', ax: ndarray | None = None, **kwargs) → Tuple[List[Any], ndarray][source]

Plot positions, orientations, velocities, and accelerations for Cartesian trajectory.

Plot a Cartesian trajectory and its first and second derivatives in aligned subplots. If velocity and acceleration are not provided, they are estimated numerically from the trajectory and time vector.

Parameters:

  • t (TimesType) – Time array (n,).

  • xt (Poses3DType) – Cartesian position trajectory (n, 7).

  • *args (ArrayLike, optional) – Cartesian velocity and acceleration trajectories (n, 6), by default None.

  • grid (bool, optional) – Grid flag, by default True.

  • fig_num (str, optional) – Figure identifier, by default “Cartesian trajectory”.

  • ax (np.ndarray, optional) – List of axes to be used for plot (3, 2), by default None.

  • **kwargs (optional) – Additional arguments passed to plot commands.

Returns:

  • hx (list) – Handles of drawn objects.

  • ax (np.ndarray) – Axes of subplots.

robotblockset.graphics.plotpathpoints(x: ndarray | None = None, T: ndarray | None = None, p: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...] | None = None, label: bool = False, fig_num: str | int = 'Path', ax: Axes | None = None, **kwargs) → Tuple[List[Any], Axes][source]

Plot the path points of a Cartesian trajectory.

Draw Cartesian sample points as a dashed 3D path with point markers. Optional labels help identify the original path points or waypoints that define the motion.

Parameters:

  • x (Poses3DType, optional) – Cartesian trajectory (n, 7), by default None.

  • T (HomogeneousMatricesType, optional) – Cartesian trajectory (n, 4, 4), by default None.

  • p (ArrayLike, optional) – Cartesian positions (n, 3), by default None.

  • label (bool, optional) – Label points, by default False.

  • fig_num (str, optional) – Figure identifier, by default “Path”.

  • ax (plt.Axes, optional) – Axes to be used for plot, by default None.

Returns:

  • hx (list) – Handles of drawn objects (points).

  • ax (plt.Axes) – Axes where the points were plotted.

robotblockset.graphics.plotwrench(t: ndarray, FTt: ndarray, grid: bool = True, ax: ndarray | None = None, fig_num: str | int = 'Task forces', **kwargs) → Tuple[List[Any], ndarray][source]

Plot force and torque signals over time.

Plot the force and torque components of a wrench in separate subplots so task-space loads can be inspected over time.

Parameters:

  • t (TimesType) – Time (n,).

  • FTt (WrenchType) – Force and torque signals (n, 6).

  • grid (bool, optional) – Grid flag, by default True.

  • fig_num (str, optional) – Figure identifier, by default “Task forces”.

  • ax (np.ndarray, optional) – List of axes to be used for plot, by default None.

  • **kwargs (optional) – Additional arguments passed to plot commands.

Returns:

  • hx (list) – Handles of drawn objects.

  • ax (np.ndarray) – Axes of subplots.

robotblockset.graphics.plotjtraj(t: ndarray, qt: ndarray, *args: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...], grid: bool = True, ax: ndarray | None = None, fig_num: str | int = 'Joint trajectory', **kwargs) → Tuple[List[Any], ndarray][source]

Plot positions, velocities, and accelerations for joint trajectory.

Visualize joint motion together with velocity and acceleration profiles. Missing derivative signals are estimated numerically from the supplied joint trajectory.

Parameters:

  • t (TimesType) – Time (n,).

  • qt (JointPathType) – Joint position trajectory (n, nj).

  • *args (ArrayLike, optional) – Joint velocity and acceleration trajectories (n, nj), by default None.

  • grid (bool, optional) – Grid flag, by default True.

  • fig_num (str, optional) – Figure identifier, by default “Joint trajectory”.

  • ax (np.ndarray, optional) – List of axes to be used for plot (3,), by default None.

  • **kwargs (optional) – Additional arguments passed to plot commands.

Returns:

  • hx (list) – Handles of drawn objects.

  • ax (np.ndarray) – Axes of subplots.

robotblockset.graphics.plotjctraj(t: ndarray, qt: ndarray, xt: ndarray, *args: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...], grid: bool = True, ax: ndarray | None = None, fig_num: str | int = 'Joint and task trajectory', **kwargs) → Tuple[List[Any], ndarray][source]

Plot positions, orientations, and velocities for joint and task trajectory.

Show joint-space and Cartesian-space signals side by side so manipulator motion can be compared with the resulting task-space path and velocity behavior.

Parameters:

  • t (TimesType) – Time (n,).

  • qt (JointPathType) – Joint position trajectory (n, nj).

  • xt (Poses3DType) – Cartesian position trajectory (n, nj).

  • *args (ArrayLike, optional) – Joint and task velocity trajectories, by default None.

  • grid (bool, optional) – Grid flag, by default True.

  • fig_num (str, optional) – Figure identifier, by default “Joint and task trajectory”.

  • ax (np.ndarray, optional) – List of axes to be used for plot (3,), by default None.

  • **kwargs (optional) – Additional arguments passed to plot commands.

Returns:

  • hx (list) – Handles of drawn objects.

  • ax (np.ndarray) – Axes of subplots.

robotblockset.graphics.plot_circle(r: float = 1, center: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...] = (0, 0), color: str = 'b', linestyle: str = '-', linewidth: float = 2) → None[source]

Plots a circle with a given radius and center using Matplotlib.

Draw a 2D circle on the current axes using a sampled parametric curve. The radius, center, color, line style, and line width can all be customized.

Parameters:

  • r (float, optional) – Radius of the circle. Defaults to 1.

  • center (ArrayLike, optional) – Coordinates of the circle center (x, y). Defaults to (0,0).

  • color (str, optional) – Color of the circle. Defaults to ‘b’ (blue).

  • linestyle (str, optional) – Line style for the circle. Defaults to ‘-‘.

  • linewidth (float, optional) – Width of the circle line. Defaults to 2.

Returns:

This function has no return value. It draws the circle on the current axes.

Return type:

None

robotblockset.graphics.linkxaxes(ax: Sequence[Axes] | None = None) → None[source]

Share the x-axis between all axes in the list.

Link the x-limits of multiple subplots so zooming or panning one axis updates the others. If no axes are provided, all axes in the current figure are linked.

Parameters:

ax (Sequence[plt.Axes], optional) – List of axes, by default None (link all subplots in current figure).

Returns:

This function has no return value. It links the x-axes of the given axes.

Return type:

None

robotblockset.graphics.display_images(images: Sequence[ndarray], bgr2rgb: bool = False) → None[source]

Display a collection of images in a near-square grid.

Arrange a list of images into a compact grid for quick visual inspection. The layout is chosen automatically to be close to square, and OpenCV-style BGR images can optionally be converted to RGB before display.

The function arranges the given images into a grid whose number of rows and columns is chosen to be as close to square as possible. Each image is rendered using a grayscale colormap and axes are hidden.

Parameters:

  • images (Sequence[OpenCVIntImageType | NumpyIntImageType | NumpyFloatImageType]) – A sequence of 2D (H, W) or 3D (H, W, C) NumPy arrays representing images. Images are displayed in the order provided.

  • bgr2rgb (bool, optional) – Convert 3-channel OpenCV BGR images to RGB before display, by default False.

Returns:

This function has no return value. It renders the images using Matplotlib.

Return type:

None

Notes

The grid dimensions are computed as:

  • cols = ceil(sqrt(N))

  • rows = ceil(N / cols)

where N is the number of images.

Functions

display_images(images[, bgr2rgb])

Display a collection of images in a near-square grid.

linkxaxes([ax])

Share the x-axis between all axes in the list.

plot_circle([r, center, color, linestyle, ...])

Plots a circle with a given radius and center using Matplotlib.

plotarrow(p1, p2[, radius, head_length, ...])

Plot an arrow from point p1 to point p2.

plotcpath(s, path[, points, auxpoints, ...])

Plot positions, orientations, velocities, and accelerations for a Cartesian path vs path parameter.

plotcpos_ori(t[, x, T, p, R, Q, typ, graph, ...])

Plot positions or orientations of Cartesian trajecotry

plotctraj(t, xt, *args[, grid, fig_num, ax])

Plot positions, orientations, velocities, and accelerations for Cartesian trajectory.

plotjctraj(t, qt, xt, *args[, grid, ax, fig_num])

Plot positions, orientations, and velocities for joint and task trajectory.

plotjtraj(t, qt, *args[, grid, ax, fig_num])

Plot positions, velocities, and accelerations for joint trajectory.

plotpathpoints([x, T, p, label, fig_num, ax])

Plot the path points of a Cartesian trajectory.

plotspheregrid([radius, alpha, pos, N, ax])

Plot a sphere grid in 3D space.

plotucs(x[, UCS_length, UCS_linewidth, ...])

Plot coordinate frame UCS (User Coordinate System).

plotwrench(t, FTt[, grid, ax, fig_num])

Plot force and torque signals over time.