ultralytics 8.3.101__py3-none-any.whl → 8.3.103__py3-none-any.whl

ultralytics/utils/callbacks/tensorboard.py

@@ -24,14 +24,42 @@ except (ImportError, AssertionError, TypeError, AttributeError):
 
 
 def _log_scalars(scalars: dict, step: int = 0) -> None:
-    """Logs scalar values to TensorBoard."""
+    """
+    Log scalar values to TensorBoard.
+
+    Args:
+        scalars (dict): Dictionary of scalar values to log to TensorBoard. Keys are scalar names and values are the
+            corresponding scalar values.
+        step (int): Global step value to record with the scalar values. Used for x-axis in TensorBoard graphs.
+
+    Examples:
+        >>> # Log training metrics
+        >>> metrics = {"loss": 0.5, "accuracy": 0.95}
+        >>> _log_scalars(metrics, step=100)
+    """
     if WRITER:
         for k, v in scalars.items():
             WRITER.add_scalar(k, v, step)
 
 
 def _log_tensorboard_graph(trainer) -> None:
-    """Log model graph to TensorBoard."""
+    """
+    Log model graph to TensorBoard.
+
+    This function attempts to visualize the model architecture in TensorBoard by tracing the model with a dummy input
+    tensor. It first tries a simple method suitable for YOLO models, and if that fails, falls back to a more complex
+    approach for models like RTDETR that may require special handling.
+
+    Args:
+        trainer (BaseTrainer): The trainer object containing the model to visualize. Must have attributes:
+            - model: PyTorch model to visualize
+            - args: Configuration arguments with 'imgsz' attribute
+
+    Notes:
+        This function requires TensorBoard integration to be enabled and the global WRITER to be initialized.
+        It handles potential warnings from the PyTorch JIT tracer and attempts to gracefully handle different
+        model architectures.
+    """
     # Input image
     imgsz = trainer.args.imgsz
     imgsz = (imgsz, imgsz) if isinstance(imgsz, int) else imgsz

ultralytics/utils/callbacks/wb.py

