voraus_simulation package

A library for simulation purposes.

class voraus_simulation.BulletEngine(mode='direct', gravity=None)

Bases: BulletEngine

Initializes the pybullet engine.

Parameters:

  • mode (Union[Literal['gui'], Literal['direct']]) – The connection mode to the engine. Either ‘direct’ or ‘giu’. Defaults to “direct”.

  • gravity (list[float] | None) – The gravity vector. Defaults to [0, 0, -9.81].

static set_parameter(fixed_time_step=None, num_solver_iterations=None, num_sub_steps=None)

Sets engine parameters.

Parameters:

  • fixed_time_step (float | None) – Engine timestep.

  • num_solver_iterations (int | None) – Maximum number of constraint solver iterations.

  • num_sub_steps (int | None) – Subdivides the physics simulation step in sub steps.

Return type:

None

class voraus_simulation.DynamicObject(glb_file, urdf_path, position=None, rotation=None, show_simulation_models=False)

Bases: StaticObject

Initializes a dynamic object for the simulation.

Parameters:

  • glb_file (Path | str | None) – The local glb file path or glb file url as string.

  • urdf_path (Path) – The urdf file path.

  • position (list[float] | None) – The initial position of the object. Defaults to None.

  • rotation (list[float] | None) – The initial rotation of the object. Defaults to None.

  • show_simulation_models (bool) – Whether to render simulation models for debugging. Defaults to False. Note, currently only base links in multi-link-bodies are supported and only simulation models defined by OBJ files are displayed.

get_visu_data()

Gets the data for visualizing the simulated dynamic object.

Return type:

list

Returns:

The data for visualizing the simulated dynamic object.

class voraus_simulation.Pose(position, orientation)

Bases: object

Defines a Cartesian pose.

orientation: list[float]
position: list[float]
class voraus_simulation.Simulation(frequency, visualization=None, engine=<voraus_simulation.engines.bullet.pub_engine.BulletEngine object>, enable_logging=False)

Bases: Simulation

Initializes the client for the simulation service.

Parameters:

  • frequency (float) – The simulation frequency to use.

  • visualization (Visu | None) – The visualization for visualizing the simulated environment. Defaults to None.

  • engine (BulletEngine) – The simulation engine to use. Defaults to BulletEngine().

  • enable_logging (bool) – Whether to enable logging messages. Defaults to False.

property engine: BulletEngine

Property for accessing the engine.

Returns:

The engine.

run()

A context manager for the simulation engine with the connected visualization.

Yields:

An empty generator guarding the running engine and the connection to the visualization.

Return type:

Generator[None, None, None]

sleep()

Sleeps the remaining time of a simulation step.

Return type:

None

step()

Triggers the next simulation step.

Return type:

None

class voraus_simulation.StaticObject(glb_file, urdf_path, position=None, rotation=None, show_simulation_models=False)

Bases: PhysicsTraits, VisuTraits

Initializes a static object for the simulation.

Parameters:

  • glb_file (Path | str | None) – The local glb file path or glb file url as string.

  • urdf_path (Path) – The urdf file path.

  • position (list[float] | None) – The initial position of the object. Defaults to None.

  • rotation (list[float] | None) – The initial rotation of the object. Defaults to None.

  • show_simulation_models (bool) – Whether to render simulation models for debugging. Defaults to False. Note, currently only base links in multi-link-bodies are supported and only simulation models defined by OBJ files are displayed.

remove()

Removes an object.

Return type:

None

voraus_simulation.get_object(identifier, object_type=None)

Returns an object.

Parameters:

  • identifier (int) – The identifier of the object to return.

  • object_type (Optional[Type[TypeVar(ObjectT, bound= object)]]) – The expected type of the object to get. If provided the found object is checked for the type. Defaults to None.

Raises:

  • KeyError – If the object was not found.

  • TypeError – If the found object is not of the expected type.

Return type:

Union[object, TypeVar(ObjectT, bound= object)]

Returns:

The object.

voraus_simulation.get_objects(object_type=None)

Returns either all objects or all objects of a specified type.

Parameters:

object_type (Optional[Type[TypeVar(ObjectT, bound= object)]]) – The type of the objects, which should be returned. Defaults to None.

Return type:

list[object] | list[TypeVar(ObjectT, bound= object)]

Returns:

The desired objects.

voraus_simulation.transforms

Contains the transformation utilities.

voraus_simulation.engines.bullet.transforms.euler_from_quaternion(quaternion)

