anki_vector.util

Utility functions and classes for the Vector SDK.

Functions

angle_z_to_quaternion(angle_z) This function converts an angle in the z axis (Euler angle z component) to a quaternion.
block_while_none([interval, max_iterations]) Use this to denote a property that may need some delay before it appears.
degrees(degrees) An Angle instance set to the specified number of degrees.
distance_inches(distance_inches) Returns an anki_vector.util.Distance instance set to the specified number of inches.
distance_mm(distance_mm) Returns an anki_vector.util.Distance instance set to the specified number of millimeters.
get_class_logger(module, obj) Helper to create logger for a given class (and module).
parse_command_args([parser]) Parses command line arguments.
radians(radians) An Angle instance set to the specified number of radians.
setup_basic_logging([custom_handler, …]) Helper to perform basic setup of the Python logger.
speed_mmps(speed_mmps) anki_vector.util.Speed instance set to the specified millimeters per second speed.

Classes

Angle([radians, degrees]) Represents an angle.
BaseOverlay(line_thickness, line_color) A base overlay is used as a base class for other forms of overlays that can be drawn on top of an image.
Component(robot) Base class for all components.
Distance([distance_mm, distance_inches]) Represents a distance.
ImageRect(x_top_left, y_top_left, width, height) Image coordinates and size
Matrix44(m00, m10, m20, m30, m01, m11, m21, …) A 4x4 Matrix for representing the rotation and/or position of an object in the world.
Pose(x, y, z[, q0, q1, q2, q3, angle_z, …]) Represents where an object is in the world.
Position(x, y, z) Represents the position of an object in the world.
Quaternion([q0, q1, q2, q3, angle_z]) Represents the rotation of an object in the world.
RectangleOverlay(width, height[, …]) A rectangle that can be drawn on top of a given image.
Speed([speed_mmps]) Represents a speed.
Vector2(x, y) Represents a 2D Vector (type/units aren’t specified).
Vector3(x, y, z) Represents a 3D Vector (type/units aren’t specified).
class anki_vector.util.Angle(radians=None, degrees=None)

Represents an angle.

Use the degrees() or radians() convenience methods to generate an Angle instance.

Parameters:
  • radians (Optional[float]) – The number of radians the angle should represent (cannot be combined with degrees)
  • degrees (Optional[float]) – The number of degress the angle should represent (cannot be combined with radians)
abs_value

anki_vector.util.Angle – The absolute value of the angle.

If the Angle is positive then it returns a copy of this Angle, otherwise it returns -Angle.

degrees

The angle in degrees.

Return type:float
radians

The angle in radians.

Return type:float
class anki_vector.util.BaseOverlay(line_thickness, line_color)

A base overlay is used as a base class for other forms of overlays that can be drawn on top of an image.

Parameters:
  • line_thickness (int) – The thickness of the line being drawn.
  • line_color (tuple) – The color of the line to be drawn.
line_color

The color of the line to be drawn.

Return type:tuple
line_thickness

The thickness of the line being drawn.

Return type:int
class anki_vector.util.Component(robot)

Base class for all components.

grpc_interface

A direct reference to the connected aiogrpc interface.

class anki_vector.util.Distance(distance_mm=None, distance_inches=None)

Represents a distance.

The class allows distances to be returned in either millimeters or inches.

Use the distance_inches() or distance_mm() convenience methods to generate a Distance instance.

Parameters:
  • distance_mm (Optional[float]) – The number of millimeters the distance should represent (cannot be combined with distance_inches).
  • distance_inches (Optional[float]) – The number of inches the distance should represent (cannot be combined with distance_mm).
distance_mm

The distance in millimeters

Return type:float
class anki_vector.util.ImageRect(x_top_left, y_top_left, width, height)

Image coordinates and size

height

The height of the object from when it was last visible within Vector’s camera view.

Return type:float
width

The width of the object from when it was last visible within Vector’s camera view.

Return type:float
x_top_left

The top left x value of where the object was last visible within Vector’s camera view.

Return type:float
y_top_left

The top left y value of where the object was last visible within Vector’s camera view.

Return type:float
class anki_vector.util.Matrix44(m00, m10, m20, m30, m01, m11, m21, m31, m02, m12, m22, m32, m03, m13, m23, m33)

A 4x4 Matrix for representing the rotation and/or position of an object in the world.

Can be generated from a Quaternion for a pure rotation matrix, or combined with a position for a full translation matrix, as done by Pose.to_matrix().

forward_xyz

tuple of 3 floats – The x,y,z components representing the matrix’s forward vector.

in_column_order

tuple of 16 floats – The contents of the matrix in column order.

in_row_order

tuple of 16 floats – The contents of the matrix in row order.

left_xyz

tuple of 3 floats – The x,y,z components representing the matrix’s left vector.

pos_xyz

