The condynsate Package

Classes

The Simulator Class

class condynsate.Simulator(keyboard=True, visualization=True, visualization_fr=24.0, animation=True, animation_fr=8.0, gravity=[0.0, 0.0, -9.81], dt=0.01)

Simulator manages the PyBullet based simulation of dynamic objects. It also provides wrappers for the Animator, Keys, and Visualizer classes so that the average condynsate project need only interact with the simulator class.

Parameters:

  • keyboard (bool, optional) – A boolean flag that indicates whether the simulator will allow the use of keyboard interactivity. The default is True.

  • visualization (bool, optional) – A boolean flag that indicates whether the simulation will be visualized in meshcat. The default is True.

  • visualization_fr (float, optional) – The frame rate (frames per second) at which the visualizer is updated. The default is 24.0.

  • animation (bool, optional) – A boolean flag that indicates whether animated plots are created in real time. The default is True.

  • animation_fr (float, optional) – The frame rate (frames per second) at which the animated plots are updated. The default is 8.0.

  • gravity (array-like, shape (3,) optional) – The gravity vectory in m/s^2. The default is [0., 0., -9.81].

  • dt (float, optional) – The fixed time step of the simulator in seconds. The default is 0.01 seconds.

Adjusting the Physics Engine

Simulator.set_gravity(gravity)

Sets the acceleration due to gravity vector.

Parameters:

gravity (array-like, shape (3,)) – The acceleration due to gravity vector in m/s^2.

Return type:

None.

Loading URDF Objects in Phyics Engine

Simulator.load_urdf(urdf_path, tex_path=None, position=[0.0, 0.0, 0.0], wxyz_quaternion=[1.0, 0.0, 0.0, 0.0], roll=None, pitch=None, yaw=None, velocity=[0.0, 0.0, 0.0], ang_velocity=[0.0, 0.0, 0.0], body_coords=False, fixed=False, update_vis=True)

Loads a URDF to the simulation engine. All joint’s velocity control is disabled (this allows the joint to move freely), angular and linear damping is set to 0 (eliminates air resistance), and joint dampling is set to 0 (eliminates joint friction).

Parameters:

  • urdf_path (string) – The path to the .urdf file that describes the urdf to be loaded into the simulation.

  • tex_path (string, optional) – The path pointing towards a texture file. This texture is applied only to static .obj objects. The default is None which loads ‘./examples/cmg_vis/check.png’.

  • position (array-like, shape (3,) optional) – The initial position of the urdf. The default is [0., 0., 0.].

  • wxyz_quaternion (array-like, shape (4,) optional) – A wxyz quaternion that describes the intial orientation of the urdf. When roll, pitch, and yaw all have None type, the quaternion is used. If any roll, pitch, or yaw have non None type, the quaternion is ignored. The default is [1., 0., 0., 0.].

  • roll (float, optional) – The initial roll angle of the urdf. The default is None.

  • pitch (float, optional) – The initial pitch angle of the urdf. The default is None.

  • yaw (float, optional) – The initial yaw angle of the urdf. The default is None.

  • velocity (array-like, shape (3,)) – The velocity to be set in either world or body coords. The default is [0., 0., 0.].

  • ang_velocity (array-like, shape (3,)) – The angular velocity to be set in either world or body coords. The default is [0., 0., 0.].

  • body_coords (bool) – A boolean flag that indicates whether the passed velocities are in world coords or body coords. The default is False.

  • fixed (bool, optional) – A boolean flag that indicates whether the base joint of the loaded urdf is fixed. The default is False.

  • update_vis (bool, optional) – A boolean flag that indicates whether this urdf will be updated by the Visualizer each time step. The default is True.

Returns:

urdf_obj – A URDF_Obj that describes the urdf that was loaded into the simulation.

Return type:

URDF_Obj

Running a Simulation

Simulator.step(real_time=True, update_vis=True, max_time=None)

Takes a single step of the simulation. In this step, the physics engine, the Visualizer (3D visualization of urdfs), and the Animator (2D animation of plots) are all updated.

Parameters:

  • real_time (bool, optional) – A boolean flag that indicates whether or not the step is taken in real time. If True, step() is suspended until the time since the last step is equal to dt seconds (the time step of the physics engine). If False, step() is run as quickly as possible. The default is True.

  • update_vis (bool, optional) – A boolean flag that indicates whether the Visualizer is updated. The default is True.

  • max_time (float or None, optional) – The maximum amount of simulated seconds the simulator is allowed to run. If None, the simulation will run until “ESC” is pressed. If None and there is no keyboard interactivity, max time is set to 10.0 seconds.

Returns:

ret_code – The return code of the simulation steps. The codes are as follows:

-4: Keyboard LOS indicating simulation step failure. No simulation step taken. No further simulation steps are to be taken. is_done flag is now true.

-3: User initiated simulation termination. No simulation step taken. No further simulation steps are to be taken. is_done flag is now true.

-2: User initiated pause is occuring. No simulation step taken. paused flag remains true.

-1: User initiated pause has ended. No simulation step taken. paused flag is now false.

0: User initiated simulation reset. No simulation step taken.

1: Normal and successful simulation step.

2: User initiated pause has started. Normal simulation step taken. paused flag is now true.

3: max_time is now reached. Normal simulation step taken. No further simulation steps are to be taken. is_done flag is now true.

Return type:

int

Simulator.reset()

Reset the physics state to the initial conditions. Reset the visualizer to the initial conditions. Reset the animator to the initial conditions

Return type:

None.

Interacting with URDF Objects in the Physics Engine

Adjusting a URDF’s Joint’s Parameters
Simulator.set_joint_force_sensor(urdf_obj, joint_name, enable_sensor)