Returns the Euler angles representation of quaternion.

Parameters:

quaternion (list[float]) – The quaternion.

Return type:

list[float]

Returns:

The Euler angles (in XYZ) representation.

voraus_simulation.engines.bullet.transforms.invert(pose)

Returns the invert of a transform.

Parameters:

pose (Pose) – The pose describing the transform.

Return type:

Pose

Returns:

The invert of a transform.

voraus_simulation.engines.bullet.transforms.multiply(pose1, pose2)

Returns the multiplication of to transfroms.

Parameters:

  • pose1 (Pose) – The pose one describing the first transform.

  • pose2 (Pose) – The pose two describing the second transform.

Return type:

Pose

Returns:

The multiplication result.

voraus_simulation.engines.bullet.transforms.quaternion_from_euler(rotation)

Returns the quaternion representation of Euler angles.

Parameters:

rotation (list[float]) – The rotation in Euler angles.

Return type:

list[float]

Returns:

The quaternion representation.

voraus_simulation.traits

Contains public usable trait classes for the simulation and visualization.

class voraus_simulation.pub_traits.DynamicTraits(object_id)

Bases: DynamicTraits

Init dynamic traits.

enable_sleep_state(sleep_threshold=None)

When sleeping is enabled, objects that don’t move (below a threshold) will be disabled as sleeping.

Parameters:

  • sleep_threshold (float | None) – An optional threshold to set which modifies the internal default threshold.

  • None. (Defaults to)

Return type:

None

set_collision_margin(collision_margin)

Sets collision margin.

Parameters:

collision_margin (float) – Depending on the shape type, it may or may not add some padding to the inside or outside of the collision shape.

Return type:

None

set_contact_properties(link_index=-1, stiffness=None, damping=None, friction_anchor=None, restitution=None, processing_threshold=None)

Sets contact properties.

Parameters:

  • link_index (int) – Index of the link whose dynamics parameter are to be changed. Use -1 for accessing the base.

  • stiffness (float | None) – Stiffness of contact constraints. Must be used together with damping.

  • damping (float | None) – Damping of contact constraints. Must be used together with stiffness.

  • friction_anchor (bool | None) – Enable or disable a friction drift correction.

  • restitution (float | None) – Bounciness of contact. Keep it a bit less than 1, preferably closer to 0.

  • processing_threshold (float | None) – Contact processing threshold. Contacts with a distance below this threshold will be processed by the constraint solver.

Return type:

None

set_damping(linear=None, angular=None)

Sets damping parameters for the object.

Parameters:

  • linear (float | None) – Linear damping.

  • angular (float | None) – Angular damping.

Return type:

None

set_friction(link_index=-1, lateral=None, spinning=None, rolling=None)

Sets friction parameters.

Parameters:

  • link_index (int) – Index of the link whose dynamics parameter are to be changed. Use -1 for accessing the base.

  • lateral (float | None) – Lateral (linear) contact friction.

  • spinning (float | None) – Torsional friction around the contact normal.

  • rolling (float | None) – Torsional friction orthogonal to contact normal. Keep the value close to 0.

Return type:

None

set_joint_limits(link_index=-1, limits=None, limit_force=None)

Sets joint limits.

Parameters:

  • link_index (int) – Index of the link whose dynamics parameter are to be changed. Use -1 for accessing the base.

  • limits (tuple[float, float] | None) – A tuple containing the lower limit and the upper limit.

  • limit_force (float | None) – Maximum force applied to satisfy a joint limit.

Return type:

None

set_mass(link_index=-1, mass=None)

Sets the mass.

Parameters:

  • link_index (int) – Index of the link whose dynamics parameter are to be changed. Use -1 for accessing the base.

  • mass (float | None) – The mass of the object in kg.

Return type:

None

class voraus_simulation.pub_traits.PhysicsTraits

Bases: PhysicsTraits

Defines physic traits for simulation purposes.

apply_external_force(force, position=None, frame='object', link_index=-1)

Applies an external force to an object.

Parameters:

  • force (list[float]) – Force vector to be applied [x,y,z].

  • position (list[float] | None) – Position on the base/link where the force is applied. Defaults to None.

  • frame (Literal['world', 'object']) – Specifies the coordinate system of force and position. Either ‘world’ for Cartesian world coordinates or ‘object’ for local object/link coordinates. Defaults to “object”.

  • link_index (int) – The index of the link on which the force is applied. Defaults to -1 for the base.

Return type:

None

batch_ray_test(from_positions, to_positions, use_local=False)

