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)

property 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

property degrees¶

The angle in degrees.

Return type: float

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

property line_color¶

The color of the line to be drawn.

Return type: tuple

property line_thickness¶

The thickness of the line being drawn.

Return type: int

class anki_vector.util.Component(robot)¶

Base class for all components.

property 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).

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

property 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

property width¶

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

Return type: float

property x_top_left¶

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

Return type: float

property 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().

property forward_xyz¶

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

Type: tuple of 3 floats

property in_column_order¶

The contents of the matrix in column order.

Type: tuple of 16 floats

property in_row_order¶

The contents of the matrix in row order.

Type: tuple of 16 floats

property left_xyz¶

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

Type: tuple of 3 floats

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

property tabulated_string¶

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

Return type: str

property 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

property is_valid¶

True if this is a valid, usable pose.

Return type: bool

property origin_id¶

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

Return type: int

property position¶

The position component of this pose.

Return type: Position

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

property 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

property q0¶

The q0 (w) value of the quaternion.

Return type: float

property q0_q1_q2_q3¶

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

Type: tuple of float

property q1¶

The q1 (i) value of the quaternion.

Return type: float

property q2¶

The q2 (j) value of the quaternion.

Return type: float

property 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

property height¶

The height of the rectangle to be drawn.

Return type: int

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

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

property x¶

The x component.

Return type: float

property x_y¶

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

Type: tuple (float, float)

property 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

property magnitude¶

The magnitude of the Vector3 instance

Return type: float

property magnitude_squared¶

The magnitude of the Vector3 instance

Return type: float
Type: float

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

property x¶

The x component.

Return type: float

property x_y_z¶

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

Type: tuple (float, float, float)

property y¶

The y component.

Return type: float

property 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 (Optional[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.