Enables reaction force, moment, and applied torque to be calculated for a joint.

Parameters:

  • urdf_obj (URDF_Obj) – A URDF_Obj that contains that joint for which the sensor is set.

  • joint_name (string) – The name of the joint whose sensor is set.

  • enable_sensor (bool) – A boolean flag that indicates whether to enable or disable the force sensor.

Return type:

None.

Simulator.set_joint_lin_ang_damp(urdf_obj, joint_name, linear_damping=0.0, angular_damping=0.0)

Allows user to set the linear and angular damping of a joint. Linear and angular damping is a way to model drag. It is typically reccomended that the user set these values to 0 for all joints.

Parameters:

  • urdf_obj (URDF_Obj) – A URDF_Obj that contains that joint whose linear and angular damping is being set.

  • joint_name (string) – The name of the joint whose linear and angular damping is set. The joint name is specified in the .urdf file.

  • linear_damping (float, optional) – The value of linear damping to apply. The default is 0..

  • angular_damping (float, optional) – The value of angular damping to apply. The default is 0..

Return type:

None.

Simulator.set_joint_damping(urdf_obj, joint_name, damping=0.0)

Sets the damping of a joint in a urdf. The damping of a joint defines the energy loss incurred during movement of the joint. It is a way to model joint friction.

Parameters:

  • urdf_obj (URDF_Obj) – A URDF_Obj that contains that joint whose damping is being set.

  • joint_name (string) – The name of the joint whose damping is set. The joint name is specified in the .urdf file.

  • damping (float, optional) – The value of damping to apply. The default is 0..

Return type:

None.

Simulator.set_joint_friction_params(urdf_obj, joint_name, lateral_friction=0.0, spinning_friction=0.0, rolling_friction=0.0)

Sets a joint’s friction parameters. These parameters determine the friction characteristics between 2 joints.

Parameters:

  • urdf_obj (URDF_Obj) – A URDF_Obj that contains that joint whose friction is being set.

  • joint_name (string) – The name of the joint whose friction is set. The joint name is specified in the .urdf file.

  • lateral_friction (float, optional) – The lateral friction applied to the joint. The default is 0.0.

  • spinning_friction (float, optional) – The spinning friction applied to the joint. The default is 0.0.

  • rolling_friction (float, optional) – The rolling friction applied to the joint. The default is 0.0.

Return type:

None.

Simulator.set_joint_contact_params(urdf_obj, joint_name, restitution=0.0, contact_damping=0.0, contact_stiffness=0.0)

Sets a joint’s contact parameters. These parameters determine the energy transfer between two joints in contact.

Parameters:

  • urdf_obj (URDF_Obj) – A URDF_Obj that contains that joint whose contact params are being set.

  • joint_name (string) – The name of the joint whose contact params are set. The joint name is specified in the .urdf file.

  • restitution (float, optional) – The restitution applied to the joint. The default is 0.0.

  • contact_damping (float, optional) – The contact damping friction applied to the joint. The default is 0.0.

  • contact_stiffness (float, optional) – The contact stiffness applied to the joint. The default is 0.0.

Return type:

None.

Setting and Reading a URDF’s Joint’s State
Simulator.set_joint_position(urdf_obj, joint_name, position=0.0, physics=False, initial_cond=False, color=False, min_pos=None, max_pos=None)

Sets the position of a joint of a urdf.

Parameters:

  • urdf_obj (URDF_Obj) – A URDF_Obj that contains that joint whose position is being set.

  • joint_name (string) – The name of the joint whose position is set. The joint name is specified in the .urdf file.

  • position (float, optional) – The position in rad to be applied to the joint. The default is 0..

  • physics (bool, optional) – A boolean flag that indicates whether physics based poisiton controller will be used to change joint position or whether the joint position will be reset immediately to the target position with zero end velocity. The default is False.

  • initial_cond (bool, optional) – A boolean flag that indicates whether the position set is an initial condition of the system. If it is an initial condition, when the simulation is reset using backspace, the joint position will be set again.

  • color (bool, optional) – A boolean flag that indicates whether to color the joint based on its position. The default is False.

  • min_pos (float) – The minimum possible position. Used only for coloring. Value is ignored if color is False. The default is None. Must be set to a float value for coloring to be applied.

  • max_pos (float) – The maximum possible position. Used only for coloring. Value is ignored if color is False. The default is None. Must be set to a float value for coloring to be applied.

Return type:

None.

Simulator.set_joint_velocity(urdf_obj, joint_name, velocity=0.0, physics=False, initial_cond=False, color=False, min_vel=-100.0, max_vel=100.0)

Sets the velocity of a joint of a urdf.

Parameters:

  • urdf_obj (URDF_Obj) – A URDF_Obj that contains that joint whose velocity is being set.

  • joint_name (string) – The name of the joint whose velocity is set. The joint name is specified in the .urdf file.

  • velocity (float, optional) – The velocity in rad/s to be applied to the joint. The default is 0..

  • physics (bool, optional) – A boolean flag that indicates whether physics based velocity controller will be used to change joint velocity or whether the joint velocity will be reset immediately to the target velocity. The default is False.

  • initial_cond (bool, optional) – A boolean flag that indicates whether the velocity set is an initial condition of the system. If it is an initial condition, when the simulation is reset using backspace, the joint velocity will be set again.

  • color (bool, optional) – A boolean flag that indicates whether to color the joint based on its velocity. The default is False.

  • min_vel (float) – The minimum possible velocity. Used only for coloring. Value is ignored if color is False. The default is -100..

  • max_vel (float) – The maximum possible velocity. Used only for coloring. Value is ignored if color is False. The default is 100..

Return type:

None.

Simulator.get_joint_state(urdf_obj, joint_name)

