cozmo.world

The “world” represents the robot’s known view of its environment.

This view includes objects, faces and pets it knows about and can currently “see” with its camera, along with what actions or behaviors the robot is current performing and the images coming back from the camera (if any).

Almost all events emitted by the robot itself, objects, faces, pets and the camera can be observed directly on the World object, which is itself accessible as cozmo.robot.Robot.world.

For example, if you only need to know whether a particular cube has been tapped, you can call the wait_for() method directly on that cube’s cozmo.objects.LightCube instance. Eg:

my_cube.wait_for(cozmo.objects.EvtObjectTapped)

If, however, you want to wait for any cube to be tapped, you could instead call the wait_for() method on the World object instead. Eg:

robot.world.wait_for(cozmo.objects.EvtObjectTapped)

In either case, wait_for will return the instance of the event’s EvtObjectTapped class, which includes a obj attribute, which identifies exactly which cube has been tapped.

The World object also has a cozmo.camera.Camera instance associated with it. It emits EvtNewCameraImage objects whenever a new camera image is available (generally up to 15 times per second), which includes the raw image from the camera, as well as an annotated version showing where faces, pets and objects have been observed.

Note

The camera must first be enabled to receive images by setting image_stream_enabled to True.

Classes

CameraImage(raw_image, image_annotator[, …]) A single image from Cozmo’s camera.
EvtNewCameraImage(**kwargs) Dispatched when a new camera image is received and processed from the robot’s camera.
World(conn, robot, **kw) Represents the state of the world, as known to a Cozmo robot.
class cozmo.world.EvtNewCameraImage(**kwargs)

Dispatched when a new camera image is received and processed from the robot’s camera.

image = 'A CameraImage object'
class cozmo.world.CameraImage(raw_image, image_annotator, image_number=0)

A single image from Cozmo’s camera.

This wraps a raw image and provides an annotate_image() method that can resize and add dynamic annotations to the image, such as marking up the location of objects, faces and pets.

annotate_image(scale=None, fit_size=None, resample_mode=0)

Adds any enabled annotations to the image.

Optionally resizes the image prior to annotations being applied. The aspect ratio of the resulting image always matches that of the raw image.

Parameters:
  • scale (float) – If set then the base image will be scaled by the supplied multiplier. Cannot be combined with fit_size
  • fit_size (tuple of int) – If set, then scale the image to fit inside the supplied (width, height) dimensions. The original aspect ratio will be preserved. Cannot be combined with scale.
  • resample_mode (int) – The resampling mode to use when scaling the image. Should be either RESAMPLE_MODE_NEAREST (fast) or RESAMPLE_MODE_BILINEAR (slower, but smoother).
Returns:

PIL.Image.Image
image_annotator = None

the image annotation object

Type:cozmo.annotate.ImageAnnotator
image_number = None

An image number that increments on every new image received

Type:int
image_recv_time = None

The time the image was received and processed by the SDK

Type:float
raw_image = None

the raw unprocessed image from the camera

Type:PIL.Image.Image
class cozmo.world.World(conn, robot, **kw)

Represents the state of the world, as known to a Cozmo robot.

active_action

True if Cozmo is currently executing an action.

Type:bool
active_behavior

True if the robot is currently executing a behavior.

Type:bool
annotator_factory = functools.partial(<class 'cozmo.annotate.ImageAnnotator'>, loop=None)

The factory function that returns an annotate.ImageAnnotator class or subclass instance.

Type:callable
auto_disconnect_from_cubes_at_end(enable=True)

Tell the SDK to auto disconnect from cubes at the end of every SDK program.

This can be used to save cube battery life if you spend a lot of time in SDK mode but aren’t running programs as much (as you’re busy writing them). Call connect_to_cubes() to re-connect to the cubes later.

Parameters:enable (bool) – True if cubes should disconnect after every SDK program exits.
charger = None

Cozmo’s charger. None if no charger connected or known about yet.

Type:cozmo.objects.Charger
charger_factory = functools.partial(<class 'cozmo.objects.Charger'>, loop=None)