Returns the batch ray test intersections.

Parameters:

  • from_positions (list[list[float]]) – The start position of each ray [x, y, z] in meter.

  • to_positions (list[list[float]]) – The end position of each ray [x, y, z] in meter.

  • use_local (bool) – Whether to use local coordinate system of the object. Defaults to False.

Return type:

list[Intersection]

Returns:

The intersections with the first hit of each ray.

check_distance(other_object, distance, own_link_index=None, other_link_index=None)

Checks if the distance to another object is less than the defined value.

Parameters:

  • other_object (int) – The object to check the closest points against.

  • distance (float) – Distance between the objects to check.

  • own_link_index (int | None) – The index of the own link which should be checked. Defaults to None.

  • other_link_index (int | None) – The index of the other link which should be checked. Defaults to None.

Return type:

bool

Returns:

Whether the distance between the objects is smaller than the defined distance.

create_constraint(child, parent_frame_position, child_frame_position, parent_frame_orientation=None, child_frame_orientation=None, parent_link_index=-1, child_link_index=-1)

Creates a constraint.

Parameters:

  • child (int) – The child object id.

  • parent_frame_position (list[float]) – The position of the joint frame relative to parent center of mass frame.

  • child_frame_position (list[float]) – The position of the joint frame relative to a given child center of mass frame (or world origin if no child specified).

  • parent_frame_orientation (list[float] | None) – The orientation of the joint frame relative to parent center of mass coordinate frame. Defaults to None.

  • child_frame_orientation (list[float] | None) – The orientation of the joint frame relative to the child center of mass coordinate frame (or world origin frame if no child specified). Defaults to None.

  • parent_link_index (int) – The parent link index. Defaults to -1 for the base.

  • child_link_index (int) – The child link index. Defaults to -1 for the base.

Return type:

Constraint

Returns:

The constraint.

property dynamics: DynamicTraits

Access dynamics traits.

Returns:

A dynamic traits instance.

enable_joint_force_sensor(joint_index, enable=True)

Enables or disables a joint force sensor of the joint.

Once enabled, if a simulation step is performed, the get_joint_state will return the joint reaction forces in the fixed degrees of freedom. For example a fixed joint will measure all 6DOF joint forces but a revolute joint force sensor will measure 5DOF reaction forces along all axis except the hinge axis.

Parameters:

  • joint_index (int) – The index of the joint from the URDF file.

  • enable (bool) – Whether to enable the sensor. Defaults to True.

Return type:

None

get_contact_points(other_object=None, own_link_index=None, other_link_index=None)

Gets the contact points of the object.

Parameters:

  • other_object (int | None) – The object to check a collision against. Defaults to None.

  • own_link_index (int | None) – The index of the own link which should be checked. Defaults to None.

  • other_link_index (int | None) – The index of the own link which should be checked. Defaults to None.

Return type:

list[Points]

Returns:

The contact points.

get_distance(other_object, own_link_index=None, other_link_index=None, threshold=100)

Gets the smallest distance to another object if the distance is less than a given threshold.

Parameters:

  • other_object (int) – The object to check the distance against.

  • own_link_index (int | None) – The index of the own link which should be checked. Defaults to None.

  • other_link_index (int | None) – The index of the other link which should be checked. Defaults to None.

  • threshold (float) – Threshold distance between objects. If exceeded, None is returned. Defaults to 100m.

Return type:

float | None

Returns:

The smallest distance between the objects. None if threshold is exceeded or target object doesn’t exist.

get_joint_state(joint_index)

Returns the joint state.

Parameters:

joint_index (int) – The index of the joint from the URDF file.

Return type:

JointState

Returns:

The joint state.

Returns the link state.

Parameters:

joint_index (int) – The index of the joint from the URDF file.

Return type:

LinkState

Returns:

The link state.

get_pose()

Gets the pose of the object.

Return type:

Pose

Returns:

The pose.

get_urdf_file()

Gets the urdf file path if set.

Return type:

str | None

Returns:

The urdf file path if set else None.

load_urdf(urdf_file, position, rotation=None, orientation=None)

Loads an urdf file of an object into the simulation.

Parameters:

  • urdf_file (Path) – The urdf file path.

  • position (list[float]) – The initial position of the object.

  • rotation (list[float] | None) – The initial rotation of the object. Defaults to None.

  • orientation (list[float] | None) – The initial orientation in quaternion. of the object. Defaults to None.

Raises:

RuntimeError – If rotation and quaternion are both provided.