Gets the state of a joint (angle and velocity for continuous joints).

Parameters:

  • urdf_obj (URDF_Obj) – A URDF_Obj whose joint state is being measured.

  • joint_name (string) – The name of the joint whose state is measured. The joint name is specified in the .urdf file.

Returns:

state –

‘position’float

The position value of this joint.

’velocity’float

The velocity value of this joint.

’reaction force’list shape(3,)

These are the joint reaction forces. Only read if a torque sensor is enabled for this joint.

’reaction torque’list shape(3,)

These are the joint reaction torques. Only read if a torque sensor is enabled for this joint.

’applied torque’float

This is the motor torque applied during the last stepSimulation. Note that this only applies in VELOCITY_CONTROL and POSITION_CONTROL. If you use TORQUE_CONTROL then the applied joint motor torque is exactly what you provide, so there is no need to report it separately.

Return type:

dictionary with the following keys

Simulator.get_joint_axis(urdf_obj, joint_name)

Get the joint axis in the world frame.

Parameters:

  • urdf_obj (URDF_Obj) – A URDF_Obj that contains that joint whose axis is found.

  • joint_name (string) – The name of the joint axis is returned.

Returns:

  • axis_inW (array-like, shape(3,)) – The joint axis in world frame.

  • pos_inW (array-like, shape(3,)) – The (x,y,z) coords of the center of the child link in world coords.

  • link_name (string) – The name of the child link of the joint.

Applying Forces and Torques to a URDF
Simulator.set_joint_torque(urdf_obj, joint_name, torque=0.0, show_arrow=False, arrow_scale=0.1, arrow_offset=0.0, color=False, min_torque=-1.0, max_torque=1.0)

Sets the torque of a joint of a urdf.

Parameters:

  • urdf_obj (URDF_Obj) – A URDF_Obj that contains that joint whose torque is being set.

  • joint_name (string) – The name of the joint whose torque is set. The joint name is specified in the .urdf file

  • torque (float, optional) – The torque in NM to be applied to the joint. The default is 0..

  • show_arrow (bool, optional) – A boolean flag that indicates whether an arrow will be rendered on the link to visualize the applied torque. The default is False.

  • arrow_scale (float, optional) – The scaling factor that determines the size of the arrow. The default is 0.1.

  • arrow_offset (float, optional) – The amount to offset the drawn arrow along the joint axis. The default is 0.0.

  • color (bool, optional) – A boolean flag that indicates whether the child link will be colored based on the applied torque. The default is False.

  • min_torque (float, optional) – The minimum value of torque that can be applied. Used for link coloring. Does nothing if color is not enabled. The default is -1..

  • max_torque (float, optional) – The maximum value of torque that can be applied. Used for link coloring. Does nothing if color is not enabled. The default is 1..

Return type:

None.

Applies an external force the to center of a specified link of a urdf.

Parameters:

  • urdf_obj (URDF_Obj) – A URDF_Obj that contains that link to which the force is applied.

  • link_name (string) – The name of the link to which the force is applied. The link name is specified in the .urdf file.

  • force (array-like, shape (3,)) – The force vector in either world or link coordinates to apply to the link.

  • link_coords (bool, optional) – A boolean flag that indicates whether force is given in link coords (True) or world coords (False). The default is False.

  • show_arrow (bool, optional) – A boolean flag that indicates whether an arrow will be rendered on the link to visualize the applied force. The default is False.

  • arrow_scale (float, optional) – The scaling factor that determines the size of the arrow. The default is 0.4.

  • arrow_offset (float, optional) – The amount by which the drawn force arrow will be offset from the center of mass along the direction of the applied force. The default is 0.0.

Return type:

None.

Simulator.apply_force_to_com(urdf_obj, force, body_coords=False, show_arrow=False, arrow_scale=0.4, arrow_offset=0.0)

Applies an external force to the center of mass of the body.

Parameters:

  • urdf_obj (URDF_Obj) – A URDF_Obj to which the force is applied.

  • force (array-like, shape (3,)) – The force vector in either world or body coordinates to apply to the body.

  • body_coords (bool, optional) – A boolean flag that indicates whether force is given in body coords (True) or world coords (False). The default is False.

  • show_arrow (bool, optional) – A boolean flag that indicates whether an arrow will be rendered on the com to visualize the applied force. The default is False.

  • arrow_scale (float, optional) – The scaling factor that determines the size of the arrow. The default is 0.4.

  • arrow_offset (float, optional) – The amount by which the drawn force arrow will be offset from the center of mass along the direction of the applied force. The default is 0.0.

Return type:

None.

Simulator.apply_external_torque(urdf_obj, torque, body_coords=False, show_arrow=False, arrow_scale=0.1, arrow_offset=0.0)

Applies an external torque to the center of mass of the body.

Parameters:

  • urdf_obj (URDF_Obj) – A URDF_Obj to which the torque is applied.

  • torque (array-like, shape(3,)) – The torque vector in world coordinates to apply to the body.

  • show_arrow (bool, optional) – A boolean flag that indicates whether an arrow will be rendered on the com to visualize the applied torque. The default is False.

  • arrow_scale (float, optional) – The scaling factor that determines the size of the arrow. The default is 0.1.

  • arrow_offset (float, optional) – The amount by which the drawn torque arrow will be offset from the center of mass along the direction of the applied torque. The default is 0.0.

Return type:

None.

Getting the Center of Mass of a URDF
Simulator.get_center_of_mass(urdf_obj)

Get the center of mass of a body .

Parameters:

urdf_obj (URDF_Obj) – A URDF_Obj whose center of mass is calculated.

Returns:

com – The cartesian coordinates of the center of mass of the body in world coordinates.

Return type:

array-like, shape(3,)

