ultralytics 8.2.48__py3-none-any.whl → 8.2.49__py3-none-any.whl

tests/test_python.py

@@ -38,7 +38,7 @@ def test_model_forward():
 
 
 def test_model_methods():
-    """Test various methods and properties of the YOLO model."""
+    """Test various methods and properties of the YOLO model to ensure correct functionality."""
     model = YOLO(MODEL)
 
     # Model methods
@@ -58,7 +58,7 @@ def test_model_methods():
 
 
 def test_model_profile():
-    """Test profiling of the YOLO model with 'profile=True' argument."""
+    """Test profiling of the YOLO model with `profile=True` to assess performance and resource usage."""
     from ultralytics.nn.tasks import DetectionModel
 
     model = DetectionModel()  # build model
@@ -68,7 +68,7 @@ def test_model_profile():
 
 @pytest.mark.skipif(not IS_TMP_WRITEABLE, reason="directory is not writeable")
 def test_predict_txt():
-    """Test YOLO predictions with sources (file, dir, glob, recursive glob) specified in a text file."""
+    """Tests YOLO predictions with file, directory, and pattern sources listed in a text file."""
     txt_file = TMP / "sources.txt"
     with open(txt_file, "w") as f:
         for x in [ASSETS / "bus.jpg", ASSETS, ASSETS / "*", ASSETS / "**/*.jpg"]:
@@ -78,7 +78,7 @@ def test_predict_txt():
 
 @pytest.mark.parametrize("model_name", MODELS)
 def test_predict_img(model_name):
-    """Test YOLO prediction on various types of image sources."""
+    """Test YOLO model predictions on various image input types and sources, including online images."""
     model = YOLO(WEIGHTS_DIR / model_name)
     im = cv2.imread(str(SOURCE))  # uint8 numpy array
     assert len(model(source=Image.open(SOURCE), save=True, verbose=True, imgsz=32)) == 1  # PIL
@@ -100,12 +100,12 @@ def test_predict_img(model_name):
 
 @pytest.mark.parametrize("model", MODELS)
 def test_predict_visualize(model):
-    """Test model predict methods with 'visualize=True' arguments."""
+    """Test model prediction methods with 'visualize=True' to generate and display prediction visualizations."""
     YOLO(WEIGHTS_DIR / model)(SOURCE, imgsz=32, visualize=True)
 
 
 def test_predict_grey_and_4ch():
-    """Test YOLO prediction on SOURCE converted to greyscale and 4-channel images."""
+    """Test YOLO prediction on SOURCE converted to greyscale and 4-channel images with various filenames."""
     im = Image.open(SOURCE)
     directory = TMP / "im4"
     directory.mkdir(parents=True, exist_ok=True)
@@ -132,11 +132,7 @@ def test_predict_grey_and_4ch():
 @pytest.mark.slow
 @pytest.mark.skipif(not ONLINE, reason="environment is offline")
 def test_youtube():
-    """
-    Test YouTube inference.
-
-    Note: ConnectionError may occur during this test due to network instability or YouTube server availability.
-    """
+    """Test YOLO model on a YouTube video stream, handling potential network-related errors."""
     model = YOLO(MODEL)
     try:
         model.predict("https://youtu.be/G17sBkb38XQ", imgsz=96, save=True)
@@ -149,9 +145,9 @@ def test_youtube():
 @pytest.mark.skipif(not IS_TMP_WRITEABLE, reason="directory is not writeable")
 def test_track_stream():
     """
-    Test streaming tracking (short 10 frame video) with non-default ByteTrack tracker.
+    Tests streaming tracking on a short 10 frame video using ByteTrack tracker and different GMC methods.
 
-    Note imgsz=160 required for tracking for higher confidence and better matches
+    Note imgsz=160 required for tracking for higher confidence and better matches.
     """
     video_url = "https://ultralytics.com/assets/decelera_portrait_min.mov"
     model = YOLO(MODEL)
@@ -175,21 +171,21 @@ def test_val():
 
 
 def test_train_scratch():
