Basic Shapes

Description

Basic shapes are building blocks to modify and customize your environment. All shapes are spawned by default as static objects complete with collision boundaries which can be useful to create walls and other obstacles. Dynamics can be enabled and disabled to facilitate dynamic events that are triggered by actor locations such as the sudden appearance of an obstacle crossing the path. The physics properties can also be modified to tune the physics response depending on the number of interacting actors and what they are colliding with.

Basic shapes include full support for parenting to build long kinematic chains or simply to group multiple shapes together so they can be moved by manipulating a single parent actor.

If you are using a large number of dynamic shapes, consider using Widgets instead. They have both limitations and additional features, but widgets are more efficient when spawning large numbers of dynamic actors.

See the Basic Shapes Tutorial to get a better understanding of using basic shapes in Quanser Interactive Labs.

Library

class qvl.basic_shape.QLabsBasicShape(qlabs, verbose=False)[source]

This class is for spawning both static and dynamic basic shapes.

Constants

QLabsBasicShape.ID_BASIC_SHAPE = 200

Class ID

QLabsBasicShape.SHAPE_CUBE = 0

See configurations

QLabsBasicShape.SHAPE_CYLINDER = 1

See configurations

QLabsBasicShape.SHAPE_SPHERE = 2

See configurations

QLabsBasicShape.SHAPE_CONE = 3

See configurations

QLabsBasicShape.COMBINE_AVERAGE = 0
QLabsBasicShape.COMBINE_MIN = 1
QLabsBasicShape.COMBINE_MULTIPLY = 2
QLabsBasicShape.COMBINE_MAX = 3

Member Variables

QLabsBasicShape.actorNumber = None

The current actor number of this class to be addressed. This will be set by spawn methods and cleared by destroy methods. It will not be modified by the destroy all actors. This can be manually altered at any time to use one object to address multiple actors.

Methods

QLabsBasicShape.__init__(qlabs, verbose=False)[source]

Constructor Method

Parameters
  • qlabs (object) – A QuanserInteractiveLabs object

  • verbose (boolean) – (Optional) Print error information to the console.

QLabsBasicShape.spawn(location=[0, 0, 0], rotation=[0, 0, 0], scale=[1, 1, 1], configuration=0, waitForConfirmation=True)

Spawns a new actor with the next available actor number within this class.

Parameters
  • location (float array[3]) – (Optional) An array of floats for x, y and z coordinates

  • rotation (float array[3]) – (Optional) An array of floats for the roll, pitch, and yaw in radians

  • scale (float array[3]) – (Optional) An array of floats for the scale in the x, y, and z directions. Scale values of 0.0 should not be used.

  • configuration (uint32) – (Optional) Spawn configuration. See class library for configuration options.

  • waitForConfirmation (boolean) – (Optional) Make this operation blocking until confirmation of the spawn has occurred. Note that if this is False, the returned actor number will be invalid.

Returns

  • status - 0 if successful, 1 class not available, 3 unknown error, -1 communications error.

  • actorNumber - An actor number to use for future references.

Return type

int32, int32

QLabsBasicShape.spawn_degrees(location=[0, 0, 0], rotation=[0, 0, 0], scale=[1, 1, 1], configuration=0, waitForConfirmation=True)

Spawns a new actor with the next available actor number within this class.

Parameters
  • location (float array[3]) – (Optional) An array of floats for x, y and z coordinates

  • rotation (float array[3]) – (Optional) An array of floats for the roll, pitch, and yaw in degrees

  • scale (float array[3]) – (Optional) An array of floats for the scale in the x, y, and z directions. Scale values of 0.0 should not be used.

  • configuration (uint32) – (Optional) Spawn configuration. See class library for configuration options.

  • waitForConfirmation (boolean) – (Optional) Make this operation blocking until confirmation of the spawn has occurred. Note that if this is False, the returned actor number will be invalid.

Returns

  • status - 0 if successful, 1 class not available, 3 unknown error, -1 communications error.

  • actorNumber - An actor number to use for future references.