Using the Visualizer

Loading URDF Objects in the Visualizer
Simulator.add_urdf_to_visualizer(urdf_obj, tex_path=None)

Adds urdfs to the Visualizer. URDFs describe systems assembles from .stl and .obj links.

Parameters:

  • vis (Visualizer) – The Visualizer to which the urdf is added.

  • urdf_obj (URDF_Obj) – A URDF_Obj that will be added to the Visualizer.

  • tex_path (string, optional) – The path pointing towards a texture file. This texture is applied to all .obj links in the urdf.

Return type:

None.

Adjusting Appearance of URDF Objects

Allows the user to change the color, transparency, and opacity of an existing urdf in the simulation. The position and orientation are not altered.

Parameters:

  • urdf_obj (URDF_Obj) – A URDF_Obj that contains that link whose color is being updated.

  • link_name (string) – The name of the link whose color is being updated. The link name is specified in the .urdf file.

  • color (array-like, size (3,), optional) – The 0-255 RGB color of the link. The default is [91, 155, 213].

  • transparent (boolean, optional) – A boolean that indicates if the link is transparent. The default is False.

  • opacity (float, optional) – The opacity of the link. Can take float values between 0.0 and 1.0. The default is 1.0.

Return type:

None.

Simulator.set_color_from_pos(urdf_obj, joint_name, min_pos, max_pos)

Sets the color of the child link of a specified joint based on the position of the joint.

Parameters:

  • urdf_obj (URDF_Obj) – A URDF_Obj that contains that joint whose position is measured.

  • joint_name (string) – The name of the joint whose position is used to set the link color. The joint name is specified in the .urdf file.

  • min_pos (float) – The minimum possible position of the given joint.

  • max_pos (float) – The maximum possible position of the given joint.

Return type:

None.

Simulator.set_color_from_vel(urdf_obj, joint_name, min_vel=-100.0, max_vel=100.0)

Sets the color of the child link of a specified joint based on the velocity of the joint.

Parameters:

  • urdf_obj (URDF_Obj) – A URDF_Obj that contains that joint whose velocity is measured.

  • joint_name (string) – The name of the joint whose velocity is used to set the link color. The joint name is specified in the .urdf file.

  • min_vel (float, optional) – The minimum possible velocity of the given joint. The default is -100.. Unless otherwise set, PyBullet does not allow joint velocities to exceed a magnitude of 100.

  • max_vel (float, optional) – The maximum possible velocity of the given joint. The default is 100.. Unless otherwise set, PyBullet does not allow joint velocities to exceed a magnitude of 100.

Return type:

None.

Simulator.set_color_from_torque(urdf_obj, joint_name, torque, min_torque=-1.0, max_torque=1.0)

Sets the color of the child link of a specified joint based on the torque applied to the joint.

Parameters:

  • urdf_obj (URDF_Obj) – A URDF_Obj that contains that joint whose torque is measured.

  • joint_name (string) – The name of the joint whose torque is used to set the link color. The joint name is specified in the .urdf file.

  • torque (float) – The torque applied to the joint.

  • min_torque (float, optional) – The minimum possible torque to apply to the joint. The default is -1..

  • max_torque (float, optional) –

    The maximum possible torque to apply to the joint. The default is

    1..

Return type:

None.

Simulator.set_color_from_mass(urdf_obj, link_name, min_mass, max_mass)

Sets the color of a link based on its mass.

Parameters:

  • urdf_obj (URDF_Obj) – A URDF_Obj that contains that joint whose torque is measured.

  • link_name (string) – The name of the link whose mass is used to set the link color. The link name is specified in the .urdf file.

  • min_mass (float, optional) – The minimum possible mass of the link.

  • max_mass (float, optional) – The maximum possible mass of the link.

Return type:

None.

Manipulating the Visualizer
Simulator.transform_camera(scale=[1.0, 1.0, 1.0], translate=[0.0, 0.0, 0.0], wxyz_quaternion=[1.0, 0.0, 0.0, 0.0], roll=None, pitch=None, yaw=None)

Transforms the position, orientation, and scale of the Visualizer’s camera.

Parameters:

  • scale (array-like, size (3,), optional) – The scaling of the camera view about the camera point along the three axes. The default is [1., 1., 1.].

  • translate (array-like, size (3,), optional) – The translation of the camera point along the three axes. The default is [0., 0., 0.].

  • wxyz_quaternion (array-like, shape (4,) optional) – A wxyz quaternion that describes the intial orientation of camera about the camera point. When roll, pitch, and yaw all have None type, the quaternion is used. If any roll, pitch, or yaw have non None type, the quaternion is ignored. The default is [1., 0., 0., 0.].

  • roll (float, optional) – The roll of the camera about the camera point. The default is None.

  • pitch (float, optional) – The pitch of the camera about the camera point. The default is None.

  • yaw (float, optional) – The yaw of the camera about the camera point. The default is None.

Return type:

None.

Simulator.set_background(top_color=None, bot_color=None)

Set the top and bottom colors of the background of the Visualizer.

Parameters:

  • top_color (array-like, shape (3,), optional) – The 0-255 color to apply to the top of the background. The default is None. If top_color is set to None, top_color is not altered.

  • bot_color (array-like, shape (3,), optional) – The 0-255 color to apply to the bottom of the background. The default is None. If bot_color is set to None, bot_color is not altered.

Return type:

None.

Simulator.set_spotlight(on=False, intensity=1.0, distance=100.0)

Sets the properties of the spotlight in the Visualizer.

Parameters:

  • on (bool, optional) – A boolean flag that indicates whether the spotlight is on. The default is False.

  • intensity (float (0. to 20.), optional) – The brightness of the spotlight. The default is 1.0.

  • distance (float (0. to 100.), optional) – The distance from the origin of the spotlight. The default is 100..