The factory function that returns an objects.Charger class or subclass instance.

Type:callable
conn = None

The underlying connection to a device.

Type:cozmo.conn.CozmoConnection
connect_to_cubes()

Connect to all cubes.

Request that Cozmo connects to all cubes - this is required if you previously called disconnect_from_cubes() or auto_disconnect_from_cubes_at_end() with enable=False. Connecting to a cube can take up to about 5 seconds, and this method will wait until either all 3 cubes are connected, or it has timed out waiting for this.

Returns:True if all 3 cubes are now connected.
Return type:bool
connected_light_cubes

yields each LightCube that Cozmo is currently connected to.

Returns:A generator yielding cozmo.objects.LightCube instances
Type:generator
create_custom_fixed_object(pose, x_size_mm, y_size_mm, z_size_mm, relative_to_robot=False, use_robot_origin=True)

Defines a cuboid of custom size and places it in the world. It cannot be observed.

Parameters:
  • pose (cozmo.util.Pose) – The pose of the object we are creating.
  • x_size_mm (float) – size of the object (in millimeters) in the x axis.
  • y_size_mm (float) – size of the object (in millimeters) in the y axis.
  • z_size_mm (float) – size of the object (in millimeters) in the z axis.
  • relative_to_robot (bool) – whether or not the pose given assumes the robot’s pose as its origin.
  • use_robot_origin (bool) – whether or not to override the origin_id in the given pose to be the origin_id of Cozmo.
Returns:

A cozmo.objects.FixedCustomObject instance with the specified dimensions and pose.
custom_object_factory = functools.partial(<class 'cozmo.objects.CustomObject'>, loop=None)

The factory function that returns an objects.CustomObject class or subclass instance.

Type:callable
define_custom_box(custom_object_type, marker_front, marker_back, marker_top, marker_bottom, marker_left, marker_right, depth_mm, width_mm, height_mm, marker_width_mm, marker_height_mm, is_unique=True)

Defines a cuboid of custom size and binds it to a specific custom object type.

The engine will now detect the markers associated with this object and send an object_observed message when they are seen. The markers must be placed in the center of their respective sides. All 6 markers must be unique.

Parameters:
Returns:

A cozmo.object.CustomObject instance with the specified dimensions.

This is None if the definition failed internally. Note: No instances of this object are added to the world until they have been seen.
Raises:
  • TypeError if the custom_object_type is of the wrong type.
  • ValueError if the 6 markers aren’t unique.
define_custom_cube(custom_object_type, marker, size_mm, marker_width_mm, marker_height_mm, is_unique=True)

Defines a cube of custom size and binds it to a specific custom object type.

The engine will now detect the markers associated with this object and send an object_observed message when they are seen. The markers must be placed in the center of their respective sides.

Parameters:
  • custom_object_type (cozmo.objects.CustomObjectTypes) – the object type you are binding this custom object to.
  • marker – (cozmo.objects.CustomObjectMarkers): the marker affixed to every side of the cube.
  • size_mm – size of each side of the cube (in millimeters).
  • marker_width_mm (float) – width of the printed marker (in millimeters).
  • maker_height_mm (float) – height of the printed marker (in millimeters).
  • is_unique (bool) – If True, the engine will assume there is only 1 of this object (and therefore only 1 of each of any of these markers) in the world.
Returns:

A cozmo.object.CustomObject instance with the specified dimensions.

This is None if the definition failed internally. Note: No instances of this object are added to the world until they have been seen.
Raises:

TypeError if the custom_object_type is of the wrong type.
define_custom_wall(custom_object_type, marker, width_mm, height_mm, marker_width_mm, marker_height_mm, is_unique=True)

Defines a wall of custom width and height, with a fixed depth of 10mm, and binds it to a specific custom object type.

The engine will now detect the markers associated with this object and send an object_observed message when they are seen. The markers must be placed in the center of their respective sides.

