Animals

Description

Animals are considered “actors” in the Open World Workspaces. The animal library controls the animals placed in Quanser Interactive Labs.

Animal actors can be spawned anywhere in the open worlds, but to use the move_to methods to allow the people to self-navigate around the environment, they must originate and travel to a connected valid nav area.

For the best visual animation, it is recommended that you use the speed constants defining different gait styles. A character will accurately travel at any specified speed up to 6m/s, but the visual animation may give the impression of “slipping” at certain speeds outside the recommended values.

Library

class qvl.animal.QLabsAnimal(qlabs, verbose=False)[source]: This class implements spawning and AI navigation of the environment for animals.

Constants

QLabsAnimal.ID_ANIMAL = 10031

QLabsAnimal.GOAT = 0: Configuration constant.

QLabsAnimal.SHEEP = 1: Configuration constant.

QLabsAnimal.COW = 2: Configuration constant.

QLabsAnimal.GOAT_STANDING = 0: Speed constant for the move_to method.

QLabsAnimal.GOAT_WALK = 0.8: Speed constant for the move_to method.

QLabsAnimal.GOAT_RUN = 4.0: Speed constant for the move_to method.

QLabsAnimal.SHEEP_STANDING = 0: Speed constant for the move_to method.

QLabsAnimal.SHEEP_WALK = 0.6: Speed constant for the move_to method.

QLabsAnimal.SHEEP_RUN = 3.0: Speed constant for the move_to method.

QLabsAnimal.COW_STANDING = 0: Speed constant for the move_to method.

QLabsAnimal.COW_WALK = 1.0: Speed constant for the move_to method.

QLabsAnimal.COW_RUN = 6.0: Speed constant for the move_to method.

Member Variables

QLabsAnimal.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

QLabsAnimal.enable_collision(enable, waitForConfirmation=True)[source]

Allows for the animal to respond and track the number of external collisions. Note that at least one collision filter must also be added.

Parameters

enable (boolean) – Enable or disable the collision response.
waitForConfirmation (boolean) – (Optional) Wait for confirmation of the before proceeding. This makes the method a blocking operation.

Returns

True if successful, False otherwise.

Return type

boolean

QLabsAnimal.add_collision_filter(class_id, waitForConfirmation=True)[source]

When collisions are enabled, the animal will respond to hits from any actor of this class. This function may be called multiple times to add multiple classes.

Parameters

class_id – The actor class number to which the person should respond to.
waitForConfirmation (boolean) – (Optional) Wait for confirmation of the before proceeding. This makes the method a blocking operation.

Returns

True if successful, False otherwise.

Return type

boolean

QLabsAnimal.get_collision_count()[source]

Get the total number of collisions this actor has experienced. Note that collisions must be enabled and at least one collision filter set for this count to be active.

Returns

status - True if successful or False otherwise
count - Number of hits the actor has registered

Return type

boolean, int32

Parent Class (actor.py) Methods

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

Constructor method

Parameters

qlabs (object) – A QuanserInteractiveLabs object
verbose (boolean) – (Optional) Print error information to the console.

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

Tip

The origin of the animal is in the center of the body so by default, it will be spawned 1m above the surface of the target. An additional vertical offset may be required if the surface is sloped to prevent the actor from falling through the world ground surface.

Tip

If you would like to use the move_to method, the actor must be spawned in a valid nav area.

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

Tip

The origin of the animal is in the center of the body so by default, it will be spawned 1m above the surface of the target. An additional vertical offset may be required if the surface is sloped to prevent the actor from falling through the world ground surface.

Tip

If you would like to use the move_to method, the actor must be spawned in a valid nav area.

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

Tip

The origin of the animal is in the center of the body so by default, it will be spawned 1m above the surface of the target. An additional vertical offset may be required if the surface is sloped to prevent the actor from falling through the world ground surface.

Tip

If you would like to use the move_to method, the actor must be spawned in a valid nav area.

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

Tip

The origin of the animal is in the center of the body so by default, it will be spawned 1m above the surface of the target. An additional vertical offset may be required if the surface is sloped to prevent the actor from falling through the world ground surface.

Tip

