ultralytics 8.3.142__py3-none-any.whl → 8.3.144__py3-none-any.whl

ultralytics/engine/trainer.py

@@ -60,6 +60,9 @@ class BaseTrainer:
     """
     A base class for creating trainers.
 
+    This class provides the foundation for training YOLO models, handling the training loop, validation, checkpointing,
+    and various training utilities. It supports both single-GPU and multi-GPU distributed training.
+
     Attributes:
         args (SimpleNamespace): Configuration for the trainer.
         validator (BaseValidator): Validator instance.
@@ -89,6 +92,19 @@ class BaseTrainer:
         csv (Path): Path to results CSV file.
         metrics (dict): Dictionary of metrics.
         plots (dict): Dictionary of plots.
+
+    Methods:
+        train: Execute the training process.
+        validate: Run validation on the test set.
+        save_model: Save model training checkpoints.
+        get_dataset: Get train and validation datasets.
+        setup_model: Load, create, or download model.
+        build_optimizer: Construct an optimizer for the model.
+
+    Examples:
+        Initialize a trainer and start training
+        >>> trainer = BaseTrainer(cfg="config.yaml")
+        >>> trainer.train()
     """
 
     def __init__(self, cfg=DEFAULT_CFG, overrides=None, _callbacks=None):
@@ -96,14 +112,14 @@ class BaseTrainer:
         Initialize the BaseTrainer class.
 
         Args:
-            cfg (str, optional): Path to a configuration file. Defaults to DEFAULT_CFG.
-            overrides (dict, optional): Configuration overrides. Defaults to None.
-            _callbacks (list, optional): List of callback functions. Defaults to None.
+            cfg (str, optional): Path to a configuration file.
+            overrides (dict, optional): Configuration overrides.
+            _callbacks (list, optional): List of callback functions.
         """
         self.args = get_cfg(cfg, overrides)
         self.check_resume(overrides)
         self.device = select_device(self.args.device, self.args.batch)
-        # update "-1" devices so post-training val does not repeat search
+        # Update "-1" devices so post-training val does not repeat search
         self.args.device = os.getenv("CUDA_VISIBLE_DEVICES") if "cuda" in str(self.device) else str(self.device)
         self.validator = None
         self.metrics = None
@@ -626,7 +642,7 @@ class BaseTrainer:
             self.ema.update(self.model)
 
     def preprocess_batch(self, batch):
-        """Allows custom preprocessing model inputs and ground truths depending on task type."""
+        """Allow custom preprocessing model inputs and ground truths depending on task type."""
         return batch
 
     def validate(self):
@@ -634,7 +650,8 @@ class BaseTrainer:
         Run validation on test set using self.validator.
 
         Returns:
-            (tuple): A tuple containing metrics dictionary and fitness score.
+            metrics (dict): Dictionary of validation metrics.
+            fitness (float): Fitness score for the validation.
         """
         metrics = self.validator(self)
         fitness = metrics.pop("fitness", -self.loss.detach().cpu().numpy())  # use loss as fitness measure if not found
@@ -647,11 +664,11 @@ class BaseTrainer:
         raise NotImplementedError("This task trainer doesn't support loading cfg files")
 
     def get_validator(self):
-        """Returns a NotImplementedError when the get_validator function is called."""
+        """Return a NotImplementedError when the get_validator function is called."""
         raise NotImplementedError("get_validator function not implemented in trainer")
 
     def get_dataloader(self, dataset_path, batch_size=16, rank=0, mode="train"):
-        """Returns dataloader derived from torch.data.Dataloader."""
+        """Return dataloader derived from torch.data.Dataloader."""
         raise NotImplementedError("get_dataloader function not implemented in trainer")
 
     def build_dataset(self, img_path, mode="train", batch=None):
