cozmo.util¶

Utility classes and functions.

Functions

`angle_z_to_quaternion`(angle_z)	This function converts an angle in the z axis (Euler angle z component) to a quaternion.
`degrees`(degrees)	Returns an `cozmo.util.Angle` instance set to the specified number of degrees.
`distance_inches`(distance_inches)	Returns an `cozmo.util.Distance` instance set to the specified number of inches.
`distance_mm`(distance_mm)	Returns an `cozmo.util.Distance` instance set to the specified number of millimeters.
`pose_quaternion`(x, y, z, q0, q1, q2, q3[, …])	Returns a `cozmo.util.Pose` instance set to the pose given in quaternion format.
`pose_z_angle`(x, y, z, angle_z[, origin_id])	Returns a `cozmo.util.Pose` instance set to the pose given in z angle format.
`radians`(radians)	Returns an `cozmo.util.Angle` instance set to the specified number of radians.
`rotation_quaternion`(q0, q1, q2, q3)	Returns a `Rotation` instance set by a quaternion.
`rotation_z_angle`(angle_z)	Returns a class:Rotation instance set by an angle in the z axis
`speed_mmps`(speed_mmps)	Returns an `cozmo.util.Speed` instance set to the specified millimeters per second speed

Classes

`Angle`([radians, degrees])	Represents an angle.
`Distance`([distance_mm, distance_inches])	Represents a distance.
`ImageBox`	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.
`Rotation`([q0, q1, q2, q3, angle_z])	An alias for `Quaternion`
`Speed`([speed_mmps])	Represents a speed.
`Timeout`([timeout, use_inf])	Utility class to keep track of a timeout condition.
`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 cozmo.util.Angle(radians=None, degrees=None)¶

Represents an angle.

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

Parameters:	radians (float) – The number of radians the angle should represent (cannot be combined with `degrees`) degrees (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:	`cozmo.util.Angle`

degrees¶

The angle in degrees.

Type:	float

radians¶

The angle in radians.

Type:	float

cozmo.util.degrees(degrees)¶: Returns an cozmo.util.Angle instance set to the specified number of degrees.

cozmo.util.radians(radians)¶: Returns an cozmo.util.Angle instance set to the specified number of radians.

class cozmo.util.ImageBox¶

Defines a bounding box within an image frame.

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

width¶: float - The width of the box.

height¶: float - The height of the box.

bottom_y¶

The y coordinate of the bottom of the box.

Type:	float

center¶

The x,y coordinates of the center of the box.

Type:	(float, float)

left_x¶

The x coordinate of the left of the box.

Type:	float

right_x¶

The x coordinate of the right of the box.

Type:	float

top_y¶

The y coordinate of the top of the box.

Type:	float

class cozmo.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 (float) – The number of millimeters the distance should represent (cannot be combined with `distance_inches`). distance_inches (float) – The number of inches the distance should represent (cannot be combined with `distance_mm`).

distance_inches¶

The distance in inches

Type:	float

distance_mm¶

The distance in millimeters

Type:	float

cozmo.util.distance_mm(distance_mm)¶: Returns an cozmo.util.Distance instance set to the specified number of millimeters.

cozmo.util.distance_inches(distance_inches)¶: Returns an cozmo.util.Distance instance set to the specified number of inches.

class cozmo.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.

Type:	str

up_xyz¶

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

Type:	tuple of 3 floats

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

Represents where an object is in the world.

Use the :func:’pose_quaternion’ to return pose in the form of position and rotation defined by a quaternion

Use the :func:’pose_z_angle’ to return pose in the form of position and rotation defined by rotation about the z axis

When the engine is initialized, and whenever Cozmo is de-localized (i.e. whenever Cozmo no longer knows where he is - e.g. when he’s picked up) Cozmo 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 Cozmo drives around, his pose (and the pose of other objects he observes - e.g. faces, cubes etc.) is relative to this initial position and orientation.

The coordinate space is relative to Cozmo, where Cozmo’s origin is the point on the ground between Cozmo’s two front wheels:

The X axis is Cozmo’s forward direction The Y axis is to Cozmo’s left The Z axis is up

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

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 (`cozmo.util.Pose`) – The pose which origin is being changed.
Returns:	A `cozmo.util.pose` object for which the origin was this pose’s origin.

invalidate()¶: Mark this pose as being invalid (unusable)

is_accurate¶

Returns True if this pose is valid and accurate.

Poses are marked as inaccurate if we detect movement via accelerometer, or if they were observed from far enough away that we’re less certain of the exact pose.

Type:	bool

is_comparable(other_pose)¶

Are these two poses comparable.

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

Parameters:	other_pose (`cozmo.util.Pose`) – The other pose to compare against.
Returns:	True if the two poses are comparable, False otherwise.
Return type:	bool

is_valid¶

Returns True if this is a valid, usable pose.

Type:	bool

origin_id¶

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

Type:	int

position¶

The position component of this pose.

Type:	`cozmo.util.Position`

rotation¶

The rotation component of this pose.

Type:	`cozmo.util.Rotation`

to_matrix()¶

Convert the Pose to a Matrix44.

Returns:	A matrix representing this Pose’s position and rotation.
Return type:	`cozmo.util.Matrix44`

cozmo.util.pose_quaternion(x, y, z, q0, q1, q2, q3, origin_id=0)¶: Returns a cozmo.util.Pose instance set to the pose given in quaternion format.

cozmo.util.pose_z_angle(x, y, z, angle_z, origin_id=0)¶: Returns a cozmo.util.Pose instance set to the pose given in z angle format.

class cozmo.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 cozmo.util.Quaternion(q0=None, q1=None, q2=None, q3=None, angle_z=None)¶

Represents the rotation of an object in the world. Can be generated with quaternion to define its rotation in 3d space, or with only a z axis rotation to define things limited to the x-y plane like Cozmo.

Use the rotation_quaternion() to return rotation defined by a quaternion.

Use the rotation_angle_z() to return rotation defined by an angle in the z axis.

angle_z¶

The z Euler component of the object’s rotation.

Defined as the rotation in the z axis.

Type:	class
Type:	Angle

euler_angles¶

Euler angles of an object.

Returns the pitch, yaw, roll Euler components of the object’s rotation defined as rotations in the x, y, and z axis respectively.

It interprets the rotations performed in the order: Z, Y, X

Type:	tuple of float

q0¶

The q0 (w) value of the quaternion.

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.

Type:	float

q2¶

The q2 (j) value of the quaternion.

Type:	float

q3¶

The q3 (k) value of the quaternion.

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:	`cozmo.util.Matrix44`

class cozmo.util.Rotation(q0=None, q1=None, q2=None, q3=None, angle_z=None)¶: An alias for Quaternion

cozmo.util.rotation_quaternion(q0, q1, q2, q3)¶: Returns a Rotation instance set by a quaternion.

cozmo.util.rotation_z_angle(angle_z)¶: Returns a class:Rotation instance set by an angle in the z axis

cozmo.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 (`cozmo.util.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)

