ultralytics 8.3.88__py3-none-any.whl → 8.3.90__py3-none-any.whl

ultralytics/models/yolo/world/train_world.py

@@ -9,49 +9,59 @@ from ultralytics.utils.torch_utils import de_parallel
 
 class WorldTrainerFromScratch(WorldTrainer):
     """
-    A class extending the WorldTrainer class for training a world model from scratch on open-set dataset.
-
-    Example:
-        ```python
-        from ultralytics.models.yolo.world.train_world import WorldTrainerFromScratch
-        from ultralytics import YOLOWorld
-
-        data = dict(
-            train=dict(
-                yolo_data=["Objects365.yaml"],
-                grounding_data=[
-                    dict(
-                        img_path="../datasets/flickr30k/images",
-                        json_file="../datasets/flickr30k/final_flickr_separateGT_train.json",
-                    ),
-                    dict(
-                        img_path="../datasets/GQA/images",
-                        json_file="../datasets/GQA/final_mixed_train_no_coco.json",
-                    ),
-                ],
-            ),
-            val=dict(yolo_data=["lvis.yaml"]),
-        )
-
-        model = YOLOWorld("yolov8s-worldv2.yaml")
-        model.train(data=data, trainer=WorldTrainerFromScratch)
-        ```
+    A class extending the WorldTrainer for training a world model from scratch on open-set datasets.
+
+    This trainer specializes in handling mixed datasets including both object detection and grounding datasets,
+    supporting training YOLO-World models with combined vision-language capabilities.
+
+    Attributes:
+        cfg (Dict): Configuration dictionary with default parameters for model training.
+        overrides (Dict): Dictionary of parameter overrides to customize the configuration.
+        _callbacks (List): List of callback functions to be executed during different stages of training.
+
+    Examples:
+        >>> from ultralytics.models.yolo.world.train_world import WorldTrainerFromScratch
+        >>> from ultralytics import YOLOWorld
+        >>> data = dict(
+        ...     train=dict(
+        ...         yolo_data=["Objects365.yaml"],
+        ...         grounding_data=[
+        ...             dict(
+        ...                 img_path="../datasets/flickr30k/images",
+        ...                 json_file="../datasets/flickr30k/final_flickr_separateGT_train.json",
+        ...             ),
+        ...             dict(
+        ...                 img_path="../datasets/GQA/images",
+        ...                 json_file="../datasets/GQA/final_mixed_train_no_coco.json",
+        ...             ),
+        ...         ],
+        ...     ),
+        ...     val=dict(yolo_data=["lvis.yaml"]),
+        ... )
+        >>> model = YOLOWorld("yolov8s-worldv2.yaml")
+        >>> model.train(data=data, trainer=WorldTrainerFromScratch)
     """
 
     def __init__(self, cfg=DEFAULT_CFG, overrides=None, _callbacks=None):
-        """Initialize a WorldTrainer object with given arguments."""
+        """Initialize a WorldTrainerFromScratch object with given configuration and callbacks."""
         if overrides is None:
             overrides = {}
         super().__init__(cfg, overrides, _callbacks)
 
     def build_dataset(self, img_path, mode="train", batch=None):
         """
-        Build YOLO Dataset.
+        Build YOLO Dataset for training or validation.
+
+        This method constructs appropriate datasets based on the mode and input paths, handling both
+        standard YOLO datasets and grounding datasets with different formats.
 
         Args:
-            img_path (List[str] | str): Path to the folder containing images.
-            mode (str): `train` mode or `val` mode, users are able to customize different augmentations for each mode.
-            batch (int, optional): Size of batches, this is for `rect`. Defaults to None.
+            img_path (List[str] | str): Path to the folder containing images or list of paths.
+            mode (str): 'train' mode or 'val' mode, allowing customized augmentations for each mode.
+            batch (int, optional): Size of batches, used for rectangular training/validation.
+
+        Returns:
+            (YOLOConcatDataset | Dataset): The constructed dataset for training or validation.
         """
         gs = max(int(de_parallel(self.model).stride.max() if self.model else 0), 32)
         if mode != "train":