Return type:

None.

Simulator.set_posx_pt_light(on=False, intensity=1.0, distance=100.0)

Sets the properties of the point light on the positive x axis in the Visualizer.

Parameters:

  • on (bool, optional) – A boolean flag that indicates whether the light is on. The default is False.

  • intensity (float (0. to 20.), optional) – The brightness of the light. The default is 1.0.

  • distance (float (0. to 100.), optional) – The distance from the origin of the light. The default is 100..

Return type:

None.

Simulator.set_negx_pt_light(on=False, intensity=1.0, distance=100.0)

Sets the properties of the point light on the negative x axis in the Visualizer.

Parameters:

  • on (bool, optional) – A boolean flag that indicates whether the light is on. The default is False.

  • intensity (float (0. to 20.), optional) – The brightness of the light. The default is 1.0.

  • distance (float (0. to 100.), optional) – The distance from the origin of the light. The default is 100..

Return type:

None.

Simulator.set_ambient_light(on=False, intensity=1.0)

Sets the properties of the ambient light of the Visualizer.

Parameters:

  • on (bool, optional) – A boolean flag that indicates whether the light is on. The default is False.

  • intensity (float (0. to 20.), optional) – The brightness of the light. The default is 1.0.

Return type:

None.

Simulator.set_fill_light(on=False, intensity=1.0)

Sets the properties of the fill light in the Visualizer.

Parameters:

  • on (bool, optional) – A boolean flag that indicates whether the light is on. The default is False.

  • intensity (float (0. to 20.), optional) – The brightness of the light. The default is 1.0.

Return type:

None.

Using the Animator

Simulator.add_plot(n_artists=1, plot_type='line', title=None, x_label=None, y_label=None, x_lim=[None, None], y_lim=[None, None], h_zero_line=False, v_zero_line=False, color='black', label=None, line_width=1.5, line_style='solid', tail=-1)

Adds a plot to the animator. This function needs to be called to define a plot before data can be added to that plot. If called after start_animator, this function will do nothing.

Parameters:

  • n_artists (int, optional) – The number of artists that draw on the plot The default is 1.

  • plot_type (either 'line' or 'bar', optional) – The type of plot. May either be ‘line’ or ‘bar’. The default is ‘line’.

  • title (string, optional) – The title of the plot. Will be written above the plot when rendered. The default is None.

  • x_label (string, optional) – The label to apply to the x axis. Will be written under the plot when rendered. The default is None.

  • y_label (string, optional) – The label to apply to the y axis. Will be written to the left of the plot when rendered. The default is None.

  • x_lim ([float, float], optional) – The limits to apply to the x axis of the plot. A value of None will apply automatically updating limits to the corresponding bound of the axis. For example [None, 10.] will fix the upper bound to exactly 10, but the lower bound will freely change to show all data.The default is [None, None].

  • y_lim ([float, float], optional) – The limits to apply to the y axis of the plot. A value of None will apply automatically updating limits to the corresponding bound of the axis. For example [None, 10.] will fix the upper bound to exactly 10, but the lower bound will freely change to show all data.The default is [None, None].

  • h_zero_line (boolean, optional) – A boolean flag that indicates whether a horizontal line will be drawn on the y=0 line. The default is false

  • v_zero_line (boolean, optional) – A boolean flag that indicates whether a vertical line will be drawn on the x=0 line. The default is false

  • color (matplotlib color string or tuple of color strings, optional) – The color each artist draws in. When tuple, must have length n_artists. The default is ‘black’.

  • label (string or tuple of strings, optional) – The label applied to each artist. For line charts, the labels are shown in a legend in the top right of the plot. For bar charts, the labels are shown on the y axis next to their corresponging bars. When tuple, must have length n_artists. When None, no labels are made. The default is None.

  • line_width (float or tuple of floats, optional) – The line weigth each artist uses. For line plots, this is the width of the plotted line, for bar charts, this is the width of the border around each bar. When tuple, must have length n_artists. The default is 1.5.

  • line_style (line style string or tuple of ls strings, optional) – The line style each artist uses. For line plots, this is the style of the plotted line, for bar charts, this argument is not used and therefore ignored. When tuple, must have length n_artists. The default is ‘solid’.

  • tail (int or tuple of ints optional) – Specifies how many data points are used to draw a line. Only the most recently added data points are kept. Any data points added more than tail data points ago are discarded and not plotted. Only valid for line plots. When tuple, must have length n_artists. A value less than or equal to 0 means that no data is ever discarded and all data points added to the animator will be drawn. The default is -1.

Raises:

TypeError – At least one of the arguments color, label, line_width, line_style, or tail is not parasble to all artists.

Returns:

  • plot_id (int) – A integer identifier that is unique to the plot created. This allows future interaction with this plot (adding data points, etc.).

  • artist_ids (tuple of ints, optional) – A tuple of integer identifiers that are unique to the artist created. This allows future interaction with these artists (adding data points, etc.). Is only returned when n_artists > 1.

Simulator.start_animator()

Opens the Animator GUI with the specified plots. After the Animator is open, no more plots can be added; however, the plot data can still be set.

Return type:

None.

Simulator.add_line_datum(plot_id, x, y, artist_id=0)

Adds a single data point to the plot. Data point is appended to the end of all previously plotted data points on the specified line.

Parameters:

  • plot_id (int) – The plot’s unique identifier.

  • x (float) – The x value of the data point added to the plot.

  • y (float) – The y value of the data point added to the plot.

  • artist_id (int, optional) – The plot’s artist index to which the data is added. If plot only has a single artist, is ignored. The default value is 0.

Return type:

None.

