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.

read_configuration(serial, name, logger)

Open the default conf file, and read it into a configparser.ConfigParser If serial is not None, this method will try to find a configuration with serial number serial, and raise an exception otherwise.

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)

Defines a bounding box within an image frame.

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

The absolute value of the angle.

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

Type

anki_vector.util.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)

Defines a bounding box within an image frame.

This is used when objects and faces are observed to denote where in the robot’s camera view the object or face actually appears. It’s then used by the annotate module to show an outline of a box around the object or face.

height

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

Return type

float

scale_by(scale_multiplier)

Scales the image rectangle by the multiplier provided.

Return type

None

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

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

Type

tuple of 3 floats

in_column_order

The contents of the matrix in column order.

Type

tuple of 16 floats

in_row_order

The contents of the matrix in row order.

Type

tuple of 16 floats

left_xyz

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

Type

tuple of 3 floats

pos_xyz

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

Type

tuple of 3 floats

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

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

Type

tuple of 3 floats

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

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

Type

tuple of float

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.

The maximum speed is 220 mm/s and is clamped internally.

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

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

Type

tuple (float, float)

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

The magnitude of the Vector3 instance

Return type

float

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

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

Type

tuple (float, float, float)

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

This will raise a VectorControlTimeoutException if the property cannot be retrieved before max_iterations.

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.