Return type

int32, int32

QLabsBasicShape.spawn_id(actorNumber, location=[0, 0, 0], rotation=[0, 0, 0], scale=[1, 1, 1], configuration=0, waitForConfirmation=True)

Spawns a new actor.

Parameters
  • actorNumber (uint32) – User defined unique identifier for the class actor in QLabs

  • location (float array[3]) – (Optional) An array of floats for x, y and z coordinates

  • rotation (float array[3]) – (Optional) An array of floats for the roll, pitch, and yaw in radians

  • scale (float array[3]) – (Optional) An array of floats for the scale in the x, y, and z directions. Scale values of 0.0 should not be used.

  • configuration (uint32) – (Optional) Spawn configuration. See class library for configuration options.

  • waitForConfirmation (boolean) – (Optional) Make this operation blocking until confirmation of the spawn has occurred.

Returns

  • status - 0 if successful, 1 class not available, 2 actor number not available or already in use, 3 unknown error, -1 communications error

Return type

int32

QLabsBasicShape.spawn_id_degrees(actorNumber, location=[0, 0, 0], rotation=[0, 0, 0], scale=[1, 1, 1], configuration=0, waitForConfirmation=True)

Spawns a new actor.

Parameters
  • actorNumber (uint32) – User defined unique identifier for the class actor in QLabs

  • location (float array[3]) – (Optional) An array of floats for x, y and z coordinates

  • rotation (float array[3]) – (Optional) An array of floats for the roll, pitch, and yaw in radians

  • scale (float array[3]) – (Optional) An array of floats for the scale in the x, y, and z directions. Scale values of 0.0 should not be used.

  • configuration (uint32) – (Optional) Spawn configuration. See class library for configuration options.

  • waitForConfirmation (boolean) – (Optional) Make this operation blocking until confirmation of the spawn has occurred.

Returns

  • status - 0 if successful, 1 class not available, 2 actor number not available or already in use, 3 unknown error, -1 communications error

Return type

int32

QLabsBasicShape.spawn_id_and_parent_with_relative_transform(actorNumber, location=[0, 0, 0], rotation=[0, 0, 0], scale=[1, 1, 1], configuration=0, parentClassID=0, parentActorNumber=0, parentComponent=0, waitForConfirmation=True)

Spawns a new actor relative to an existing actor and creates a kinematic relationship.

Parameters
  • actorNumber (uint32) – User defined unique identifier for the class actor in QLabs

  • location (float array[3]) – (Optional) An array of floats for x, y and z coordinates

  • rotation (float array[3]) – (Optional) An array of floats for the roll, pitch, and yaw in radians

  • scale (float array[3]) – (Optional) An array of floats for the scale in the x, y, and z directions. Scale values of 0.0 should not be used.

  • configuration (uint32) – (Optional) Spawn configuration. See class library for configuration options.

  • parentClassID (uint32) – See the ID variables in the respective library classes for the class identifier

  • parentActorNumber (uint32) – User defined unique identifier for the class actor in QLabs

  • parentComponent (uint32) – 0 for the origin of the parent actor, see the parent class for additional reference frame options

  • waitForConfirmation (boolean) – (Optional) Make this operation blocking until confirmation of the spawn has occurred.

Returns

  • status - 0 if successful, 1 class not available, 2 actor number not available or already in use, 3 cannot find the parent actor, 4 unknown error, -1 communications error

Return type

int32

QLabsBasicShape.spawn_id_and_parent_with_relative_transform_degrees(actorNumber, location=[0, 0, 0], rotation=[0, 0, 0], scale=[1, 1, 1], configuration=0, parentClassID=0, parentActorNumber=0, parentComponent=0, waitForConfirmation=True)

Spawns a new actor relative to an existing actor and creates a kinematic relationship.