Parameters:
  • custom_object_type (cozmo.objects.CustomObjectTypes) – the object type you are binding this custom object to.
  • marker – (cozmo.objects.CustomObjectMarkers): the marker affixed to the front and back of the wall
  • width_mm (float) – width of the object (in millimeters). (Y axis).
  • height_mm (float) – height of the object (in millimeters). (Z axis).
  • width_mm – width of the wall (along Y axis) (in millimeters).
  • height_mm – height of the wall (along Z axis) (in millimeters).
  • marker_width_mm (float) – width of the printed marker (in millimeters).
  • maker_height_mm (float) – height of the printed marker (in millimeters).
  • is_unique (bool) – If True, the engine will assume there is only 1 of this object (and therefore only 1 of each of any of these markers) in the world.
Returns:

A cozmo.object.CustomObject instance with the specified dimensions.

This is None if the definition failed internally. Note: No instances of this object are added to the world until they have been seen.
Raises:

TypeError if the custom_object_type is of the wrong type.
delete_all_custom_objects()

Causes the robot to forget about all custom (fixed + marker) objects it currently knows about.

Note: This includes all fixed custom objects, and all custom marker object instances, BUT this does NOT remove the custom marker object definitions, so Cozmo will continue to add new objects if he sees the markers again. To remove the definitions for those objects use: undefine_all_custom_marker_objects()

delete_custom_marker_objects()

Causes the robot to forget about all custom marker objects it currently knows about.

Note: This removes custom marker object instances only, it does NOT remove fixed custom objects, nor does it remove the custom marker object definitions, so Cozmo will continue to add new objects if he sees the markers again. To remove the definitions for those objects use: undefine_all_custom_marker_objects()

delete_fixed_custom_objects()

Causes the robot to forget about all fixed custom objects it currently knows about.

Note: This removes fixed custom objects only, it does NOT remove the custom marker object instances or definitions.

disconnect_from_cubes()

Disconnect from all cubes (to save battery life etc.).

Call connect_to_cubes() to re-connect to the cubes later.

enable_block_tap_filter(enable=True)

Enable or disable the block tap filter in the engine.

The block (AKA LightCube) tap filter removes low intensity taps, and filters out taps that come in rapidly together and instead just sends the strongest one

Parameters:enable (bool) – specifies whether the filter should be enabled or disabled
face_factory = functools.partial(<class 'cozmo.faces.Face'>, loop=None)

The factory function that returns a faces.Face class or subclass instance.

Type:callable
get_light_cube(cube_id)

Returns the light cube with the given cube ID

Parameters:cube_id (int) – The light cube ID - should be one of LightCube1Id, LightCube2Id and LightCube3Id. Note: the cube_id is not the same thing as the object_id.
Returns:The LightCube object with that cube_id
Return type:cozmo.objects.LightCube
Raises:ValueError if the cube_id is invalid.
image_annotator = None

The image annotator used to add annotations to the raw camera images.

Type:cozmo.annotate.ImageAnnotator
latest_image = None

The latest image received, or None.

Type:CameraImage
light_cube_factory = functools.partial(<class 'cozmo.objects.LightCube'>, loop=None)

The factory function that returns an objects.LightCube class or subclass instance.

Type:callable
nav_memory_map

Returns the latest navigation memory map for Cozmo.

Returns:
Current navigation
memory map. This will be none unless you’ve previously called request_nav_memory_map() with a positive frequency to request the data be sent over from the engine.
Return type:NavMemoryMapGrid
pet_factory = functools.partial(<class 'cozmo.pets.Pet'>, loop=None)

The factory function that returns a pets.Pet class or subclass instance.

Type:callable
request_nav_memory_map(frequency_s)

Request navigation memory map data from Cozmo.

The memory map can be accessed via nav_memory_map, it will be None until request_nav_memory_map() has been called and a map has been received. The memory map provides a quad-tree map of where Cozmo thinks there are objects, and where Cozmo thinks it is safe to drive.

Parameters:frequency_s (float) – number of seconds between each update being sent. Negative values, e.g. -1.0, will disable any updates being sent.
robot = None

The primary robot

Type:cozmo.robot.Robot
undefine_all_custom_marker_objects()

