The condynsate Package

The project Subpackage

The project Module

This module provides the Project class which is the primary interface with which users interact when using condynsate.

The Project Class

class condynsate.Project(**kwargs)

The Project class ties together a Simulator, Visualizer, Animator, and Keyboard into class.

Parameters:

**kwargs

Keyword Arguments:

  • simulator_gravity (3 tuple of floats, optional) – The gravity vector used in the simulation. The default value is (0.0, 0.0, -9.81).

  • simulator_dt (float, optional) – The finite time step size used by the simulator. If set too small, can result in visualizer, simulator desynch. Too small is determined by the number of total links in the simulation. The default value is 0.01.

  • visualizer (bool, optional) – A boolean flag that indicates if the project should include a visualizer. This visualizer provides a 3D rendering of the simulation state. The default is True.

  • visualizer_frame_rate (bool, optional) – The frame rate of the visualizer. When None, attempts to run at unlimited. This is not reccomended because it can cause communication bottlenecks that cause slow downs. The default value is 45.

  • visualizer_record (bool, optional) – A boolean flag that indicates if the visualizer will record. True, all frames from the start function call to the terminate function call are recorded. After the terminate function call, these frames are saved with h.264 and outputs in an MP4 container. The saved file name has the form visualizer.mp4. The default is False.

  • animator (bool, optional) – A boolean flag that indicates if the project should include an animator. This animator provides real-time 2D plotting. The default is False.

  • animator_frame_rate (float, optional) – The upper limit of the allowed frame rate in frames per second. When set, the animator will not update faster than this speed. The default is 15.0

  • animator_record (bool, optional) – A boolean flag that indicates if the animator should be recorded. If True, all frames from the start function call to the terminate function call are recorded. After the terminate function call, these frames are saved with h.264 and outputs in an MP4 container. The saved file name has the form animator.mp4. The default is False.

simulator

The instance of the condynsate.Simulator class used by this project.

Type:

condynsate.Simulator

visualizer

The instance of the condynsate.Visualizer class used by this project. None if this project uses no visualizer.

Type:

condynsate.Visualizer or None

animator

The instance of the condynsate.Animator class used by this project. None if this project uses no animator.

Type:

condynsate.Animator or None

keyboard

The instance of the condynsate.Keyboard class used by this project. None if this project uses no keyboard.

Type:

condynsate.Keyboard or None

bodies

All bodies loaded into the project via the load_urdf fnc.

Type:

List of condynsate.simulator.objects.Body

simtime

The current simulation time in seconds.

Type:

float

Project.load_urdf(path, **kwargs)

