Merge branch 'master' into master

benchmarks.py

@@ -60,7 +60,41 @@ def run(
     pt_only=False,  # test PyTorch only
     hard_fail=False,  # throw error on benchmark failure
 ):
-    """Run YOLOv5 benchmarks on multiple export formats and log results for model performance evaluation."""
+    """
+    Run YOLOv5 benchmarks on multiple export formats and log results for model performance evaluation.
+
+    Args:
+        weights (Path | str): Path to the model weights file (default: ROOT / "yolov5s.pt").
+        imgsz (int): Inference size in pixels (default: 640).
+        batch_size (int): Batch size for inference (default: 1).
+        data (Path | str): Path to the dataset.yaml file (default: ROOT / "data/coco128.yaml").
+        device (str): CUDA device, e.g., '0' or '0,1,2,3' or 'cpu' (default: None).
+        half (bool): Use FP16 half-precision inference (default: False).
+        test (bool): Test export formats only (default: False).
+        pt_only (bool): Test PyTorch format only (default: False).
+        hard_fail (bool): Throw an error on benchmark failure if True (default: False).
+
+    Returns:
+        None. Logs information about the benchmark results, including the format, size, mAP50-95, and inference time.
+
+    Notes:
+        Supported export formats and models include PyTorch, TorchScript, ONNX, OpenVINO, TensorRT, CoreML, TensorFlow
+        SavedModel, TensorFlow GraphDef, TensorFlow Lite, and TensorFlow Edge TPU. Edge TPU and TF.js are unsupported.
+
+    Examples:
+        ```python
+        $ python benchmarks.py --weights yolov5s.pt --img 640
+        ```
+
+    Usage:
+        Install required packages:
+          $ pip install -r requirements.txt coremltools onnx onnx-simplifier onnxruntime openvino-dev tensorflow-cpu  # CPU support
+          $ pip install -r requirements.txt coremltools onnx onnx-simplifier onnxruntime-gpu openvino-dev tensorflow   # GPU support
+          $ pip install -U nvidia-tensorrt --index-url https://pypi.ngc.nvidia.com  # TensorRT
+
+        Run benchmarks:
+          $ python benchmarks.py --weights yolov5s.pt --img 640
+    """
     y, t = [], time.time()
     device = select_device(device)
     model_type = type(attempt_load(weights, fuse=False))  # DetectionModel, SegmentationModel, etc.
@@ -125,7 +159,23 @@ def test(
     pt_only=False,  # test PyTorch only
     hard_fail=False,  # throw error on benchmark failure
 ):
-    """Run YOLOv5 export tests for all supported formats and log the results, including inference speed and mAP."""
+    """
+    Run YOLOv5 export tests for all supported formats and log the results, including export statuses.
+
+    Args:
+        weights (Path | str): Path to the model weights file (.pt format). Default is 'ROOT / "yolov5s.pt"'.
+        imgsz (int): Inference image size (in pixels). Default is 640.
+        batch_size (int): Batch size for testing. Default is 1.
+        data (Path | str): Path to the dataset configuration file (.yaml format). Default is 'ROOT / "data/coco128.yaml"'.
+        device (str): Device for running the tests, can be 'cpu' or a specific CUDA device ('0', '0,1,2,3', etc.). Default is an empty string.
+        half (bool): Use FP16 half-precision for inference if True. Default is False.
+        test (bool): Test export formats only without running inference. Default is False.
+        pt_only (bool): Test only the PyTorch model if True. Default is False.
+        hard_fail (bool): Raise error on export or test failure if True. Default is False.
+
+    Returns:
+        pd.DataFrame: DataFrame containing the results of the export tests, including format names and export statuses.
+    """
     y, t = [], time.time()
     device = select_device(device)
     for i, (name, f, suffix, gpu) in export.export_formats().iterrows():  # index, (name, file, suffix, gpu-capable)