Parameters
  • actorNumber (uint32) – User defined unique identifier for the class actor in QLabs

  • location (float array[3]) – (Optional) An array of floats for x, y and z coordinates

  • rotation (float array[3]) – (Optional) An array of floats for the roll, pitch, and yaw in degrees

  • scale (float array[3]) – (Optional) An array of floats for the scale in the x, y, and z directions. Scale values of 0.0 should not be used.

  • configuration (uint32) – (Optional) Spawn configuration. See class library for configuration options.

  • parentClassID (uint32) – See the ID variables in the respective library classes for the class identifier

  • parentActorNumber (uint32) – User defined unique identifier for the class actor in QLabs

  • parentComponent (uint32) – 0 for the origin of the parent actor, see the parent class for additional reference frame options

  • waitForConfirmation (boolean) – (Optional) Make this operation blocking until confirmation of the spawn has occurred.

Returns

  • status - 0 if successful, 1 class not available, 2 actor number not available or already in use, 3 cannot find the parent actor, 4 unknown error, -1 communications error

Return type

int32

QLabsBasicShape.set_material_properties(color, roughness=0.4, metallic=False, waitForConfirmation=True)[source]

Sets the visual surface properties of the shape.

Parameters
  • color (float array[3]) – Red, Green, Blue components of the RGB color on a 0.0 to 1.0 scale.

  • roughness (float) – A value between 0.0 (completely smooth and reflective) to 1.0 (completely rough and diffuse). Note that reflections are rendered using screen space reflections. Only objects visible in the camera view will be rendered in the reflection of the object.

  • metallic (boolean) – Metallic (True) or non-metallic (False)

  • waitForConfirmation (boolean) – (Optional) Wait for confirmation of the operation before proceeding. This makes the method a blocking operation.

Returns

True if successful, False otherwise

Return type

boolean

QLabsBasicShape.get_material_properties()[source]

Gets the visual surface properties of the shape.

Returns

  • status - True if successful or False otherwise

  • color - Red, Green, Blue components of the RGB color on a 0.0 to 1.0 scale.

  • roughness - A value between 0.0 (completely smooth and reflective) to 1.0 (completely rough and diffuse).

  • metallic - Metallic (True) or non-metallic (False)

Return type

boolean, float array[3], float, boolean

QLabsBasicShape.set_enable_dynamics(enableDynamics, waitForConfirmation=True)[source]

Sets the visual surface properties of the shape.

Parameters
  • enableDynamics (boolean) – Enable (True) or disable (False) the shape dynamics. A dynamic actor can be pushed with other static or dynamic actors. A static actor will generate collisions, but will not be affected by interactions with other actors.

  • waitForConfirmation (boolean) – (Optional) Wait for confirmation of the operation before proceeding. This makes the method a blocking operation.

Returns

True if successful, False otherwise

Return type

boolean

QLabsBasicShape.set_enable_collisions(enableCollisions, waitForConfirmation=True)[source]

Enables and disables physics collisions. When disabled, other physics or velocity-based actors will be able to pass through.

Parameters
  • enableCollisions (boolean) – Enable (True) or disable (False) the collision.

  • waitForConfirmation (boolean) – (Optional) Wait for confirmation of the operation before proceeding. This makes the method a blocking operation.

Returns

True if successful, False otherwise

Return type

boolean

QLabsBasicShape.set_physics_properties(enableDynamics, mass=1.0, linearDamping=0.01, angularDamping=0.0, staticFriction=0.0, dynamicFriction=0.7, frictionCombineMode=COMBINE_AVERAGE, restitution=0.3, restitutionCombineMode=COMBINE_AVERAGE, waitForConfirmation=True)[source]

Sets the dynamic properties of the shape.