Remove all custom marker object definitions, and any instances of them in the world.

visible_face_count()

Returns the number of faces that Cozmo can currently see.

Returns:The number of faces currently visible.
Return type:int
visible_faces

yields each face that Cozmo can currently see.

Returns:A generator yielding cozmo.faces.Face instances
Type:generator
visible_object_count(object_type=None)

Returns the number of objects that Cozmo can currently see.

Parameters:object_type (ObservableObject subclass) – Which type of object to count. If None, return the total number of currently visible objects.
Returns:The number of objects that Cozmo can currently see.
Return type:int
visible_objects

yields each object that Cozmo can currently see.

For faces, see visible_faces(). For pets, see visible_pets().

Returns:A generator yielding cozmo.objects.BaseObject instances
Type:generator
visible_pet_count()

Returns the number of pets that Cozmo can currently see.

Returns:The number of pets currently visible.
Return type:int
visible_pets

yields each pet that Cozmo can currently see.

Returns:A generator yielding cozmo.pets.Pet instances
Type:generator
wait_for_observed_charger(timeout=None, include_existing=True)

Waits for a charger to be observed by the robot.

Parameters:
  • timeout (float) – Number of seconds to wait for a charger to be observed, or None for indefinite
  • include_existing (bool) – Specifies whether to include chargers that are already visible.
Returns:

The cozmo.objects.Charger object that was observed.
wait_for_observed_face(timeout=None, include_existing=True)

Waits for a face to be observed by the robot.

Parameters:
  • timeout (float) – Number of seconds to wait for a face to be observed, or None for indefinite
  • include_existing (bool) – Specifies whether to include faces that are already visible.
Returns:

The cozmo.faces.Face object that was observed.
wait_for_observed_light_cube(timeout=None, include_existing=True)

Waits for one of the light cubes to be observed by the robot.

Parameters:
  • timeout (float) – Number of seconds to wait for a cube to be observed, or None for indefinite
  • include_existing (bool) – Specifies whether to include light cubes that are already visible.
Returns:

The cozmo.objects.LightCube object that was observed.
wait_for_observed_pet(timeout=None, include_existing=True)

Waits for a pet to be observed by the robot.

Parameters:
  • timeout (float) – Number of seconds to wait for a pet to be observed, or None for indefinite
  • include_existing (bool) – Specifies whether to include pets that are already visible.
Returns:

The cozmo.pets.Pet object that was observed.
wait_until_num_objects_visible(num, object_type=None, timeout=None)

Waits for at least a specific number of objects to be seen concurrently.

Unlike wait_until_observe_num_objects() which returns when several objects have become visible, but not necessarily simultaneously, this method will only return if the specific number of objects are visible to the camera at the same time (as defined by objects.OBJECT_VISIBILITY_TIMEOUT).

Parameters:
  • num (float) – The number of unique objects to wait for.
  • (class (object_type) – cozmo.objects.ObservableObject): If provided this will cause only the selected object types to be counted.
  • timeout (float) – Maximum amount of time in seconds to wait for the requested number of objects to be observed.
Returns:

The number of objects seen (num or higher).
Return type:

int
Raises:

asyncio.TimeoutError if the required count wasn’t seen.
wait_until_observe_num_objects(num, object_type=None, timeout=None, include_existing=True)

Waits for a certain number of unique objects to be seen at least once.

This method waits for a number of unique objects to be seen, but not necessarily concurrently. That is, if cube 1 appears to the camera and then moves out of view to be replaced by cube 2, then that will count as 2 observed objects.

To wait for multiple objects to be visible simultaneously, see wait_until_num_objects_visible().

Parameters:
  • num (float) – The number of unique objects to wait for.
  • (class (object_type) – cozmo.objects.ObservableObject): If provided this will cause only the selected object types to be counted.
  • timeout (float) – Maximum amount of time in seconds to wait for the requested number of objects to be observed.
  • include_existing (bool) – Specifies whether to include objects that are already visible.
Returns:

A list of length <= num of the unique objects class:cozmo.objects.ObservableObject observed during this wait.