@@ -660,7 +677,7 @@ class BaseTrainer:
 
     def label_loss_items(self, loss_items=None, prefix="train"):
         """
-        Returns a loss dict with labelled training loss items tensor.
+        Return a loss dict with labelled training loss items tensor.
 
         Note:
             This is not needed for classification but necessary for segmentation & detection
@@ -672,20 +689,20 @@ class BaseTrainer:
         self.model.names = self.data["names"]
 
     def build_targets(self, preds, targets):
-        """Builds target tensors for training YOLO model."""
+        """Build target tensors for training YOLO model."""
         pass
 
     def progress_string(self):
-        """Returns a string describing training progress."""
+        """Return a string describing training progress."""
         return ""
 
     # TODO: may need to put these following functions into callback
     def plot_training_samples(self, batch, ni):
-        """Plots training samples during YOLO training."""
+        """Plot training samples during YOLO training."""
         pass
 
     def plot_training_labels(self):
-        """Plots training labels for YOLO model."""
+        """Plot training labels for YOLO model."""
         pass
 
     def save_metrics(self, metrics):
@@ -702,7 +719,7 @@ class BaseTrainer:
         pass
 
     def on_plot(self, name, data=None):
-        """Registers plots (e.g. to be consumed in callbacks)."""
+        """Register plots (e.g. to be consumed in callbacks)."""
         path = Path(name)
         self.plots[path] = {"data": data, "timestamp": time.time()}
 
@@ -796,12 +813,12 @@ class BaseTrainer:
         Args:
             model (torch.nn.Module): The model for which to build an optimizer.
             name (str, optional): The name of the optimizer to use. If 'auto', the optimizer is selected
-                based on the number of iterations. Default: 'auto'.
-            lr (float, optional): The learning rate for the optimizer. Default: 0.001.
-            momentum (float, optional): The momentum factor for the optimizer. Default: 0.9.
-            decay (float, optional): The weight decay for the optimizer. Default: 1e-5.
+                based on the number of iterations.
+            lr (float, optional): The learning rate for the optimizer.
+            momentum (float, optional): The momentum factor for the optimizer.
+            decay (float, optional): The weight decay for the optimizer.
             iterations (float, optional): The number of iterations, which determines the optimizer if
-                name is 'auto'. Default: 1e5.
+                name is 'auto'.
 
         Returns:
             (torch.optim.Optimizer): The constructed optimizer.

ultralytics/engine/tuner.py

@@ -18,6 +18,7 @@ import random
 import shutil
 import subprocess
 import time
+from typing import Dict, List, Optional
 
 import numpy as np
 import torch
@@ -35,7 +36,7 @@ class Tuner:
     search space and retraining the model to evaluate their performance.
 
     Attributes:
-        space (dict): Hyperparameter search space containing bounds and scaling factors for mutation.
+        space (Dict[str, tuple]): Hyperparameter search space containing bounds and scaling factors for mutation.
         tune_dir (Path): Directory where evolution logs and results will be saved.
         tune_csv (Path): Path to the CSV file where evolution logs are saved.
         args (dict): Configuration arguments for the tuning process.
@@ -43,8 +44,8 @@ class Tuner:
         prefix (str): Prefix string for logging messages.
 
     Methods:
-        _mutate: Mutates the given hyperparameters within the specified bounds.
-        __call__: Executes the hyperparameter evolution across multiple iterations.
+        _mutate: Mutate hyperparameters based on bounds and scaling factors.
+        __call__: Execute the hyperparameter evolution across multiple iterations.
 
     Examples:
         Tune hyperparameters for YOLO11n on COCO8 at imgsz=640 and epochs=30 for 300 tuning iterations.
@@ -58,13 +59,13 @@ class Tuner:
         >>> model.tune(space={key1: val1, key2: val2})  # custom search space dictionary
     """
 
-    def __init__(self, args=DEFAULT_CFG, _callbacks=None):
+    def __init__(self, args=DEFAULT_CFG, _callbacks: Optional[List] = None):
         """
         Initialize the Tuner with configurations.
 
         Args:
             args (dict): Configuration for hyperparameter evolution.
-            _callbacks (list, optional): Callback functions to be executed during tuning.
+            _callbacks (List, optional): Callback functions to be executed during tuning.
         """
         self.space = args.pop("space", None) or {  # key: (min, max, gain(optional))
             # 'optimizer': tune.choice(['SGD', 'Adam', 'AdamW', 'NAdam', 'RAdam', 'RMSProp']),
@@ -106,7 +107,9 @@ class Tuner:
             f"{self.prefix}💡 Learn about tuning at https://docs.ultralytics.com/guides/hyperparameter-tuning"
         )
 
-    def _mutate(self, parent="single", n=5, mutation=0.8, sigma=0.2):
+    def _mutate(
+        self, parent: str = "single", n: int = 5, mutation: float = 0.8, sigma: float = 0.2
+    ) -> Dict[str, float]:
         """
         Mutate hyperparameters based on bounds and scaling factors specified in `self.space`.
 
@@ -117,7 +120,7 @@ class Tuner:
             sigma (float): Standard deviation for Gaussian random number generator.
 
         Returns:
-            (dict): A dictionary containing mutated hyperparameters.
+            (Dict[str, float]): A dictionary containing mutated hyperparameters.
         """
         if self.tune_csv.exists():  # if CSV file exists: select best hyps and mutate
             # Select parent(s)
@@ -152,14 +155,14 @@ class Tuner:
 
         return hyp
 