Parameters
  • enableDynamics (boolean) – Enable (True) or disable (False) the shape dynamics. A dynamic actor can be pushed with other static or dynamic actors. A static actor will generate collisions, but will not be affected by interactions with other actors.

  • mass (float) – (Optional) Sets the mass of the actor in kilograms.

  • linearDamping (float) – (Optional) Sets the damping of the actor for linear motions.

  • angularDamping (float) – (Optional) Sets the damping of the actor for angular motions.

  • staticFriction (float) – (Optional) Sets the coefficient of friction when the actor is at rest. A value of 0.0 is frictionless.

  • dynamicFriction (float) – (Optional) Sets the coefficient of friction when the actor is moving relative to the surface it is on. A value of 0.0 is frictionless.

  • frictionCombineMode (byte) – (Optional) Defines how the friction between two surfaces with different coefficients should be calculated (see COMBINE constants).

  • restitution (float) – (Optional) The coefficient of restitution defines how plastic or elastic a collision is. A value of 0.0 is plastic and will absorb all energy. A value of 1.0 is elastic and will bounce forever. A value greater than 1.0 will add energy with each collision.

  • restitutionCombineMode (byte) – (Optional) Defines how the restitution between two surfaces with different coefficients should be calculated (see COMBINE constants).

  • waitForConfirmation (boolean) – (Optional) Wait for confirmation of the operation before proceeding. This makes the method a blocking operation.

Returns

True if successful, False otherwise

Return type

boolean

QLabsBasicShape.set_transform(location, rotation, scale, waitForConfirmation=True)[source]

Sets the location, rotation in radians, and scale. If a shape is parented to another actor then the location, rotation, and scale are relative to the parent actor.

Parameters
  • location (float array[3]) – An array of floats for x, y and z coordinates in full-scale units.

  • rotation (float array[3]) – An array of floats for the roll, pitch, and yaw in radians

  • scale (float array[3]) – An array of floats for the scale in the x, y, and z directions.

  • waitForConfirmation (boolean) – (Optional) Wait for confirmation of the operation before proceeding. This makes the method a blocking operation.

Returns

True if successful or False otherwise

Return type

boolean

QLabsBasicShape.set_transform_degrees(location, rotation, scale, waitForConfirmation=True)[source]

Sets the location, rotation in degrees, and scale. If a shape is parented to another actor then the location, rotation, and scale are relative to the parent actor.

Parameters
  • location (float array[3]) – An array of floats for x, y and z coordinates in full-scale units.

  • rotation (float array[3]) – An array of floats for the roll, pitch, and yaw in degrees

  • scale (float array[3]) – An array of floats for the scale in the x, y, and z directions.

  • waitForConfirmation (boolean) – (Optional) Wait for confirmation of the operation before proceeding. This makes the method a blocking operation.

Returns

True if successful or False otherwise

Return type

boolean

QLabsBasicShape.spawn_id_box_walls_from_end_points(actorNumber, startLocation, endLocation, height, thickness, color=[1, 1, 1], waitForConfirmation=True)[source]

Given a start and end point, this helper method calculates the position, rotation, and scale required to place a box on top of this line.

Parameters
  • actorNumber (uint32) – User defined unique identifier for the class actor in QLabs

  • startLocation (float array[3]) – An array of floats for x, y and z coordinates.

  • endLocation (float array[3]) – An array of floats for x, y and z coordinates.

  • height (float) – The height of the wall.

  • thickness (float) – The width or thickness of the wall.

  • color (float array[3]) – Red, Green, Blue components of the RGB color on a 0.0 to 1.0 scale.

  • waitForConfirmation (boolean) – (Optional) Wait for confirmation of the operation before proceeding. This makes the method a blocking operation.

Returns

True if successful or False otherwise

Return type

boolean

QLabsBasicShape.spawn_id_box_walls_from_center(actorNumbers, centerLocation, yaw, xSize, ySize, zHeight, wallThickness, floorThickness=0, wallColor=[1, 1, 1], floorColor=[1, 1, 1], waitForConfirmation=True)[source]

Creates a container-like box with 4 walls and an optional floor.

