API Reference

Everything you can import from detectors_world.

create_detector

create_detector(kind: str, **options: Any) -> Detector

Create a detector by name.

Parameters:

Name	Type	Description	Default
kind	str	"hand", "pose", "face" or "face_mesh".	required
**options	Any	Passed to the detector class, for example max_hands=1. See Hand, Pose, Face and FaceMesh.	{}

Raises:

Type	Description
ValueError	If kind is not a known detector.

Hand

Hand(*, max_hands: int = 2, detection_confidence: float = 0.5, tracking_confidence: float = 0.5, static_image: bool = False, model_path: PathLike | None = None)

Bases: _LandmarkDetector

Finds hands and their 21 landmarks (wrist, knuckles and fingertips).

Parameters:

Name	Type	Description	Default
max_hands	int	Largest number of hands to look for.	2
detection_confidence	float	Minimum confidence (0.0 to 1.0) to report a new hand.	0.5
tracking_confidence	float	Minimum confidence (0.0 to 1.0) to keep tracking a hand between frames.	0.5
static_image	bool	True for unrelated still images, False (default) for video frames.	False
model_path	PathLike | None	Use a local hand_landmarker.task file instead of downloading one.	None

detect

detect(frame: ndarray, *, draw: bool = True, color: Color = (224, 224, 224), point_color: Color = (0, 0, 255)) -> list[Landmarks]

Find hands in frame and optionally draw them on it.

Returns:

Type	Description
list[Landmarks]	One Landmarks per hand, with label set to "Left" or "Right".
list[Landmarks]	An empty list when no hand is visible. Labels name the person's own hands,
list[Landmarks]	and MediaPipe swaps them on a mirrored frame such as cv.flip(frame, 1).

locate

locate(frame: ndarray, *, hand: int = 0, draw: bool = True, color: Color = (0, 255, 0), radius: int = 6) -> list[list[int]]

Pixel positions of one hand's landmarks from the latest detect() call.

Parameters:

Name	Type	Description	Default
frame	ndarray	The image to draw on.	required
hand	int	Which hand to return, starting at 0.	0
draw	bool	Draw a dot on each landmark.	True
color	Color	Dot color in BGR.	(0, 255, 0)
radius	int	Dot radius in pixels.	6

Returns:

Type	Description
list[list[int]]	[[id, x, y], ...] for the 21 landmarks, or [] if that hand is not visible.

Pose

Pose(*, model: str = 'full', max_poses: int = 1, detection_confidence: float = 0.5, tracking_confidence: float = 0.5, static_image: bool = False, model_path: PathLike | None = None)

Bases: _LandmarkDetector

Finds a body and its 33 landmarks (face, shoulders, arms, hips, legs).

Parameters:

Name	Type	Description	Default
model	str	"lite" (fastest), "full" (default) or "heavy" (most accurate).	'full'
max_poses	int	Largest number of people to look for.	1
detection_confidence	float	Minimum confidence (0.0 to 1.0) to report a new body.	0.5
tracking_confidence	float	Minimum confidence (0.0 to 1.0) to keep tracking a body between frames.	0.5
static_image	bool	True for unrelated still images, False (default) for video frames.	False
model_path	PathLike | None	Use a local pose_landmarker_*.task file instead of downloading one.	None

detect

detect(frame: ndarray, *, draw: bool = True, color: Color = (224, 224, 224), point_color: Color = (0, 0, 255)) -> list[Landmarks]

Find bodies in frame and optionally draw them on it.

Returns:

Type	Description
list[Landmarks]	One Landmarks per body, or an empty list when nobody is visible.

locate

locate(frame: ndarray, *, pose: int = 0, draw: bool = True, color: Color = (0, 255, 0), radius: int = 6) -> list[list[int]]

Pixel positions of one body's landmarks from the latest detect() call.

Returns:

Type	Description
list[list[int]]	[[id, x, y], ...] for the 33 landmarks, or [] if nobody is visible.

Face

Face(*, detection_confidence: float = 0.6, static_image: bool = False, model_path: PathLike | None = None)

Bases: Detector

Finds faces and returns a box around each one (faces within about 2 m of the camera).

Parameters:

Name	Type	Description	Default
detection_confidence	float	Minimum confidence (0.0 to 1.0) to report a face.	0.6
static_image	bool	True for unrelated still images, False (default) for video frames.	False
model_path	PathLike | None	Use a local blaze_face_short_range.tflite file instead of downloading one.	None

detect

detect(frame: ndarray, *, draw: bool = True, color: Color = (0, 255, 0)) -> list[FaceBox]

Find faces in frame and optionally draw a box and key points on each.

Returns:

Type	Description
list[FaceBox]	One FaceBox per face, or an empty list when no face is visible.

locate