@@ -66,9 +76,17 @@ class WorldTrainerFromScratch(WorldTrainer):
 
     def get_dataset(self):
         """
-        Get train, val path from data dict if it exists.
+        Get train and validation paths from data dictionary.
+
+        Processes the data configuration to extract paths for training and validation datasets,
+        handling both YOLO detection datasets and grounding datasets.
 
-        Returns None if data format is not recognized.
+        Returns:
+            (str): Train dataset path.
+            (str): Validation dataset path.
+
+        Raises:
+            AssertionError: If train or validation datasets are not found, or if validation has multiple datasets.
         """
         final_data = {}
         data_yaml = self.args.data
@@ -98,11 +116,18 @@ class WorldTrainerFromScratch(WorldTrainer):
         return final_data["train"], final_data["val"][0]
 
     def plot_training_labels(self):
-        """DO NOT plot labels."""
+        """Do not plot labels for YOLO-World training."""
         pass
 
     def final_eval(self):
-        """Performs final evaluation and validation for object detection YOLO-World model."""
+        """
+        Perform final evaluation and validation for the YOLO-World model.
+
+        Configures the validator with appropriate dataset and split information before running evaluation.
+
+        Returns:
+            (Dict): Dictionary containing evaluation metrics and results.
+        """
         val = self.args.data["val"]["yolo_data"][0]
         self.validator.args.data = val
         self.validator.args.split = "minival" if isinstance(val, str) and "lvis" in val else "val"

ultralytics/nn/autobackend.py

@@ -19,11 +19,7 @@ from ultralytics.utils.downloads import attempt_download_asset, is_url
 
 
 def check_class_names(names):
-    """
-    Check class names.
-
-    Map imagenet class codes to human-readable names if required. Convert lists to dicts.
-    """
+    """Check class names and convert to dict format if needed."""
     if isinstance(names, list):  # names is a list
         names = dict(enumerate(names))  # convert to dict
     if isinstance(names, dict):
@@ -78,8 +74,23 @@ class AutoBackend(nn.Module):
             | IMX                   | *_imx_model/      |
             | RKNN                  | *_rknn_model/     |
 
-    This class offers dynamic backend switching capabilities based on the input model format, making it easier to deploy
-    models across various platforms.
+    Attributes:
+        model (torch.nn.Module): The loaded YOLO model.
+        device (torch.device): The device (CPU or GPU) on which the model is loaded.
+        task (str): The type of task the model performs (detect, segment, classify, pose).
+        names (Dict): A dictionary of class names that the model can detect.
+        stride (int): The model stride, typically 32 for YOLO models.
+        fp16 (bool): Whether the model uses half-precision (FP16) inference.
+
+    Methods:
+        forward: Run inference on an input image.
+        from_numpy: Convert numpy array to tensor.
+        warmup: Warm up the model with a dummy input.
+        _model_type: Determine the model type from file path.
+
+    Examples:
+        >>> model = AutoBackend(weights="yolov8n.pt", device="cuda")
+        >>> results = model(img)
     """
 
     @torch.no_grad()
@@ -101,7 +112,7 @@ class AutoBackend(nn.Module):
             weights (str | torch.nn.Module): Path to the model weights file or a module instance. Defaults to 'yolo11n.pt'.
             device (torch.device): Device to run the model on. Defaults to CPU.
             dnn (bool): Use OpenCV DNN module for ONNX inference. Defaults to False.
-            data (str | Path | optional): Path to the additional data.yaml file containing class names. Optional.
+            data (str | Path | optional): Path to the additional data.yaml file containing class names.
             fp16 (bool): Enable half-precision inference. Supported only on specific backends. Defaults to False.
             batch (int): Batch-size to assume for inference.
             fuse (bool): Fuse Conv2D + BatchNorm layers for optimization. Defaults to True.
@@ -539,12 +550,12 @@ class AutoBackend(nn.Module):
 
         Args:
             im (torch.Tensor): The image tensor to perform inference on.
-            augment (bool): whether to perform data augmentation during inference, defaults to False
-            visualize (bool): whether to visualize the output predictions, defaults to False
-            embed (list, optional): A list of feature vectors/embeddings to return.
+            augment (bool): Whether to perform data augmentation during inference. Defaults to False.
+            visualize (bool): Whether to visualize the output predictions. Defaults to False.
+            embed (List, optional): A list of feature vectors/embeddings to return.
 
         Returns:
-            (tuple): Tuple containing the raw output tensor, and processed output for visualization (if visualize=True)
+            (torch.Tensor | List[torch.Tensor]): The raw output tensor(s) from the model.
         """
         b, ch, h, w = im.shape  # batch, channel, height, width
         if self.fp16 and im.dtype != torch.float16:
@@ -776,10 +787,13 @@ class AutoBackend(nn.Module):
     def _model_type(p="path/to/model.pt"):
         """
         Takes a path to a model file and returns the model type. Possibles types are pt, jit, onnx, xml, engine, coreml,
-        saved_model, pb, tflite, edgetpu, tfjs, ncnn or paddle.
+        saved_model, pb, tflite, edgetpu, tfjs, ncnn, mnn, imx or paddle.
 
         Args:
-            p (str): path to the model file. Defaults to path/to/model.pt
+            p (str): Path to the model file. Defaults to path/to/model.pt
+
+        Returns:
+            (List[bool]): List of booleans indicating the model type.
 
         Examples:
             >>> model = AutoBackend(weights="path/to/model.onnx")

ultralytics/nn/modules/__init__.py

@@ -2,19 +2,19 @@
 """
 Ultralytics modules.
 
-Example:
-    Visualize a module with Netron.
-    ```python
-    from ultralytics.nn.modules import *
-    import torch
-    import os
+This module provides access to various neural network components used in Ultralytics models, including convolution blocks,
+attention mechanisms, transformer components, and detection/segmentation heads.
 
-    x = torch.ones(1, 128, 40, 40)
-    m = Conv(128, 128)
-    f = f"{m._get_name()}.onnx"
-    torch.onnx.export(m, x, f)
-    os.system(f"onnxslim {f} {f} && open {f}")  # pip install onnxslim
-    ```
+Examples:
+    Visualize a module with Netron.
+    >>> from ultralytics.nn.modules import *
+    >>> import torch
+    >>> import os
+    >>> x = torch.ones(1, 128, 40, 40)
+    >>> m = Conv(128, 128)
+    >>> f = f"{m._get_name()}.onnx"
+    >>> torch.onnx.export(m, x, f)
+    >>> os.system(f"onnxslim {f} {f} && open {f}")  # pip install onnxslim
 """
 
 from .block import (

ultralytics/nn/modules/activation.py

@@ -6,10 +6,19 @@ import torch.nn as nn
 
 
 class AGLU(nn.Module):
-    """Unified activation function module from https://github.com/kostas1515/AGLU."""
+    """
+    Unified activation function module from https://github.com/kostas1515/AGLU.
+
+    This class implements a parameterized activation function with learnable parameters lambda and kappa.
+
+    Attributes:
+        act (nn.Softplus): Softplus activation function with negative beta.
+        lambd (nn.Parameter): Learnable lambda parameter initialized with uniform distribution.
+        kappa (nn.Parameter): Learnable kappa parameter initialized with uniform distribution.
+    """
 
     def __init__(self, device=None, dtype=None) -> None:
-        """Initialize the Unified activation function."""
+        """Initialize the Unified activation function with learnable parameters."""
         super().__init__()
         self.act = nn.Softplus(beta=-1.0)
         self.lambd = nn.Parameter(nn.init.uniform_(torch.empty(1, device=device, dtype=dtype)))  # lambda parameter
@@ -17,5 +26,5 @@ class AGLU(nn.Module):
 
     def forward(self, x: torch.Tensor) -> torch.Tensor:
         """Compute the forward pass of the Unified activation function."""
-        lam = torch.clamp(self.lambd, min=0.0001)
+        lam = torch.clamp(self.lambd, min=0.0001)  # Clamp lambda to avoid division by zero
         return torch.exp((1 / lam) * self.act((self.kappa * x) - torch.log(lam)))