class cozmo.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 (float) – The number of millimeters per second the speed should represent.

speed_mmps¶

The speed in millimeters per second (mmps).

Type:	float

cozmo.util.speed_mmps(speed_mmps)¶: Returns an cozmo.util.Speed instance set to the specified millimeters per second speed

class cozmo.util.Timeout(timeout=None, use_inf=False)¶

Utility class to keep track of a timeout condition.

This measures a timeout from the point in time that the class is instantiated.

Parameters:	timeout (float) – Amount of time (in seconds) allotted to pass before considering the timeout condition to be met. use_inf (bool) – If True, then `remaining` will return `math.inf` if timeout is None, else it will return None.

is_timed_out¶

True if the timeout has expired.

Type:	bool

remaining¶

The number of seconds remaining before reaching the timeout.

Will return a number of zero or higher, even if the timer has since expired (it will never return a negative value).

Will return None or math.inf (if use_inf was passed as True to the constructor) if the original timeout was None.

Type:	float

class cozmo.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 vector.

Parameters:	rhs (`Vector2`) – The right-hand-side of this assignment - the source vector to copy into this vector.

x¶

The x component.

Type:	float

x_y¶

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

Type:	tuple (float, float)

y¶

The y component.

Type:	float

class cozmo.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

set_to(rhs)¶

Copy the x, y and z components of the given vector.

Parameters:	rhs (`Vector3`) – The right-hand-side of this assignment - the source vector to copy into this vector.

x¶

The x component.

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.

Type:	float

z¶

The z component.

Type:	float