ultralytics 8.2.60__py3-none-any.whl → 8.2.62__py3-none-any.whl

ultralytics/__init__.py

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

ultralytics/cfg/__init__.py

@@ -79,7 +79,7 @@ CLI_HELP_MSG = f"""
         yolo export model=yolov8n-cls.pt format=onnx imgsz=224,128
 
     5. Explore your datasets using semantic search and SQL with a simple GUI powered by Ultralytics Explorer API
-        yolo explorer
+        yolo explorer data=data.yaml model=yolov8n.pt
     
     6. Streamlit real-time object detection on your webcam with Ultralytics YOLOv8
         yolo streamlit-predict
@@ -187,34 +187,31 @@ CFG_BOOL_KEYS = {  # boolean-only arguments
 
 def cfg2dict(cfg):
     """
-    Convert a configuration object to a dictionary, whether it is a file path, a string, or a SimpleNamespace object.
+    Converts a configuration object to a dictionary.
 
     Args:
-        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.
+        cfg (str | Path | Dict | SimpleNamespace): Configuration object to be converted. Can be a file path,
+            a string, a dictionary, or a SimpleNamespace object.
 
     Returns:
-        (dict): Configuration object in dictionary format.
+        (Dict): Configuration object in dictionary format.
 
-    Example:
-        ```python
-        from ultralytics.cfg import cfg2dict
-        from types import SimpleNamespace
+    Examples:
+        Convert a YAML file path to a dictionary:
+        >>> config_dict = cfg2dict('config.yaml')
 
-        # Example usage with a file path
-        config_dict = cfg2dict('config.yaml')
+        Convert a SimpleNamespace to a dictionary:
+        >>> from types import SimpleNamespace
+        >>> config_sn = SimpleNamespace(param1='value1', param2='value2')
+        >>> config_dict = cfg2dict(config_sn)
 
-        # 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'})
-        ```
+        Pass through an already existing 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 cfg is a path or string, it's loaded as YAML and converted to a dictionary.
+        - If cfg is a SimpleNamespace object, it's converted to a dictionary using vars().
+        - If cfg is already a dictionary, it's returned unchanged.
     """
     if isinstance(cfg, (str, Path)):
         cfg = yaml_load(cfg)  # load dict
@@ -228,33 +225,23 @@ def get_cfg(cfg: Union[str, Path, Dict, SimpleNamespace] = DEFAULT_CFG_DICT, ove
     Load and merge configuration data from a file or dictionary, with optional overrides.
 
     Args:
-        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.
+        cfg (str | Path | Dict | SimpleNamespace): Configuration data source. Can be a file path, dictionary, or
+            SimpleNamespace object.
+        overrides (Dict | None): Dictionary containing key-value pairs to override the base configuration.
 
     Returns:
-        (SimpleNamespace): Namespace containing the merged training arguments.
+        (SimpleNamespace): Namespace containing the merged configuration arguments.
+
+    Examples:
+        >>> from ultralytics.cfg import get_cfg
+        >>> config = get_cfg()  # Load default configuration
+        >>> config = get_cfg('path/to/config.yaml', overrides={'epochs': 50, 'batch_size': 16})
 
     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, ...}
-        ```
+        - Special handling ensures alignment and correctness of the configuration, such as converting numeric
+          `project` and `name` to strings and validating configuration keys and values.
+        - The function performs type and value checks on the configuration data.
     """
     cfg = cfg2dict(cfg)
 