-    def __call__(self, model=None, iterations=10, cleanup=True):
+    def __call__(self, model=None, iterations: int = 10, cleanup: bool = True):
         """
         Execute the hyperparameter evolution process when the Tuner instance is called.
 
         This method iterates through the number of iterations, performing the following steps in each iteration:
 
         1. Load the existing hyperparameters or initialize new ones.
-        2. Mutate the hyperparameters using the `mutate` method.
+        2. Mutate the hyperparameters using the `_mutate` method.
         3. Train a YOLO model with the mutated hyperparameters.
         4. Log the fitness score and mutated hyperparameters to a CSV file.
 

ultralytics/engine/validator.py

@@ -67,6 +67,8 @@ class BaseValidator:
         save_dir (Path): Directory to save results.
         plots (dict): Dictionary to store plots for visualization.
         callbacks (dict): Dictionary to store various callback functions.
+        stride (int): Model stride for padding calculations.
+        loss (torch.Tensor): Accumulated loss during training validation.
 
     Methods:
         __call__: Execute validation process, running inference on dataloader and computing performance metrics.
@@ -84,7 +86,7 @@ class BaseValidator:
         check_stats: Check statistics.
         print_results: Print the results of the model's predictions.
         get_desc: Get description of the YOLO model.
-        on_plot: Register plots (e.g. to be consumed in callbacks).
+        on_plot: Register plots for visualization.
         plot_val_samples: Plot validation samples during training.
         plot_predictions: Plot YOLO model predictions on batch images.
         pred_to_json: Convert predictions to JSON format.
@@ -138,7 +140,7 @@ class BaseValidator:
             model (nn.Module, optional): Model to validate if not using a trainer.
 
         Returns:
-            stats (dict): Dictionary containing validation statistics.
+            (dict): Dictionary containing validation statistics.
         """
         self.training = trainer is not None
         augment = self.args.augment and (not self.training)
@@ -149,7 +151,6 @@ class BaseValidator:
             self.args.half = self.device.type != "cpu" and trainer.amp
             model = trainer.ema.ema or trainer.model
             model = model.half() if self.args.half else model.float()
-            # self.model = model
             self.loss = torch.zeros_like(trainer.loss_items, device=trainer.device)
             self.args.plots &= trainer.stopper.possible_stop or (trainer.epoch == trainer.epochs - 1)
             model.eval()
@@ -164,7 +165,6 @@ class BaseValidator:
                 data=self.args.data,
                 fp16=self.args.half,
             )
-            # self.model = model
             self.device = model.device  # update device
             self.args.half = model.fp16  # update half
             stride, pt, jit, engine = model.stride, model.pt, model.jit, model.engine
@@ -184,7 +184,7 @@ class BaseValidator:
 
             if self.device.type in {"cpu", "mps"}:
                 self.args.workers = 0  # faster CPU val as time dominated by inference, not dataloading
-            if not (pt or getattr(model, "dynamic", False)):
+            if not (pt or (getattr(model, "dynamic", False) and not model.imx)):
                 self.args.rect = False
             self.stride = model.stride  # used in get_dataloader() for padding
             self.dataloader = self.dataloader or self.get_dataloader(self.data.get(self.args.split), self.args.batch)
@@ -263,7 +263,7 @@ class BaseValidator:
             pred_classes (torch.Tensor): Predicted class indices of shape (N,).
             true_classes (torch.Tensor): Target class indices of shape (M,).
             iou (torch.Tensor): An NxM tensor containing the pairwise IoU values for predictions and ground truth.
-            use_scipy (bool): Whether to use scipy for matching (more precise).
+            use_scipy (bool, optional): Whether to use scipy for matching (more precise).
 
         Returns:
             (torch.Tensor): Correct tensor of shape (N, 10) for 10 IoU thresholds.
@@ -292,7 +292,6 @@ class BaseValidator:
                     if matches.shape[0] > 1:
                         matches = matches[iou[matches[:, 0], matches[:, 1]].argsort()[::-1]]
                         matches = matches[np.unique(matches[:, 1], return_index=True)[1]]
-                        # matches = matches[matches[:, 2].argsort()[::-1]]
                         matches = matches[np.unique(matches[:, 0], return_index=True)[1]]
                     correct[matches[:, 1].astype(int), i] = True
         return torch.tensor(correct, dtype=torch.bool, device=pred_classes.device)
@@ -356,10 +355,9 @@ class BaseValidator:
         return []
 
     def on_plot(self, name, data=None):
-        """Register plots (e.g. to be consumed in callbacks)."""
+        """Register plots for visualization."""
         self.plots[Path(name)] = {"data": data, "timestamp": time.time()}
 