Loads a body defined by a .URDF file (https://wiki.ros.org/urdf) into the project.

Parameters:

  • path (string) – The path pointing to the .URDF file that defines the body.

  • **kwargs

Keyword Arguments:

fixed (boolean, optional) – A flag that indicates if the body is fixed (has 0 DoF) or free (has 6 DoF).

Returns:

body – The body added to the simulation. This retured object facilitates user interaction with the body and its joints and links.

Return type:

condynsate.core.objects.Body

Project.step(real_time=True, stable_step=True)

Takes a single simulation step and updates the visualizer to reflect the new simulator state.

Parameters:

  • real_time (bool, optional) – A boolean flag that indicates whether the step is to be taken in real time (True) or as fast as possible (False). The default is True.

  • stable_step (bool, optional) –

    Boolean flag that indicates the type of real time stepping that should be used. The default is False.

    When real_time is False, this flag is ignored.

    When real_time is True and stable_step is False, the time of the first step() call since instantiation or reset is noted. Then, at every subsequent step() call, the function will sleep until it has been exactly dt*(n-1) seconds since the noted epoch. dt is the simulator time step and n is the number of times step() has been called since instantiation or reset. This guarantees a more accurate total run time, but less stable frame rates, especially if, at any point while running a simulation, there is a long pause between step() calls.

    When real_time and stable_step are True, the function will sleep until the duration since the last time step() was called is equal to the time step of the simulation. This guarantees a more stable frame rate, but less accurate total run time.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Project.reset()

Resets the simulator, visualizer (if there is one), and animator (if there is one). If the animator is not already running, starts the animator then resets it

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Project.refresh_visualizer()

Refreshes the visualizer to synchronize it to the current simulator state. This is automatically called by load_urdf, reset, step, await_keypress, and await_anykeys. Therefore, its use cases are limited to when bodies are modified outside of the main simulation loop.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Project.refresh_animator()

Refreshes the animator GUI to keep it responsive. This is automatically called by step, await_keypress, and await_anykeys so the animator will remain responsive during those calls.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Project.await_keypress(key_str, timeout=None)

Blocks progress until the user presses a desired key.

Parameters:

  • key_str (string) – The key to be detected. May be a lowercase letter, a digit, a special character, or a punctuation mark that does not use shift on a QWERTY keyboard. The special keys are as follows: “esc”, “f1”, “f2”, “f3”, “f4”, “f5”, “f6”, “f7”, “f8”, “f9”, “f10”, “f11”, “f12”, “print_screen”, “scroll_lock”, “pause”, “backspace”, “insert”, “home”, “page_up”, “num_lock”, “tab”, “delete”, “end”, “page_down”, “caps_lock”, “enter”, “up”, “left”, “down”, “right” The punctuation marks that do not use shift on a QWERTY keyboard are as follows: “`”, “-”, “=”, “[”, “]”, “”, “;”, “’”, “,”, “.”, “/” The following modifiers can also be used: “shift”, “alt”, “ctrl”, “cmd”. Modifiers are added with the following format: “shift+a”, “ctrl+a”, “alt+a”, “shift+ctrl+alt+a”, etc.

  • timeout (float, optional) – The timeout time at which the function will stop blocking and exit. The default is None. When None, this function will not timeout.

Raises:

AttributeError: – If the project has no keyboard.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Project.await_anykeys(timeout=None)

Blocks progress until the user presses any key or any set of keys. Returns which key or keys were pressed.

Parameters:

timeout (float, optional) – The timeout time at which the function will stop blocking and exit. The default is None. When None, this function will not timeout.

Raises:

AttributeError: – If the project has no keyboard.

Returns:

keys – A list of which keys were pressed.

Return type:

list

Project.terminate()

Gracefully terminates the project and all children threads.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

The simulator Subpackage

The simulator Module

This module provides the simulator class which is used to run physics simulations using the PyBullet package.

The Simulator Class

class condynsate.Simulator(**kwargs)

The Simulator class handles running the physics simulation.

Parameters:

**kwargs

Keyword Arguments:

  • gravity (3 tuple of floats, optional) – The gravity vector used in the simulation. The default value is (0.0, 0.0, -9.81).

  • dt (float, optional) – The finite time step size used by the simulator. If set too small, can result in visualizer, simulator desync. Too small is determined by the number of total links in the simulation. The default value is 0.01.

dt

The simulator time step in seconds.

Type:

float

time

The current simulation time in seconds.

Type:

float

step_num

The number of steps the simulation has taken since instatiation or reset.

Type:

int

bodies

All bodies loaded into the simultor via the load_urdf fnc.

Type:

List of condynsate.simulator.objects.Body

Simulator.set_gravity(gravity)

Sets the acceleration due to gravity

Parameters:

gravity (array-like, shape (3,)) – The graavity vector in world coordinates with metric units.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Simulator.load_urdf(path, **kwargs)

Loads a body defined by a .URDF file (https://wiki.ros.org/urdf) into the simulator.

Parameters:

  • path (string) – The path pointing to the .URDF file that defines the body.

  • **kwargs

Keyword Arguments:

fixed (boolean, optional) – A flag that indicates if the body is fixed (has 0 DoF) or free (has 6 DoF).

Returns:

body – The body added to the simulation. This retured object facilitates user interaction with the body and its joints and links.

Return type:

condynsate.simulator.objects.Body

Simulator.step(real_time=True, stable_step=False)

Takes a single simulation step.

Parameters:

  • real_time (bool, optional) – A boolean flag that indicates whether the step is to be taken in real time (True) or as fast as possible (False). The default is True.

  • stable_step (bool, optional) –

    Boolean flag that indicates the type of real time stepping that should be used. The default is False.

    When real_time is False, this flag is ignored.

    When real_time is True and stable_step is False, the time of the first step() call since instantiation or reset is noted. Then, at every subsequent step() call, the function will sleep until it has been exactly dt*(n-1) seconds since the noted epoch. dt is the simulator time step and n is the number of times step() has been called since instantiation or reset. This guarantees a more accurate total run time, but less stable frame rates, especially if, at any point while running a simulation, there is a long pause between step() calls.

    When real_time and stable_step are True, the function will sleep until the duration since the last time step() was called is equal to the time step of the simulation. This guarantees a more stable frame rate, but less accurate total run time.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Simulator.reset()

Resets the simulation and all bodies loaded in the simulation to the initial state.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Simulator.terminate()

Terminates the simulator.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

The dataclasses Module

This module provides the dataclasses which simulator objects use.

class condynsate.simulator.dataclasses.BodyState(**kwargs)

Stores state information about the base of a body.

Parameters:

**kwargs

Keyword Arguments:

  • position (3 tuple of floats, optional) – The XYZ position in world coordinates. The default is (0., 0., 0.)

  • orientation (4 tuple of floats, optional) – The wxyz quaternion representation of the orientation in world coordinates. The default is (1., 0., 0., 0.)

  • velocity (3 tuple of floats, optional) – The XYZ velocity in either world or body coordinates. Body coordinates are defined based on objects orientation. The default is (0., 0., 0.)

  • omega (3 tuple of floats, optional) – The XYZ angular velocity in either world or body coordinates. Body coordinates are defined based on objects orientation. The default is (0., 0., 0.)

  • body (bool, optional) – Whether velocity and omega are being set in world or body coordinates. The default is False

position

The (x,y,z) position in world coordinates.

Type:

3 tuple of floats

orientation

The wxyz quaternion representation of the orientation in world coordinates.

Type:

4 tuple of floats

ypr

The (z-y’-x’ Tait–Bryan) Euler angles in radians ordered as (yaw, pitch, roll).

Type:

3 tuple of floats

velocity

The (x,y,z) velocity in world coordinates.

Type:

3 tuple of floats

omega

The (x,y,z) angular velocity in world coordinates.

Type:

3 tuple of floats

velocity_in_body

The (x,y,z) velocity in body coordinates.

Type:

3 tuple of floats

omega_in_body

The (x,y,z) angular velocity in body coordinates.

Type:

3 tuple of floats

class condynsate.simulator.dataclasses.JointState(**kwargs)

Stores state information about a joint.

Parameters:

**kwargs

Keyword Arguments:

  • angle (float, optional) – The angle of the joint about the joint axis. The default is 0.

  • omega (float, optional) – The angular velocity of the joint about the joint axis. The default is 0.

angle

The angle of the joint about the joint axis.

Type:

float

omega

The angular velocity of the joint about the joint axis.

Type:

float

class condynsate.simulator.dataclasses.LinkState(**kwargs)

Stores state information about a link.

Parameters:

**kwargs

Keyword Arguments:

  • position (3 tuple of floats, optional) – The XYZ position in world coordinates. The default is (0., 0., 0.)

  • orientation (4 tuple of floats, optional) – The wxyz quaternion representation of the orientation in world coordinates. The default is (1., 0., 0., 0.)

  • velocity (3 tuple of floats, optional) – The XYZ velocity in either world or body coordinates. Body coordinates are defined based on objects orientation. The default is (0., 0., 0.)

  • omega (3 tuple of floats, optional) – The XYZ angular velocity in either world or body coordinates. Body coordinates are defined based on objects orientation. The default is (0., 0., 0.)

  • body (bool, optional) – Whether velocity and omega are being set in world or body coordinates. The default is False

position

The (x,y,z) position in world coordinates.

Type:

3 tuple of floats

orientation

The wxyz quaternion representation of the orientation in world coordinates.

Type:

4 tuple of floats

ypr

The (z-y’-x’ Tait–Bryan) Euler angles in radians ordered as (yaw, pitch, roll).

Type:

3 tuple of floats

velocity

The (x,y,z) velocity in world coordinates.

Type:

3 tuple of floats

omega

The (x,y,z) angular velocity in world coordinates.

Type:

3 tuple of floats

velocity_in_body

The (x,y,z) velocity in body coordinates.

Type:

3 tuple of floats

omega_in_body

The (x,y,z) angular velocity in body coordinates.

Type:

3 tuple of floats

The objects Module

This module provides the objects that reside in the simulator class which is used to run physics simulations using the PyBullet package.

The Body Class

class condynsate.simulator.objects.Body(client, path, **kwargs)

The class stores information about and allows interaction with a body in the simulation. This body is defined from a URDF file and is comprised of a set of links and joints.

Parameters:

  • client (pybullet_utils.bullet_client.BulletClient) – The PyBullet physics client in which the body lives.

  • path (string) – The path pointing to the URDF file that defines the body.

  • **kwargs

Keyword Arguments:

fixed (boolean, optional) – A flag that indicates if the body is fixed (has 0 DoF) or free (has 6 DoF).

initial_state

The initial state of the body. Can be upated with the set_initial_state function.

Type:

condynsate.simulator.dataclasses.BodyState

state

The current state of the body in simulation. Can be upated either by the simulation or with the set_state function.

Type:

condynsate.simulator.dataclasses.BodyState

center_of_mass

The center of mass of the body in world coordinates.

Type:

3 tuple of floats

visual_data

All data needed to render the body assuming each link is rendered individually.

Type:

list of dicts

A dictionary whose keys are link names (as defined by the .URDF) and whose values are the Link objects that facilitate interaction.

Type:

dict of condynsate.simulator.objects.Link

joints

A dictionary whose keys are joints names (as defined by the .URDF) and whose values are the Joint objects that facilitate interaction.

Type:

dict of condynsate.simulator.objects.Joint

Body.set_initial_state(**kwargs)

Sets the initial state of the body. When the simulation is reset, this object will be reset to this state.

Parameters:

**kwargs

Keyword Arguments:

  • position (3 tuple of floats, optional) – The XYZ position in world coordinates. The default is (0., 0., 0.)

  • yaw (float, optional) – The (z-y’-x’ Tait–Bryan) yaw angle of the object in radians.

  • pitch (float, optional) – The (z-y’-x’ Tait–Bryan) pitch angle of the object in radians.

  • roll (float, optional) – The (z-y’-x’ Tait–Bryan) roll angle of the object in radians.

  • velocity (3 tuple of floats, optional) – The XYZ velocity in either world or body coordinates. Body coordinates are defined based on object’s orientation. The default is (0., 0., 0.)

  • omega (3 tuple of floats, optional) – The XYZ angular velocity in either world or body coordinates. Body coordinates are defined based on object’s orientation. The default is (0., 0., 0.)

  • body (bool, optional) – Whether velocity and omega are being set in world or body coordinates. The default is False

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Body.set_state(**kwargs)

Sets the state of the body.

Parameters:

**kwargs

Keyword Arguments:

  • position (3 tuple of floats, optional) – The XYZ position in world coordinates. The default is (0., 0., 0.)

  • yaw (float, optional) – The (z-y’-x’ Tait–Bryan) yaw angle of the object in radians.

  • pitch (float, optional) – The (z-y’-x’ Tait–Bryan) pitch angle of the object in radians.

  • roll (float, optional) – The (z-y’-x’ Tait–Bryan) roll angle of the object in radians.

  • velocity (3 tuple of floats, optional) – The XYZ velocity in either world or body coordinates. Body coordinates are defined based on object’s orientation. The default is (0., 0., 0.)

  • omega (3 tuple of floats, optional) – The XYZ angular velocity in either world or body coordinates. Body coordinates are defined based on object’s orientation. The default is (0., 0., 0.)

  • body (bool, optional) – Whether velocity and omega are being set in world or body coordinates. The default is False

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Body.apply_force(force, **kwargs)

Applies force to the center of mass of the body.

Parameters:

  • force (3 tuple of floats) – The force being applied to the center of mass.

  • **kwargs

Keyword Arguments:

  • body (bool, optional) – A Boolean flag that indicates if the force argument is in body coordinates (True), or in world coordinates (False). The default is False.

  • draw_arrow (bool, optional) – A Boolean flag that indicates if an arrow should be drawn to represent the applied force. The default is False.

  • arrow_scale (float, optional) – The scaling factor, relative to the size of the applied force, that is used to size the force arrow. The default is 1.0.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Body.apply_torque(torque, **kwargs)

Applies external torque to the body.

Parameters:

  • torque (3 tuple of floats) – The torque being applied.

  • **kwargs

Keyword Arguments:

  • body (bool, optional) – A Boolean flag that indicates if the torque argument is in body coordinates (True), or in world coordinates (False). The default is False.

  • draw_arrow (bool, optional) – A Boolean flag that indicates if an arrow should be drawn to represent the applied torque. The default is False.

  • arrow_scale (float, optional) – The scaling factor, relative to the size of the applied torque, that is used to size the torque arrow. The default is 1.0.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Body.reset()

Resets body and each of its joints to their initial conditions.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Body.clear_visual_buffer()

Clears the body’s visual buffer. If visual_data is not collected each time step, then clear_visual_buffer must be called to prevent the visual_data buffer from growing indeterminately.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

The Joint Class

class condynsate.simulator.objects.Joint(sim_obj, idx, child)

The class stores information about and allows interaction with a joint on a body in the simulation.

Parameters:

  • sim_obj (condynsate.core.objects.Body) – The member of the Body class to which the joint belongs

  • idx (int) – The unique number that identifies the joint in the PyBullet client.

  • child (condynsate.core.objects.Link) – The child link of the joint.

initial_state

The initial state of the joint. Can be upated with the set_initial_state function.

Type:

condynsate.simulator.dataclasses.JointState

state

The current state of the joint in simulation. Read only.

Type:

condynsate.simulator.dataclasses.JointState

axis

The axis, in world coordinates, about which the joint operates.

Type:

3 tuple of floats

Joint.set_dynamics(**kwargs)

Set the joint damping and the maximum joint angular velocity.

Parameters:

**kwargs

Keyword Arguments:

  • damping (float, optional) – The damping of the joint about the joint axis. The default value is 0.001.

  • max_omega (float, optional) – The maximum allowed angular velocity of the joint about the joint axis. The default value is 1000.0

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Joint.set_initial_state(**kwargs)

Sets the initial state of the joint. When the simulation is reset the joint will be reset to this value

Parameters:

**kwargs

Keyword Arguments:

  • angle (float, optional) – The (angle in radians) of the joint about the joint axis.

  • omega (float, optional) – The angular velocity (angle in radians / second) of the joint about the joint axis.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Joint.set_state(**kwargs)

Sets the current state of the joint.

Parameters:

**kwargs

Keyword Arguments:

  • angle (float, optional) – The (angle in radians) of the joint about the joint axis. When not defined, does not change from current value.

  • omega (float, optional) – The angular velocity (angle in radians / second) of the joint about the joint axis. When not defined, does not change from current value.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Joint.apply_torque(torque, **kwargs)

Applies torque to a joint for a single simulation step.

Parameters:

  • torque (float) – The torque being applied about the joint’s axis..

  • **kwargs

Keyword Arguments:

  • draw_arrow (bool, optional) – A Boolean flag that indicates if an arrow should be drawn to represent the applied torque. The default is False.

  • arrow_scale (float, optional) – The scaling factor, relative to the size of the applied torque, that is used to size the torque arrow. The default is 1.0.

  • arrow_offset (float, optional) – The amount by which the drawn is offset from the center of the joint’s child link along the joint axis. The default is 0.0.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Joint.reset()

Resets the joint to its initial conditions.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

The visualizer Subpackage

The visualizer Module

This module provides the Visualizer class.

The Visualizer Class

class condynsate.Visualizer(frame_rate=45.0, record=False)

Visualizer manages the meshcat based visulation.

Parameters:

  • frame_rate (bool, optional) – The frame rate of the visualizer. When None, attempts to run at unlimited. This is not recommended because it can cause communication bottlenecks that cause slow downs. The default value is 45.

  • record (bool, optional) – A boolean flag that indicates if the visualizer will record.

frame_delta

The time, in seconds, between each visualizer frame update.

Type:

float

record

A boolean flag that indicates if the visualizer is recording or not.

Type:

bool

Visualizer.set_grid(visible)

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

Parameters:

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

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Visualizer.set_axes(visible)

Controls the visibility state of the axes in the visualizer.

Parameters:

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

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Visualizer.set_background(top=None, bottom=None)

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

Parameters:

  • top (3 tuple of floats between 0.0 and 1.0, optional) – The RGB color to apply to the top of the background. If None, is not altered. The default is None

  • bottom (3 tuple of floats between 0.0 and 1.0, optional) – The RGB color to apply to the bottom of the background. If None, is not altered. The default is None

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Visualizer.set_spotlight(**kwargs)

Sets the properties of the spotlight in the scene.

Parameters:

**kwargs

Keyword Arguments:

  • on (bool) – Boolean flag that indicates if the light is on.

  • position (3tuple of floats) – The position of the light source in (x,y,z) world coordinates. Does not apply to amblight type sources.

  • intensity (float) – Numeric value of the light’s strength/intensity.

  • distance (float) – Maximum range of the light. Default is 0 (no limit).

  • decay (float) – The amount a ptlight or spotlight type light dims along the distance of the light.

  • angle (float between 0.0 and 1.5707) – The beam angle of a spotlight type light in radians.

  • shadow (bool) – Boolean flag that indicates if the light casts a shadow.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Visualizer.set_ptlight_1(**kwargs)

Sets the properties of the first point light.

Parameters:

**kwargs

Keyword Arguments:

  • on (bool) – Boolean flag that indicates if the light is on.

  • position (3tuple of floats) – The position of the light source in (x,y,z) world coordinates. Does not apply to amblight type sources.

  • intensity (float) – Numeric value of the light’s strength/intensity.

  • distance (float) – Maximum range of the light. Default is 0 (no limit).

  • shadow (bool) – Boolean flag that indicates if the light casts a shadow.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Visualizer.set_ptlight_2(**kwargs)

Sets the properties of the second point light.

Parameters:

**kwargs

Keyword Arguments:

  • on (bool) – Boolean flag that indicates if the light is on.

  • position (3tuple of floats) – The position of the light source in (x,y,z) world coordinates. Does not apply to amblight type sources.

  • intensity (float) – Numeric value of the light’s strength/intensity.

  • distance (float) – Maximum range of the light. Default is 0 (no limit).

  • shadow (bool) – Boolean flag that indicates if the light casts a shadow.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Visualizer.set_amblight(**kwargs)

Sets the properties ambient light of the scene.

Parameters:

**kwargs

Keyword Arguments:

  • on (bool) – Boolean flag that indicates if the light is on.

  • intensity (float) – Numeric value of the light’s strength/intensity.

  • shadow (bool) – Boolean flag that indicates if the light casts a shadow.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Visualizer.set_dirnlight(**kwargs)

Sets the properties fill light of the scene.

Parameters:

**kwargs

Keyword Arguments:

  • on (bool) – Boolean flag that indicates if the light is on.

  • position (3tuple of floats) – The position of the light source in (x,y,z) world coordinates. Does not apply to amblight type sources.

  • intensity (float) – Numeric value of the light’s strength/intensity.

  • shadow (bool) – Boolean flag that indicates if the light casts a shadow.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Visualizer.set_cam_position(p)

Set the XYZ position of camera.

Parameters:

p (3Vec of floats) – The XYZ position to which the camera will be moved. After moving, the camera will automatically adjust its orientation to continue looking directly at its target.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Visualizer.set_cam_target(t)

Set the XYZ position of the point the camera is looking at.

Parameters:

t (3Vec of floats) – The XYZ position for the camera to look at. Regardless of updates to the camera position, the camera will always look directly at this point.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Visualizer.set_cam_zoom(zoom)

Sets the zoom value of the camera

Parameters:

zoom (float greater than 0 and less than or equal to 100.) – The zoom value .

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Visualizer.set_cam_frustum(**kwargs)

Sets the size and shape of the camera’s frustum.

Parameters:

**kwargs

Keyword Arguments:

  • aspect (float) – The aspect ratio of the near and far planes of the frustum.

  • fov (float) – The vertical field of view of the frustum in degrees.

  • near (float less than far) – The distance to the near plane of the frustum.

  • far (float greater than near) – The distance to the far plane of the frustum.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Visualizer.add_object(name, path, **kwargs)

Adds an object to the visualizer scene.

Parameters:

  • name (string or tuple of strings) – A list of strings defining the name of the object as well as its position in the scene heirarchy. For example, (‘foo’, ‘bar’) would insert a new object to the scene at location /Scene/foo/bar while ‘baz’ would insert the object at /Scene/baz

  • path (string) – Path pointing to the file that describes the object’s geometry. The file may be of type .obj, .stl, or .dae.

  • **kwargs

Keyword Arguments:

  • tex_path (string) – The path pointing to a .png file that defines the texture of the object being added. Is only applied correctly if object is of type .obj or .dae. .stl files do not support proper texturing and attempting to apply texture to .stl may result in unexpected viual results. If None, no texture is applied. The default is None

  • color (3vec of floats) – The color to apply to the object being added. In the form of (R, G, B) where all elements range from 0.0 to 1.0. The default is (1.0, 1.0, 1.0).

  • shininess (float) – The shininess of the object being added. Ranges from 0.0 to 1.0 The default value of 0.01.

  • opacity (float) – The opacity of the object being added. Ranges from 0.0 to 1.0. The default value is 1.0.

  • position (3vec of floats) – The extrinsic position to set. The default value is (0., 0., 0.)

  • wxyz_quat (4vec of floats) – The extrinsic rotation to set as defined by a quaternion. The default value is (1., 0., 0., 0.)

  • yaw (float) – The intrinsic yaw angle to set in degrees. Defined about the object’s Z axis. The default value is 0.0.

  • pitch (float) – The intrinsic pitch angle to set in degrees. Defined about the object’s Y axis. The default value is 0.0.

  • roll (float) – The intrinsic roll angle to set in degrees. Defined about the object’s X axis. The default value is 0.0.

  • scale (3vec of floats) – The intrinsic scale of the object. When not set, defaults to (1., 1., 1.).

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Visualizer.set_transform(name, **kwargs)

Sets the position, orientation, and scale of a scene object relative to its original origin and size.

Parameters:

  • name (string or tuple of strings) – A list of strings defining the name of the object as well as its position in the scene heirarchy. For example, (‘foo’, ‘bar’) would refers to the object at the scene location /Scene/foo/bar while ‘baz’ refers to the object at scene location /Scene/baz

  • **kwargs

Keyword Arguments:

  • position (3vec of floats, optional) – The extrinsic position to set. The default value is (0., 0., 0.)

  • wxyz_quat (4vec of floats, optional) – The extrinsic rotation to set as defined by a quaternion. The default value is (1., 0., 0., 0.)

  • yaw (float, optional) – The intrinsic yaw angle to set in radians. Defined about the object’s Z axis. The default value is 0.0.

  • pitch (float, optional) – The intrinsic pitch angle to set in radians. Defined about the object’s Y axis. The default value is 0.0.

  • roll (float, optional) – The intrinsic roll angle to set in radians. Defined about the object’s X axis. The default value is 0.0.

  • scale (3vec of floats, optional) – The intrinsic scale of the object. When not set, defaults to (1., 1., 1.).

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Visualizer.set_material(name, **kwargs)

Sets an objects material.

Parameters:

  • name (string or tuple of strings) – A list of strings defining the name of the object as well as its position in the scene heirarchy. For example, (‘foo’, ‘bar’) refers to the object at the scene location /Scene/foo/bar while ‘baz’ refers to the object at scene location /Scene/baz

  • **kwargs

Keyword Arguments:

  • tex_path (string, optional) – The path pointing to a .png file that defines the texture of the object being added. Is only applied correctly if object is of type .obj or .dae. .stl files do not support proper texturing and attempting to apply texture to .stl may result in unexpected viual results. If None, no texture is applied. The default is None

  • color (3vec of floats, optional) – The color to apply to the object. In the form of (R, G, B) where all elements range from 0.0 to 1.0. The default is (1.0, 1.0, 1.0).

  • shininess (float, optional) – The shininess of the object. Ranges from 0.0 to 1.0. The default value is 0.01

  • opacity (float, optional) – The opacity of the object. Ranges from 0.0 to 1.0. The default value is 1.0.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Visualizer.reset()

Resets the recording data.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Visualizer.terminate()

Terminates the visualizer’s communication with the web browser.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

The animator Subpackage

The animator Module

This module provides the Animator class which is used to draw data to a plot in real time.

The Animator Class

class condynsate.Animator(frame_rate=20, record=False)

The animator main class. Creates, modifies, and displays lineplots and barcharts in real time according to user inputs

Parameters:

  • frame_rate (float, optional) – The upper limit of the allowed frame rate in frames per second. When set, the animator will not update faster than this speed. When none, the animator will update each time refresh is called. The default is 20.

  • record (bool, optional) – A boolean flag that indicates if the animator should be recorded. If True, all frames from the start function call to the terminate function call are recorded. After the terminate function call, these frames are saved with h.264 and outputs in an MP4 container. The saved file name has the form animator_video.mp4

frame_delta

The time, in seconds, between each animator frame update.

Type:

float

record

A boolean flag that indicates if the animator is recording or not.

Type:

bool

is_running

A boolean flag that indicates if the animator is running or not.

Type:

bool

Animator.add_lineplot(n_lines, **kwargs)

Adds a lineplot to the animator window. Neither the lineplot nor the window appear until the user calls the start function.

Parameters:

  • n_lines (int) – The number of lines that are drawn on the plot. Must be integer between [1, 16].

  • **kwargs

Keyword Arguments:

  • 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

  • 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. When tuple, must have length n_lines. 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.

  • 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.

  • label (string or tuple of strings, optional) – The label applied to each artist. The labels are shown in a legend in the top right of the plot. When tuple, must have length n_lines. When None, no labels are made. The default is None.

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

  • line_width (float or tuple of floats, optional) – The line weigth each artist uses. When tuple, must have length n_lines. The default is 1.5.

  • line_style (line style string or tuple of ls strings, optional) – The line style each artist uses. When tuple, must have length n_lines. The default is ‘solid’. Select from ‘solid’, ‘dashed’, ‘dashdot’, or ‘dotted’.

Raises:

  • RuntimeError – If cannot add another subplot or the animator was already running. Can only add up to 16 subplots total.

  • ValueError – If n_lines is not an int or is less than 1 or greater than 16.

Returns:

lines_ids – A unique identifier that allows the user to address each line in the lineplot. For example, if n_lines = 3, the tuple will have length three; however, if n_lines = 1, the returned value will be the hex id of the only line (not a tuple).

Return type:

hex or tuple of hex

Animator.add_barchart(n_bars, **kwargs)

Adds a barchart to the animator window. Neither the barchart nor the window appear until the user calls the start function.

Parameters:

  • n_bars (int) – The number of bars on the chart. Must be integer between [1, 16].

  • **kwargs

Keyword Arguments:

  • 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

  • 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.

  • label (string or tuple of strings, optional) – The label applied to each bar. The labels are shown in a legend in the top right of the chart. When tuple, must have length n_bars. When None, no labels are made. The default is None.

  • color (matplotlib color string or tuple of color strings, optional) – The color of each bar. When tuple, must have length n_bars. The default is ‘blue’.

Raises:

  • RuntimeError – If cannot add another subplot or the animator was already running. Can only add up to 16 subplots total.

  • ValueError – If n_bars is not an int or is less than 1 or greater than 16.

Returns:

bar_ids – A unique identifier that allows the user to address each bar in the barchart. For example, if n_bars = 3, the tuple will have length three; however, if n_bars = 1, the returned value will be the hex id of the only bar (not a tuple).

Return type:

tuple of hex

Animator.start()

Starts the animator. Creates a new window and begins displaying live subplot data to it. Please ensure to call the terminate function when done to ensure all child threads are killed.

Raises:

RuntimeError – If something goes wrong while attempting to start the animator.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Animator.refresh()

Updates the animator GUI with the most recently drawn figure. Must be called regularly to maintain responsivness of GUI.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Animator.barchart_set_value(bar_id, value)

Set’s a bar’s value.

Parameters:

  • bar_id (hex string) – The id of the bar whose value is being set.

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

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Animator.lineplot_append_point(line_id, x_val, y_val)

Appends a single y versus x data point to the end of a line.

Parameters:

  • line_id (hex string) – The id of the line to which a point is appended.

  • x_val (float) – The x coordinate of the data point being appended.

  • y_val (float) – The y coordinate of the data point being appended.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Animator.lineplot_set_data(line_id, x_vals, y_vals)

Plots y_vals versus x_vals.

Parameters:

  • line_id (hex string) – The id of the line on which that data are plotted.

  • x_vals (list of floats) – A list of x coordinates of the points being plotted.

  • y_vals (list of floats) – A list of y coordinates of the points being plotted.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Animator.reset()

Resets all data on all subplots and the recording, if applicable.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

Animator.terminate()

Terminates and removes all subplots from the animator. Should be called when done with Animator.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int

The keyboard Subpackage

The keyboard Module

This module provides the Keyboard class which monitors the keyboard and tells users which keys are pressed.

The Keyboard Class

class condynsate.Keyboard

Keyboard asynchronously detects and reports keyboard events. Used to detect which keys are pressed and which modifiers are being used. Works best on QWERTY keyboards.

Keyboard.get_pressed()

Returns a list of all keys that are currently pressed.

Returns:

keys_pressed – The list of keys to be detected. Each item in list may be a lowercase letter, a digit, a special character, or a punctuation mark that does not use shift on a QWERTY keyboard. The special keys are as follows: “esc”, “f1”, “f2”, “f3”, “f4”, “f5”, “f6”, “f7”, “f8”, “f9”, “f10”, “f11”, “f12”, “print_screen”, “scroll_lock”, “pause”, “backspace”, “insert”, “home”, “page_up”, “num_lock”, “tab”, “delete”, “end”, “page_down”, “caps_lock”, “enter”, “up”, “left”, “down”, “right” The punctuation marks that do not use shift on a QWERTY keyboard are as follows: “`”, “-”, “=”, “[”, “]”, “”, “;”, “’”, “,”, “.”, “/” If one of the following modifiers are used: “shift”, “alt”, “ctrl”, “cmd”, each item in the list will prepend them following format: “shift+a”, “ctrl+a”, “alt+a”, “cmd+a”, “shift+ctrl+a”, etc.

Return type:

list of strings

Keyboard.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 a lowercase letter, a digit, a special character, or a punctuation mark that does not use shift on a QWERTY keyboard. The special keys are as follows: “esc”, “f1”, “f2”, “f3”, “f4”, “f5”, “f6”, “f7”, “f8”, “f9”, “f10”, “f11”, “f12”, “print_screen”, “scroll_lock”, “pause”, “backspace”, “insert”, “home”, “page_up”, “num_lock”, “tab”, “delete”, “end”, “page_down”, “caps_lock”, “enter”, “up”, “left”, “down”, “right” The punctuation marks that do not use shift on a QWERTY keyboard are as follows: “`”, “-”, “=”, “[”, “]”, “”, “;”, “’”, “,”, “.”, “/” The following modifiers can also be used: “shift”, “alt”, “ctrl”, “cmd”. Modifiers are added with the following format: “shift+a”, “ctrl+a”, “alt+a”, “shift+ctrl+alt+a”, etc.

Returns:

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

Return type:

bool

Keyboard.await_press(key_str, timeout=None)

Waits until the user presses a specified key or until the timeout condition is met

Parameters:

  • key_str (string) – The key to await. May be a lowercase letter, a digit, a special character, or a punctuation mark that does not use shift on a QWERTY keyboard. The special keys are as follows: “esc”, “f1”, “f2”, “f3”, “f4”, “f5”, “f6”, “f7”, “f8”, “f9”, “f10”, “f11”, “f12”, “print_screen”, “scroll_lock”, “pause”, “backspace”, “insert”, “home”, “page_up”, “num_lock”, “tab”, “delete”, “end”, “page_down”, “caps_lock”, “enter”, “up”, “left”, “down”, “right” The punctuation marks that do not use shift on a QWERTY keyboard are as follows: “`”, “-”, “=”, “[”, “]”, “”, “;”, “’”, “,”, “.”, “/” The following modifiers can also be used: “shift”, “alt”, “ctrl”, “cmd”. Modifiers are added with the following format: “shift+a”, “ctrl+a”, “alt+a”, “shift+ctrl+alt+a”, etc.

  • timeout (float > 0.0, optional) – The timeout value in seconds. The default is None.

Returns:

ret_code – 0 is the key is pressed, -1 is the timeout value is reached before the key is pressed.

Return type:

int

Keyboard.terminate()

Terminates the Keyboard asynchronous listener. Should be called when done with the keyboard.

Returns:

ret_code – 0 if successful, -1 if something went wrong.

Return type:

int