@@ -282,7 +269,33 @@ def get_cfg(cfg: Union[str, Path, Dict, SimpleNamespace] = DEFAULT_CFG_DICT, ove
 
 
 def check_cfg(cfg, hard=True):
-    """Validate Ultralytics configuration argument types and values, converting them if necessary."""
+    """
+    Checks configuration argument types and values for the Ultralytics library.
+
+    This function validates the types and values of configuration arguments, ensuring correctness and converting
+    them if necessary. It checks for specific key types defined in global variables such as CFG_FLOAT_KEYS,
+    CFG_FRACTION_KEYS, CFG_INT_KEYS, and CFG_BOOL_KEYS.
+
+    Args:
+        cfg (Dict): Configuration dictionary to validate.
+        hard (bool): If True, raises exceptions for invalid types and values; if False, attempts to convert them.
+
+    Examples:
+        >>> config = {
+        ...     'epochs': 50,     # valid integer
+        ...     'lr0': 0.01,      # valid float
+        ...     'momentum': 1.2,  # invalid float (out of 0.0-1.0 range)
+        ...     'save': 'true',   # invalid bool
+        ... }
+        >>> check_cfg(config, hard=False)
+        >>> print(config)
+        {'epochs': 50, 'lr0': 0.01, 'momentum': 1.2, 'save': False}  # corrected 'save' key
+
+    Notes:
+        - The function modifies the input dictionary in-place.
+        - None values are ignored as they may be from optional arguments.
+        - Fraction keys are checked to be within the range [0.0, 1.0].
+    """
     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)):
@@ -318,7 +331,25 @@ def check_cfg(cfg, hard=True):
 
 
 def get_save_dir(args, name=None):
-    """Returns the directory path for saving outputs, derived from arguments or default settings."""
+    """
+    Returns the directory path for saving outputs, derived from arguments or default settings.
+
+    Args:
+        args (SimpleNamespace): Namespace object containing configurations such as 'project', 'name', 'task',
+            'mode', and 'save_dir'.
+        name (str | None): Optional name for the output directory. If not provided, it defaults to 'args.name'
+            or the 'args.mode'.
+
+    Returns:
+        (Path): Directory path where outputs should be saved.
+
+    Examples:
+        >>> from types import SimpleNamespace
+        >>> args = SimpleNamespace(project='my_project', task='detect', mode='train', exist_ok=True)
+        >>> save_dir = get_save_dir(args)
+        >>> print(save_dir)
+        my_project/detect/train
+    """
 
     if getattr(args, "save_dir", None):
         save_dir = args.save_dir
@@ -333,7 +364,23 @@ def get_save_dir(args, name=None):
 
 
 def _handle_deprecation(custom):
-    """Handles deprecated configuration keys by mapping them to current equivalents with deprecation warnings."""
+    """
+    Handles deprecated configuration keys by mapping them to current equivalents with deprecation warnings.
+
+    Args:
+        custom (Dict): Configuration dictionary potentially containing deprecated keys.
+
+    Examples:
+        >>> custom_config = {"boxes": True, "hide_labels": "False", "line_thickness": 2}
+        >>> _handle_deprecation(custom_config)
+        >>> print(custom_config)
+        {'show_boxes': True, 'show_labels': True, 'line_width': 2}
+
+    Notes:
+        This function modifies the input dictionary in-place, replacing deprecated keys with their current
+        equivalents. It also handles value conversions where necessary, such as inverting boolean values for
+        'hide_labels' and 'hide_conf'.
+    """
 
     for key in custom.copy().keys():
         if key == "boxes":
@@ -354,35 +401,29 @@ def _handle_deprecation(custom):
 
 def check_dict_alignment(base: Dict, custom: Dict, e=None):
     """
-    Check for key alignment between custom and base configuration dictionaries, catering for deprecated keys and
-    providing informative error messages for mismatched keys.
+    Checks alignment between custom and base configuration dictionaries, handling deprecated keys and providing error
+    messages for mismatched keys.
 
     Args:
-        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.
+        base (Dict): The base configuration dictionary containing valid keys.
+        custom (Dict): The custom configuration dictionary to be checked for alignment.
+        e (Exception | None): Optional error instance passed by the calling function.
 
     Raises:
-        SystemExit: Terminates the program execution if mismatched keys are found.
+        SystemExit: If mismatched keys are found between the custom and base dictionaries.
+
+    Examples:
+        >>> 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:
+        ...     print("Mismatched keys 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
-        ```
+        - Suggests corrections for mismatched keys based on similarity to valid keys.
+        - Automatically replaces deprecated keys in the custom configuration with updated equivalents.
+        - Prints detailed error messages for each mismatched key to help users correct their configurations.
     """
     custom = _handle_deprecation(custom)
     base_keys, custom_keys = (set(x.keys()) for x in (base, custom))