Return type:

None

property object_id: int

Returns the object_id for interacting with object in the simulation.

Raises:

RuntimeError – If the object was not loaded into the simulation.

Returns:

The object_id for interacting with object in the simulation.

ray_test(point_a, point_b)

Returns the ray test intersections.

Parameters:

  • point_a (list[float]) – The starting point of the ray.

  • point_b (list[float]) – The ending point of the ray.

Return type:

list[Intersection]

Returns:

The intersections.

set_collision_filter_pair(other_object=None, own_link_index=None, other_link_index=None, enable_collision=False)

Enables or disables collision detection between specific pairs of links.

Parameters:

  • other_object (int | None) – The object to check a collision against. Defaults to None.

  • own_link_index (int | None) – The index of the own link which should be checked. Defaults to None.

  • other_link_index (int | None) – The index of the own link which should be checked. Defaults to None.

  • enable_collision (bool) – Enable or disable collision. Defaults to False.

Return type:

None

set_joint_motor_position_control_2(joint_index, target_position, max_velocity, max_force)

Sets the joint motor control target position.

Parameters:

  • joint_index (int) – The index of the joint from the URDF file.

  • target_position (float) – The target position of the joint.

  • max_velocity (float) – The maximum velocity for the motor.

  • max_force (float) – The maximum force for the motor.

Return type:

None

set_pose(pose)

Sets the pose of the object.

Parameters:

pose (Pose) – The pose to set.

Return type:

None

set_velocity(linear_velocity=None, angular_velocity=None, use_local=False)

Sets the velocity of the object.

Parameters:

  • linear_velocity (list[float] | None) – The linear velocity to set. Defaults to None.

  • angular_velocity (list[float] | None) – The angular velocity to set.. Defaults to None.

  • use_local (bool) – Whether to use the object’s coordinate system. Defaults to False.

Return type:

None

class voraus_simulation.pub_traits.VisuTraits

Bases: VisuTraits

Defines non physic traits, which are used for visualization only.

deregister_visualization_object()

Deregister a visualization object.

Return type:

None

get_glb_source()

Gets the glb source path or url if set.

Return type:

str | None

Returns:

The glb source path or url if set else None.

get_obj_file()

Gets the obj file path if set.

Return type:

str | None

Returns:

The obj file path if set else None.

get_visu_data()

Overwritable method for getting the data for visualizing the simulated object.

Return type:

list

Returns:

The data for visualizing the simulated object.

load_glb(glb_file, pose, unique_material=False)

Loads glb files into the visualization.

Parameters:

  • glb_file (Path | str) – The local glb file path or glb file url as string.

  • pose (Pose) – The initial pose of the object for visualizing it.

  • unique_material (bool) – Results in additional copying of the material properties.

Return type:

None

load_obj(obj_file, pose, unique_material=False)

Loads obj files into the visualization.

Parameters:

  • obj_file (Path) – The local obj file path.

  • pose (Pose) – The initial pose of the object for visualizing it.

  • unique_material (bool) – Results in additional copying of the material properties.

Return type:

None

register_visualization_object()

Registers an object for visualization purposes with the context.

Return type:

None

property visu: Visu

Returns the visualization client object.

Returns:

The visualization client object.

property visu_object: Model

Returns the visu_object for interacting with object in the visualization.

Raises:

RuntimeError – If the object was not loaded into the visualization.

Returns:

The visu_object for interacting with object in the visualization.

property visu_simulation_object: Model

Returns the simulation visu_object for interacting with object in the visualization.

Raises:

RuntimeError – If the object was not loaded into the visualization.

Returns:

The visu_object for interacting with object in the visualization.

voraus_simulation.bullet_types

Contains types.

class voraus_simulation.engines.bullet.types.Constraint(parent, child, parent_frame_position, child_frame_position, parent_frame_orientation=None, child_frame_orientation=None, parent_link_index=-1, child_link_index=-1, joint_type=Joint.FIXED, joint_axis=None)

Bases: Constraint

Initializes a constraint.

Parameters:

  • parent (int) – The id of the parent object.

  • child (int) – The id of the child object.

  • parent_frame_position (list[float]) – The position of the joint frame relative to parent center of mass frame.

  • child_frame_position (list[float]) – The position of the joint frame relative to a given child center of mass frame (or world origin if no child specified).

  • parent_frame_orientation (list[float] | None) – The orientation of the joint frame relative to parent center of mass coordinate frame. Defaults to None.

  • child_frame_orientation (list[float] | None) – The orientation of the joint frame relative to the child center of mass coordinate frame (or world origin frame if no child specified). Defaults to None.

  • parent_link_index (int) – The parent link index. Defaults to -1 for the base.

  • child_link_index (int) – The child link index. Defaults to -1 for the base.

  • joint_type (Joint) – The joint type of the constraint. Defaults to Joint.FIXED.

  • joint_axis (list[float] | None) – The joint axis in child link frame. Defaults to None.