tuple of 3 floats – The x,y,z components representing the matrix’s position vector.

set_forward(x, y, z)

Set the x,y,z components representing the matrix’s forward vector.

Parameters:
  • x (float) – The X component.
  • y (float) – The Y component.
  • z (float) – The Z component.
set_left(x, y, z)

Set the x,y,z components representing the matrix’s left vector.

Parameters:
  • x (float) – The X component.
  • y (float) – The Y component.
  • z (float) – The Z component.
set_pos(x, y, z)

Set the x,y,z components representing the matrix’s position vector.

Parameters:
  • x (float) – The X component.
  • y (float) – The Y component.
  • z (float) – The Z component.
set_up(x, y, z)

Set the x,y,z components representing the matrix’s up vector.

Parameters:
  • x (float) – The X component.
  • y (float) – The Y component.
  • z (float) – The Z component.
tabulated_string

A multi-line string formatted with tabs to show the matrix contents.

Return type:str
up_xyz

tuple of 3 floats – The x,y,z components representing the matrix’s up vector.

class anki_vector.util.Pose(x, y, z, q0=None, q1=None, q2=None, q3=None, angle_z=None, origin_id=-1)

Represents where an object is in the world.

Whenever Vector is delocalized (i.e. whenever Vector no longer knows where he is - e.g. when he’s picked up), Vector creates a new pose starting at (0,0,0) with no rotation, with origin_id incremented to show that these poses cannot be compared with earlier ones. As Vector drives around, his pose (and the pose of other objects he observes - e.g. faces, his LightCube, charger, etc.) is relative to this initial position and orientation.

The coordinate space is relative to Vector, where Vector’s origin is the point on the ground between Vector’s two front wheels. The X axis is Vector’s forward direction, the Y axis is to Vector’s left, and the Z axis is up.

Only poses of the same origin_id can safely be compared or operated on.

import anki_vector
from anki_vector.util import degrees, Pose

with anki_vector.Robot() as robot:
    pose = Pose(x=50, y=0, z=0, angle_z=anki_vector.util.Angle(degrees=0))
    robot.behavior.go_to_pose(pose)
define_pose_relative_this(new_pose)

Creates a new pose such that new_pose’s origin is now at the location of this pose.

Parameters:new_pose (anki_vector.util.Pose) – The pose which origin is being changed.
Returns:A anki_vector.util.Pose object for which the origin was this pose’s origin.
is_comparable(other_pose)

Checks whether these two poses are comparable.

Poses are comparable if they’re valid and having matching origin IDs.

Parameters:other_pose – The other pose to compare against. Type is Pose.
Returns:True if the two poses are comparable, False otherwise.
Return type:bool
is_valid

True if this is a valid, usable pose.

Return type:bool
origin_id

An ID maintained by the robot which represents which coordinate frame this pose is in.

Return type:int
position

The position component of this pose.

Return type:Position
rotation

The rotation component of this pose.

Return type:Quaternion
to_matrix()

Convert the Pose to a Matrix44.

Returns:A matrix representing this Pose’s position and rotation.
Return type:Matrix44
to_proto_pose_struct()

Converts the Pose into the robot’s messaging pose format.

Return type:PoseStruct
class anki_vector.util.Position(x, y, z)

Represents the position of an object in the world.

A position consists of its x, y and z values in millimeters.

Parameters:
  • x (float) – X position in millimeters
  • y (float) – Y position in millimeters
  • z (float) – Z position in millimeters
class anki_vector.util.Quaternion(q0=None, q1=None, q2=None, q3=None, angle_z=None)

Represents the rotation of an object in the world.

angle_z

An Angle instance representing the z Euler component of the object’s rotation.

Defined as the rotation in the z axis.

Return type:Angle
q0

The q0 (w) value of the quaternion.

Return type:float
q0_q1_q2_q3

tuple of float – Contains all elements of the quaternion (q0,q1,q2,q3)

q1

The q1 (i) value of the quaternion.

Return type:float
q2

The q2 (j) value of the quaternion.

Return type:float
q3

The q3 (k) value of the quaternion.

Return type:float
to_matrix(pos_x=0.0, pos_y=0.0, pos_z=0.0)

Convert the Quaternion to a 4x4 matrix representing this rotation.

A position can also be provided to generate a full translation matrix.

Parameters:
  • pos_x (float) – The x component for the position.
  • pos_y (float) – The y component for the position.
  • pos_z (float) – The z component for the position.
Returns:

A matrix representing this Quaternion’s rotation, with the provided position (which defaults to 0,0,0).

Return type:

anki_vector.util.Matrix44

class anki_vector.util.RectangleOverlay(width, height, line_thickness=5, line_color=(255, 0, 0))

A rectangle that can be drawn on top of a given image.