-    """Test training the YOLO model from scratch."""
+    """Test training the YOLO model from scratch using the provided configuration."""
     model = YOLO(CFG)
     model.train(data="coco8.yaml", epochs=2, imgsz=32, cache="disk", batch=-1, close_mosaic=1, name="model")
     model(SOURCE)
 
 
 def test_train_pretrained():
-    """Test training the YOLO model from a pre-trained state."""
+    """Test training of the YOLO model starting from a pre-trained checkpoint."""
     model = YOLO(WEIGHTS_DIR / "yolov8n-seg.pt")
     model.train(data="coco8-seg.yaml", epochs=1, imgsz=32, cache="ram", copy_paste=0.5, mixup=0.5, name=0)
     model(SOURCE)
 
 
 def test_all_model_yamls():
-    """Test YOLO model creation for all available YAML configurations."""
+    """Test YOLO model creation for all available YAML configurations in the `cfg/models` directory."""
     for m in (ROOT / "cfg" / "models").rglob("*.yaml"):
         if "rtdetr" in m.name:
             if TORCH_1_9:  # torch<=1.8 issue - TypeError: __init__() got an unexpected keyword argument 'batch_first'
@@ -208,7 +204,7 @@ def test_workflow():
 
 
 def test_predict_callback_and_setup():
-    """Test callback functionality during YOLO prediction."""
+    """Test callback functionality during YOLO prediction setup and execution."""
 
     def on_predict_batch_end(predictor):
         """Callback function that handles operations at the end of a prediction batch."""
@@ -232,7 +228,7 @@ def test_predict_callback_and_setup():
 
 @pytest.mark.parametrize("model", MODELS)
 def test_results(model):
-    """Test various result formats for the YOLO model."""
+    """Ensure YOLO model predictions can be processed and printed in various formats."""
     results = YOLO(WEIGHTS_DIR / model)([SOURCE, SOURCE], imgsz=160)
     for r in results:
         r = r.cpu().numpy()
@@ -247,7 +243,7 @@ def test_results(model):
 
 
 def test_labels_and_crops():
-    """Test output from prediction args for saving detection labels and crops."""
+    """Test output from prediction args for saving YOLO detection labels and crops; ensures accurate saving."""
     imgs = [SOURCE, ASSETS / "zidane.jpg"]
     results = YOLO(WEIGHTS_DIR / "yolov8n.pt")(imgs, imgsz=160, save_txt=True, save_crop=True)
     save_path = Path(results[0].save_dir)
@@ -270,7 +266,7 @@ def test_labels_and_crops():
 
 @pytest.mark.skipif(not ONLINE, reason="environment is offline")
 def test_data_utils():
-    """Test utility functions in ultralytics/data/utils.py."""
+    """Test utility functions in ultralytics/data/utils.py, including dataset stats and auto-splitting."""
     from ultralytics.data.utils import HUBDatasetStats, autosplit
     from ultralytics.utils.downloads import zip_directory
 
@@ -290,7 +286,7 @@ def test_data_utils():
 
 @pytest.mark.skipif(not ONLINE, reason="environment is offline")
 def test_data_converter():
-    """Test dataset converters."""
+    """Test dataset conversion functions from COCO to YOLO format and class mappings."""
     from ultralytics.data.converter import coco80_to_coco91_class, convert_coco
 
     file = "instances_val2017.json"
@@ -300,7 +296,7 @@ def test_data_converter():
 
 
 def test_data_annotator():