@@ -99,7 +99,22 @@ def _plot_curve(
 
 
 def _log_plots(plots, step):
-    """Logs plots from the input dictionary if they haven't been logged already at the specified step."""
+    """
+    Log plots to WandB at a specific step if they haven't been logged already.
+
+    This function checks each plot in the input dictionary against previously processed plots and logs
+    new or updated plots to WandB at the specified step.
+
+    Args:
+        plots (dict): Dictionary of plots to log, where keys are plot names and values are dictionaries
+            containing plot metadata including timestamps.
+        step (int): The step/epoch at which to log the plots in the WandB run.
+
+    Notes:
+        - The function uses a shallow copy of the plots dictionary to prevent modification during iteration
+        - Plots are identified by their stem name (filename without extension)
+        - Each plot is logged as a WandB Image object
+    """
     for name, params in plots.copy().items():  # shallow copy to prevent plots dict changing during iteration
         timestamp = params["timestamp"]
         if _processed_plots.get(name) != timestamp:

ultralytics/utils/dist.py

@@ -26,7 +26,26 @@ def find_free_network_port() -> int:
 
 
 def generate_ddp_file(trainer):
-    """Generates a DDP file and returns its file name."""
+    """
+    Generate a DDP (Distributed Data Parallel) file for multi-GPU training.
+
+    This function creates a temporary Python file that enables distributed training across multiple GPUs.
+    The file contains the necessary configuration to initialize the trainer in a distributed environment.
+
+    Args:
+        trainer (object): The trainer object containing training configuration and arguments.
+                         Must have args attribute and be a class instance.
+
+    Returns:
+        (str): Path to the generated temporary DDP file.
+
+    Notes:
+        The generated file is saved in the USER_CONFIG_DIR/DDP directory and includes:
+        - Trainer class import
+        - Configuration overrides from the trainer arguments
+        - Model path configuration
+        - Training initialization code
+    """
     module, name = f"{trainer.__class__.__module__}.{trainer.__class__.__name__}".rsplit(".", 1)
 
     content = f"""
@@ -80,6 +99,20 @@ def generate_ddp_command(world_size, trainer):
 
 
 def ddp_cleanup(trainer, file):
-    """Delete temp file if created."""
+    """
+    Delete temporary file if created during distributed data parallel (DDP) training.
+
+    This function checks if the provided file contains the trainer's ID in its name, indicating it was created
+    as a temporary file for DDP training, and deletes it if so.
+
+    Args:
+        trainer (object): The trainer object used for distributed training.
+        file (str): Path to the file that might need to be deleted.
+
+    Examples:
+        >>> trainer = YOLOTrainer()
+        >>> file = "/tmp/ddp_temp_123456789.py"
+        >>> ddp_cleanup(trainer, file)
+    """
     if f"{id(trainer)}.py" in file:  # if temp_file suffix in file
         os.remove(file)

ultralytics/utils/errors.py

@@ -5,18 +5,39 @@ from ultralytics.utils import emojis
 
 class HUBModelError(Exception):
     """
-    Custom exception class for handling errors related to model fetching in Ultralytics YOLO.
+    Exception raised when a model cannot be found or retrieved from Ultralytics HUB.
 
-    This exception is raised when a requested model is not found or cannot be retrieved.
-    The message is also processed to include emojis for better user experience.
+    This custom exception is used specifically for handling errors related to model fetching in Ultralytics YOLO.
+    The error message is processed to include emojis for better user experience.
 
     Attributes:
         message (str): The error message displayed when the exception is raised.
 
-    Note:
-        The message is automatically processed through the 'emojis' function from the 'ultralytics.utils' package.
+    Methods:
+        __init__: Initialize the HUBModelError with a custom message.
+
+    Examples:
+        >>> try:
+        >>> # Code that might fail to find a model
+        >>>     raise HUBModelError("Custom model not found message")
+        >>> except HUBModelError as e:
+        >>>     print(e)  # Displays the emoji-enhanced error message
     """
 
     def __init__(self, message="Model not found. Please check model URL and try again."):
-        """Create an exception for when a model is not found."""
+        """
+        Initialize a HUBModelError exception.
+
+        This exception is raised when a requested model is not found or cannot be retrieved from Ultralytics HUB.
+        The message is processed to include emojis for better user experience.
+
+        Args:
+            message (str, optional): The error message to display when the exception is raised.
+
+        Examples:
+            >>> try:
+            ...     raise HUBModelError("Custom model error message")
+            ... except HUBModelError as e:
+            ...     print(e)
+        """
         super().__init__(emojis(message))

ultralytics/utils/metrics.py

@@ -523,7 +523,7 @@ def plot_mc_curve(px, py, save_dir=Path("mc_curve.png"), names={}, xlabel="Confi
     else:
         ax.plot(px, py.T, linewidth=1, color="grey")  # plot(confidence, metric)
 
-    y = smooth(py.mean(0), 0.05)
+    y = smooth(py.mean(0), 0.1)
     ax.plot(px, y, linewidth=3, color="blue", label=f"all classes {y.max():.2f} at {px[y.argmax()]:.3f}")
     ax.set_xlabel(xlabel)
     ax.set_ylabel(ylabel)

ultralytics/utils/patches.py

@@ -18,10 +18,14 @@ def imread(filename: str, flags: int = cv2.IMREAD_COLOR):
 
     Args:
         filename (str): Path to the file to read.
-        flags (int, optional): Flag that can take values of cv2.IMREAD_*.
+        flags (int): Flag that can take values of cv2.IMREAD_*. Controls how the image is read.
 
     Returns:
         (np.ndarray): The read image.
+
+    Examples:
+        >>> img = imread("path/to/image.jpg")
+        >>> img = imread("path/to/image.jpg", cv2.IMREAD_GRAYSCALE)
     """
     return cv2.imdecode(np.fromfile(filename, np.uint8), flags)
 
@@ -36,7 +40,14 @@ def imwrite(filename: str, img: np.ndarray, params=None):
         params (List[int], optional): Additional parameters for image encoding.
 
     Returns:
-        (bool): True if the file was written, False otherwise.
+        (bool): True if the file was written successfully, False otherwise.
+
+    Examples:
+        >>> import numpy as np
+        >>> img = np.zeros((100, 100, 3), dtype=np.uint8)  # Create a black image
+        >>> success = imwrite("output.jpg", img)  # Write image to file
+        >>> print(success)
+        True
     """
     try:
         cv2.imencode(Path(filename).suffix, img, params)[1].tofile(filename)
@@ -49,9 +60,19 @@ def imshow(winname: str, mat: np.ndarray):
     """
     Display an image in the specified window.
 
+    This function is a wrapper around OpenCV's imshow function that displays an image in a named window. It is
+    particularly useful for visualizing images during development and debugging.
+
     Args:
-        winname (str): Name of the window.
-        mat (np.ndarray): Image to be shown.
+        winname (str): Name of the window where the image will be displayed. If a window with this name already
+            exists, the image will be displayed in that window.
+        mat (np.ndarray): Image to be shown. Should be a valid numpy array representing an image.
+
+    Examples:
+        >>> import numpy as np
+        >>> img = np.zeros((300, 300, 3), dtype=np.uint8)  # Create a black image
+        >>> img[:100, :100] = [255, 0, 0]  # Add a blue square
+        >>> imshow("Example Window", img)  # Display the image
     """
     _imshow(winname.encode("unicode_escape").decode(), mat)
 
@@ -74,7 +95,7 @@ def torch_load(*args, **kwargs):
     Returns:
         (Any): The loaded PyTorch object.
 
-    Note:
+    Notes:
         For PyTorch versions 2.0 and above, this function automatically sets 'weights_only=False'
         if the argument is not provided, to avoid deprecation warnings.
     """
@@ -96,6 +117,13 @@ def torch_save(*args, **kwargs):
     Args:
         *args (Any): Positional arguments to pass to torch.save.
         **kwargs (Any): Keyword arguments to pass to torch.save.
+
+    Returns:
+        (Any): Result of torch.save operation if successful, None otherwise.
+
+    Examples:
+        >>> model = torch.nn.Linear(10, 1)
+        >>> torch_save(model.state_dict(), "model.pt")
     """
     for i in range(4):  # 3 retries
         try:

ultralytics/utils/torch_utils.py

@@ -386,14 +386,18 @@ def model_info_for_loggers(trainer):
 
 def get_flops(model, imgsz=640):
     """
-    Return a YOLO model's FLOPs.
+    Calculate FLOPs (floating point operations) for a model in billions.
+
+    Attempts two calculation methods: first with a stride-based tensor for efficiency,
+    then falls back to full image size if needed (e.g., for RTDETR models). Returns 0.0
+    if thop library is unavailable or calculation fails.
 
     Args:
         model (nn.Module): The model to calculate FLOPs for.
         imgsz (int | List[int], optional): Input image size. Defaults to 640.
 
     Returns:
-        (float): The model's FLOPs in billions.
+        (float): The model FLOPs in billions.
     """
     if not thop:
         return 0.0  # if not installed return 0.0 GFLOPs
@@ -404,13 +408,13 @@ def get_flops(model, imgsz=640):
         if not isinstance(imgsz, list):
             imgsz = [imgsz, imgsz]  # expand if int/float
         try:
-            # Use stride size for input tensor
+            # Method 1: Use stride-based input tensor
             stride = max(int(model.stride.max()), 32) if hasattr(model, "stride") else 32  # max stride
             im = torch.empty((1, p.shape[1], stride, stride), device=p.device)  # input image in BCHW format
             flops = thop.profile(deepcopy(model), inputs=[im], verbose=False)[0] / 1e9 * 2  # stride GFLOPs
             return flops * imgsz[0] / stride * imgsz[1] / stride  # imgsz GFLOPs
         except Exception:
-            # Use actual image size for input tensor (i.e. required for RTDETR models)
+            # Method 2: Use actual image size (required for RTDETR models)
             im = torch.empty((1, p.shape[1], *imgsz), device=p.device)  # input image in BCHW format
             return thop.profile(deepcopy(model), inputs=[im], verbose=False)[0] / 1e9 * 2  # imgsz GFLOPs
     except Exception:
@@ -611,10 +615,10 @@ def unset_deterministic():
 
 class ModelEMA:
     """
-    Updated Exponential Moving Average (EMA) from https://github.com/rwightman/pytorch-image-models.
+    Updated Exponential Moving Average (EMA) implementation.
 
     Keeps a moving average of everything in the model state_dict (parameters and buffers).
-    For EMA details see https://www.tensorflow.org/api_docs/python/tf/train/ExponentialMovingAverage
+    For EMA details see References.
 
     To disable EMA set the `enabled` attribute to `False`.
 
@@ -623,6 +627,10 @@ class ModelEMA:
         updates (int): Number of EMA updates.
         decay (function): Decay function that determines the EMA weight.
         enabled (bool): Whether EMA is enabled.
+
+    References:
+        - https://github.com/rwightman/pytorch-image-models
+        - https://www.tensorflow.org/api_docs/python/tf/train/ExponentialMovingAverage
     """
 
     def __init__(self, model, decay=0.9999, tau=2000, updates=0):

ultralytics/utils/triton.py

@@ -25,6 +25,9 @@ class TritonRemoteModel:
         output_names (List[str]): The names of the model outputs.
         metadata: The metadata associated with the model.
 
+    Methods:
+        __call__: Call the model with the given inputs and return the outputs.
+
     Examples:
         Initialize a Triton client with HTTP
         >>> model = TritonRemoteModel(url="localhost:8000", endpoint="yolov8", scheme="http")
@@ -34,7 +37,7 @@ class TritonRemoteModel:
 
     def __init__(self, url: str, endpoint: str = "", scheme: str = ""):
         """
-        Initialize the TritonRemoteModel.
+        Initialize the TritonRemoteModel for interacting with a remote Triton Inference Server.
 
         Arguments may be provided individually or parsed from a collective 'url' argument of the form
         <scheme>://<netloc>/<endpoint>/<task_name>
@@ -43,6 +46,10 @@ class TritonRemoteModel:
             url (str): The URL of the Triton server.
             endpoint (str): The name of the model on the Triton server.
             scheme (str): The communication scheme ('http' or 'grpc').
+
+        Examples:
+            >>> model = TritonRemoteModel(url="localhost:8000", endpoint="yolov8", scheme="http")
+            >>> model = TritonRemoteModel(url="http://localhost:8000/yolov8")
         """
         if not endpoint and not scheme:  # Parse all args from URL string
             splits = urlsplit(url)
@@ -83,10 +90,16 @@ class TritonRemoteModel:
         Call the model with the given inputs.
 
         Args:
-            *inputs (np.ndarray): Input data to the model.
+            *inputs (np.ndarray): Input data to the model. Each array should match the expected shape and type
+                for the corresponding model input.
 
         Returns:
-            (List[np.ndarray]): Model outputs with the same dtype as the input.
+            (List[np.ndarray]): Model outputs with the same dtype as the input. Each element in the list
+                corresponds to one of the model's output tensors.
+
+        Examples:
+            >>> model = TritonRemoteModel(url="localhost:8000", endpoint="yolov8", scheme="http")
+            >>> outputs = model(np.random.rand(1, 3, 640, 640).astype(np.float32))
         """
         infer_inputs = []
         input_format = inputs[0].dtype

ultralytics/utils/tuner.py

@@ -1,7 +1,7 @@
 # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
 
 from ultralytics.cfg import TASK2DATA, TASK2METRIC, get_cfg, get_save_dir
-from ultralytics.utils import DEFAULT_CFG, DEFAULT_CFG_DICT, LOGGER, NUM_THREADS, checks
+from ultralytics.utils import DEFAULT_CFG, DEFAULT_CFG_DICT, LOGGER, NUM_THREADS, checks, colorstr
 
 
 def run_ray_tune(
@@ -95,7 +95,7 @@ def run_ray_tune(
         return results.results_dict
 
     # Get search space
-    if not space:
+    if not space and not train_args.get("resume"):
         space = default_space
         LOGGER.warning("WARNING ⚠️ search space not provided, using default search space.")
 
@@ -123,15 +123,23 @@ def run_ray_tune(
 
     # Create the Ray Tune hyperparameter search tuner
     tune_dir = get_save_dir(
-        get_cfg(DEFAULT_CFG, train_args), name=train_args.pop("name", "tune")
+        get_cfg(
+            DEFAULT_CFG,
+            {**train_args, **{"exist_ok": train_args.pop("resume", False)}},  # resume w/ same tune_dir
+        ),
+        name=train_args.pop("name", "tune"),  # runs/{task}/{tune_dir}
     ).resolve()  # must be absolute dir
     tune_dir.mkdir(parents=True, exist_ok=True)
-    tuner = tune.Tuner(
-        trainable_with_resources,
-        param_space=space,
-        tune_config=tune.TuneConfig(scheduler=asha_scheduler, num_samples=max_samples),
-        run_config=RunConfig(callbacks=tuner_callbacks, storage_path=tune_dir),
-    )
+    if tune.Tuner.can_restore(tune_dir):
+        LOGGER.info(f"{colorstr('Tuner: ')} Resuming tuning run {tune_dir}...")
+        tuner = tune.Tuner.restore(str(tune_dir), trainable=trainable_with_resources, resume_errored=True)
+    else:
+        tuner = tune.Tuner(
+            trainable_with_resources,
+            param_space=space,
+            tune_config=tune.TuneConfig(scheduler=asha_scheduler, num_samples=max_samples),
+            run_config=RunConfig(callbacks=tuner_callbacks, storage_path=tune_dir.parent, name=tune_dir.name),
+        )
 
     # Run the hyperparameter search
     tuner.fit()

{ultralytics-8.3.101.dist-info → ultralytics-8.3.103.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ultralytics
-Version: 8.3.101
+Version: 8.3.103
 Summary: Ultralytics YOLO 🚀 for SOTA object detection, multi-object tracking, instance segmentation, pose estimation and image classification.
 Author-email: Glenn Jocher <glenn.jocher@ultralytics.com>, Jing Qiu <jing.qiu@ultralytics.com>
 Maintainer-email: Ultralytics <hello@ultralytics.com>
@@ -56,7 +56,6 @@ Requires-Dist: coverage[toml]; extra == "dev"
 Requires-Dist: mkdocs>=1.6.0; extra == "dev"
 Requires-Dist: mkdocs-material>=9.5.9; extra == "dev"
 Requires-Dist: mkdocstrings[python]; extra == "dev"
-Requires-Dist: mkdocs-redirects; extra == "dev"
 Requires-Dist: mkdocs-ultralytics-plugin>=0.1.17; extra == "dev"
 Requires-Dist: mkdocs-macros-plugin>=1.0.5; extra == "dev"
 Provides-Extra: export
@@ -71,8 +70,8 @@ Requires-Dist: keras; extra == "export"
 Requires-Dist: flatbuffers<100,>=23.5.26; platform_machine == "aarch64" and extra == "export"
 Requires-Dist: h5py!=3.11.0; platform_machine == "aarch64" and extra == "export"
 Provides-Extra: solutions
-Requires-Dist: shapely>=2.0.0; extra == "solutions"
-Requires-Dist: streamlit; extra == "solutions"
+Requires-Dist: shapely<2.1.0,>=2.0.0; extra == "solutions"
+Requires-Dist: streamlit<1.44.0,>=1.29.0; extra == "solutions"
 Provides-Extra: logging
 Requires-Dist: comet; extra == "logging"
 Requires-Dist: tensorboard>=2.13.0; extra == "logging"