@@ -401,30 +442,21 @@ def check_dict_alignment(base: Dict, custom: Dict, e=None):
 
 def merge_equals_args(args: List[str]) -> List[str]:
     """
-    Merges arguments around isolated '=' args in a list of strings. The function considers cases where the first
-    argument ends with '=' or the second starts with '=', as well as when the middle one is an equals sign.
+    Merges arguments around isolated '=' in a list of strings, handling three cases:
+    1. ['arg', '=', 'val'] becomes ['arg=val'],
+    2. ['arg=', 'val'] becomes ['arg=val'],
+    3. ['arg', '=val'] becomes ['arg=val'].
 
     Args:
-        args (List[str]): A list of strings where each element is an argument.
+        args (List[str]): A list of strings where each element represents an argument.
 
     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"]
-        ```
+    Examples:
+        >>> args = ["arg1", "=", "value", "arg2=", "value2", "arg3", "=value3"]
+        >>> merge_equals_args(args)
+        ['arg1=value', 'arg2=value2', 'arg3=value3']
     """
     new_args = []
     for i, arg in enumerate(args):
@@ -443,21 +475,24 @@ def merge_equals_args(args: List[str]) -> List[str]:
 
 def handle_yolo_hub(args: List[str]) -> None:
     """
-    Handle Ultralytics HUB command-line interface (CLI) commands.
+    Handles Ultralytics HUB command-line interface (CLI) commands for 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.
+    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. The first argument should be either 'login'
+            or 'logout'. For 'login', an optional second argument can be the API key.
 
-    Returns:
-        None
-
-    Example:
+    Examples:
         ```bash
         yolo hub login YOUR_API_KEY
         ```
+
+    Notes:
+        - The function imports the 'hub' module from ultralytics to perform login and logout operations.
+        - For the 'login' command, if no API key is provided, an empty string is passed to the login function.
+        - The 'logout' command does not require any additional arguments.
     """
     from ultralytics import hub
 
