From 2012ec7bcb3a78f12471f442a10c749097a0a157 Mon Sep 17 00:00:00 2001 From: LinasKo Date: Wed, 14 Aug 2024 12:46:16 +0300 Subject: [PATCH] Unify how optional values are marked in docstings * No longer means 'has default value'. Removed where it meant that. * `Optional[datatype]` is now used instead of `datatype, optional` * Fixed a handful of incorrect type annotations --- .../count_people_in_zone/inference_example.py | 2 +- .../ultralytics_example.py | 2 +- examples/time_in_zone/utils/timers.py | 2 +- supervision/annotators/core.py | 2 +- supervision/dataset/core.py | 20 +++++++------- supervision/dataset/formats/pascal_voc.py | 2 +- supervision/dataset/formats/yolo.py | 4 +-- supervision/detection/core.py | 8 +++--- supervision/detection/overlap_filter.py | 10 +++---- supervision/detection/tools/polygon_zone.py | 2 +- supervision/detection/utils.py | 2 +- supervision/draw/utils.py | 14 +++++----- supervision/keypoint/annotators.py | 27 ++++++++++--------- supervision/metrics/detection.py | 2 +- supervision/tracker/byte_tracker/core.py | 10 +++---- supervision/utils/image.py | 8 +++--- supervision/utils/internal.py | 9 ++++--- supervision/utils/video.py | 2 +- 18 files changed, 67 insertions(+), 61 deletions(-) diff --git a/examples/count_people_in_zone/inference_example.py b/examples/count_people_in_zone/inference_example.py index 96e3e83c..8f42ff43 100644 --- a/examples/count_people_in_zone/inference_example.py +++ b/examples/count_people_in_zone/inference_example.py @@ -75,7 +75,7 @@ def detect( frame (np.ndarray): The frame to process, expected to be a NumPy array. model (RoboflowInferenceModel): The Inference model used for processing the frame. - confidence_threshold (float, optional): The confidence threshold for filtering + confidence_threshold (float): The confidence threshold for filtering detections. Default is 0.5. Returns: diff --git a/examples/count_people_in_zone/ultralytics_example.py b/examples/count_people_in_zone/ultralytics_example.py index 87badadb..2fd07782 100644 --- a/examples/count_people_in_zone/ultralytics_example.py +++ b/examples/count_people_in_zone/ultralytics_example.py @@ -72,7 +72,7 @@ def detect( Args: frame (np.ndarray): The frame to process, expected to be a NumPy array. model (YOLO): The YOLO model used for processing the frame. - confidence_threshold (float, optional): The confidence threshold for filtering + confidence_threshold (float): The confidence threshold for filtering detections. Default is 0.5. Returns: diff --git a/examples/time_in_zone/utils/timers.py b/examples/time_in_zone/utils/timers.py index cb5b471f..7afa9af3 100644 --- a/examples/time_in_zone/utils/timers.py +++ b/examples/time_in_zone/utils/timers.py @@ -22,7 +22,7 @@ class FPSBasedTimer: """Initializes the FPSBasedTimer with the specified frames per second rate. Args: - fps (int, optional): The frame rate of the video stream. Defaults to 30. + fps (int): The frame rate of the video stream. Defaults to 30. """ self.fps = fps self.frame_id = 0 diff --git a/supervision/annotators/core.py b/supervision/annotators/core.py index ca2a71f8..b9a307da 100644 --- a/supervision/annotators/core.py +++ b/supervision/annotators/core.py @@ -1975,7 +1975,7 @@ class PercentageBarAnnotator(BaseAnnotator): border_color: Color = Color.BLACK, position: Position = Position.TOP_CENTER, color_lookup: ColorLookup = ColorLookup.CLASS, - border_thickness: int = None, + border_thickness: Optional[int] = None, ): """ Args: diff --git a/supervision/dataset/core.py b/supervision/dataset/core.py index 7d320bbc..37ba530b 100644 --- a/supervision/dataset/core.py +++ b/supervision/dataset/core.py @@ -181,11 +181,11 @@ class DetectionDataset(BaseDataset): using the provided split_ratio. Args: - split_ratio (float, optional): The ratio of the training + split_ratio (float): The ratio of the training set to the entire dataset. - random_state (int, optional): The seed for the random number generator. + random_state (Optional[int]): The seed for the random number generator. This is used for reproducibility. - shuffle (bool, optional): Whether to shuffle the data before splitting. + shuffle (bool): Whether to shuffle the data before splitting. Returns: Tuple[DetectionDataset, DetectionDataset]: A tuple containing @@ -396,7 +396,7 @@ class DetectionDataset(BaseDataset): images_directory_path (str): Path to the directory containing the images. annotations_directory_path (str): Path to the directory containing the PASCAL VOC XML annotations. - force_masks (bool, optional): If True, forces masks to + force_masks (bool): If True, forces masks to be loaded for all annotations, regardless of whether they are present. Returns: @@ -455,10 +455,10 @@ class DetectionDataset(BaseDataset): containing the YOLO annotation files. data_yaml_path (str): The path to the data YAML file containing class information. - force_masks (bool, optional): If True, forces + force_masks (bool): If True, forces masks to be loaded for all annotations, regardless of whether they are present. - is_obb (bool, optional): If True, loads the annotations in OBB format. + is_obb (bool): If True, loads the annotations in OBB format. OBB annotations are defined as `[class_id, x, y, x, y, x, y, x, y]`, where pairs of [x, y] are box corners. @@ -565,7 +565,7 @@ class DetectionDataset(BaseDataset): images_directory_path (str): The path to the directory containing the images. annotations_path (str): The path to the json annotation files. - force_masks (bool, optional): If True, + force_masks (bool): If True, forces masks to be loaded for all annotations, regardless of whether they are present. @@ -784,11 +784,11 @@ class ClassificationDataset(BaseDataset): using the provided split_ratio. Args: - split_ratio (float, optional): The ratio of the training + split_ratio (float): The ratio of the training set to the entire dataset. - random_state (int, optional): The seed for the + random_state (Optional[int]): The seed for the random number generator. This is used for reproducibility. - shuffle (bool, optional): Whether to shuffle the data before splitting. + shuffle (bool): Whether to shuffle the data before splitting. Returns: Tuple[ClassificationDataset, ClassificationDataset]: A tuple containing diff --git a/supervision/dataset/formats/pascal_voc.py b/supervision/dataset/formats/pascal_voc.py index b9724564..49c59a39 100644 --- a/supervision/dataset/formats/pascal_voc.py +++ b/supervision/dataset/formats/pascal_voc.py @@ -147,7 +147,7 @@ def load_pascal_voc_annotations( images_directory_path (str): The path to the directory containing the images. annotations_directory_path (str): The path to the directory containing the PASCAL VOC annotation files. - force_masks (bool, optional): If True, forces masks to be loaded for all + force_masks (bool): If True, forces masks to be loaded for all annotations, regardless of whether they are present. Returns: diff --git a/supervision/dataset/formats/yolo.py b/supervision/dataset/formats/yolo.py index 0ecbac4b..1f9033fc 100644 --- a/supervision/dataset/formats/yolo.py +++ b/supervision/dataset/formats/yolo.py @@ -138,9 +138,9 @@ def load_yolo_annotations( containing the YOLO annotation files. data_yaml_path (str): The path to the data YAML file containing class information. - force_masks (bool, optional): If True, forces masks to be loaded + force_masks (bool): If True, forces masks to be loaded for all annotations, regardless of whether they are present. - is_obb (bool, optional): If True, loads the annotations in OBB format. + is_obb (bool): If True, loads the annotations in OBB format. OBB annotations are defined as `[class_id, x, y, x, y, x, y, x, y]`, where pairs of [x, y] are box corners. diff --git a/supervision/detection/core.py b/supervision/detection/core.py index 73daadda..87142ef6 100644 --- a/supervision/detection/core.py +++ b/supervision/detection/core.py @@ -1149,10 +1149,10 @@ class Detections: from a segmentation model, the IoU mask is applied. Otherwise, box IoU is used. Args: - threshold (float, optional): The intersection-over-union threshold + threshold (float): The intersection-over-union threshold to use for non-maximum suppression. I'm the lower the value the more restrictive the NMS becomes. Defaults to 0.5. - class_agnostic (bool, optional): Whether to perform class-agnostic + class_agnostic (bool): Whether to perform class-agnostic non-maximum suppression. If True, the class_id of each detection will be ignored. Defaults to False. @@ -1204,9 +1204,9 @@ class Detections: Perform non-maximum merging on the current set of object detections. Args: - threshold (float, optional): The intersection-over-union threshold + threshold (float): The intersection-over-union threshold to use for non-maximum merging. Defaults to 0.5. - class_agnostic (bool, optional): Whether to perform class-agnostic + class_agnostic (bool): Whether to perform class-agnostic non-maximum merging. If True, the class_id of each detection will be ignored. Defaults to False. diff --git a/supervision/detection/overlap_filter.py b/supervision/detection/overlap_filter.py index f51f1dce..461e413c 100644 --- a/supervision/detection/overlap_filter.py +++ b/supervision/detection/overlap_filter.py @@ -55,9 +55,9 @@ def mask_non_max_suppression( masks (np.ndarray): A 3D array of binary masks corresponding to the predictions. Shape: `(N, H, W)`, where N is the number of predictions, and H, W are the dimensions of each mask. - iou_threshold (float, optional): The intersection-over-union threshold + iou_threshold (float): The intersection-over-union threshold to use for non-maximum suppression. - mask_dimension (int, optional): The dimension to which the masks should be + mask_dimension (int): The dimension to which the masks should be resized before computing IOU values. Defaults to 640. Returns: @@ -103,7 +103,7 @@ def box_non_max_suppression( predictions (np.ndarray): An array of object detection predictions in the format of `(x_min, y_min, x_max, y_max, score)` or `(x_min, y_min, x_max, y_max, score, class)`. - iou_threshold (float, optional): The intersection-over-union threshold + iou_threshold (float): The intersection-over-union threshold to use for non-maximum suppression. Returns: @@ -158,7 +158,7 @@ def group_overlapping_boxes( predictions (npt.NDArray[np.float64]): An array of shape `(n, 5)` containing the bounding boxes coordinates in format `[x1, y1, x2, y2]` and the confidence scores. - iou_threshold (float, optional): The intersection-over-union threshold + iou_threshold (float): The intersection-over-union threshold to use for non-maximum suppression. Defaults to 0.5. Returns: @@ -202,7 +202,7 @@ def box_non_max_merge( containing the bounding boxes coordinates in format `[x1, y1, x2, y2]`, the confidence scores and class_ids. Omit class_id column to allow detections of different classes to be merged. - iou_threshold (float, optional): The intersection-over-union threshold + iou_threshold (float): The intersection-over-union threshold to use for non-maximum suppression. Defaults to 0.5. Returns: diff --git a/supervision/detection/tools/polygon_zone.py b/supervision/detection/tools/polygon_zone.py index f1c48f94..c1e030f9 100644 --- a/supervision/detection/tools/polygon_zone.py +++ b/supervision/detection/tools/polygon_zone.py @@ -147,7 +147,7 @@ class PolygonZoneAnnotator: Parameters: scene (np.ndarray): The image on which the polygon zone will be annotated - label (Optional[str]): An optional label for the count of detected objects + label (Optional[str]): A label for the count of detected objects within the polygon zone (default: None) Returns: diff --git a/supervision/detection/utils.py b/supervision/detection/utils.py index a02a6a1f..1a336ca7 100644 --- a/supervision/detection/utils.py +++ b/supervision/detection/utils.py @@ -106,7 +106,7 @@ def mask_iou_batch( Args: masks_true (np.ndarray): 3D `np.ndarray` representing ground-truth masks. masks_detection (np.ndarray): 3D `np.ndarray` representing detection masks. - memory_limit (int, optional): memory limit in MB, default is 1024 * 5 MB (5GB). + memory_limit (int): memory limit in MB, default is 1024 * 5 MB (5GB). Returns: np.ndarray: Pairwise IoU of masks from `masks_true` and `masks_detection`. diff --git a/supervision/draw/utils.py b/supervision/draw/utils.py index 884f6d18..36651811 100644 --- a/supervision/draw/utils.py +++ b/supervision/draw/utils.py @@ -142,7 +142,7 @@ def draw_polygon( scene (np.ndarray): The scene to draw the polygon on. polygon (np.ndarray): The polygon to be drawn, given as a list of vertices. color (Color): The color of the polygon. - thickness (int, optional): The thickness of the polygon lines, by default 2. + thickness (int): The thickness of the polygon lines, by default 2. Returns: np.ndarray: The scene with the polygon drawn on it. @@ -172,14 +172,14 @@ def draw_text( text (str): The text to be drawn. text_anchor (Point): The anchor point for the text, represented as a Point object with x and y attributes. - text_color (Color, optional): The color of the text. Defaults to black. - text_scale (float, optional): The scale of the text. Defaults to 0.5. - text_thickness (int, optional): The thickness of the text. Defaults to 1. - text_padding (int, optional): The amount of padding to add around the text + text_color (Color): The color of the text. Defaults to black. + text_scale (float): The scale of the text. Defaults to 0.5. + text_thickness (int): The thickness of the text. Defaults to 1. + text_padding (int): The amount of padding to add around the text when drawing a rectangle in the background. Defaults to 10. - text_font (int, optional): The font to use for the text. + text_font (int): The font to use for the text. Defaults to cv2.FONT_HERSHEY_SIMPLEX. - background_color (Color, optional): The color of the background rectangle, + background_color (Optional[Color]): The color of the background rectangle, if one is to be drawn. Defaults to None. Returns: diff --git a/supervision/keypoint/annotators.py b/supervision/keypoint/annotators.py index e50043e1..6258ac12 100644 --- a/supervision/keypoint/annotators.py +++ b/supervision/keypoint/annotators.py @@ -34,8 +34,8 @@ class VertexAnnotator(BaseKeyPointAnnotator): ) -> None: """ Args: - color (Color, optional): The color to use for annotating key points. - radius (int, optional): The radius of the circles used to represent the key + color (Color): The color to use for annotating key points. + radius (int): The radius of the circles used to represent the key points. """ self.color = color @@ -108,8 +108,8 @@ class EdgeAnnotator(BaseKeyPointAnnotator): ) -> None: """ Args: - color (Color, optional): The color to use for the edges. - thickness (int, optional): The thickness of the edges. + color (Color): The color to use for the edges. + thickness (int): The thickness of the edges. edges (Optional[List[Tuple[int, int]]]): The edges to draw. If set to `None`, will attempt to select automatically. """ @@ -202,16 +202,16 @@ class VertexLabelAnnotator: ): """ Args: - color (Union[Color, List[Color]], optional): The color to use for each + color (Union[Color, List[Color]]): The color to use for each keypoint label. If a list is provided, the colors will be used in order for each keypoint. - text_color (Union[Color, List[Color]], optional): The color to use + text_color (Union[Color, List[Color]]): The color to use for the labels. If a list is provided, the colors will be used in order for each keypoint. - text_scale (float, optional): The scale of the text. - text_thickness (int, optional): The thickness of the text. - text_padding (int, optional): The padding around the text. - border_radius (int, optional): The radius of the rounded corners of the + text_scale (float): The scale of the text. + text_thickness (int): The thickness of the text. + text_padding (int): The padding around the text. + border_radius (int): The radius of the rounded corners of the boxes. Set to a high value to produce circles. """ self.border_radius: int = border_radius @@ -222,7 +222,10 @@ class VertexLabelAnnotator: self.text_padding: int = text_padding def annotate( - self, scene: ImageType, key_points: KeyPoints, labels: List[str] = None + self, + scene: ImageType, + key_points: KeyPoints, + labels: Optional[List[str]] = None, ) -> ImageType: """ A class that draws labels of skeleton vertices on images. It uses specified key @@ -234,7 +237,7 @@ class VertexLabelAnnotator: `PIL.Image.Image`. key_points (KeyPoints): A collection of key points where each key point consists of x and y coordinates. - labels (List[str], optional): A list of labels to be displayed on the + labels (Optional[List[str]]): A list of labels to be displayed on the annotated image. If not provided, keypoint indices will be used. Returns: diff --git a/supervision/metrics/detection.py b/supervision/metrics/detection.py index bbbfa711..5b9e6ca4 100644 --- a/supervision/metrics/detection.py +++ b/supervision/metrics/detection.py @@ -806,7 +806,7 @@ class MeanAveragePrecision: prediction_confidence (np.ndarray): Objectness value from 0-1. prediction_class_ids (np.ndarray): Predicted object classes. true_class_ids (np.ndarray): True object classes. - eps (float, optional): Small value to prevent division by zero. + eps (float): Small value to prevent division by zero. Returns: np.ndarray: Average precision for different IoU levels. diff --git a/supervision/tracker/byte_tracker/core.py b/supervision/tracker/byte_tracker/core.py index bd9bae50..4be3b184 100644 --- a/supervision/tracker/byte_tracker/core.py +++ b/supervision/tracker/byte_tracker/core.py @@ -197,19 +197,19 @@ class ByteTrack: Parameters: - track_activation_threshold (float, optional): Detection confidence threshold + track_activation_threshold (float): Detection confidence threshold for track activation. Increasing track_activation_threshold improves accuracy and stability but might miss true detections. Decreasing it increases completeness but risks introducing noise and instability. - lost_track_buffer (int, optional): Number of frames to buffer when a track is lost. + lost_track_buffer (int): Number of frames to buffer when a track is lost. Increasing lost_track_buffer enhances occlusion handling, significantly reducing the likelihood of track fragmentation or disappearance caused by brief detection gaps. - minimum_matching_threshold (float, optional): Threshold for matching tracks with detections. + minimum_matching_threshold (float): Threshold for matching tracks with detections. Increasing minimum_matching_threshold improves accuracy but risks fragmentation. Decreasing it improves completeness but risks false positives and drift. - frame_rate (int, optional): The frame rate of the video. - minimum_consecutive_frames (int, optional): Number of consecutive frames that an object must + frame_rate (int): The frame rate of the video. + minimum_consecutive_frames (int): Number of consecutive frames that an object must be tracked before it is considered a 'valid' track. Increasing minimum_consecutive_frames prevents the creation of accidental tracks from false detection or double detection, but risks missing shorter tracks. diff --git a/supervision/utils/image.py b/supervision/utils/image.py index d6972189..edd34c8e 100644 --- a/supervision/utils/image.py +++ b/supervision/utils/image.py @@ -158,7 +158,7 @@ def resize_image( accepting either `numpy.ndarray` or `PIL.Image.Image`. resolution_wh (Tuple[int, int]): The target resolution as `(width, height)`. - keep_aspect_ratio (bool, optional): Flag to maintain the image's original + keep_aspect_ratio (bool): Flag to maintain the image's original aspect ratio. Defaults to `False`. Returns: @@ -360,9 +360,9 @@ class ImageSink: Args: target_dir_path (str): The target directory where images will be saved. - overwrite (bool, optional): Whether to overwrite the existing directory. + overwrite (bool): Whether to overwrite the existing directory. Defaults to False. - image_name_pattern (str, optional): The image file name pattern. + image_name_pattern (str): The image file name pattern. Defaults to "image_{:05d}.png". Examples: @@ -399,7 +399,7 @@ class ImageSink: Args: image (np.ndarray): The image to be saved. The image must be in BGR color format. - image_name (str, optional): The name to use for the saved image. + image_name (Optional[str]): The name to use for the saved image. If not provided, a name will be generated using the `image_name_pattern`. """ diff --git a/supervision/utils/internal.py b/supervision/utils/internal.py index cc8d4c79..10f4a450 100644 --- a/supervision/utils/internal.py +++ b/supervision/utils/internal.py @@ -56,9 +56,9 @@ def deprecated_parameter( Parameters: old_parameter (str): The name of the deprecated parameter. new_parameter (str): The name of the parameter that should be used instead. - map_function (Callable, optional): A function used to map the value of the old + map_function (Callable): A function used to map the value of the old parameter to the new parameter. Defaults to the identity function. - warning_message (str, optional): The warning message to be displayed when the + warning_message (str): The warning message to be displayed when the deprecated parameter is used. Defaults to a generic warning message with placeholders for the old parameter, new parameter, and function name. **message_kwargs: Additional keyword arguments that can be used to customize @@ -121,7 +121,9 @@ def deprecated(reason: str): return decorator -T = TypeVar('T') + +T = TypeVar("T") + class classproperty(Generic[T]): """ @@ -134,6 +136,7 @@ class classproperty(Generic[T]): def my_method(cls): ... """ + def __init__(self, fget: Callable[..., T]): """ Args: diff --git a/supervision/utils/video.py b/supervision/utils/video.py index 7e9836de..26405ec4 100644 --- a/supervision/utils/video.py +++ b/supervision/utils/video.py @@ -19,7 +19,7 @@ class VideoInfo: width (int): width of the video in pixels height (int): height of the video in pixels fps (int): frames per second of the video - total_frames (int, optional): total number of frames in the video, + total_frames (Optional[int]): total number of frames in the video, default is None Examples: