albumentations.core.keypoints_utils
Module for handling keypoint operations during augmentation. This module provides utilities for working with keypoints in various formats during the augmentation process. It includes functions for converting between coordinate systems, filtering keypoints based on visibility, validating keypoint data, and applying transformations to keypoints. The module supports different keypoint formats including xy, yx, and those with additional angle or size information.
Members
- classKeypointParams
- classKeypointsProcessor
- functionangle_to_2pi_range
- functioncheck_keypoints
- functionconvert_keypoints_from_albumentations
- functionconvert_keypoints_to_albumentations
- functionfilter_keypoints
KeypointParamsclass
KeypointParams(
format: str,
label_fields: Sequence[str] | None = None,
remove_invisible: bool = True,
angle_in_degrees: bool = True,
check_each_transform: bool = True
)Parameters of keypoints
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| format | str | - | format of keypoints. Should be '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 | One of:
| None | list of fields that are joined with keypoints, e.g labels. Should be same type as keypoints. |
| remove_invisible | bool | True | to remove invisible points after transform or not |
| angle_in_degrees | bool | True | angle in degrees or radians in 'xya', 'xyas', 'xysa' keypoints |
| check_each_transform | bool | True | if `True`, then keypoints will be checked after each dual transform. Default: `True` |
Notes
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.
KeypointsProcessorclass
KeypointsProcessor(
params: KeypointParams,
additional_targets: dict[str, str] | None = None
)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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| params | KeypointParams | - | Parameters for keypoint processing. |
| additional_targets | One of:
| None | Dictionary mapping additional target names to their types. |
angle_to_2pi_rangefunction
angle_to_2pi_range(
angles: np.ndarray
)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π.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| 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π).
check_keypointsfunction
check_keypoints(
keypoints: np.ndarray,
shape: ShapeType
)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. If depth is provided in shape, z-coordinates are within [0, depth) 4. Angles are within the range [0, 2π)
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| keypoints | np.ndarray | - | Array of keypoints with shape (N, 5+), where N is the number of keypoints. - First 2 columns are always x, y - Column 3 (if present) is z - Column 4 (if present) is angle - Column 5+ (if present) are additional attributes |
| shape | ShapeType | - | The shape of the image/volume: - For 2D: {'height': int, 'width': int} - For 3D: {'height': int, 'width': int, 'depth': int} |
Notes
- The function assumes that keypoint coordinates are in absolute pixel values, not normalized - Angles are in radians - Z-coordinates are only checked if 'depth' is present in shape
convert_keypoints_from_albumentationsfunction
convert_keypoints_from_albumentations(
keypoints: np.ndarray,
target_format: Literal['xy', 'yx', 'xya', 'xys', 'xyas', 'xysa', 'xyz'],
shape: ShapeType,
check_validity: bool = False,
angle_in_degrees: bool = True
)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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| 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 | One of:
| - | 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 | ShapeType | - | The shape of the image {'height': height, 'width': width, 'depth': depth}. |
| check_validity | bool | False | If True, check if the keypoints are within the image boundaries. Defaults to False. |
| angle_in_degrees | bool | True | 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+).
Notes
- 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
convert_keypoints_to_albumentationsfunction
convert_keypoints_to_albumentations(
keypoints: np.ndarray,
source_format: Literal['xy', 'yx', 'xya', 'xys', 'xyas', 'xysa', 'xyz'],
shape: ShapeType,
check_validity: bool = False,
angle_in_degrees: bool = True
)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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| 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 | One of:
| - | 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 | ShapeType | - | The shape of the image {'height': height, 'width': width, 'depth': depth}. |
| check_validity | bool | False | If True, check if the converted keypoints are within the image boundaries. Defaults to False. |
| angle_in_degrees | bool | True | 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+).
Notes
- 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
filter_keypointsfunction
filter_keypoints(
keypoints: np.ndarray,
shape: ShapeType,
remove_invisible: bool
)Filter keypoints to remove those outside the boundaries.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| keypoints | np.ndarray | - | A numpy array of shape (N, 5+) where N is the number of keypoints. Each row represents a keypoint (x, y, z, angle, scale, ...). |
| shape | ShapeType | - | Shape to check against as {'height': height, 'width': width, 'depth': depth}. |
| remove_invisible | bool | - | If True, remove keypoints outside the boundaries. |
Returns
- np.ndarray: Filtered keypoints.