@@ -472,25 +507,26 @@ def handle_yolo_hub(args: List[str]) -> None:
 
 def handle_yolo_settings(args: List[str]) -> None:
     """
-    Handle YOLO settings command-line interface (CLI) commands.
+    Handles 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 and updating individual settings. 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
-        yolo settings reset
-        ```
+    Examples:
+        >>> handle_yolo_settings(["reset"])  # Reset YOLO settings
+        >>> handle_yolo_settings(["default_cfg_path=yolov8n.yaml"])  # Update a specific setting
 
     Notes:
-        For more information on handling YOLO settings, visit:
-        https://docs.ultralytics.com/quickstart/#ultralytics-settings
+        - If no arguments are provided, the function will display the current settings.
+        - The 'reset' command will delete the existing settings file and create new default settings.
+        - Other arguments are treated as key-value pairs to update specific settings.
+        - The function will check for alignment between the provided settings and the existing ones.
+        - After processing, the updated settings will be displayed.
+        - 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:
@@ -510,22 +546,84 @@ def handle_yolo_settings(args: List[str]) -> None:
         LOGGER.warning(f"WARNING ⚠️ settings error: '{e}'. Please see {url} for help.")
 
 
-def handle_explorer():
-    """Open the Ultralytics Explorer GUI for dataset exploration and analysis."""
+def handle_explorer(args: List[str]):
+    """
+    This function launches a graphical user interface that provides tools for interacting with and analyzing datasets
+    using the Ultralytics Explorer API. It checks for the required 'streamlit' package and informs the user that the
+    Explorer dashboard is loading.
+
+    Args:
+        args (List[str]): A list of optional command line arguments.
+
+    Examples:
+        ```bash
+        yolo explorer data=data.yaml model=yolov8n.pt
+        ```
+
+    Notes:
+        - Requires 'streamlit' package version 1.29.0 or higher.
+        - The function does not take any arguments or return any values.
+        - It is typically called from the command line interface using the 'yolo explorer' command.
+    """
     checks.check_requirements("streamlit>=1.29.0")
     LOGGER.info("💡 Loading Explorer dashboard...")
-    subprocess.run(["streamlit", "run", ROOT / "data/explorer/gui/dash.py", "--server.maxMessageSize", "2048"])
+    cmd = ["streamlit", "run", ROOT / "data/explorer/gui/dash.py", "--server.maxMessageSize", "2048"]
+    new = dict(parse_key_value_pair(a) for a in args)
+    check_dict_alignment(base={k: DEFAULT_CFG_DICT[k] for k in ["model", "data"]}, custom=new)
+    for k, v in new.items():
+        cmd += [k, v]
+    subprocess.run(cmd)
 
 
 def handle_streamlit_inference():
-    """Open the Ultralytics Live Inference streamlit app for real time object detection."""
+    """
+    Open the Ultralytics Live Inference Streamlit app for real-time object detection.
+
+    This function initializes and runs a Streamlit application designed for performing live object detection using
+    Ultralytics models. It checks for the required Streamlit package and launches the app.
+
+    Examples:
+        >>> handle_streamlit_inference()
+
+    Notes:
+        - Requires Streamlit version 1.29.0 or higher.
+        - The app is launched using the 'streamlit run' command.
+        - The Streamlit app file is located in the Ultralytics package directory.
+    """
     checks.check_requirements("streamlit>=1.29.0")
     LOGGER.info("💡 Loading Ultralytics Live Inference app...")
     subprocess.run(["streamlit", "run", ROOT / "solutions/streamlit_inference.py", "--server.headless", "true"])
 
 
-def parse_key_value_pair(pair):
-    """Parse one 'key=value' pair and return key and value."""
+def parse_key_value_pair(pair: str = "key=value"):
+    """
+    Parses a key-value pair string into separate key and value components.
+
+    Args:
+        pair (str): A string containing a key-value pair in the format "key=value".
+
+    Returns:
+        (tuple): A tuple containing two elements:
+            - key (str): The parsed key.
+            - value (str): The parsed value.
+
+    Raises:
+        AssertionError: If the value is missing or empty.
+
+    Examples:
+        >>> key, value = parse_key_value_pair("model=yolov8n.pt")
+        >>> print(f"Key: {key}, Value: {value}")
+        Key: model, Value: yolov8n.pt
+
+        >>> key, value = parse_key_value_pair("epochs=100")
+        >>> print(f"Key: {key}, Value: {value}")
+        Key: epochs, Value: 100
+
+    Notes:
+        - The function splits the input string on the first '=' character.
+        - Leading and trailing whitespace is removed from both key and value.
+        - An assertion error is raised if the value is empty after stripping.
+    """
     k, v = pair.split("=", 1)  # split on first '=' sign
     k, v = k.strip(), v.strip()  # remove spaces
     assert v, f"missing '{k}' value"
@@ -533,7 +631,36 @@ def parse_key_value_pair(pair):
 
 
 def smart_value(v):
-    """Convert a string to its appropriate type (int, float, bool, None, etc.)."""
+    """
+    Converts a string representation of a value to its appropriate Python type.
+
+    This function attempts to convert a given string into a Python object of the most appropriate type. It handles
+    conversions to None, bool, int, float, and other types that can be evaluated safely.
+
+    Args:
+        v (str): The string representation of the value to be converted.
+
+    Returns:
+        (Any): The converted value. The type can be None, bool, int, float, or the original string if no conversion
+            is applicable.
+
+    Examples:
+        >>> smart_value("42")
+        42
+        >>> smart_value("3.14")
+        3.14
+        >>> smart_value("True")
+        True
+        >>> smart_value("None")
+        None
+        >>> smart_value("some_string")
+        'some_string'
+
+    Notes:
+        - The function uses a case-insensitive comparison for boolean and None values.
+        - For other types, it attempts to use Python's eval() function, which can be unsafe if used on untrusted input.
+        - If no conversion is possible, the original string is returned.
+    """
     v_lower = v.lower()
     if v_lower == "none":
         return None
@@ -551,31 +678,26 @@ def entrypoint(debug=""):
     """
     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
+    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 "".
+        debug (str): Space-separated string of command-line arguments for debugging purposes.
 
-    Returns:
-        (None): This function does not return any value.
+    Examples:
+        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")
 
-    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")
 
-        # 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")
 