-    # TODO: may need to put these following functions into callback
     def plot_val_samples(self, batch, ni):
         """Plot validation samples during training."""
         pass

ultralytics/hub/__init__.py

@@ -31,8 +31,8 @@ def login(api_key: str = None, save: bool = True) -> bool:
     environment variable if successfully authenticated.
 
     Args:
-        api_key (str, optional): API key to use for authentication. If not provided, it will be retrieved from SETTINGS
-            or HUB_API_KEY environment variable.
+        api_key (str, optional): API key to use for authentication. If not provided, it will be retrieved from
+            SETTINGS or HUB_API_KEY environment variable.
         save (bool, optional): Whether to save the API key to SETTINGS if authentication is successful.
 
     Returns:
@@ -68,13 +68,7 @@ def login(api_key: str = None, save: bool = True) -> bool:
 
 
 def logout():
-    """
-    Log out of Ultralytics HUB by removing the API key from the settings file. To log in again, use 'yolo login'.
-
-    Examples:
-        >>> from ultralytics import hub
-        >>> hub.logout()
-    """
+    """Log out of Ultralytics HUB by removing the API key from the settings file."""
     SETTINGS["api_key"] = ""
     LOGGER.info(f"{PREFIX}logged out ✅. To log in again, use 'yolo login'.")
 
@@ -89,7 +83,7 @@ def reset_model(model_id: str = ""):
 
 
 def export_fmts_hub():
-    """Returns a list of HUB-supported export formats."""
+    """Return a list of HUB-supported export formats."""
     from ultralytics.engine.exporter import export_formats
 
     return list(export_formats()["Argument"][1:]) + ["ultralytics_tflite", "ultralytics_coreml"]
@@ -125,14 +119,18 @@ def get_export(model_id: str = "", format: str = "torchscript"):
 
     Args:
         model_id (str): The ID of the model to retrieve from Ultralytics HUB.
-        format (str): The export format to retrieve. Must be one of the supported formats returned by export_fmts_hub().
+        format (str): The export format to retrieve. Must be one of the supported formats returned by
+            export_fmts_hub().
+
+    Returns:
+        (dict): JSON response containing the exported model information.
 
     Raises:
         AssertionError: If the specified format is not supported or if the API request fails.
 
     Examples:
         >>> from ultralytics import hub
-        >>> hub.get_export(model_id="your_model_id", format="torchscript")
+        >>> result = hub.get_export(model_id="your_model_id", format="torchscript")
     """
     assert format in export_fmts_hub(), f"Unsupported export format '{format}', valid formats are {export_fmts_hub()}"
     r = requests.post(
@@ -160,7 +158,7 @@ def check_dataset(path: str, task: str) -> None:
         >>> check_dataset("path/to/dota8.zip", task="obb")  # OBB dataset
         >>> check_dataset("path/to/imagenet10.zip", task="classify")  # classification dataset
 
-    Note:
+    Notes:
         Download *.zip files from https://github.com/ultralytics/hub/tree/main/example_datasets
         i.e. https://github.com/ultralytics/hub/raw/main/example_datasets/coco8.zip for coco8.zip.
     """

ultralytics/hub/auth.py

@@ -21,6 +21,19 @@ class Auth:
         id_token (str | bool): Token used for identity verification, initialized as False.
         api_key (str | bool): API key for authentication, initialized as False.
         model_key (bool): Placeholder for model key, initialized as False.
+
+    Methods:
+        authenticate: Attempt to authenticate with the server using either id_token or API key.
+        auth_with_cookies: Attempt to fetch authentication via cookies and set id_token.
+        get_auth_header: Get the authentication header for making API requests.
+        request_api_key: Prompt the user to input their API key.
+
+    Examples:
+        Initialize Auth with an API key
+        >>> auth = Auth(api_key="your_api_key_here")
+
+        Initialize Auth without API key (will prompt for input)
+        >>> auth = Auth()
     """
 
     id_token = api_key = model_key = False
@@ -71,7 +84,15 @@ class Auth:
             LOGGER.info(f"{PREFIX}Get API key from {API_KEY_URL} and then run 'yolo login API_KEY'")
 
     def request_api_key(self, max_attempts: int = 3) -> bool:
-        """Prompt the user to input their API key."""
+        """
+        Prompt the user to input their API key.
+
+        Args:
+            max_attempts (int): Maximum number of authentication attempts.
+
+        Returns:
+            (bool): True if authentication is successful, False otherwise.
+        """
         import getpass
 
         for attempts in range(max_attempts):
@@ -134,4 +155,3 @@ class Auth:
             return {"authorization": f"Bearer {self.id_token}"}
         elif self.api_key:
             return {"x-api-key": self.api_key}
-        # else returns None

ultralytics/hub/google/__init__.py

@@ -31,7 +31,7 @@ class GCPRegions:
     """
 
     def __init__(self):
-        """Initializes the GCPRegions class with predefined Google Cloud Platform regions and their details."""
+        """Initialize the GCPRegions class with predefined Google Cloud Platform regions and their details."""
         self.regions = {
             "asia-east1": (1, "Taiwan", "China"),
             "asia-east2": (2, "Hong Kong", "China"),
@@ -74,11 +74,11 @@ class GCPRegions:
         }
 
     def tier1(self) -> List[str]:
-        """Returns a list of GCP regions classified as tier 1 based on predefined criteria."""
+        """Return a list of GCP regions classified as tier 1 based on predefined criteria."""
         return [region for region, info in self.regions.items() if info[0] == 1]
 
     def tier2(self) -> List[str]:
-        """Returns a list of GCP regions classified as tier 2 based on predefined criteria."""
+        """Return a list of GCP regions classified as tier 2 based on predefined criteria."""
         return [region for region, info in self.regions.items() if info[0] == 2]
 
     @staticmethod
@@ -87,19 +87,19 @@ class GCPRegions:
         Ping a specified GCP region and measure network latency statistics.
 
         Args:
-                region (str): The GCP region identifier to ping (e.g., 'us-central1').
-                attempts (int): Number of ping attempts to make for calculating statistics.
+            region (str): The GCP region identifier to ping (e.g., 'us-central1').
+            attempts (int, optional): Number of ping attempts to make for calculating statistics.
 
         Returns:
-                region (str): The GCP region identifier that was pinged.
-                mean_latency (float): Mean latency in milliseconds, or infinity if all pings failed.
-                min_latency (float): Minimum latency in milliseconds, or infinity if all pings failed.
-                max_latency (float): Maximum latency in milliseconds, or infinity if all pings failed.
-                std_dev (float): Standard deviation of latencies in milliseconds, or infinity if all pings failed.
+            region (str): The GCP region identifier that was pinged.
+            mean_latency (float): Mean latency in milliseconds, or infinity if all pings failed.
+            std_dev (float): Standard deviation of latencies in milliseconds, or infinity if all pings failed.
+            min_latency (float): Minimum latency in milliseconds, or infinity if all pings failed.
+            max_latency (float): Maximum latency in milliseconds, or infinity if all pings failed.
 
         Examples:
-                >>> region, mean, min_lat, max_lat, std = GCPRegions._ping_region("us-central1", attempts=3)
-                >>> print(f"Region {region} has mean latency: {mean:.2f}ms")
+            >>> region, mean, std, min_lat, max_lat = GCPRegions._ping_region("us-central1", attempts=3)
+            >>> print(f"Region {region} has mean latency: {mean:.2f}ms")
         """
         url = f"https://{region}-docker.pkg.dev"
         latencies = []
@@ -107,7 +107,7 @@ class GCPRegions:
             try:
                 start_time = time.time()
                 _ = requests.head(url, timeout=5)
-                latency = (time.time() - start_time) * 1000  # convert latency to milliseconds
+                latency = (time.time() - start_time) * 1000  # Convert latency to milliseconds
                 if latency != float("inf"):
                     latencies.append(latency)
             except requests.RequestException:
@@ -126,17 +126,17 @@ class GCPRegions:
         attempts: int = 1,
     ) -> List[Tuple[str, float, float, float, float]]:
         """
-        Determines the GCP regions with the lowest latency based on ping tests.
+        Determine the GCP regions with the lowest latency based on ping tests.
 
         Args:
-            top (int): Number of top regions to return.
-            verbose (bool): If True, prints detailed latency information for all tested regions.
-            tier (int | None): Filter regions by tier (1 or 2). If None, all regions are tested.
-            attempts (int): Number of ping attempts per region.
+            top (int, optional): Number of top regions to return.
+            verbose (bool, optional): If True, prints detailed latency information for all tested regions.
+            tier (int | None, optional): Filter regions by tier (1 or 2). If None, all regions are tested.
+            attempts (int, optional): Number of ping attempts per region.
 
         Returns:
             (List[Tuple[str, float, float, float, float]]): List of tuples containing region information and
-            latency statistics. Each tuple contains (region, mean_latency, std_dev, min_latency, max_latency).
+                latency statistics. Each tuple contains (region, mean_latency, std_dev, min_latency, max_latency).
 
         Examples:
             >>> regions = GCPRegions()