-    """Test automatic data annotation."""
+    """Automatically annotate data using specified detection and segmentation models."""
     from ultralytics.data.annotator import auto_annotate
 
     auto_annotate(
@@ -323,7 +319,7 @@ def test_events():
 
 
 def test_cfg_init():
-    """Test configuration initialization utilities."""
+    """Test configuration initialization utilities from the 'ultralytics.cfg' module."""
     from ultralytics.cfg import check_dict_alignment, copy_default_cfg, smart_value
 
     with contextlib.suppress(SyntaxError):
@@ -334,7 +330,7 @@ def test_cfg_init():
 
 
 def test_utils_init():
-    """Test initialization utilities."""
+    """Test initialization utilities in the Ultralytics library."""
     from ultralytics.utils import get_git_branch, get_git_origin_url, get_ubuntu_version, is_github_action_running
 
     get_ubuntu_version()
@@ -344,7 +340,7 @@ def test_utils_init():
 
 
 def test_utils_checks():
-    """Test various utility checks."""
+    """Test various utility checks for filenames, git status, requirements, image sizes, and versions."""
     checks.check_yolov5u_filename("yolov5n.pt")
     checks.git_describe(ROOT)
     checks.check_requirements()  # check requirements.txt
@@ -356,14 +352,14 @@ def test_utils_checks():
 
 @pytest.mark.skipif(WINDOWS, reason="Windows profiling is extremely slow (cause unknown)")
 def test_utils_benchmarks():
-    """Test model benchmarking."""
+    """Benchmark model performance using 'ProfileModels' from 'ultralytics.utils.benchmarks'."""
     from ultralytics.utils.benchmarks import ProfileModels
 
     ProfileModels(["yolov8n.yaml"], imgsz=32, min_time=1, num_timed_runs=3, num_warmup_runs=1).profile()
 
 
 def test_utils_torchutils():
-    """Test Torch utility functions."""
+    """Test Torch utility functions including profiling and FLOP calculations."""
     from ultralytics.nn.modules.conv import Conv
     from ultralytics.utils.torch_utils import get_flops_with_torch_profiler, profile, time_sync
 
@@ -378,14 +374,14 @@ def test_utils_torchutils():
 @pytest.mark.slow
 @pytest.mark.skipif(not ONLINE, reason="environment is offline")
 def test_utils_downloads():
-    """Test file download utilities."""
+    """Test file download utilities from ultralytics.utils.downloads."""
     from ultralytics.utils.downloads import get_google_drive_file_info
 
     get_google_drive_file_info("https://drive.google.com/file/d/1cqT-cJgANNrhIHCrEufUYhQ4RqiWG_lJ/view?usp=drive_link")
 
 
 def test_utils_ops():
-    """Test various operations utilities."""
+    """Test utility operations functions for coordinate transformation and normalization."""
     from ultralytics.utils.ops import (
         ltwh2xywh,
         ltwh2xyxy,
@@ -414,7 +410,7 @@ def test_utils_ops():
 
 
 def test_utils_files():
-    """Test file handling utilities."""
+    """Test file handling utilities including file age, date, and paths with spaces."""
     from ultralytics.utils.files import file_age, file_date, get_latest_run, spaces_in_path
 
     file_age(SOURCE)
@@ -429,7 +425,7 @@ def test_utils_files():
 
 @pytest.mark.slow
 def test_utils_patches_torch_save():
-    """Test torch_save backoff when _torch_save throws RuntimeError."""
+    """Test torch_save backoff when _torch_save raises RuntimeError to ensure robustness."""
     from unittest.mock import MagicMock, patch
 
     from ultralytics.utils.patches import torch_save
@@ -444,7 +440,7 @@ def test_utils_patches_torch_save():
 
 
 def test_nn_modules_conv():
-    """Test Convolutional Neural Network modules."""
+    """Test Convolutional Neural Network modules including CBAM, Conv2, and ConvTranspose."""
     from ultralytics.nn.modules.conv import CBAM, Conv2, ConvTranspose, DWConvTranspose2d, Focus
 
     c1, c2 = 8, 16  # input and output channels
@@ -463,7 +459,7 @@ def test_nn_modules_conv():
 
 
 def test_nn_modules_block():
-    """Test Neural Network block modules."""
+    """Test various blocks in neural network modules including C1, C3TR, BottleneckCSP, C3Ghost, and C3x."""
     from ultralytics.nn.modules.block import C1, C3TR, BottleneckCSP, C3Ghost, C3x
 
     c1, c2 = 8, 16  # input and output channels
@@ -479,7 +475,7 @@ def test_nn_modules_block():
 
 @pytest.mark.skipif(not ONLINE, reason="environment is offline")
 def test_hub():
-    """Test Ultralytics HUB functionalities."""
+    """Test Ultralytics HUB functionalities (e.g. export formats, logout)."""
     from ultralytics.hub import export_fmts_hub, logout
     from ultralytics.hub.utils import smart_request
 
@@ -490,7 +486,7 @@ def test_hub():
 
 @pytest.fixture
 def image():
-    """Loads an image from a predefined source using OpenCV."""
+    """Load and return an image from a predefined source using OpenCV."""
     return cv2.imread(str(SOURCE))
 
 
@@ -504,7 +500,7 @@ def image():
     ],
 )
 def test_classify_transforms_train(image, auto_augment, erasing, force_color_jitter):