If you would like to use the move_to method, the actor must be spawned in a valid nav area.

QLabsAnimal.move_to(location, speed, waitForConfirmation=True)

Commands an actor to move from the present location to a new target location by using AI path navigation.

Parameters

location (float array[3]) – A target destination as an array of floats for x, y and z coordinates in full-scale units.
speed (float) – The speed at which the person should walk to the destination (refer to the constants for recommended speeds)
waitForConfirmation (boolean) – (Optional) Wait for confirmation before proceeding. This makes the method a blocking operation, but only until the command is received. The time for the actor to traverse to the destination is always non-blocking.

Returns

status - True if successful, False otherwise

Return type

boolean

Tip

Ensure the start and end locations are in valid navigation areas so the actor can find a path to the destination.

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

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

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

QLabsAnimal.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]

QLabsAnimal.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]

Configurations

There are 3 configurations (0-2) for a animal generated in QLabs.

Connection Points

There are no connection points for the animal actor.

Animals Tutorial

Python Tutorial

Raw to download this tutorial: Animals Tutorial (.py).

"""
Animal Example
---------------

.. note::

    Make sure you have Quanser Interactive Labs open before running this
    example.  This example is designed to run in the QCar Cityscape.

"""
 
from qvl import qlabs
from qvl.animal import QLabsAnimal
from qvl.qlabs import QuanserInteractiveLabs
from qvl.free_camera import QLabsFreeCamera 
from qvl.environment_outdoors import QLabsEnvironmentOutdoors
from qvl.system import QLabsSystem

import time
import os
import math


# initialize our variables
# note that you can use the ..Coordinate Helper to pick locations for your actor.
LOCATION_START_P1 = [-6.85, 40.396, 0.005]
ROTATION_P1P2 = [0,0,math.pi/2]
SCALE = [1,1,1]

LOCATION_START_P2 = [-8.53, 40.7, 0.005]
LOCATION_START_P3 = [-11.884, 40.292, 0.005]
ROTATION_P3 = [0,0,90]

LOCATION_END_P1 = [-7.637, 51, 0.005]
LOCATION_END_P2 = [-11.834, 51, 0.005]
LOCATION_END_P3 = [-23.71, 43.245, 0.005]


