Cameras

Description

Cameras in the Open Worlds are used for observing the workspace from different views and capturing image data. Cameras are considered “actors”. The camera library controls the camera actors.

A camera must be initialized first by spawning the camera in the location (or attached to the parent actor of choice) in order to use it.

See the Camera Tutorial to get a better understanding of using cameras in Quanser Interactive Labs.

Camera Library

class qvl.free_camera.QLabsFreeCamera(qlabs, verbose=False)[source]: This class supports the spawning and control of free movement cameras in QLabs open worlds.

Constants

QLabsFreeCamera.ID_FREE_CAMERA = 170: Class ID

Member Variables

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

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

Constructor Method

Parameters

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

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

Scale will not affect the camera, but will affect attached children.

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

Scale will not affect the camera, but will affect attached children.

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

Scale will not affect the camera, but will affect attached children.

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

Scale will not affect the camera, but will affect attached children.

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

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

QLabsFreeCamera.possess()[source]

Possess (take control of) a camera in QLabs.

Returns: True if possessing the camera was successful, False otherwise
Return type: boolean

QLabsFreeCamera.set_camera_properties(fieldOfView, depthOfField, aperture, focusDistance)[source]

Sets the camera properties. When depthOfField is enabled, the camera will produce more realistic (and cinematic) results by adding some blur to the view at distances closer and further away from a given focal distance. For more blur, use a large aperture (small value) and a narrow field of view.

Parameters

fieldOfView (int) – The field of view that the camera can see (range:5-150 degrees). When depthOfField is True, smaller values will increase focal blur at distances relative to the focusDistance.
depthOfField (boolean) – Enable or disable the depth of field visual effect
aperture (float) – The amount of light allowed into the camera sensor (range:2.0-22.0). Smaller values (larger apertures) increase the light and decrease the depth of field. This parameter is only active when depthOfField is True.
focusDistance (float) – The distance to the focal plane of the camera. (range:0.1-50.0 meters). This parameter is only active when depthOfField is True.

Returns

True if setting the camera properties was successful, False otherwise

Return type

boolean

QLabsFreeCamera.set_transform(location, rotation)[source]

Change the location and rotation of a spawned camera in radians

Parameters

location (array[3]) – An array of floats for x, y and z coordinates
rotation (array[3]) – An array of floats for the roll, pitch, yaw in radians

Returns

True if spawn was successful, False otherwise

Return type

boolean

QLabsFreeCamera.set_transform_degrees(location, rotation)[source]

Change the location and rotation of a spawned camera in degrees

Parameters

location (array[3]) – An array of floats for x, y and z coordinates
rotation (array[3]) – An array of floats for the roll, pitch, yaw in degrees

Returns

True if spawn was successful, False otherwise

Return type

boolean

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

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

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

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

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

QLabsFreeCamera.set_image_capture_resolution(width=640, height=480)[source]

Change the default width and height of image resolution for capture

Parameters

width (uint32) – Must be an even number. Default 640
height (uint32) – Must be an even number. Default 480

Returns

True if spawn was successful, False otherwise

Return type

boolean

QLabsFreeCamera.get_image()[source]

Request an image from the camera actor. Note, set_image_capture_resolution must be set once per camera otherwise this method will fail.

Returns: Success, RGB image data
Return type: boolean, byte array[variable]

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

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

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

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

Configurations

There are no configuration options for the camera actor.

Connection Points

There are no connection points for the free camera actor.

Tip

There is a few easy steps to initializing a new camera in an environment using the interface as well as the code:

Pick a Location for your camera using the Coordinate Helper section.
Copy the location and rotation desired.
Use spawn or spawn_degrees to initialize a new camera. Paste the copied location and rotation into their respective places.

Camera Tutorial

Python Tutorial

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

"""
Free Camera Library 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.

"""
# imports to important libraries
import time
import cv2

from qvl.qlabs import QuanserInteractiveLabs
from qvl.free_camera import QLabsFreeCamera
from qvl.system import QLabsSystem