Simulator.set_bar_value(plot_id, value, artist_id=0)

Sets the value of one of the bars in a bar plot.

Parameters:

  • plot_id (int) – The plot’s unique identifier.

  • value (float) – The value to which the bar is being set.

  • artist_id (int, optional) – The plot’s artist index whose value is being set. The default is 0.

Return type:

None.

Simulator.reset_animator()

Removes all previously plotted data from all plots.

Return type:

None.

Simulator.terminate_animator()

Terminates the animator window.

Return type:

None.

Using the Keyboard

Simulator.is_pressed(key)

Wrapper for the keyboard.Keys.is_pressed() function. Returns a boolean flag to indicate whether a desired key is pressed. The key may be alpha numeric or some special keys.

Parameters:

key (string) – The key to be detected. May be alpha numeric (“a”, “A”, “1”, “!”, “`”, etc.) or some special keys. The special keys are as follows: “space”, “enter”, “backspace”, “tab”, “shift”, “alt”, “ctrl”, and “esc”. The following modifiers can also be used: “shift+”, “alt+”, and “ctrl+”. Modifiers are added with the following format: “shift+a”, “ctrl+a”, “alt+a”, “shift+ctrl+alt+a”, etc. If “esc” is pressed, the keyboard listener will automatically stop and cannot be restarted.

Returns:

A boolean flag to indicate whether the desired key is pressed. If the keyboard is disabled, always returns False.

Return type:

bool

Simulator.await_keypress(key='enter')

Waits until a specified keystroke is recieved. When an Animator GUI is open, this function must be called to keep the GUI responsive. If a GUI is not present, this function is optional.

Parameters:

key (string, optional) – The key string identifier. The default is “enter”.

Return type:

None.

Simulator.iterate_val(curr_val, down_key, up_key, iter_val=0.0333, min_val=-inf, max_val=inf)

Iterates a current value by some amount every time this function is called according to which keys are pressed. If no keys are pressed, no iteration occurs. If the down key is pressed, decrement the value. If the up key is pressed, increment the value. If both the up and down keys are pressed, do nothing. The iterated value is clipped between [min_val and max_val].

Parameters:

  • curr_val (numeric value) – The current value which will be incremented or decremented.

  • down_key (string) – A Keyboard string that specifies what must be depressed for decrementation to occur.

  • up_key (string) – A Keyboard string that specifies what must be depressed for incrementation to occur.

  • iter_val (numeric value, optional) – The value by which the current value is either incremented or decremented. The default is 0.0333.

  • min_val (numeric value, optional) – The minimum possible value that can be returned. The default is -np.inf.

  • max_val (numeric value, optional) – The maximum possible value that can be returned. The default is np.inf.

Returns:

new_val – The iterated value.

Return type:

numeric value

The Animator Class

class condynsate.Animator(fr=8.0)

Animator manages the real time plotting in QT GUI.

Parameters:

fr (float, optional) – The frame rate (frames per second) at which the animated plots are updated. The default is 8.0.

The Animation Sequence

Animator.add_plot(n_artists=1, plot_type='line', title=None, x_label=None, y_label=None, x_lim=[None, None], y_lim=[None, None], h_zero_line=False, v_zero_line=False, color='black', label=None, line_width=1.5, line_style='solid', tail=-1)

Adds a plot to the animator. This function needs to be called to define a plot before data can be added to that plot. If called after start_animator, this function will do nothing.

Parameters:

  • n_artists (int, optional) – The number of artists that draw on the plot The default is 1.

  • plot_type (either 'line' or 'bar', optional) – The type of plot. May either be ‘line’ or ‘bar’. The default is ‘line’.

  • title (string, optional) – The title of the plot. Will be written above the plot when rendered. The default is None.

  • x_label (string, optional) – The label to apply to the x axis. Will be written under the plot when rendered. The default is None.

  • y_label (string, optional) – The label to apply to the y axis. Will be written to the left of the plot when rendered. The default is None.

  • x_lim ([float, float], optional) – The limits to apply to the x axis of the plot. A value of None will apply automatically updating limits to the corresponding bound of the axis. For example [None, 10.] will fix the upper bound to exactly 10, but the lower bound will freely change to show all data.The default is [None, None].

  • y_lim ([float, float], optional) – The limits to apply to the y axis of the plot. A value of None will apply automatically updating limits to the corresponding bound of the axis. For example [None, 10.] will fix the upper bound to exactly 10, but the lower bound will freely change to show all data.The default is [None, None].

  • h_zero_line (boolean, optional) – A boolean flag that indicates whether a horizontal line will be drawn on the y=0 line. The default is false

  • v_zero_line (boolean, optional) – A boolean flag that indicates whether a vertical line will be drawn on the x=0 line. The default is false

  • color (matplotlib color string or tuple of color strings, optional) – The color each artist draws in. When tuple, must have length n_artists. The default is ‘black’.

  • label (string or tuple of strings, optional) – The label applied to each artist. For line charts, the labels are shown in a legend in the top right of the plot. For bar charts, the labels are shown on the y axis next to their corresponging bars. When tuple, must have length n_artists. When None, no labels are made. The default is None.

  • line_width (float or tuple of floats, optional) – The line weigth each artist uses. For line plots, this is the width of the plotted line, for bar charts, this is the width of the border around each bar. When tuple, must have length n_artists. The default is 1.5.

  • line_style (line style string or tuple of ls strings, optional) – The line style each artist uses. For line plots, this is the style of the plotted line, for bar charts, this argument is not used and therefore ignored. When tuple, must have length n_artists. The default is ‘solid’.

  • tail (int or tuple of ints optional) – Specifies how many data points are used to draw a line. Only the most recently added data points are kept. Any data points added more than tail data points ago are discarded and not plotted. Only valid for line plots. When tuple, must have length n_artists. A value less than or equal to 0 means that no data is ever discarded and all data points added to the animator will be drawn. The default is -1.

Raises:

TypeError – At least one of the arguments color, label, line_width, line_style, or tail is not parasble to all artists.

Returns:

  • plot_id (int) – A integer identifier that is unique to the plot created. This allows future interaction with this plot (adding data points, etc.).

  • artist_ids (tuple of ints, optional) – A tuple of integer identifiers that are unique to the artist created. This allows future interaction with these artists (adding data points, etc.). Is only returned when n_artists > 1.

Animator.start_animator()

Builds and shows the animator GUI. Starts the GUI thread that runs until the terminate_animator function is called. Once start_animator is called, no more plots can be added.

Return type:

None.

Animator.add_line_datum(plot_id, x, y, artist_id=0)

Adds a single data point to the plot. Data point is appended to the end of all previously plotted data points on the specified line.

Parameters:

  • plot_id (int) – The plot’s unique identifier.

  • x (float) – The x value of the data point added to the plot.

  • y (float) – The y value of the data point added to the plot.

  • artist_id (int, optional) – The plot’s artist index to which the data is added. If plot only has a single artist, is ignored. The default value is 0.

Return type:

None.

Animator.set_bar_value(plot_id, value, artist_id=0)

Sets the value of one of the bars in a bar plot.

Parameters:

  • plot_id (int) – The plot’s unique identifier.

  • value (float) – The value to which the bar is being set.

  • artist_id (int, optional) – The plot’s artist index whose value is being set. The default is 0.

Return type:

None.

Animator.reset_animator()

Removes all previously plotted data from all plots.

Return type:

None.

Animator.terminate_animator()

Terminates the animator window.

Return type:

None.

The Keys Class

class condynsate.Keys

Keys detected keyboard events and stores key information. Used for polling key presses. Starts a new non-blocking thread that listens to the keyboard. Starts 2 new threads to detect script termination events.

is_pressed(key_str)

Returns a boolean flag to indicate whether a desired key is pressed. The key may be alpha numeric or some special keys.

Parameters:

key_str (string) –

The key to be detected. May be alpha numeric (“a”, “1”, “`”, etc.) or some special keys.