-        # 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")
-        ```
+    Notes:
+        - If no arguments are passed, the function will display the usage help message.
+        - For a list of all available commands and their arguments, see the provided help messages and the
+          Ultralytics documentation at https://docs.ultralytics.com.
     """
     args = (debug.split(" ") if debug else ARGV)[1:]
     if not args:  # no arguments passed
@@ -591,7 +713,7 @@ def entrypoint(debug=""):
         "hub": lambda: handle_yolo_hub(args[1:]),
         "login": lambda: handle_yolo_hub(args),
         "copy-cfg": copy_default_cfg,
-        "explorer": lambda: handle_explorer(),
+        "explorer": lambda: handle_explorer(args[1:]),
         "streamlit-predict": lambda: handle_streamlit_inference(),
     }
     full_args_dict = {**DEFAULT_CFG_DICT, **{k: None for k in TASKS}, **{k: None for k in MODES}, **special}
@@ -713,7 +835,26 @@ def entrypoint(debug=""):
 
 # Special modes --------------------------------------------------------------------------------------------------------
 def copy_default_cfg():
-    """Copy and create a new default configuration file with '_copy' appended to its name, providing usage example."""
+    """
+    Copies the default configuration file and creates a new one with '_copy' appended to its name.
+
+    This function duplicates the existing default configuration file (DEFAULT_CFG_PATH) and saves it
+    with '_copy' appended to its name in the current working directory. It provides a convenient way
+    to create a custom configuration file based on the default settings.
+
+    Examples:
+        >>> copy_default_cfg()
+        # Output: default.yaml copied to /path/to/current/directory/default_copy.yaml
+        # Example YOLO command with this new custom cfg:
+        #   yolo cfg='/path/to/current/directory/default_copy.yaml' imgsz=320 batch=8
+
+    Notes:
+        - The new configuration file is created in the current working directory.
+        - After copying, the function prints a message with the new file's location and an example
+          YOLO command demonstrating how to use the new configuration file.
+        - This function is useful for users who want to modify the default configuration without
+          altering the original file.
+    """
     new_file = Path.cwd() / DEFAULT_CFG_PATH.name.replace(".yaml", "_copy.yaml")
     shutil.copy2(DEFAULT_CFG_PATH, new_file)
     LOGGER.info(

ultralytics/data/annotator.py

@@ -9,20 +9,24 @@ def auto_annotate(data, det_model="yolov8x.pt", sam_model="sam_b.pt", device="",
     """
     Automatically annotates images using a YOLO object detection model and a SAM segmentation model.
 
+    This function processes images in a specified directory, detects objects using a YOLO model, and then generates
+    segmentation masks using a SAM model. The resulting annotations are saved as text files.
+
     Args:
         data (str): Path to a folder containing images to be annotated.
-        det_model (str, optional): Pre-trained YOLO detection model. Defaults to 'yolov8x.pt'.
-        sam_model (str, optional): Pre-trained SAM segmentation model. Defaults to 'sam_b.pt'.
-        device (str, optional): Device to run the models on. Defaults to an empty string (CPU or GPU, if available).
-        output_dir (str | None | optional): Directory to save the annotated results.
-            Defaults to a 'labels' folder in the same directory as 'data'.
-
-    Example:
-        ```python
-        from ultralytics.data.annotator import auto_annotate
-
-        auto_annotate(data='ultralytics/assets', det_model='yolov8n.pt', sam_model='mobile_sam.pt')
-        ```
+        det_model (str): Path or name of the pre-trained YOLO detection model.
+        sam_model (str): Path or name of the pre-trained SAM segmentation model.
+        device (str): Device to run the models on (e.g., 'cpu', 'cuda', '0').
+        output_dir (str | None): Directory to save the annotated results. If None, a default directory is created.
+
+    Examples:
+        >>> from ultralytics.data.annotator import auto_annotate
+        >>> auto_annotate(data='ultralytics/assets', det_model='yolov8n.pt', sam_model='mobile_sam.pt')
+
+    Notes:
+        - The function creates a new directory for output if not specified.
+        - Annotation results are saved as text files with the same names as the input images.
+        - Each line in the output text file represents a detected object with its class ID and segmentation points.
     """
     det_model = YOLO(det_model)
     sam_model = SAM(sam_model)