cozmo.faces¶

Face recognition and enrollment.

Cozmo is capable of recognizing human faces, tracking their position and rotation (“pose”) and assigning names to them via an enrollment process.

The cozmo.world.World object keeps track of faces the robot currently knows about, along with those that are currently visible to the camera.

Each face is assigned a Face object, which generates a number of observable events whenever the face is observed, has its ID updated, is renamed, etc.

Note that these face-specific events are also passed up to the cozmo.world.World object, so events for all known faces can be observed by adding handlers there.

Functions

`erase_all_enrolled_faces`(conn)	Erase the enrollment (name) records for all faces.
`erase_enrolled_face_by_id`(conn, face_id)	Erase the enrollment (name) record for the face with this ID.
`update_enrolled_face_by_id`(conn, face_id, …)	Update the name enrolled for a given face.

Classes

`EvtErasedEnrolledFace`(**kwargs)	Triggered when a face enrollment is removed (via erase_enrolled_face_by_id)
`EvtFaceAppeared`(**kwargs)	Triggered whenever a face is first visually identified by a robot.
`EvtFaceDisappeared`(**kwargs)	Triggered whenever a face that was previously being observed is no longer visible.
`EvtFaceIdChanged`(**kwargs)	Triggered whenever a face has its ID updated in engine.
`EvtFaceObserved`(**kwargs)	Triggered whenever a face is visually identified by the robot.
`EvtFaceRenamed`(**kwargs)	Triggered whenever a face is renamed (via RobotRenamedEnrolledFace)
`Face`(conn, world, robot[, face_id])	A single face that Cozmo has detected.

cozmo.faces.FACE_VISIBILITY_TIMEOUT = 0.4¶: Length of time in seconds to go without receiving an observed event before assuming that Cozmo can no longer see a face.

cozmo.faces.FACIAL_EXPRESSION_UNKNOWN = 'unknown'¶: Facial expression not recognized. Call cozmo.robot.Robot.enable_facial_expression_estimation() to enable recognition.

cozmo.faces.FACIAL_EXPRESSION_NEUTRAL = 'neutral'¶: Facial expression neutral

cozmo.faces.FACIAL_EXPRESSION_HAPPY = 'happy'¶: Facial expression happy

cozmo.faces.FACIAL_EXPRESSION_SURPRISED = 'surprised'¶: Facial expression surprised

cozmo.faces.FACIAL_EXPRESSION_ANGRY = 'angry'¶: Facial expression angry

cozmo.faces.FACIAL_EXPRESSION_SAD = 'sad'¶: Facial expression sad

class cozmo.faces.EvtErasedEnrolledFace(**kwargs)¶

Triggered when a face enrollment is removed (via erase_enrolled_face_by_id)

face = 'The Face instance that the enrollment is being erased for'¶

old_name = 'The name previously used for this face'¶

class cozmo.faces.EvtFaceAppeared(**kwargs)¶

Triggered whenever a face is first visually identified by a robot.

This differs from EvtFaceObserved in that it’s only triggered when a face initially becomes visible. If it disappears for more than FACE_VISIBILITY_TIMEOUT seconds and then is seen again, a EvtFaceDisappeared will be dispatched, followed by another EvtFaceAppeared event.

For continuous tracking information about a visible face, see EvtFaceObserved.

face = 'The Face instance that was observed'¶

image_box = "A comzo.util.ImageBox defining where the face is within Cozmo's camera view"¶

name = 'The name associated with the face that was observed'¶

pose = 'The cozmo.util.Pose defining the position and rotation of the face.'¶

updated = 'A set of field names that have changed'¶

class cozmo.faces.EvtFaceDisappeared(**kwargs)¶

Triggered whenever a face that was previously being observed is no longer visible.

face = 'The Face instance that is no longer being observed'¶

class cozmo.faces.EvtFaceIdChanged(**kwargs)¶

Triggered whenever a face has its ID updated in engine.

Generally occurs when: 1) A tracked but unrecognized face (negative ID) is recognized and receives a positive ID or 2) Face records get merged (on realization that 2 faces are actually the same)

face = 'The Face instance that is being given a new id'¶

new_id = 'The new ID that will be used for this face'¶

old_id = 'The ID previously used for this face'¶

class cozmo.faces.EvtFaceObserved(**kwargs)¶

Triggered whenever a face is visually identified by the robot.

A stream of these events are produced while a face is visible to the robot. Each event has an updated image_box field.

