pyplot._pyplot

Copyright (C) 2025 Murilo Marques Marinho (www.murilomarinho.info)

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

Author: Murilo M. Marinho

Module Contents

Functions

plot

An aggregator for all plot functions related to dqrobotics. Currently, supports DQ and DQ_SerialManipulator.

_plot_dq

Implementing the pyplot valid options of https://github.com/dqrobotics/matlab/blob/master/%40DQ/plot.m the particular plotting functions did not inherit from these implementations and are an informed attempt of using DQ operators to plot the objects.

_plot_plane

Draw a plane representing the DQ pi_dq. In this plot, the normal will be represented by the local z-axis of the plane and the plane will span in its local x-y axis.

_plot_serial_manipulator

Draw a serial manipulator at a given joint configuration q. Each joint transformation will be connected by a line with spec line_color and width linewidth.

_plot_pose

Draw a reference frame at a given pose x.

_plot_line

Draw a line representing the DQ l_dq.

_plot_sphere

Draw a sphere of a given radius centered at p, where p is a pure quaternion.

__plot_revolute_joint

This internal function is used to draw cylinders, for now, for DQ_SerialManipulators. The cylinder’s height is through its z-axis, and it spans from -height_z/2 to +height_z/2.

__dq_adjoint

This internal function currently does not seem to exist in the implementation of dqrobotics. It will be replaced when it’s available. I’m basing this on (25) of https://faculty.sites.iastate.edu/jia/files/inline-files/dual-quaternion.pdf.

__dq_adjoint_grid

This internal function runs __dq_adjoint through all elements of a grid so that calculations are simplified. For instance, to move a cylinder or other surface around a plot.

__plot_cylinder

Internal method to draw a cylinder. x is a unit dual quaternion that defines the centre of the cylinder. The cylinder will span from -height_z/2 to +height_z/2. Use param_dict to define anything to be passed on to plot_surface.

API

pyplot._pyplot.plot(obj, **kwargs)

An aggregator for all plot functions related to dqrobotics. Currently, supports DQ and DQ_SerialManipulator.

Import it as follows:

import dqrobotics_extensions.pyplot as dqp

Before this can be used, please remember to initialise the plt Axes. Example:

plt.figure()
ax = plt.axes(projection='3d')
dqp.plot(i_)
plt.show()

Plotting a unit DQ x (See internal function pyplot._pyplot._plot_pose):

dqp.plot(x)

Plotting a line DQ l_dq (See internal function pyplot._pyplot._plot_line):

dqp.plot(l_dq, line=True)

Plotting a plane DQ pi_dq (See internal function pyplot._pyplot._plot_plane):

dqp.plot(pi_dq, plane=True)

Plotting a DQ_SerialManipulator called robot at joint configurations q (See internal function pyplot._pyplot._plot_serial_manipulator):

dqp.plot(robot, q=q)
Parameters:

  • obj – The input to be plotted.

  • kwargs – For arguments depending on the type of plot you need, see the description above.

Raises:

RuntimeError – If the input instance obj has no meaning for function, or if the obj is not valid for the input options.

pyplot._pyplot._plot_dq(dq: DQ, scale: float = 0.1, line=None, plane=None, sphere=None, radius=None, color='r', alpha=0.8, ax=None)

Implementing the pyplot valid options of https://github.com/dqrobotics/matlab/blob/master/%40DQ/plot.m the particular plotting functions did not inherit from these implementations and are an informed attempt of using DQ operators to plot the objects.

Parameters:

  • dq – The input DQ.

  • scale – If not None, defines the size of the frame.

  • line – If not None, draw the input DQ as a line.

  • plane – If not None, draw the input DQ as a plane.

  • sphere – If not None, draw the input DQ as a sphere.

  • color – Define the color of the frame, line, or plane.

  • alpha – Define the alpha of the plane.

  • ax – Figure Axes or plt.gca() if None.

pyplot._pyplot._plot_plane(pi_dq, length_x: float, length_y: float, color, alpha: float, ax=None)

Draw a plane representing the DQ pi_dq. In this plot, the normal will be represented by the local z-axis of the plane and the plane will span in its local x-y axis.

Parameters:

  • pi_dq – The DQ representation of the plane.

  • length_x – The desired x-axis length.

  • length_y – The desired y-axis length.

  • color – Define the color of the plane.

  • alpha – Define the alpha of the plane.

  • ax – Figure Axes or plt.gca() if None.

Raises:

RuntimeError – If argument x is not a plane.