Parameters
  • actorNumbers (uint32 array[5]) – An array of 5 user defined unique identifiers for the class actors in QLabs.

  • centerLocation (float array[3]) – An array of floats for x, y and z coordinates.

  • yaw (float) – Rotation about the z axis in radians.

  • xSize (float) – Size of the box in the x direction.

  • ySize (float) – Size of the box in the y direction.

  • zSize (float) – Size of the box in the z direction.

  • wallThickness (float) – The thickness of the walls.

  • floorThickness (float) – (Optional) The thickness of the floor. Setting this to 0 will spawn a box without a floor.

  • wallColor (float array[3]) – (Optional) Red, Green, Blue components of the wall color on a 0.0 to 1.0 scale.

  • floorColor (float array[3]) – (Optional) Red, Green, Blue components of the floor color on a 0.0 to 1.0 scale.

  • waitForConfirmation (boolean) – (Optional) Wait for confirmation of the operation before proceeding. This makes the method a blocking operation.

Returns

True if successful or False otherwise

Return type

boolean

QLabsBasicShape.spawn_id_box_walls_from_center_degrees(actorNumbers, centerLocation, yaw, xSize, ySize, zHeight, wallThickness, floorThickness=0, wallColor=[1, 1, 1], floorColor=[1, 1, 1], waitForConfirmation=True)[source]

Creates a container-like box with 4 walls and an optional floor.

Parameters
  • actorNumbers (uint32 array[5]) – An array of 5 user defined unique identifiers for the class actors in QLabs.

  • centerLocation (float array[3]) – An array of floats for x, y and z coordinates.

  • yaw (float) – Rotation about the z axis in degrees.

  • xSize (float) – Size of the box in the x direction.

  • ySize (float) – Size of the box in the y direction.

  • zSize (float) – Size of the box in the z direction.

  • wallThickness (float) – The thickness of the walls.

  • floorThickness (float) – (Optional) The thickness of the floor. Setting this to 0 will spawn a box without a floor.

  • wallColor (float array[3]) – (Optional) Red, Green, Blue components of the wall color on a 0.0 to 1.0 scale.

  • floorColor (float array[3]) – (Optional) Red, Green, Blue components of the floor color on a 0.0 to 1.0 scale.

  • waitForConfirmation (boolean) – (Optional) Wait for confirmation of the operation before proceeding. This makes the method a blocking operation.

Returns

True if successful or False otherwise

Return type

boolean

QLabsBasicShape.destroy()

Find and destroy a specific actor. This is a blocking operation.

Returns

  • numActorsDestroyed - The number of actors destroyed. -1 if failed.

Return type

int32

QLabsBasicShape.destroy_all_actors_of_class()

Find and destroy all actors of this class. This is a blocking operation.

Returns

  • numActorsDestroyed - The number of actors destroyed. -1 if failed.

Return type

int32

QLabsBasicShape.get_world_transform()

Get the location, rotation, and scale in world coordinates of the actor.

Returns

  • status - True if successful, False otherwise

  • location

  • rotation

  • scale

Return type

boolean, float array[3], float array[3], float array[3]

QLabsBasicShape.get_world_transform_degrees()

Get the location, rotation, and scale in world coordinates of the actor.

Returns

  • status - True if successful, False otherwise

  • location

  • rotation

  • scale

Return type

boolean, float array[3], float array[3], float array[3]

QLabsBasicShape.ping()

Checks if the actor is still present in the environment. Note that if you did not spawn the actor with one of the spawn functions, you may need to manually set the actorNumber member variable.

Returns

  • status - True if successful, False otherwise

Return type

boolean

QLabsBasicShape.parent_with_relative_transform(location=[0, 0, 0], rotation=[0, 0, 0], scale=[1, 1, 1], parentClassID=0, parentActorNumber=0, parentComponent=0, waitForConfirmation=True)

Parents one existing actor to another to create a kinematic relationship.

Parameters
  • location (float array[3]) – (Optional) An array of floats for x, y and z coordinates

  • rotation (float array[3]) – (Optional) An array of floats for the roll, pitch, and yaw in radians

  • scale (float array[3]) – (Optional) An array of floats for the scale in the x, y, and z directions. Scale values of 0.0 should not be used.

  • parentClassID (uint32) – See the ID variables in the respective library classes for the class identifier

  • parentActorNumber (uint32) – User defined unique identifier for the class actor in QLabs

  • parentComponent (uint32) – 0 for the origin of the parent actor, see the parent class for additional reference frame options

  • waitForConfirmation (boolean) – (Optional) Make this operation blocking until confirmation of the spawn has occurred.