-    """Tests classification transforms during training with various augmentation settings."""
+    """Tests classification transforms during training with various augmentations to ensure proper functionality."""
     from ultralytics.data.augment import classify_augmentations
 
     transform = classify_augmentations(
@@ -533,7 +529,7 @@ def test_classify_transforms_train(image, auto_augment, erasing, force_color_jit
 @pytest.mark.slow
 @pytest.mark.skipif(not ONLINE, reason="environment is offline")
 def test_model_tune():
-    """Tune YOLO model for performance."""
+    """Tune YOLO model for performance improvement."""
     YOLO("yolov8n-pose.pt").tune(data="coco8-pose.yaml", plots=False, imgsz=32, epochs=1, iterations=2, device="cpu")
     YOLO("yolov8n-cls.pt").tune(data="imagenet10", plots=False, imgsz=32, epochs=1, iterations=2, device="cpu")
 
@@ -550,7 +546,7 @@ def test_model_embeddings():
 
 @pytest.mark.skipif(checks.IS_PYTHON_3_12, reason="YOLOWorld with CLIP is not supported in Python 3.12")
 def test_yolo_world():
-    """Tests YOLO world models with different configurations, including classes, detection, and training scenarios."""
+    """Tests YOLO world models with CLIP support, including detection and training scenarios."""
     model = YOLO("yolov8s-world.pt")  # no YOLOv8n-world model yet
     model.set_classes(["tree", "window"])
     model(SOURCE, conf=0.01)
@@ -581,7 +577,7 @@ def test_yolo_world():
 
 
 def test_yolov10():
-    """A simple test for yolov10 for now."""
+    """Test YOLOv10 model training, validation, and prediction steps with minimal configurations."""
     model = YOLO("yolov10n.yaml")
     # train/val/predict
     model.train(data="coco8.yaml", epochs=1, imgsz=32, close_mosaic=1, cache="disk")

ultralytics/__init__.py

@@ -1,6 +1,6 @@
 # Ultralytics YOLO 🚀, AGPL-3.0 license
 
-__version__ = "8.2.48"
+__version__ = "8.2.49"
 
 import os
 

ultralytics/cfg/__init__.py

@@ -187,10 +187,31 @@ def cfg2dict(cfg):
     Convert a configuration object to a dictionary, whether it is a file path, a string, or a SimpleNamespace object.
 
     Args:
-        cfg (str | Path | dict | SimpleNamespace): Configuration object to be converted to a dictionary.
+        cfg (str | Path | dict | SimpleNamespace): Configuration object to be converted to a dictionary. This may be a
+            path to a configuration file, a dictionary, or a SimpleNamespace object.
 
     Returns:
-        cfg (dict): Configuration object in dictionary format.
+        (dict): Configuration object in dictionary format.
+
+    Example:
+        ```python
+        from ultralytics.cfg import cfg2dict
+        from types import SimpleNamespace
+
+        # Example usage with a file path
+        config_dict = cfg2dict('config.yaml')
+
+        # Example usage with a SimpleNamespace
+        config_sn = SimpleNamespace(param1='value1', param2='value2')
+        config_dict = cfg2dict(config_sn)
+
+        # Example usage with a dictionary (returns the same dictionary)
+        config_dict = cfg2dict({'param1': 'value1', 'param2': 'value2'})
+        ```
+
+    Notes:
+        - If `cfg` is a path or a string, it will be loaded as YAML and converted to a dictionary.
+        - If `cfg` is a SimpleNamespace object, it will be converted to a dictionary using `vars()`.
     """
     if isinstance(cfg, (str, Path)):
         cfg = yaml_load(cfg)  # load dict
@@ -201,14 +222,36 @@ def cfg2dict(cfg):
 
 def get_cfg(cfg: Union[str, Path, Dict, SimpleNamespace] = DEFAULT_CFG_DICT, overrides: Dict = None):
     """
-    Load and merge configuration data from a file or dictionary.
+    Load and merge configuration data from a file or dictionary, with optional overrides.
 
     Args:
-        cfg (str | Path | Dict | SimpleNamespace): Configuration data.
-        overrides (str | Dict | optional): Overrides in the form of a file name or a dictionary. Default is None.
+        cfg (str | Path | dict | SimpleNamespace, optional): Configuration data source. Defaults to `DEFAULT_CFG_DICT`.
+        overrides (dict | None, optional): Dictionary containing key-value pairs to override the base configuration.
+            Defaults to None.
 
     Returns:
-        (SimpleNamespace): Training arguments namespace.
+        (SimpleNamespace): Namespace containing the merged training arguments.
+
+    Notes:
+        - If both `cfg` and `overrides` are provided, the values in `overrides` will take precedence.
+        - Special handling ensures alignment and correctness of the configuration, such as converting numeric `project`
+          and `name` to strings and validating the configuration keys and values.
+
+    Example:
+        ```python
+        from ultralytics.cfg import get_cfg
+
+        # Load default configuration
+        config = get_cfg()
+
+        # Load from a custom file with overrides
+        config = get_cfg('path/to/config.yaml', overrides={'epochs': 50, 'batch_size': 16})
+        ```
+
+        Configuration dictionary merged with overrides:
+        ```python
+        {'epochs': 50, 'batch_size': 16, ...}
+        ```
     """
     cfg = cfg2dict(cfg)
 
@@ -236,7 +279,7 @@ def get_cfg(cfg: Union[str, Path, Dict, SimpleNamespace] = DEFAULT_CFG_DICT, ove
 
 
 def check_cfg(cfg, hard=True):
-    """Check Ultralytics configuration argument types and values."""
+    """Validate Ultralytics configuration argument types and values, converting them if necessary."""
     for k, v in cfg.items():
         if v is not None:  # None values may be from optional args
             if k in CFG_FLOAT_KEYS and not isinstance(v, (int, float)):
@@ -272,7 +315,7 @@ def check_cfg(cfg, hard=True):
 
 
 def get_save_dir(args, name=None):
-    """Return save_dir as created from train/val/predict arguments."""
+    """Returns the directory path for saving outputs, derived from arguments or default settings."""
 
     if getattr(args, "save_dir", None):
         save_dir = args.save_dir
@@ -287,7 +330,7 @@ def get_save_dir(args, name=None):
 
 
 def _handle_deprecation(custom):
-    """Hardcoded function to handle deprecated config keys."""
+    """Handles deprecated configuration keys by mapping them to current equivalents with deprecation warnings."""
 
     for key in custom.copy().keys():
         if key == "boxes":
@@ -308,13 +351,35 @@ def _handle_deprecation(custom):
 
 def check_dict_alignment(base: Dict, custom: Dict, e=None):
     """
-    This function checks for any mismatched keys between a custom configuration list and a base configuration list. If
-    any mismatched keys are found, the function prints out similar keys from the base list and exits the program.
+    Check for key alignment between custom and base configuration dictionaries, catering for deprecated keys and
+    providing informative error messages for mismatched keys.
 
     Args:
-        custom (dict): a dictionary of custom configuration options
-        base (dict): a dictionary of base configuration options
-        e (Error, optional): An optional error that is passed by the calling function.
+        base (dict): The base configuration dictionary containing valid keys.
+        custom (dict): The custom configuration dictionary to be checked for alignment.
+        e (Exception, optional): An optional error instance passed by the calling function. Default is None.
+
+    Raises:
+        SystemExit: Terminates the program execution if mismatched keys are found.
+
+    Notes:
+        - The function provides suggestions for mismatched keys based on their similarity to valid keys in the
+          base configuration.
+        - Deprecated keys in the custom configuration are automatically handled and replaced with their updated
+          equivalents.
+        - A detailed error message is printed for each mismatched key, helping users to quickly identify and correct
+          their custom configurations.
+
+    Example:
+        ```python
+        base_cfg = {'epochs': 50, 'lr0': 0.01, 'batch_size': 16}
+        custom_cfg = {'epoch': 100, 'lr': 0.02, 'batch_size': 32}
+
+        try:
+            check_dict_alignment(base_cfg, custom_cfg)
+        except SystemExit:
+            # Handle the error or correct the configuration
+        ```
     """
     custom = _handle_deprecation(custom)
     base_keys, custom_keys = (set(x.keys()) for x in (base, custom))
@@ -341,6 +406,22 @@ def merge_equals_args(args: List[str]) -> List[str]:
 
     Returns:
         (List[str]): A list of strings where the arguments around isolated '=' are merged.
+
+    Example:
+        The function modifies the argument list as follows:
+        ```python
+        args = ["arg1", "=", "value"]
+        new_args = merge_equals_args(args)
+        print(new_args)  # Output: ["arg1=value"]
+
+        args = ["arg1=", "value"]
+        new_args = merge_equals_args(args)
+        print(new_args)  # Output: ["arg1=value"]
+
+        args = ["arg1", "=value"]
+        new_args = merge_equals_args(args)
+        print(new_args)  # Output: ["arg1=value"]
+        ```
     """
     new_args = []
     for i, arg in enumerate(args):
@@ -361,15 +442,18 @@ def handle_yolo_hub(args: List[str]) -> None:
     """
     Handle Ultralytics HUB command-line interface (CLI) commands.
 
-    This function processes Ultralytics HUB CLI commands such as login and logout.
-    It should be called when executing a script with arguments related to HUB authentication.
+    This function processes Ultralytics HUB CLI commands such as login and logout. It should be called when executing
+    a script with arguments related to HUB authentication.
 
     Args:
-        args (List[str]): A list of command line arguments
+        args (List[str]): A list of command line arguments.
+
+    Returns:
+        None
 
     Example:
         ```bash
-        python my_script.py hub login your_api_key
+        yolo hub login YOUR_API_KEY
         ```
     """
     from ultralytics import hub
@@ -387,16 +471,23 @@ def handle_yolo_settings(args: List[str]) -> None:
     """
     Handle YOLO settings command-line interface (CLI) commands.
 
-    This function processes YOLO settings CLI commands such as reset.
-    It should be called when executing a script with arguments related to YOLO settings management.
+    This function processes YOLO settings CLI commands such as reset. It should be called when executing a script with
+    arguments related to YOLO settings management.
 
     Args:
         args (List[str]): A list of command line arguments for YOLO settings management.
 
+    Returns:
+        None
+
     Example:
         ```bash
-        python my_script.py yolo settings reset
+        yolo settings reset
         ```
+
+    Notes:
+        For more information on handling YOLO settings, visit:
+        https://docs.ultralytics.com/quickstart/#ultralytics-settings
     """
     url = "https://docs.ultralytics.com/quickstart/#ultralytics-settings"  # help URL
     try:
@@ -417,7 +508,7 @@ def handle_yolo_settings(args: List[str]) -> None:
 
 
 def handle_explorer():
-    """Open the Ultralytics Explorer GUI."""
+    """Open the Ultralytics Explorer GUI for dataset exploration and analysis."""
     checks.check_requirements("streamlit")
     LOGGER.info("💡 Loading Explorer dashboard...")
     subprocess.run(["streamlit", "run", ROOT / "data/explorer/gui/dash.py", "--server.maxMessageSize", "2048"])
@@ -432,7 +523,7 @@ def parse_key_value_pair(pair):
 
 
 def smart_value(v):
-    """Convert a string to an underlying type such as int, float, bool, etc."""
+    """Convert a string to its appropriate type (int, float, bool, None, etc.)."""
     v_lower = v.lower()
     if v_lower == "none":
         return None
@@ -448,18 +539,33 @@ def smart_value(v):
 
 def entrypoint(debug=""):
     """
-    This function is the ultralytics package entrypoint, it's responsible for parsing the command line arguments passed
-    to the package.
-
-    This function allows for:
-    - passing mandatory YOLO args as a list of strings
-    - specifying the task to be performed, either 'detect', 'segment' or 'classify'
-    - specifying the mode, either 'train', 'val', 'test', or 'predict'
-    - running special modes like 'checks'
-    - passing overrides to the package's configuration
-
-    It uses the package's default cfg and initializes it using the passed overrides.
-    Then it calls the CLI function with the composed cfg
+    Ultralytics entrypoint function for parsing and executing command-line arguments.
+
+    This function serves as the main entry point for the Ultralytics CLI, parsing  command-line arguments and
+    executing the corresponding tasks such as training, validation, prediction, exporting models, and more.
+
+    Args:
+        debug (str, optional): Space-separated string of command-line arguments for debugging purposes. Default is "".
+
+    Returns:
+        (None): This function does not return any value.
+
+    Notes:
+        - For a list of all available commands and their arguments, see the provided help messages and the Ultralytics
+          documentation at https://docs.ultralytics.com.
+        - If no arguments are passed, the function will display the usage help message.
+
+    Example:
+        ```python
+        # Train a detection model for 10 epochs with an initial learning_rate of 0.01
+        entrypoint("train data=coco8.yaml model=yolov8n.pt epochs=10 lr0=0.01")
+
+        # Predict a YouTube video using a pretrained segmentation model at image size 320
+        entrypoint("predict model=yolov8n-seg.pt source='https://youtu.be/LNwODJXcvt4' imgsz=320")
+
+        # Validate a pretrained detection model at batch-size 1 and image size 640
+        entrypoint("val model=yolov8n.pt data=coco8.yaml batch=1 imgsz=640")
+        ```
     """
     args = (debug.split(" ") if debug else ARGV)[1:]
     if not args:  # no arguments passed
@@ -596,7 +702,7 @@ def entrypoint(debug=""):
 
 # Special modes --------------------------------------------------------------------------------------------------------
 def copy_default_cfg():
-    """Copy and create a new default configuration file with '_copy' appended to its name."""
+    """Copy and create a new default configuration file with '_copy' appended to its name, providing usage example."""
     new_file = Path.cwd() / DEFAULT_CFG_PATH.name.replace(".yaml", "_copy.yaml")
     shutil.copy2(DEFAULT_CFG_PATH, new_file)
     LOGGER.info(

ultralytics/data/explorer/explorer.py

@@ -22,6 +22,7 @@ from .utils import get_sim_index_schema, get_table_schema, plot_query_result, pr
 
 class ExplorerDataset(YOLODataset):
     def __init__(self, *args, data: dict = None, **kwargs) -> None:
+        """Initializes the ExplorerDataset with the provided data arguments, extending the YOLODataset class."""
         super().__init__(*args, data=data, **kwargs)
 
     def load_image(self, i: int) -> Union[Tuple[np.ndarray, Tuple[int, int], Tuple[int, int]], Tuple[None, None, None]]:
@@ -59,6 +60,7 @@ class Explorer:
         model: str = "yolov8n.pt",
         uri: str = USER_CONFIG_DIR / "explorer",
     ) -> None:
+        """Initializes the Explorer class with dataset path, model, and URI for database connection."""
         # Note duckdb==0.10.0 bug https://github.com/ultralytics/ultralytics/pull/8181
         checks.check_requirements(["lancedb>=0.4.3", "duckdb<=0.9.2"])
         import lancedb
@@ -416,6 +418,7 @@ class Explorer:
     def _check_imgs_or_idxs(
         self, img: Union[str, np.ndarray, List[str], List[np.ndarray], None], idx: Union[None, int, List[int]]
     ) -> List[np.ndarray]:
+        """Determines whether to fetch images or indexes based on provided arguments and returns image paths."""
         if img is None and idx is None:
             raise ValueError("Either img or idx must be provided.")
         if img is not None and idx is not None:

ultralytics/engine/model.py

@@ -505,7 +505,7 @@ class Model(nn.Module):
                 used to customize various aspects of the validation process.
 
         Returns:
-            (dict): Validation metrics obtained from the validation process.
+            (ultralytics.utils.metrics.DetMetrics): Validation metrics obtained from the validation process.
 
         Raises:
             AssertionError: If the model is not a PyTorch model.