Parameters:
  • width (int) – The width of the rectangle to be drawn.
  • height (int) – The height of the rectangle to be drawn.
  • line_thickness (int) – The thickness of the line being drawn.
  • line_color (tuple) – The color of the line to be drawn.
apply_overlay(image)

Draw a rectangle on top of the given image.

Return type:None
height

The height of the rectangle to be drawn.

Return type:int
width

The width of the rectangle to be drawn.

Return type:int
class anki_vector.util.Speed(speed_mmps=None)

Represents a speed.

This class allows speeds to be measured in millimeters per second.

Use speed_mmps() convenience methods to generate a Speed instance.

Parameters:speed_mmps (Optional[float]) – The number of millimeters per second the speed should represent.
speed_mmps

The speed in millimeters per second (mmps).

Return type:float
class anki_vector.util.Vector2(x, y)

Represents a 2D Vector (type/units aren’t specified).

Parameters:
  • x (float) – X component
  • y (float) – Y component
set_to(rhs)

Copy the x and y components of the given Vector2 instance.

Parameters:rhs – The right-hand-side of this assignment - the source Vector2 to copy into this Vector2 instance.
x

The x component.

Return type:float
x_y

tuple (float, float) – The X, Y elements of the Vector2 (x,y)

y

The y component.

Return type:float
class anki_vector.util.Vector3(x, y, z)

Represents a 3D Vector (type/units aren’t specified).

Parameters:
  • x (float) – X component
  • y (float) – Y component
  • z (float) – Z component
cross(other)

The cross product of this and another Vector3 instance

dot(other)

The dot product of this and another Vector3 instance

magnitude

The magnitude of the Vector3 instance

Return type:float
magnitude_squared

float – The magnitude of the Vector3 instance

Return type:float
normalized

A Vector3 instance with the same direction and unit magnitude

set_to(rhs)

Copy the x, y and z components of the given Vector3 instance.

Parameters:rhs – The right-hand-side of this assignment - the source Vector3 to copy into this Vector3 instance.
x

The x component.

Return type:float
x_y_z

tuple (float, float, float) – The X, Y, Z elements of the Vector3 (x,y,z)

y

The y component.

Return type:float
z

The z component.

Return type:float
anki_vector.util.angle_z_to_quaternion(angle_z)

This function converts an angle in the z axis (Euler angle z component) to a quaternion.

Parameters:angle_z (Angle) – The z axis angle.
Returns:
A tuple with all the members
of a quaternion defined by angle_z.
Return type:q0, q1, q2, q3 (float, float, float, float)
anki_vector.util.block_while_none(interval=0.1, max_iterations=50)

Use this to denote a property that may need some delay before it appears.

Parameters:
  • interval (float) – how often to check if the property is no longer None
  • max_iterations (int) – how many times to check the property before raising an error
anki_vector.util.degrees(degrees)

An Angle instance set to the specified number of degrees.

Return type:Angle
anki_vector.util.distance_mm(distance_mm)

Returns an anki_vector.util.Distance instance set to the specified number of millimeters.

anki_vector.util.distance_inches(distance_inches)

Returns an anki_vector.util.Distance instance set to the specified number of inches.

anki_vector.util.get_class_logger(module, obj)

Helper to create logger for a given class (and module).

import anki_vector

logger = anki_vector.util.get_class_logger("module_name", "object_name")
Parameters:
  • module (str) – The name of the module to which the object belongs.
  • obj (object) – the object that owns the logger.
Return type:

Logger

anki_vector.util.parse_command_args(parser=None)

Parses command line arguments.

Attempts to read the robot serial number from the command line arguments. If no serial number is specified, we next attempt to read the robot serial number from environment variable ANKI_ROBOT_SERIAL. If ANKI_ROBOT_SERIAL is specified, the value will be used as the robot’s serial number.

import anki_vector

import argparse

parser = argparse.ArgumentParser()
parser.add_argument("--new_param")
args = anki_vector.util.parse_command_args(parser)
Parameters:parser (Optional[ArgumentParser]) – To add new command line arguments, pass an argparse parser with the new options already defined. Leave empty to use the defaults.
anki_vector.util.radians(radians)

An Angle instance set to the specified number of radians.

Return type:Angle
anki_vector.util.setup_basic_logging(custom_handler=None, general_log_level=None, target=None)

Helper to perform basic setup of the Python logger.

Parameters:
  • custom_handler (Optional[Handler]) – provide an external logger for custom logging locations
  • general_log_level (Optional[str]) – ‘DEBUG’, ‘INFO’, ‘WARN’, ‘ERROR’ or an equivalent constant from the logging module. If None then a value will be read from the VECTOR_LOG_LEVEL environment variable.
  • target (object) – The stream to send the log data to; defaults to stderr
anki_vector.util.speed_mmps(speed_mmps)

anki_vector.util.Speed instance set to the specified millimeters per second speed.