def main():

    print("\n\n------------- Communications -------------------\n")

    # Creates a server connection with Quanser Interactive Labs and manages
    # the communications
    qlabs = QuanserInteractiveLabs()

    # Ensure that QLabs is running on your local machine
    print("Connecting to QLabs...")
    if (not qlabs.open("localhost")):
        print("Unable to connect to QLabs")
        return   

    print("Connected")

    # Use hSystem to set the tutorial title on the qlabs display screen
    hSystem = QLabsSystem(qlabs)
    hSystem.set_title_string('Animals Tutorial')

    num_destroyed = qlabs.destroy_all_spawned_actors()

    # create a camera in this qlabs instance
    camera = QLabsFreeCamera(qlabs)

    #place the custom camera at a specified location and rotation using radians
    camera.spawn([-0., 43.807, 8.82], [-0, 0.606, 3.127])

    # to switch our view from our current camera to the new camera we just initialized to
    # be able to view where our animals will spawn
    camera.possess()

    # Animal configurations 
    #
    #   Goat = 0
    #   Sheep = 1
    #   Cow = 2

    # creates an instance of the Animal
    goat = QLabsAnimal(qlabs)

    # place the Animal at a specified location and rotation using radians
    # spawn_id allows us to specify the internal number for the actor
    goat.spawn_id(0, LOCATION_START_P1, ROTATION_P1P2, SCALE, 0, True)

    # creates a second instance of a animal
    sheep = QLabsAnimal(qlabs)

    # place the animal at a specified location and rotation using radians
    # spawn creates the internal number for the actor automatically using
    # the next available actor number
    sheep.spawn(LOCATION_START_P2, ROTATION_P1P2, SCALE, 1, True)

    # creates a third instance of a animal
    cow = QLabsAnimal(qlabs, True)

    # place the animal at a specified location and rotation using degrees
    # spawn_degrees creates the internal number for the actor automatically using the next
    # available number and takes the inputted rotation as degrees
    cow.spawn_degrees(LOCATION_START_P3, ROTATION_P3, SCALE, 2, True)

    # move the 3 people created to a new location
    goat.move_to(LOCATION_END_P1, goat.GOAT_WALK, True)
    sheep.move_to(LOCATION_END_P2, sheep.SHEEP_RUN, True)
    cow.move_to(LOCATION_END_P3, cow.COW_RUN, True)

    # time.sleep to change camera angle 
    time.sleep(7)

    # destroy each animal one by one 
    goat.destroy()
    time.sleep(1)

    sheep.destroy()
    time.sleep(1)

    cow.destroy()
    time.sleep(1)

    # re position camera
    hCameraAnimals = QLabsFreeCamera(qlabs)
    x = hCameraAnimals.spawn([25.243, 46.069, 1.628], [-0, 0.188, 1.098])
    hCameraAnimals.possess()

    # Spawn a Goat and make it run to a specific location  
    hGoat = QLabsAnimal(qlabs)
    hGoat.spawn([26.206, 57, 1], [0,0,0], [1,1,1], hGoat.GOAT, True)
    hGoat.move_to([27.214, 49.286, 0], hGoat.GOAT_RUN, True)
    time.sleep(3)

    # Move the Goat at walking speed to your desired location 
    hGoat.move_to([28.338, 47.826, 0], hGoat.GOAT_WALK, True)
    time.sleep(4)
    hGoat.destroy()

    # Spawn a Sheep and make it run to a specific location
    hSheep = QLabsAnimal(qlabs)
    hSheep.spawn([26.206, 57, 1], [0,0,0], [1,1,1], hSheep.SHEEP, True)
    hSheep.move_to([27.214, 49.286, 0], hSheep.SHEEP_RUN, True)
    time.sleep(3)

    # Move the Sheep at walking speed to your desired location
    hSheep.move_to([28.338, 47.826, 0], hSheep.SHEEP_WALK, True)
    time.sleep(4)
    hSheep.destroy()

    # Spawn a Cow and make it run to a specific location
    hCow = QLabsAnimal(qlabs)
    hCow.spawn([26.206, 57, 1], [0,0,0], [1,1,1], hCow.COW, True)
    hCow.move_to([27.214, 49.286, 0], hCow.COW_RUN, True)
    time.sleep(3)

    # Move the Cow at walking speed to your desired location
    hCow.move_to([28.338, 47.826, 0], hCow.COW_WALK, True)
    time.sleep(6)
    
    # Close qlabs
    qlabs.close()
    print('Done!')

if __name__ == "__main__":
    main()

Matlab Tutorial

Raw to download this tutorial: Animals Tutorial (.m).

% Animal Example
% -------------------------
% 
% .. note::
% 
%     Make sure you have Quanser Interactive Labs open before running this
%     example.  This example is designed to best be run in QCar Cityscape.

close all;
clear all;
clc;

% --------------------------------------------------------------
% Setting MATLAB Path for the libraries
% Always keep at the start, it will make sure it finds the correct references
newPathEntry = fullfile(getenv('QAL_DIR'), '0_libraries', 'matlab', 'qvl');
pathCell = regexp(path, pathsep, 'split');
if ispc  % Windows is not case-sensitive
  onPath = any(strcmpi(newPathEntry, pathCell));
else
  onPath = any(strcmp(newPathEntry, pathCell));
end

if onPath == 0
    path(path, newPathEntry)
    savepath
end
% --------------------------------------------------------------

fprintf('\n\n----------------- Communications -------------------\n\n');

qlabs =  QuanserInteractiveLabs();
connection_established = qlabs.open('localhost');

if connection_established == false
    disp("Failed to open connection.")
    return
end

disp('Connected')

num_destroyed = qlabs.destroy_all_spawned_actors();

fprintf('%d actors destroyed', num_destroyed);

% Use hSystem to set the tutorial title on the qlabs display screen
hSystem = QLabsSystem(qlabs);
hSystem.set_title_string('Animals Tutorial')

% initialize our variables
% Note that you can use the 
% Coordinate Helper to pick locations for your actor.