change(joint_child_pivot=None, joint_child_frame_orientation=None, max_force=None, gear_ratio=None, erp=None)

Changes parameters of the constraint.

Parameters:

  • joint_child_pivot (list[float] | None) – The updated child pivot. Defaults to None.

  • joint_child_frame_orientation (list[float] | None) – The updated child frame orientation as quaternion. Defaults to None.

  • max_force (float | None) – Maximum force that constraint can apply.

  • gear_ratio (float | None) – Ratio between the rates at which the two gears rotate

  • erp (float | None) – Constraint error reduction parameter.

Raises:

RuntimeError – If constraint already removed.

Return type:

None

remove()

Deletes the constraint.

Raises:

RuntimeError – If constraint already removed.

Return type:

None

class voraus_simulation.engines.bullet.types.Intersection(object_unique_id, link_index, hit_fraction, hit_position, hit_normal)

Bases: object

Defines a intersection.

classmethod from_list(values)

Initializes a intersection from a list.

Parameters:

values (list) – The values to initialize the intersection with.

Return type:

Intersection

Returns:

The intersection.

classmethod from_nested_list(list_of_lists)

Initializes multiple intersections from a nested list.

Parameters:

list_of_lists (list[list]) – A list containing intersection values as a list itself.

Return type:

list[Intersection]

Returns:

The intersections.

hit_fraction: float
hit_normal: list[float]
hit_position: list[float]
object_unique_id: int
class voraus_simulation.engines.bullet.types.Joint(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Joint types for bullet engine.

FIXED = 4
GEAR = 6
PLANAR = 3
POINT2POINT = 5
PRISMATIC = 1
REVOLUTE = 0
SPHERICAL = 2
class voraus_simulation.engines.bullet.types.JointState(joint_position, joint_velocity, joint_reaction_forces, applied_joint_motor_torque)

Bases: object

Defines a joint state.

applied_joint_motor_torque: float
classmethod from_list(values)

Initializes a joint state from a list.

Parameters:

values (list) – The values to initialize the joint state with.

Return type:

JointState

Returns:

The joint state.

joint_position: float
joint_reaction_forces: list[float]
joint_velocity: float
class voraus_simulation.engines.bullet.types.LinkState(link_world_position, link_world_orientation, local_inertial_frame_position, local_inertial_frame_orientation, world_link_frame_position, world_link_frame_orientation, world_link_linear_velocity, world_link_angular_velocity)

Bases: object

Defines a link state.

classmethod from_list(values)

Initializes a link state from a list.

Parameters:

values (list) – The values to initialize the link state with.

Return type:

LinkState

Returns:

The link state.

classmethod from_nested_list(list_of_lists)

Initializes multiple link states from a nested list.

Parameters:

list_of_lists (list[list]) – A list containing link state values as a list itself.

Return type:

list[LinkState]

Returns:

The link states.

local_inertial_frame_orientation: list[float]
local_inertial_frame_position: list[float]
class voraus_simulation.engines.bullet.types.Points(contact_flag, body_unique_id_a, body_unique_id_b, link_index_a, link_index_b, position_on_a, position_on_b, contact_normal_on_b, contact_distance, normal_force, lateral_friction_1, lateral_friction_dir_1, lateral_friction_2, lateral_friction_dir_2)

Bases: object

Defines points between two objects.

body_unique_id_a: int
body_unique_id_b: int
contact_distance: float
contact_flag: int
contact_normal_on_b: list[float]
classmethod from_list(values)

Initializes points from a list.

Parameters:

values (list) – The values to initialize the points with.

Return type:

Points

Returns:

The points.

classmethod from_nested_list(list_of_lists)

Initializes a multiple points from a nested list.

Parameters:

list_of_lists (list[list]) – A list containing point values as a list itself.

Return type:

list[Points]

Returns:

The points.

lateral_friction_1: float
lateral_friction_2: float
lateral_friction_dir_1: float
lateral_friction_dir_2: float
normal_force: float
position_on_a: list[float]
position_on_b: list[float]