The special keys are as follows: “space”, “enter”, “backspace”, “tab”, “tab”, and “esc”.

The following modifiers can also be used: “shift+”, “alt+”, and “ctrl+”.

Modifiers are added with the following format: “shift+a”, “ctrl+a”, “alt+a”, “shift+ctrl+alt+a”, etc.

If “esc” is pressed, the keyboard listener will automatically stop and cannot be restarted.

Returns:

A boolean flag to indicate whether the desired key is pressed.

Return type:

bool

The Visualizer Class

class condynsate.Visualizer(grid_vis=True, axes_vis=True)

Visualizer manages the meshcat based visulation.

Parameters:

  • grid_vis (bool, optional) – The boolean value to which the visibility of the XY grid is set. The default is True.

  • axes_vis (bool, optional) – The boolean value to which the visibility of the axes is set. The default is True.

Adjusting the Appearance of the Viewer

Visualizer.set_grid(visible=True)

Controls the visibility state of the XY grid in the visualizer.

Parameters:

visible (bool, optional) – The boolean value to which the visibility of the XY grid is set. The default is True.

Return type:

None.

Visualizer.set_axes(visible=True)

Controls the visibility state of the axes in the visualizer.

Parameters:

visible (bool, optional) – The boolean value to which the visibility of the axes is set. The default is True.

Return type:

None.

Visualizer.set_background(top_color=None, bot_color=None)

Set the top and bottom colors of the background of the scene.

Parameters:

  • top_color (array-like, shape (3,), optional) – The 0-255 color to apply to the top of the background. The default is None. If top_color is set to None, top_color is not altered.

  • bot_color (array-like, shape (3,), optional) – The 0-255 color to apply to the bottom of the background. The default is None. If bot_color is set to None, bot_color is not altered.

Return type:

None.

Visualizer.set_spotlight(on=False, intensity=1.0, radius=0.0, distance=100.0)

Sets the properties of the spotlight in the scene.

Parameters:

  • on (bool, optional) – A boolean flag that indicates whether the light is on. The default is False.

  • intensity (float (0. to 20.), optional) – The brightness of the light. The default is 1.0.

  • distance (float (0. to 100.), optional) – The distance from the origin of the light. The default is 100..

Return type:

None.

Visualizer.set_posx_pt_light(on=False, intensity=1.0, distance=100.0)

Sets the properties of the point light on the positive x axis in the scene.

Parameters:

  • on (bool, optional) – A boolean flag that indicates whether the light is on. The default is False.

  • intensity (float (0. to 20.), optional) – The brightness of the light. The default is 1.0.

  • distance (float (0. to 100.), optional) – The distance from the origin of the light. The default is 100..

Return type:

None.

Visualizer.set_negx_pt_light(on=False, intensity=1.0, distance=100.0)

Sets the properties of the point light on the negative x axis in the scene.

Parameters:

  • on (bool, optional) – A boolean flag that indicates whether the light is on. The default is False.

  • intensity (float (0. to 20.), optional) – The brightness of the light. The default is 1.0.

  • distance (float (0. to 100.), optional) – The distance from the origin of the light. The default is 100..

Return type:

None.

Visualizer.set_ambient_light(on=False, intensity=1.0)

Sets the properties ambient light of the scene.

Parameters:

  • on (bool, optional) – A boolean flag that indicates whether the light is on. The default is False.

  • intensity (float (0. to 20.), optional) – The brightness of the light. The default is 1.0.

Return type:

None.