See EvtFaceAppeared if you only want to know when a face first becomes visible.

face = 'The Face instance that was observed'¶

image_box = "A comzo.util.ImageBox defining where the face is within Cozmo's camera view"¶

name = 'The name associated with the face that was observed'¶

pose = 'The cozmo.util.Pose defining the position and rotation of the face.'¶

updated = 'A set of field names that have changed'¶

class cozmo.faces.EvtFaceRenamed(**kwargs)¶

Triggered whenever a face is renamed (via RobotRenamedEnrolledFace)

face = 'The Face instance that is being given a new name'¶

new_name = 'The new name that will be used for this face'¶

old_name = 'The name previously used for this face'¶

class cozmo.faces.Face(conn, world, robot, face_id=None, **kw)¶

A single face that Cozmo has detected.

May represent a face that has previously been enrolled, in which case name will hold the name that it was enrolled with.

Each Face instance has a face_id integer - This may change if Cozmo later gets an improved view and makes a different prediction about which face it is looking at.

See parent class ObservableElement for additional properties and methods.

erase_enrolled_face()¶

Remove the name associated with this face.

Cozmo will no longer remember the name associated with this face between SDK runs.

expression¶

The facial expression Cozmo has recognized on the face.

Will be FACIAL_EXPRESSION_UNKNOWN by default if you haven’t called cozmo.robot.Robot.enable_facial_expression_estimation() to enable the facial expression estimation. Otherwise it will be equal to one of: FACIAL_EXPRESSION_NEUTRAL, FACIAL_EXPRESSION_HAPPY, FACIAL_EXPRESSION_SURPRISED, FACIAL_EXPRESSION_ANGRY, or FACIAL_EXPRESSION_SAD.

Type:	string

expression_score¶

The score/confidence that expression was correct.

Will be 0 if expression is FACIAL_EXPRESSION_UNKNOWN (e.g. if cozmo.robot.Robot.enable_facial_expression_estimation() wasn’t called yet). The maximum possible score is 100.

Type:	int

face_id¶

The internal ID assigned to the face.

This value can only be assigned once as it is static in the engine.

Type:	int

has_updated_face_id¶

True if this face been updated / superseded by a face with a new ID

Type:	bool

known_expression¶

The known facial expression Cozmo has recognized on the face.

Like expression() but returns an empty string for the unknown expression.

Type:	string

left_eye¶

points representing the outline of the left eye

Type:	sequence of tuples of float (x,y)

mouth¶

points representing the outline of the mouth

Type:	sequence of tuples of float (x,y)

name¶

The name Cozmo has associated with the face in his memory.

This string will be empty if the face is not recognized or enrolled.

Type:	string

name_face(name)¶

Assign a name to this face. Cozmo will remember this name between SDK runs.

Parameters:	name (string) – The name that will be assigned to this face. Must be a non-empty ASCII string of alphabetic characters only.
Returns:	An instance of `cozmo.behavior.Behavior` object
Raises:	`ValueError` if name is invalid.

nose¶

points representing the outline of the nose

Type:	sequence of tuples of float (x,y)

rename_face(new_name)¶

Change the name assigned to the face. Cozmo will remember this name between SDK runs.

Parameters:	new_name (string) – The new name that will be assigned to this face. Must be a non-empty ASCII string of alphabetic characters only.
Raises:	`ValueError` if new_name is invalid.

right_eye¶

points representing the outline of the right eye

Type:	sequence of tuples of float (x,y)

updated_face_id¶

The ID for the face that superseded this one (if any, otherwise face_id())

Type:	int

visibility_timeout = 0.4¶: Length of time in seconds to go without receiving an observed event before assuming that Cozmo can no longer see a face.

cozmo.faces.erase_all_enrolled_faces(conn)¶

Erase the enrollment (name) records for all faces.

Parameters:	conn (`CozmoConnection`) – The connection to send the message over

cozmo.faces.erase_enrolled_face_by_id(conn, face_id)¶

Erase the enrollment (name) record for the face with this ID.

Parameters:	conn (`CozmoConnection`) – The connection to send the message over face_id (int) – The ID of the face to erase.

cozmo.faces.update_enrolled_face_by_id(conn, face_id, old_name, new_name)¶

Update the name enrolled for a given face.

Parameters:	conn (`CozmoConnection`) – The connection to send the message over. face_id (int) – The ID of the face to rename. old_name (string) – The old name of the face (must be correct, otherwise message is ignored). new_name (string) – The new name for the face.