locate(frame: ndarray, *, draw: bool = True, color: Color = (0, 255, 0)) -> list[list[Any]]

Face boxes from the latest detect() call.

Parameters:

Name	Type	Description	Default
frame	ndarray	The image to draw on.	required
draw	bool	Draw a framed box and the confidence percentage on each face.	True
color	Color	Drawing color in BGR.	(0, 255, 0)

Returns:

Type	Description
list[list[Any]]	[[id, (x, y, width, height), score], ...], or [] when no face is visible.

FaceMesh

FaceMesh(*, max_faces: int = 2, detection_confidence: float = 0.5, tracking_confidence: float = 0.5, static_image: bool = False, model_path: PathLike | None = None)

Bases: _LandmarkDetector

Finds faces and their 478 mesh landmarks (including the irises).

Parameters:

Name	Type	Description	Default
max_faces	int	Largest number of faces to look for.	2
detection_confidence	float	Minimum confidence (0.0 to 1.0) to report a new face.	0.5
tracking_confidence	float	Minimum confidence (0.0 to 1.0) to keep tracking a face between frames.	0.5
static_image	bool	True for unrelated still images, False (default) for video frames.	False
model_path	PathLike | None	Use a local face_landmarker.task file instead of downloading one.	None

detect

detect(frame: ndarray, *, draw: bool = True, color: Color = (224, 224, 224), thickness: int = 1, radius: int = 2) -> list[Landmarks]

Find faces in frame and optionally draw the mesh on them.

Parameters:

Name	Type	Description	Default
frame	ndarray	A BGR image from OpenCV.	required
draw	bool	Draw a ring on each landmark and the face outlines (eyes, brows, lips, face oval).	True
color	Color	Drawing color in BGR.	(224, 224, 224)
thickness	int	Line thickness in pixels.	1
radius	int	Landmark ring radius in pixels.	2

Returns:

Type	Description
list[Landmarks]	One Landmarks per face, or an empty list when no face is visible.

locate

locate(frame: ndarray, *, face: int = 0, draw: bool = False, show_ids: bool = False, color: Color = (0, 255, 0), radius: int = 1) -> list[list[int]]

Pixel positions of one face's landmarks from the latest detect() call.

Parameters:

Name	Type	Description	Default
frame	ndarray	The image to draw on.	required
face	int	Which face to return, starting at 0.	0
draw	bool	Draw a dot on each landmark.	False
show_ids	bool	Write each landmark's number next to it, to find the ids you need.	False
color	Color	Dot and text color in BGR.	(0, 255, 0)
radius	int	Dot radius in pixels.	1

Returns:

Type	Description
list[list[int]]	[[id, x, y], ...] for the 478 landmarks, or [] if that face is not visible.

Detector

Detector(model: bytes, static_image: bool)

Bases: ABC

Base class for all detectors.

Detectors hold a loaded model. Use them as a context manager, or call close() when you are done, to release it.

detect abstractmethod

detect(frame: ndarray, *, draw: bool = True) -> list[Any]

Run the model on frame (a BGR image from OpenCV) and return what was found.

locate abstractmethod

locate(frame: ndarray) -> list[Any]

Return pixel positions from the latest detect() call.

close

close() -> None

Release the model. The detector cannot be used afterwards.

Landmarks dataclass

Landmarks(points: tuple[tuple[int, int], ...], normalized: tuple[tuple[float, float, float], ...], label: str | None = None, score: float | None = None)

Landmarks of one detected hand, body, or face mesh.

Attributes:

Name	Type	Description
points	tuple[tuple[int, int], ...]	(x, y) pixel coordinates, one per landmark.
normalized	tuple[tuple[float, float, float], ...]	(x, y, z) coordinates relative to the image size (0.0 to 1.0 for x and y).
label	str | None	"Left" or "Right" for hands, otherwise None. This is the person's own hand, and MediaPipe swaps the labels on a mirrored frame.
score	float | None	Confidence of label for hands, otherwise None.

FaceBox dataclass

FaceBox(x: int, y: int, width: int, height: int, score: float, keypoints: tuple[tuple[int, int], ...] = ())

One detected face.

Attributes:

Name	Type	Description
x	int	Left edge in pixels.
y	int	Top edge in pixels.
width	int	Box width in pixels.
height	int	Box height in pixels.
score	float	Detection confidence, from 0.0 to 1.0.
keypoints	tuple[tuple[int, int], ...]	(x, y) pixel positions of the eyes, nose tip, mouth and ear tragions.

box property

box: tuple[int, int, int, int]

The box as (x, y, width, height).

cache_dir

cache_dir() -> Path

Folder where downloaded model files are kept.

Set the DETECTORS_WORLD_CACHE environment variable to use another folder.

DetectorCreator

DetectorCreator()

Deprecated: use create_detector instead. Kept so 0.x code keeps running.