pyplot._pyplot._plot_serial_manipulator(robot: dqrobotics.robot_modeling.DQ_SerialManipulator, q: numpy.ndarray, line_color: str = 'k', line_width=3, cylinder_color: str = 'b', cylinder_alpha: float = 0.8, cylinder_radius: float = 0.02, cylinder_height: float = 0.07, ax=None)

Draw a serial manipulator at a given joint configuration q. Each joint transformation will be connected by a line with spec line_color and width linewidth.

Parameters:

  • robot – A concrete subclass of DQ_SerialManipulator.

  • q – The joint configurations.

  • line_color – A suitable color for the line.

  • line_width – The width is compatible with matplotlib.

  • cylinder_color – A suitable color for the cylinder.

  • cylinder_alpha – The alpha of the cylinder.

  • ax – Figure Axes or plt.gca() if None.

pyplot._pyplot._plot_pose(x: DQ, length: float = 0.1, ax=None)

Draw a reference frame at a given pose x.

Parameters:

  • x – the pose as a unit DQ.

  • length – the length of each axis’ line. Has a default value.

  • ax – Figure Axes or plt.gca() if None.

Raises:

RuntimeError – If argument x is not a unit dual quaternion.

pyplot._pyplot._plot_line(l_dq: DQ, color: str = 'r', length: float = 10.0, ax=None)

Draw a line representing the DQ l_dq.

Parameters:

  • l_dq – the DQ representation of the line.

  • color – the color.

  • length – the length.

  • ax – Figure Axes or plt.gca() if None.

Raises:

RuntimeError – If argument x is not a line.

pyplot._pyplot._plot_sphere(p: DQ, radius: float, color='b', alpha: float = 0.8, ax=None)

Draw a sphere of a given radius centered at p, where p is a pure quaternion.

See: https://stackoverflow.com/questions/64656951/plotting-spheres-of-radius-r.

Parameters:

  • p – the DQ representing the centre of the sphere.

  • radius – the radius of the sphere.

  • color – the color of the sphere.

  • alpha – the transparency of the sphere.

  • ax – Figure Axes or plt.gca() if None.

Raises:

RuntimeError: If p is not a pure quaternion.

pyplot._pyplot.__plot_revolute_joint(x, height_z, radius, color, alpha, ax=None)

This internal function is used to draw cylinders, for now, for DQ_SerialManipulators. The cylinder’s height is through its z-axis, and it spans from -height_z/2 to +height_z/2.

Parameters:

  • x – the pose as a DQ.

  • height_z – the height of the cylinder.

  • radius – the radius of the cylinder.

  • color – the color of the cylinder.

  • alpha – the transparency of the cylinder.

  • ax – Figure Axes or plt.gca() if None.

pyplot._pyplot.__dq_adjoint(x: DQ, t: DQ)

This internal function currently does not seem to exist in the implementation of dqrobotics. It will be replaced when it’s available. I’m basing this on (25) of https://faculty.sites.iastate.edu/jia/files/inline-files/dual-quaternion.pdf.

Parameters:

  • x – A unit dual quaternion.

  • t – A pure quaternion representing the point to be transformed.

Returns:

A pure quaternion of representing the transformed point.

Raises:

RuntimeError – If argument x is not a unit dual quaternion, or if t is not a pure quaternion.

pyplot._pyplot.__dq_adjoint_grid(x: DQ, x_grid, y_grid, z_grid)

This internal function runs __dq_adjoint through all elements of a grid so that calculations are simplified. For instance, to move a cylinder or other surface around a plot.

Parameters:

  • x – A unit dual quaternion.

  • x_grid – A suitable x-axis grid element.

  • y_grid – A suitable y-axis grid element.

  • z_grid – A suitable z-axis grid element.

Returns:

The transformed grids by x.

Raises:

RuntimeError – If argument grids have different shapes.

pyplot._pyplot.__plot_cylinder(x, height_z: float, radius: float, color: str, alpha: float, ax=None)

Internal method to draw a cylinder. x is a unit dual quaternion that defines the centre of the cylinder. The cylinder will span from -height_z/2 to +height_z/2. Use param_dict to define anything to be passed on to plot_surface.

Parameters:

  • x – a unit dual quaternion representing the pose of the centre of the cylinder.

  • height_z – the height of the cylinder.

  • radius – the radius of the cylinder.

  • color – the color of the cylinder.

  • alpha – the transparency of the cylinder.

  • ax – Figure Axes or plt.gca() if None.

Raises:

RuntimeError – If argument x is not a unit dual quaternion.