Returns

  • status - 0 if successful, 1 cannot find this actor, 2 cannot find the parent actor, 3 unknown error, -1 communications error

Return type

int32

QLabsBasicShape.parent_with_relative_transform_degrees(location=[0, 0, 0], rotation=[0, 0, 0], scale=[1, 1, 1], parentClassID=0, parentActorNumber=0, parentComponent=0, waitForConfirmation=True)

Parents one existing actor to another to create a kinematic relationship.

Parameters
  • location (float array[3]) – (Optional) An array of floats for x, y and z coordinates

  • rotation (float array[3]) – (Optional) An array of floats for the roll, pitch, and yaw in degrees

  • scale (float array[3]) – (Optional) An array of floats for the scale in the x, y, and z directions. Scale values of 0.0 should not be used.

  • parentClassID (uint32) – (Optional) See the ID variables in the respective library classes for the class identifier

  • parentActorNumber (uint32) – (Optional) User defined unique identifier for the class actor in QLabs

  • parentComponent (uint32) – (Optional) 0 for the origin of the parent actor, see the parent class for additional reference frame options

  • waitForConfirmation (boolean) – (Optional) Make this operation blocking until confirmation of the spawn has occurred.

Returns

  • status - 0 if successful, 1 cannot find this actor, 2 cannot find the parent actor, 3 unknown error, -1 communications error

Return type

int32

QLabsBasicShape.parent_with_current_world_transform(parentClassID=0, parentActorNumber=0, parentComponent=0, waitForConfirmation=True)

Parents one existing actor to another to create a kinematic relationship while preserving the current world transform of the child actor.

Parameters
  • parentClassID (uint32) – See the ID variables in the respective library classes for the class identifier

  • parentActorNumber (uint32) – User defined unique identifier for the class actor in QLabs

  • parentComponent (uint32) – 0 for the origin of the parent actor, see the parent class for additional reference frame options

  • waitForConfirmation (boolean) – (Optional) Make this operation blocking until confirmation of the spawn has occurred.

Returns

  • status - 0 if successful, 1 cannot find this actor, 2 cannot find the parent actor, 3 unknown error, -1 communications error

Return type

int32

QLabsBasicShape.parent_break(waitForConfirmation=True)

Breaks any relationship with a parent actor (if it exists) and preserves the current world transform

Parameters

waitForConfirmation (boolean) – (Optional) Make this operation blocking until confirmation of the spawn has occurred.

Returns

  • status - 0 if successful, 1 cannot find this actor, -1 communications error

Return type

int32

QLabsBasicShape.set_custom_properties(measuredMass=0, IDTag=0, properties='', waitForConfirmation=True)

Assigns custom properties to an actor.

Parameters
  • measuredMass (float) – A float value for use with mass sensor instrumented actors. This does not alter the dynamic properties.

  • IDTag (uint32) – An integer value for use with IDTag sensor instrumented actors or for custom use.

  • properties (string) – A string for use with properties sensor instrumented actors. This can contain any string that is available for use to parse user-customized parameters.

  • waitForConfirmation (boolean) – (Optional) Make this operation blocking until confirmation of the spawn has occurred.

Returns

  • status - True if successful, False otherwise

Return type

boolean

QLabsBasicShape.get_custom_properties()

Gets previously assigned custom properties to an actor.

Returns

  • status - True if successful, False otherwise

  • measuredMass - float value

  • IDTag - integer value

  • properties - UTF-8 string

Return type

boolean, float, int32, string

Configurations

There are four configurations (0-3) for the basic shape actor class.

  • 0 - Cube

  • 1 - Cylinder

  • 2 - Sphere

  • 3 - Cone

../_images/configuration_basicshapes.png

Connection Points

There are no connection points for this actor class.


Basic Shapes Tutorial