# medipipe Python API: `depthai_nodes.node.parsers.utils.medipipe` mediapipe.py. Description: This script contains utility functions for decoding the output of the MediaPipe hand tracking model. This script contains code that is based on or directly taken from a public GitHub repository: [https://github.com/geaxgx/depthai_hand_tracker](https://github.com/geaxgx/depthai_hand_tracker) Original code author(s): geaxgx License: MIT License Copyright (c) [2021] [geax] ## Classes ### HandRegion Store a detected palm and its derived rotated region. #### Methods ##### init ```python def __init__(pd_score=None, pd_box=None, pd_kps=None): ``` Store palm detection values before deriving a rotated region. Parameters * `pd_score`: Optional detection confidence. * `pd_box`: Optional normalized `[x, y, width, height]` box. * `pd_kps`: Optional normalized palm keypoints. #### Attributes ##### pd_box Normalized `[x, y, width, height]` box in the square image. ##### pd_kps Normalized `[x, y]` palm keypoints in the square image. ##### pd_score Palm detection confidence. ##### rect_h Normalized rectangle height, which may exceed 1. ##### rect_h_a Rectangle height in square-image pixels. ##### rect_points Four rectangle corners in pixels. Coordinates refer to the square image during processing and the source image on return. ##### rect_w Normalized rectangle width, which may exceed 1. ##### rect_w_a Rectangle width in square-image pixels. ##### rect_x_center Normalized rotated-rectangle center X coordinate. ##### rect_x_center_a Rectangle center X coordinate in square-image pixels. ##### rect_y_center Normalized rotated-rectangle center Y coordinate. ##### rect_y_center_a Rectangle center Y coordinate in square-image pixels. ##### rotation Rectangle rotation relative to the Y axis, in radians. ## Functions ### calculate_scale ```python def calculate_scale(min_scale, max_scale, stride_index, num_strides): ``` Interpolate an anchor scale across feature strides. Parameters * `min_scale`: Scale at the first stride. * `max_scale`: Scale at the last stride. * `stride_index`: Zero-based stride index. * `num_strides`: Number of strides; when one, use the midpoint scale. Returns * Interpolated anchor scale. ### compute_mediapipe_palm_detections ```python def compute_mediapipe_palm_detections(bboxes: np.ndarray, scores: np.ndarray, *, anchors: np.ndarray, conf_threshold: float, iou_threshold: float, max_det: int, scale: int, label_names: list[str] | None = None) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, list[str] | None]: ``` Decode MediaPipe palms into rotated detections and apply suppression. Parameters * `bboxes` (`np.ndarray`): Per-anchor palm box and landmark predictions. * `scores` (`np.ndarray`): Per-anchor palm score logits. * `anchors` (`np.ndarray`): Precomputed anchor coordinates used to decode model predictions. * `conf_threshold` (`float`): Minimum detection confidence used to filter candidates. * `iou_threshold` (`float`): Intersection-over-union threshold for non-maximum suppression. * `max_det` (`int`): Maximum number of detection candidates to retain or consider during suppression. * `scale` (`int`): Side length of the square model input in pixels. * `label_names` (`list[str] | None`): Optional class-name lookup indexed by predicted class ID. Returns * `tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, list[str] | None]`: Normalized center-XY/width/height boxes, confidence scores, angles in degrees, zero-valued class IDs, and optional class names. ### decode ```python def decode(bboxes, scores, anchors, threshold=0.5, scale=192): ``` Decode palm predictions and attach rotated pixel rectangles. Parameters * `bboxes`: Per-anchor box and landmark offsets of shape `(N, 18)`. * `scores`: One score logit per anchor. * `anchors`: Precomputed anchors matching the model input dimensions. * `threshold`: Minimum sigmoid score for keeping a detection. * `scale`: Side length of the square model input in pixels. Returns * List of `HandRegion` objects containing normalized palm geometry and pixel-space rotated rectangles. ### decode_bboxes ```python def decode_bboxes(score_thresh, scores, bboxes, anchors, scale=128, best_only=False): ``` Decode palm boxes and seven landmarks using SSD anchors. Parameters * `score_thresh`: Minimum sigmoid confidence for retaining a palm. * `scores`: One score logit per anchor. * `bboxes`: Per-anchor box and landmark offsets of shape `(N, 18)`. * `anchors`: Normalized center-XY/width/height anchors matching the prediction count. * `scale`: Model input side length used to normalize the predicted offsets. * `best_only`: Compatibility flag for highest-score selection; the standard decoding path uses false. Returns * List of `HandRegion` objects with normalized palm boxes and keypoints. Negative-width or negative-height boxes are discarded. Raises * `IndexError`: If predictions and anchors cannot be selected together. The current highest-score path also raises when a candidate meets the threshold. ### detections_to_rect ```python def detections_to_rect(regions): ``` Add normalized rotated-rectangle geometry to each palm in place. Parameters * `regions`: Hand regions with palm boxes and landmarks. The wrist-to-middle-finger direction determines rotation. ### generate_anchors ```python def generate_anchors(options): ``` Generate SSD anchors using MediaPipe's anchor layout. Based on the MediaPipe `ssd_anchors_calculator.cc` implementation. Parameters * `options` (`SSDAnchorOptions`): Layer sizes, strides, scales, and aspect ratios. Returns * Array of anchors in `[x_center, y_center, width, height]` format. ### generate_handtracker_anchors ```python def generate_handtracker_anchors(input_size_width, input_size_height): ``` Generate anchors for the MediaPipe palm-detection layout. Parameters * `input_size_width`: Model input width in pixels. * `input_size_height`: Model input height in pixels. Returns * Array of normalized center-XY/width/height anchors for strides 8, 16, 16, and 16. ### normalize_radians ```python def normalize_radians(angle): ``` Wrap an angle to the interval [-pi, pi). Parameters * `angle`: Input angle in radians. Returns * Equivalent angle between -pi inclusive and pi exclusive. ### rect_transformation ```python def rect_transformation(regions, w, h, no_shift=False): ``` Convert rotated regions to pixel rectangles in place. Parameters * `regions`: Regions already populated by `detections_to_rect()`. * `w`: Source image width in pixels. * `h`: Source image height in pixels. * `no_shift`: If false, shift toward the fingers and expand the square by 2.9; if true, keep the center and use the original longer side. ### rotated_rect_to_points ```python def rotated_rect_to_points(cx, cy, w, h, rotation): ``` Convert a rotated rectangle into integer pixel corners. Parameters * `cx`: Rectangle center X coordinate. * `cy`: Rectangle center Y coordinate. * `w`: Rectangle width in pixels. * `h`: Rectangle height in pixels. * `rotation`: Rotation angle in radians. Returns * Four integer XY coordinate lists in perimeter order. ## Attributes ### SSDAnchorOptions