def main():

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

    # initialize our desired variables
    # note that you can use the coordinate helper to pick locations for your camera.
    loc = [-5.631, -1.467, 2.198]
    rot = [0, -2.386, -20.528]

    # trying to connect to QLabs and open the instance we have created - program will end if this fails
    print("Connecting to QLabs...")
    try:
        qlabs.open("localhost")
    except:
        print("Unable to connect to QLabs")
        return

    # destroy any spawned actors in our QLabs that currently exist
    qlabs.destroy_all_spawned_actors()

    title = QLabsSystem(qlabs)
    title.set_title_string("Camera Tutorial")

    # create a camera in this qlabs instance
    camera = QLabsFreeCamera(qlabs)
    # add a custom camera at a specified location and rotation using degrees
    camera.spawn_degrees(location=loc, rotation=rot)
    # to switch our view from our current camera to the new camera we just initialized
    camera.possess()

    time.sleep(3)

    camera.set_camera_properties(60, 1, 2.0, 1.3)

    [success, location, rotation, scale] = camera.get_world_transform()

    ping = camera.ping()

    # Take a image from the first camera angle 
    if ping:
        camera.set_image_capture_resolution()
        [success, image1] = camera.get_image()
        
        if not success:
            print("Image decoding failure")
        # if success:
        #     cv2.imshow('image1',image1)
        # else:
        #     print("Image decoding failure")
            
        
    time.sleep(2)    

    # Initialize and spawn the second camera angle 
    loc2 = [-33.17276819, 13.50500671, 2.282]
    rot2 = [0, 0.077, 0.564]
    camera2 = QLabsFreeCamera(qlabs)
    x = camera2.spawn_id(2, loc2, rot2)
    camera2.possess()

    time.sleep(2)

    camera.destroy()

    [success, location, rotation, scale] = camera2.get_world_transform()
    camera2.set_camera_properties(40, True, 2.3, 0.6)

    time.sleep(2)

    # Focus the camera 
    for y in range(1, 52):
        camera2.set_camera_properties(40, True, 2.3, (0.6 + ((y / 50) ** 3) * 23.7))

    camera.set_image_capture_resolution()

    # Take image of the second camera angle 
    [success, image2] = camera.get_image()
    print(success)

    time.sleep(2)

    # Initialize and spawn the third camera angle 
    camera3 = QLabsFreeCamera(qlabs)
    loc3 = [-21.456, 31.995, 3.745]
    rot3 = [0, 18.814, 0.326]
    camera3.spawn_degrees(loc3, rot3)
    camera3.possess()

    # Display a image of the first camera angle 
    cv2.imshow('image1',image1)
    cv2.waitKey(0)

    # Closing qlabs
    qlabs.close()
    print('Done!')

if __name__ == "__main__":
    main()

Matlab Tutorial

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

% Free Camera Library 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'), '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('Camera Tutorial')

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

% Add a custom camera at a specified location and rotation using degrees
location = [-5.631, -1.467, 2.198];
rotation = [0, -2.386, -20.528];
camera.spawn_degrees(location, rotation);

% Switch our view from our current camera to the new camera we just initialized
camera.possess();

pause(3);

camera.set_camera_properties(60, 1, 2.0, 1.3);

[success, location, rotation, scale] = camera.get_world_transform();

ping = camera.ping();

% Take a image from the first camera angle 
if ping
    camera.set_image_capture_resolution();
    [success, image1] = camera.get_image();
    
    if ~success
        disp('Image decoding failure');
    end
end

pause(2);

% Initialize and spawn the second camera angle 
loc2 = [-33.17276819, 13.50500671, 2.282];
rot2 = [0, 0.077, 0.564];
camera2 = QLabsFreeCamera(qlabs);
x = camera2.spawn_id(2, loc2, rot2);
camera2.possess();

pause(2);

camera.destroy();

[success, location, rotation, scale] = camera2.get_world_transform();
camera2.set_camera_properties(40, true, 2.3, 0.6);

pause(2);

% Focus the camera 
for y = 1:51
    camera2.set_camera_properties(40, true, 2.3, (0.6 + ((y / 50)^3) * 23.7));
end

camera.set_image_capture_resolution();

% Take image of the second camera angle 
[success, image2] = camera.get_image();
disp(success);

pause(2);

% Initialize and spawn the third camera angle 
camera3 = QLabsFreeCamera(qlabs);
loc3 = [-21.456, 31.995, 3.745];
rot3 = [0, 18.814, 0.326];
camera3.spawn_degrees(loc3, rot3);
camera3.possess();

% Display a image of the first camera angle 
imshow(image1);

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