LOCATION_START_P1 = [-6.85, 40.396, 0.005];
ROTATION_P1P2 = [0,0,pi/2];
SCALE = [1,1,1];

LOCATION_START_P2 = [-8.53, 40.7, 0.005];
LOCATION_START_P3 = [-11.884, 40.292, 0.005];
ROTATION_P3 = [0,0,90];

LOCATION_END_P1 = [-7.637, 51, 0.005];
LOCATION_END_P2 = [-11.834, 51, 0.005];
LOCATION_END_P3 = [-23.71, 43.245, 0.005];

% create a camera in this qlabs instance
camera = QLabsFreeCamera(qlabs);

% place the custom camera at a specified location and rotation using radians
camera.spawn([-0., 43.807, 8.82], [-0, 0.606, 3.127]);

% to switch our view from our current camera
% to the new camera we just initialized 
% to be able to view where our animals will spawn
camera.possess();

% creates an instance of the Animal
goat = QLabsAnimal(qlabs);

% Animal configurations 
%
%   Goat = 0
%   Sheep = 1
%   Cow = 2

% place the animal at a specified location and rotation using radians
% spawn_id allows us to specify the internal number for the actor
goat.spawn_id(0, LOCATION_START_P1, ROTATION_P1P2, SCALE, 0, 1);

% creates a second instance of a animal 
sheep = QLabsAnimal(qlabs);

% place the animal at a specified location and rotation using radians
% spawn creates the internal number for the actor automatically using
% the next available actor number
sheep.spawn(LOCATION_START_P2, ROTATION_P1P2, SCALE, 1, 1)

% creates a third instance of a animal
cow = QLabsAnimal(qlabs, 1);

% place the animal at a specified location and rotation using degrees
% spawn_degrees creates the internal actor number
% automatically using the next available number 
% this function also takes the input rotation as degrees
cow.spawn_degrees(LOCATION_START_P3, ROTATION_P3, SCALE, 2, 1);

% move the 3 animals created to a new location
goat.move_to(LOCATION_END_P1, goat.GOAT_WALK, 1);
sheep.move_to(LOCATION_END_P2, sheep.SHEEP_RUN, 1);
cow.move_to(LOCATION_END_P3, cow.COW_RUN, 1);

% pause to change camera
pause(7);

% destroy each animal one by one 

goat.destroy();
pause(1);

sheep.destroy();
pause(1);

cow.destroy();
pause(1);

% re position camera
hCameraAnimals = QLabsFreeCamera(qlabs);
x = hCameraAnimals.spawn([25.243, 46.069, 1.628], [-0, 0.188, 1.098]);
hCameraAnimals.possess();

% Spawn a Goat and make it run to a specific location 
hGoat = QLabsAnimal(qlabs);
hGoat.spawn([26.206, 57, 1], [0,0,0], [1,1,1], hGoat.GOAT, true);
hGoat.move_to([27.214, 49.286, 0], hGoat.GOAT_RUN, true);
pause(3);

% Move the Goat at walking speed to your desired location 
hGoat.move_to([28.338, 47.826, 0], hGoat.GOAT_WALK, true);
pause(4);
hGoat.destroy();

% Spawn a Sheep and make it run to a specific location
hSheep = QLabsAnimal(qlabs);
hSheep.spawn([26.206, 57, 1], [0,0,0], [1,1,1], hSheep.SHEEP, true);
hSheep.move_to([27.214, 49.286, 0], hSheep.SHEEP_RUN, true);
pause(3);

% Move the Sheep at walking speed to your desired location 
hSheep.move_to([28.338, 47.826, 0], hSheep.SHEEP_WALK, true);
pause(4);
hSheep.destroy();

% Spawn a Cow and make it run to a specific location
hCow = QLabsAnimal(qlabs);
hCow.spawn([26.206, 57, 1], [0,0,0], [1,1,1], hCow.COW, true);
hCow.move_to([27.214, 49.286, 0], hCow.COW_RUN, true);
pause(3);

% Move the Cow at walking speed to your desired location
hCow.move_to([28.338, 47.826, 0], hCow.COW_WALK, true);
pause(6);

% close qlabs
qlabs.close();
disp('Done !')