albumentations.core.keypoints_utils

Convert angles to the range [0, 2π). This function takes an array of angles and ensures they are all within the range of 0 to 2π (exclusive) by applying modulo 2π. Args: angles (np.ndarray): Array of angle values in radians. Returns: np.ndarray: Array of the same shape as input with angles normalized to [0, 2π).

Parameters

Parameters of keypoints Args: coord_format (Literal["xy", "yx", "xya", "xys", "xyas", "xysa", "xyz"]): Coordinate format of keypoints. Should be one of: 'xy', 'yx', 'xya', 'xys', 'xyas', 'xysa', 'xyz'. x - X coordinate, y - Y coordinate z - Z coordinate (for 3D keypoints) s - Keypoint scale a - Keypoint orientation in radians or degrees (depending on KeypointParams.angle_in_degrees) label_fields (list[str]): list of fields that are joined with keypoints, e.g labels. Should be same type as keypoints. remove_invisible (bool): to remove invisible points after transform or not angle_in_degrees (bool): angle in degrees or radians in 'xya', 'xyas', 'xysa' keypoints check_each_transform (bool): if `True`, then keypoints will be checked after each dual transform. Default: `True` label_mapping (dict[str, dict[str, dict[Any, Any]]] | None): Dictionary mapping transform names to label field mappings. Structure: {transform_name: {label_field: {from_label: to_label}}}. For example: {'HorizontalFlip': {'keypoint_labels': {'left_eye': 'right_eye', 'right_eye': 'left_eye'}}} or {'HorizontalFlip': {'keypoint_labels': {0: 1, 1: 0}}}. Works with any hashable label type. Can map multiple label fields per transform. Default: None. Note: The internal Albumentations format is [x, y, z, angle, scale]. For 2D formats (xy, yx, xya, xys, xyas, xysa), z coordinate is set to 0. For formats without angle or scale, these values are set to 0.

Parameters

Processor for keypoint data transformation. This class handles the conversion, validation, and filtering of keypoints during transformations. It ensures keypoints are correctly formatted and processed according to the specified keypoint parameters. Args: params (KeypointParams): Parameters for keypoint processing. additional_targets (dict[str, str] | None): Dictionary mapping additional target names to their types.

Parameters

Check if keypoint coordinates are within valid ranges for the given shape. This function validates that: 1. All x-coordinates are within [0, width) 2. All y-coordinates are within [0, height) 3. For 3D keypoints: All z-coordinates are within [0, depth) 4. Angles are within the range [0, 2π) Args: keypoints (np.ndarray): Array of keypoints with shape (N, 3+) for 3D or (N, 2+) for 2D. - First 2 columns are always x, y - Column 3 (if present) is z for 3D or angle for 2D - Column 4 (if present) is angle for 3D or scale for 2D - Column 5+ (if present) are additional attributes shape (tuple[int, int] | tuple[int, int, int]): The shape of the image/volume - (height, width) for 2D - (depth, height, width) for 3D Raises: ValueError: If any keypoint coordinate is outside the valid range, or if angles are invalid. The error message will detail which keypoints are invalid and why. Note: - The function assumes that keypoint coordinates are in absolute pixel values, not normalized - Angles are in radians

Parameters

Filter keypoints to remove those outside the boundaries. Args: keypoints (np.ndarray): A numpy array of shape (N, 3+) where N is the number of keypoints. Each row represents a keypoint (x, y, z, ...) for 3D or (x, y, ...) for 2D. shape (tuple[int, int] | tuple[int, int, int]): Shape to check against as (height, width) for 2D or (depth, height, width) for 3D. remove_invisible (bool): If True, remove keypoints outside the boundaries. Returns: np.ndarray: Filtered keypoints.

Parameters

Convert keypoints from various formats to the Albumentations format. This function takes keypoints in different formats and converts them to the standard Albumentations format: [x, y, z, angle, scale]. For 2D formats, z is set to 0. For formats without angle or scale, these values are set to 0. Args: keypoints (np.ndarray): Array of keypoints with shape (N, 2+), where N is the number of keypoints. The number of columns depends on the source_format. source_format (Literal["xy", "yx", "xya", "xys", "xyas", "xysa", "xyz"]): The format of the input keypoints. - "xy": [x, y] - "yx": [y, x] - "xya": [x, y, angle] - "xys": [x, y, scale] - "xyas": [x, y, angle, scale] - "xysa": [x, y, scale, angle] - "xyz": [x, y, z] shape (tuple[int, int] | tuple[int, int, int]): The shape of the image (height, width) or volume (depth, height, width). check_validity (bool, optional): If True, check if the converted keypoints are within the image/volume boundaries. Defaults to False. angle_in_degrees (bool, optional): If True, convert input angles from degrees to radians. Defaults to True. Returns: np.ndarray: Array of keypoints in Albumentations format [x, y, z, angle, scale] with shape (N, 5+). Any additional columns from the input keypoints are preserved and appended after the first 5 columns. Raises: ValueError: If the source_format is not one of the supported formats. Note: - For 2D formats (xy, yx, xya, xys, xyas, xysa), z coordinate is set to 0 - Angles are converted to the range [0, 2π) radians - If the input keypoints have additional columns beyond what's specified in the source_format, these columns are preserved in the output

Parameters

Convert keypoints from Albumentations format to various other formats. This function takes keypoints in the standard Albumentations format [x, y, z, angle, scale] and converts them to the specified target format. Args: keypoints (np.ndarray): Array of keypoints in Albumentations format with shape (N, 5+), where N is the number of keypoints. Each row represents a keypoint [x, y, z, angle, scale, ...]. target_format (Literal["xy", "yx", "xya", "xys", "xyas", "xysa", "xyz"]): The desired output format. - "xy": [x, y] - "yx": [y, x] - "xya": [x, y, angle] - "xys": [x, y, scale] - "xyas": [x, y, angle, scale] - "xysa": [x, y, scale, angle] - "xyz": [x, y, z] shape (tuple[int, int] | tuple[int, int, int]): The shape of the image (height, width) or volume (depth, height, width). check_validity (bool, optional): If True, check if the keypoints are within the image/volume boundaries. Defaults to False. angle_in_degrees (bool, optional): If True, convert output angles to degrees. If False, angles remain in radians. Defaults to True. Returns: np.ndarray: Array of keypoints in the specified target format with shape (N, 2+). Any additional columns from the input keypoints beyond the first 5 are preserved and appended after the converted columns. Raises: ValueError: If the target_format is not one of the supported formats. Note: - Input angles are assumed to be in the range [0, 2π) radians - If the input keypoints have additional columns beyond the first 5, these columns are preserved in the output

Parameters