@@ -151,7 +201,28 @@ def test(
 
 
 def parse_opt():
-    """Parses command-line arguments for YOLOv5 model inference configuration."""
+    """
+    Parses command-line arguments for YOLOv5 model inference configuration.
+
+    Args:
+        weights (str): The path to the weights file. Defaults to 'ROOT / "yolov5s.pt"'.
+        imgsz (int): Inference size in pixels. Defaults to 640.
+        batch_size (int): Batch size. Defaults to 1.
+        data (str): Path to the dataset YAML file. Defaults to 'ROOT / "data/coco128.yaml"'.
+        device (str): CUDA device, e.g., '0' or '0,1,2,3' or 'cpu'. Defaults to an empty string (auto-select).
+        half (bool): Use FP16 half-precision inference. This is a flag and defaults to False.
+        test (bool): Test exports only. This is a flag and defaults to False.
+        pt_only (bool): Test PyTorch only. This is a flag and defaults to False.
+        hard_fail (bool|str): Throw an error on benchmark failure. Can be a boolean or a string representing a minimum metric
+            floor, i.e., '0.29'. Defaults to False.
+
+    Returns:
+        argparse.Namespace: Parsed command-line arguments encapsulated in an argparse Namespace object.
+
+    Notes:
+        The function modifies the 'opt.data' by checking and validating the YAML path using 'check_yaml()'.
+        The parsed arguments are printed for reference using 'print_args()'.
+    """
     parser = argparse.ArgumentParser()
     parser.add_argument("--weights", type=str, default=ROOT / "yolov5s.pt", help="weights path")
     parser.add_argument("--imgsz", "--img", "--img-size", type=int, default=640, help="inference size (pixels)")
@@ -169,7 +240,34 @@ def parse_opt():
 
 
 def main(opt):
-    """Executes a test run if `opt.test` is True, otherwise starts training or inference with provided options."""
+    """
+    Executes YOLOv5 benchmark tests or main training/inference routines based on the provided command-line arguments.
+
+    Args:
+        opt (argparse.Namespace): Parsed command-line arguments including options for weights, image size, batch size, data
+        configuration, device, and other flags for inference settings.
+
+    Returns:
+        None: This function does not return any value. It leverages side-effects such as logging and running benchmarks.
+
+    Example:
+        ```python
+        if __name__ == "__main__":
+            opt = parse_opt()
+            main(opt)
+        ```
+
+    Notes:
+        - For a complete list of supported export formats and their respective requirements, refer to the
+          [Ultralytics YOLOv5 Export Formats](https://github.com/ultralytics/yolov5#export-formats).
+        - Ensure that you have installed all necessary dependencies by following the installation instructions detailed in
+          the [main repository](https://github.com/ultralytics/yolov5#installation).
+
+        ```shell
+        # Running benchmarks on default weights and image size
+        $ python benchmarks.py --weights yolov5s.pt --img 640
+        ```
+    """
     test(**vars(opt)) if opt.test else run(**vars(opt))
 
 

detect.py

@@ -97,7 +97,56 @@ def run(
     dnn=False,  # use OpenCV DNN for ONNX inference
     vid_stride=1,  # video frame-rate stride
 ):
-    """Runs YOLOv5 detection inference on various sources like images, videos, directories, streams, etc."""
+    """
+    Runs YOLOv5 detection inference on various sources like images, videos, directories, streams, etc.
+
+    Args:
+    weights (str | Path): Path to the model weights file or a Triton URL. Default is 'yolov5s.pt'.
+    source (str | Path): Input source, which can be a file, directory, URL, glob pattern, screen capture, or webcam index.
+        Default is 'data/images'.
+    data (str | Path): Path to the dataset YAML file. Default is 'data/coco128.yaml'.
+    imgsz (tuple[int, int]): Inference image size as a tuple (height, width). Default is (640, 640).
+    conf_thres (float): Confidence threshold for detections. Default is 0.25.
+    iou_thres (float): Intersection Over Union (IOU) threshold for non-max suppression. Default is 0.45.
+    max_det (int): Maximum number of detections per image. Default is 1000.
+    device (str): CUDA device identifier (e.g., '0' or '0,1,2,3') or 'cpu'. Default is an empty string, which
+        uses the best available device.
+    view_img (bool): If True, display inference results using OpenCV. Default is False.
+    save_txt (bool): If True, save results in a text file. Default is False.
+    save_csv (bool): If True, save results in a CSV file. Default is False.
+    save_conf (bool): If True, include confidence scores in the saved results. Default is False.
+    save_crop (bool): If True, save cropped prediction boxes. Default is False.
+    nosave (bool): If True, do not save inference images or videos. Default is False.
+    classes (list[int]): List of class indices to filter detections by. Default is None.
+    agnostic_nms (bool): If True, perform class-agnostic non-max suppression. Default is False.
+    augment (bool): If True, use augmented inference. Default is False.
+    visualize (bool): If True, visualize feature maps. Default is False.
+    update (bool): If True, update all models' weights. Default is False.
+    project (str | Path): Directory to save results. Default is 'runs/detect'.
+    name (str): Name of the current experiment; used to create a subdirectory within 'project'. Default is 'exp'.
+    exist_ok (bool): If True, existing directories with the same name are reused instead of being incremented. Default is
+        False.
+    line_thickness (int): Thickness of bounding box lines in pixels. Default is 3.
+    hide_labels (bool): If True, do not display labels on bounding boxes. Default is False.
+    hide_conf (bool): If True, do not display confidence scores on bounding boxes. Default is False.
+    half (bool): If True, use FP16 half-precision inference. Default is False.
+    dnn (bool): If True, use OpenCV DNN backend for ONNX inference. Default is False.
+    vid_stride (int): Stride for processing video frames, to skip frames between processing. Default is 1.
+
+    Returns:
+    None
+
+    Examples:
+    ```python
+    from ultralytics import run
+
+    # Run inference on an image
+    run(source='data/images/example.jpg', weights='yolov5s.pt', device='0')
+
+    # Run inference on a video with specific confidence threshold
+    run(source='data/videos/example.mp4', weights='yolov5s.pt', conf_thres=0.4, device='0')
+    ```
+    """
     source = str(source)
     save_img = not nosave and not source.endswith(".txt")  # save inference images
     is_file = Path(source).suffix[1:] in (IMG_FORMATS + VID_FORMATS)
@@ -266,7 +315,48 @@ def write_to_csv(image_name, prediction, confidence):
 
 
 def parse_opt():
-    """Parses command-line arguments for YOLOv5 detection, setting inference options and model configurations."""
+    """
+    Parses command-line arguments for YOLOv5 detection, setting inference options and model configurations.
+
+    Args:
+        --weights (str | list[str], optional): Model path or Triton URL. Defaults to ROOT / 'yolov5s.pt'.
+        --source (str, optional): File/dir/URL/glob/screen/0(webcam). Defaults to ROOT / 'data/images'.
+        --data (str, optional): Dataset YAML path. Provides dataset configuration information.
+        --imgsz (list[int], optional): Inference size (height, width). Defaults to [640].
+        --conf-thres (float, optional): Confidence threshold. Defaults to 0.25.
+        --iou-thres (float, optional): NMS IoU threshold. Defaults to 0.45.
+        --max-det (int, optional): Maximum number of detections per image. Defaults to 1000.
+        --device (str, optional): CUDA device, i.e., '0' or '0,1,2,3' or 'cpu'. Defaults to "".
+        --view-img (bool, optional): Flag to display results. Defaults to False.
+        --save-txt (bool, optional): Flag to save results to *.txt files. Defaults to False.
+        --save-csv (bool, optional): Flag to save results in CSV format. Defaults to False.
+        --save-conf (bool, optional): Flag to save confidences in labels saved via --save-txt. Defaults to False.
+        --save-crop (bool, optional): Flag to save cropped prediction boxes. Defaults to False.
+        --nosave (bool, optional): Flag to prevent saving images/videos. Defaults to False.
+        --classes (list[int], optional): List of classes to filter results by, e.g., '--classes 0 2 3'. Defaults to None.
+        --agnostic-nms (bool, optional): Flag for class-agnostic NMS. Defaults to False.
+        --augment (bool, optional): Flag for augmented inference. Defaults to False.
+        --visualize (bool, optional): Flag for visualizing features. Defaults to False.
+        --update (bool, optional): Flag to update all models in the model directory. Defaults to False.
+        --project (str, optional): Directory to save results. Defaults to ROOT / 'runs/detect'.
+        --name (str, optional): Sub-directory name for saving results within --project. Defaults to 'exp'.
+        --exist-ok (bool, optional): Flag to allow overwriting if the project/name already exists. Defaults to False.
+        --line-thickness (int, optional): Thickness (in pixels) of bounding boxes. Defaults to 3.
+        --hide-labels (bool, optional): Flag to hide labels in the output. Defaults to False.
+        --hide-conf (bool, optional): Flag to hide confidences in the output. Defaults to False.
+        --half (bool, optional): Flag to use FP16 half-precision inference. Defaults to False.
+        --dnn (bool, optional): Flag to use OpenCV DNN for ONNX inference. Defaults to False.
+        --vid-stride (int, optional): Video frame-rate stride, determining the number of frames to skip in between consecutive frames. Defaults to 1.
+
+    Returns:
+        argparse.Namespace: Parsed command-line arguments as an argparse.Namespace object.
+
+    Example:
+        ```python
+        from ultralytics import YOLOv5
+        args = YOLOv5.parse_opt()
+        ```
+    """
     parser = argparse.ArgumentParser()
     parser.add_argument("--weights", nargs="+", type=str, default=ROOT / "yolov5s.pt", help="model path or triton URL")
     parser.add_argument("--source", type=str, default=ROOT / "data/images", help="file/dir/URL/glob/screen/0(webcam)")
@@ -303,7 +393,28 @@ def parse_opt():
 
 
 def main(opt):
-    """Executes YOLOv5 model inference with given options, checking requirements before running the model."""
+    """
+    Executes YOLOv5 model inference based on provided command-line arguments, validating dependencies before running.
+
+    Args:
+      opt (argparse.Namespace): Command-line arguments for YOLOv5 detection. See function `parse_opt` for details.
+
+    Returns:
+      None
+
+    Note:
+      This function performs essential pre-execution checks and initiates the YOLOv5 detection process based on user-specified options.
+      Refer to the usage guide and examples for more information about different sources and formats at:
+      https://github.com/ultralytics/ultralytics
+
+    Example usage:
+
+    ```python
+    if __name__ == "__main__":
+        opt = parse_opt()
+        main(opt)
+    ```
+    """
     check_requirements(ROOT / "requirements.txt", exclude=("tensorboard", "thop"))
     run(**vars(opt))