Visualizer.set_fill_light(on=False, intensity=1.0)

Sets the properties fill light of the scene.

Parameters:

  • on (bool, optional) – A boolean flag that indicates whether the light is on. The default is False.

  • intensity (float (0. to 20.), optional) – The brightness of the light. The default is 1.0.

Return type:

None.

Visualizer.transform_camera(scale=[1.0, 1.0, 1.0], translate=[0.0, 0.0, 0.0], wxyz_quaternion=[1.0, 0.0, 0.0, 0.0], roll=None, pitch=None, yaw=None)

Transforms the position, orientation, and scale of the camera in the scene.

Parameters:

  • scale (array-like, size (3,), optional) – The scaling of the camera view about the camera point along the three axes. The default is [1., 1., 1.].

  • translate (array-like, size (3,), optional) – The translation of the camera point along the three axes. The default is [0., 0., 0.].

  • wxyz_quaternion (array-like, shape (4,) optional) – A wxyz quaternion that describes the intial orientation of camera about the camera point. When roll, pitch, and yaw all have None type, the quaternion is used. If any roll, pitch, or yaw have non None type, the quaternion is ignored. The default is [1., 0., 0., 0.].

  • roll (float, optional) – The roll of the camera about the camera point. The default is None.

  • pitch (float, optional) – The pitch of the camera about the camera point. The default is None.

  • yaw (float, optional) – The yaw of the camera about the camera point. The default is None.

Return type:

None.

Adding Elements to the Viewer

Visualizer.add_obj(urdf_name, link_name, obj_path, tex_path, scale=[1.0, 1.0, 1.0], translate=[0.0, 0.0, 0.0], wxyz_quaternion=[1.0, 0.0, 0.0, 0.0])

Adds a textured .obj to the visualization.

Parameters:

  • urdf_name (string) – The name of the urdf to which the .obj is being added as a link. URDF objects define robots or assemblies.

  • link_name (string) – The name of the link.

  • tex_path (string) – Relative path pointing to the .png file that provides the texture.

  • scale (array-like, size (3,), optional) – The initial scaling along the three axes applied to the .obj. The default is [1., 1., 1.].

  • translate (array-like, size (3,), optional) – The initial translation along the three axes applied to the .obj. The default is [0., 0., 0.].

  • wxyz_quaternion (array-like, size (4,), optional) – The wxyz quaternion that defines the initial rotation applied to the .obj. The default is [1., 0., 0., 0.].

Returns:

  • obj_geometry (meshcat.geometry.ObjMeshGeometry) – The object mesh.

  • obj_texture (meshcat.geometry.MeshPhongMaterial) – The object texture.

Visualizer.add_stl(urdf_name, link_name, stl_path, color=[91, 155, 213], transparent=False, opacity=1.0, scale=[1.0, 1.0, 1.0], translate=[0.0, 0.0, 0.0], wxyz_quaternion=[1.0, 0.0, 0.0, 0.0])

Adds a colored .stl to the visualization.

Parameters:

  • urdf_name (string) – The name of the urdf to which the .stl is being added as a link. URDF objects define robots or assemblies.

  • link_name (string) – The name of the link.

  • stl_path (string) – The relative path pointing to the .stl description of the link that is being added.

  • color (array-like, size (3,), optional) – The 0-255 RGB color of the .stl. The default is [91, 155, 213].

  • transparent (boolean, optional) – A boolean that indicates if the .stl is transparent. The default is False.

  • opacity (float, optional) – The opacity of the .stl. Can take float values between 0.0 and 1.0. The default is 1.0.

  • scale (array-like, size (3,), optional) – The initial scaling along the three axes applied to the .stl. The default is [1., 1., 1.].

  • translate (array-like, size (3,), optional) – The initial translation along the three axes applied to the .stl. The default is [0., 0., 0.].

  • wxyz_quaternion (array-like, size (4,), optional) – The wxyz quaternion that defines the initial rotation applied to the .stl. The default is [1., 0., 0., 0.].

Returns:

  • link_geometry (meshcat.geometry.StlMeshGeometry) – The link mesh.

  • link_mat (meshcat.geometry.MeshPhongMaterial) – The link material.

Adjusting Elements in the Viewer

Set a link color by deleting it and then adding another copy of it.

Parameters:

  • urdf_name (string) – The name of the urdf that contains the link being refreshed. URDF objects define robots or assemblies.

  • link_name (string) – The name of the link.

  • link_geometry (meshcat.geometry.StlMeshGeometry) – The link mesh.

  • color (array-like, size (3,), optional) – The 0-255 RGB color of the link. The default is [91, 155, 213].

  • transparent (boolean, optional) – A boolean that indicates if the link is transparent. The default is False.

  • opacity (float, optional) – The opacity of the link. Can take float values between 0.0 and 1.0. The default is 1.0.

Return type:

None.

Visualizer.apply_transform(urdf_name, link_name, scale=[1.0, 1.0, 1.0], translate=[0.0, 0.0, 0.0], wxyz_quaternion=[1.0, 0.0, 0.0, 0.0])

Applies a 3D affine transformation inclunding scaling, translating, and rotating to a specified link.

Parameters:

  • urdf_name (string) – The name of the urdf being transformed.

  • link_name (string) – The name of the link being transformed.

  • scale (array-like, size (3,), optional) – The scaling along the three axes. The default is [1., 1., 1.].

  • translate (array-like, size (3,), optional) – The translation along the three axes. The default is [0., 0., 0.].

  • wxyz_quaternion (array-like, size (4,), optional) – The wxyz quaternion that defines the rotation. The default is [1., 0., 0., 0.].

Returns:

transform – The 4x4 3D affine transformation matrix applied to the link.

Return type:

array-like, size (4,4)

Examples