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

ultralytics/models/yolo/detect/val.py

@@ -18,18 +18,40 @@ class DetectionValidator(BaseValidator):
     """
     A class extending the BaseValidator class for validation based on a detection model.
 
-    Example:
-        ```python
-        from ultralytics.models.yolo.detect import DetectionValidator
-
-        args = dict(model="yolo11n.pt", data="coco8.yaml")
-        validator = DetectionValidator(args=args)
-        validator()
-        ```
+    This class implements validation functionality specific to object detection tasks, including metrics calculation,
+    prediction processing, and visualization of results.
+
+    Attributes:
+        nt_per_class (np.ndarray): Number of targets per class.
+        nt_per_image (np.ndarray): Number of targets per image.
+        is_coco (bool): Whether the dataset is COCO.
+        is_lvis (bool): Whether the dataset is LVIS.
+        class_map (List): Mapping from model class indices to dataset class indices.
+        metrics (DetMetrics): Object detection metrics calculator.
+        iouv (torch.Tensor): IoU thresholds for mAP calculation.
+        niou (int): Number of IoU thresholds.
+        lb (List): List for storing ground truth labels for hybrid saving.
+        jdict (List): List for storing JSON detection results.
+        stats (Dict): Dictionary for storing statistics during validation.
+
+    Examples:
+        >>> from ultralytics.models.yolo.detect import DetectionValidator
+        >>> args = dict(model="yolo11n.pt", data="coco8.yaml")
+        >>> validator = DetectionValidator(args=args)
+        >>> validator()
     """
 
     def __init__(self, dataloader=None, save_dir=None, pbar=None, args=None, _callbacks=None):
-        """Initialize detection model with necessary variables and settings."""
+        """
+        Initialize detection validator with necessary variables and settings.
+
+        Args:
+            dataloader (torch.utils.data.DataLoader, optional): Dataloader to use for validation.
+            save_dir (Path, optional): Directory to save results.
+            pbar (Any, optional): Progress bar for displaying progress.
+            args (Dict, optional): Arguments for the validator.
+            _callbacks (List, optional): List of callback functions.
+        """
         super().__init__(dataloader, save_dir, pbar, args, _callbacks)
         self.nt_per_class = None
         self.nt_per_image = None
@@ -48,7 +70,15 @@ class DetectionValidator(BaseValidator):
             )
 
     def preprocess(self, batch):
-        """Preprocesses batch of images for YOLO training."""
+        """
+        Preprocess batch of images for YOLO validation.
+
+        Args:
+            batch (Dict): Batch containing images and annotations.
+
+        Returns:
+            (Dict): Preprocessed batch.
+        """
         batch["img"] = batch["img"].to(self.device, non_blocking=True)
         batch["img"] = (batch["img"].half() if self.args.half else batch["img"].float()) / 255
         for k in ["batch_idx", "cls", "bboxes"]:
@@ -66,7 +96,12 @@ class DetectionValidator(BaseValidator):
         return batch
 
     def init_metrics(self, model):
-        """Initialize evaluation metrics for YOLO."""
+        """
+        Initialize evaluation metrics for YOLO detection validation.
+
+        Args:
+            model (torch.nn.Module): Model to validate.
+        """
         val = self.data.get(self.args.split, "")  # validation path
         self.is_coco = (
             isinstance(val, str)
@@ -91,7 +126,15 @@ class DetectionValidator(BaseValidator):
         return ("%22s" + "%11s" * 6) % ("Class", "Images", "Instances", "Box(P", "R", "mAP50", "mAP50-95)")
 
     def postprocess(self, preds):
-        """Apply Non-maximum suppression to prediction outputs."""
+        """
+        Apply Non-maximum suppression to prediction outputs.
+
+        Args:
+            preds (torch.Tensor): Raw predictions from the model.
+
+        Returns:
+            (List[torch.Tensor]): Processed predictions after NMS.
+        """
         return ops.non_max_suppression(
             preds,
             self.args.conf,
@@ -106,7 +149,16 @@ class DetectionValidator(BaseValidator):
         )
 
     def _prepare_batch(self, si, batch):
-        """Prepares a batch of images and annotations for validation."""
+        """
+        Prepare a batch of images and annotations for validation.
+
+        Args:
+            si (int): Batch index.
+            batch (Dict): Batch data containing images and annotations.
+
+        Returns:
+            (Dict): Prepared batch with processed annotations.
+        """
         idx = batch["batch_idx"] == si
         cls = batch["cls"][idx].squeeze(-1)
         bbox = batch["bboxes"][idx]
@@ -119,7 +171,16 @@ class DetectionValidator(BaseValidator):
         return {"cls": cls, "bbox": bbox, "ori_shape": ori_shape, "imgsz": imgsz, "ratio_pad": ratio_pad}
 
     def _prepare_pred(self, pred, pbatch):
-        """Prepares a batch of images and annotations for validation."""
+        """
+        Prepare predictions for evaluation against ground truth.
+
+        Args:
+            pred (torch.Tensor): Model predictions.
+            pbatch (Dict): Prepared batch information.
+
+        Returns:
+            (torch.Tensor): Prepared predictions in native space.
+        """
         predn = pred.clone()
         ops.scale_boxes(
             pbatch["imgsz"], predn[:, :4], pbatch["ori_shape"], ratio_pad=pbatch["ratio_pad"]
@@ -127,7 +188,13 @@ class DetectionValidator(BaseValidator):
         return predn
 
     def update_metrics(self, preds, batch):
-        """Metrics."""
+        """
+        Update metrics with new predictions and ground truth.
+
+        Args:
+            preds (List[torch.Tensor]): List of predictions from the model.
+            batch (Dict): Batch data containing ground truth.
+        """
         for si, pred in enumerate(preds):
             self.seen += 1
             npr = len(pred)
@@ -176,12 +243,23 @@ class DetectionValidator(BaseValidator):
                 )
 
     def finalize_metrics(self, *args, **kwargs):
-        """Set final values for metrics speed and confusion matrix."""
+        """
+        Set final values for metrics speed and confusion matrix.
+
+        Args:
+            *args (Any): Variable length argument list.
+            **kwargs (Any): Arbitrary keyword arguments.
+        """
         self.metrics.speed = self.speed
         self.metrics.confusion_matrix = self.confusion_matrix
 
     def get_stats(self):
-        """Returns metrics statistics and results dictionary."""
+        """
+        Calculate and return metrics statistics.
+
+        Returns:
+            (Dict): Dictionary containing metrics results.
+        """
         stats = {k: torch.cat(v, 0).cpu().numpy() for k, v in self.stats.items()}  # to numpy
         self.nt_per_class = np.bincount(stats["target_cls"].astype(int), minlength=self.nc)
         self.nt_per_image = np.bincount(stats["target_img"].astype(int), minlength=self.nc)
@@ -191,7 +269,7 @@ class DetectionValidator(BaseValidator):
         return self.metrics.results_dict
 
     def print_results(self):
-        """Prints training/validation set metrics per class."""
+        """Print training/validation set metrics per class."""
         pf = "%22s" + "%11i" * 2 + "%11.3g" * len(self.metrics.keys)  # print format
         LOGGER.info(pf % ("all", self.seen, self.nt_per_class.sum(), *self.metrics.mean_results()))
         if self.nt_per_class.sum() == 0:
@@ -223,10 +301,6 @@ class DetectionValidator(BaseValidator):
 
         Returns:
             (torch.Tensor): Correct prediction matrix of shape (N, 10) for 10 IoU levels.
-
-        Note:
-            The function does not return any value directly usable for metrics calculation. Instead, it provides an
-            intermediate representation used for evaluating predictions against ground truth.
         """
         iou = box_iou(gt_bboxes, detections[:, :4])
         return self.match_predictions(detections[:, 5], gt_cls, iou)
@@ -238,17 +312,35 @@ class DetectionValidator(BaseValidator):
         Args:
             img_path (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.
+            batch (int, optional): Size of batches, this is for `rect`.
+
+        Returns:
+            (Dataset): YOLO dataset.
         """
         return build_yolo_dataset(self.args, img_path, batch, self.data, mode=mode, stride=self.stride)
 
     def get_dataloader(self, dataset_path, batch_size):
-        """Construct and return dataloader."""
+        """
+        Construct and return dataloader.
+
+        Args:
+            dataset_path (str): Path to the dataset.
+            batch_size (int): Size of each batch.
+
+        Returns:
+            (torch.utils.data.DataLoader): Dataloader for validation.
+        """
         dataset = self.build_dataset(dataset_path, batch=batch_size, mode="val")
         return build_dataloader(dataset, batch_size, self.args.workers, shuffle=False, rank=-1)  # return dataloader
 
     def plot_val_samples(self, batch, ni):
-        """Plot validation image samples."""
+        """
+        Plot validation image samples.
+
+        Args:
+            batch (Dict): Batch containing images and annotations.
+            ni (int): Batch index.
+        """
         plot_images(
             batch["img"],
             batch["batch_idx"],
@@ -261,7 +353,14 @@ class DetectionValidator(BaseValidator):
         )
 
     def plot_predictions(self, batch, preds, ni):
-        """Plots predicted bounding boxes on input images and saves the result."""
+        """
+        Plot predicted bounding boxes on input images and save the result.
+
+        Args:
+            batch (Dict): Batch containing images and annotations.
+            preds (List[torch.Tensor]): List of predictions from the model.
+            ni (int): Batch index.
+        """
         plot_images(
             batch["img"],
             *output_to_target(preds, max_det=self.args.max_det),
@@ -272,7 +371,15 @@ class DetectionValidator(BaseValidator):
         )  # pred
 
     def save_one_txt(self, predn, save_conf, shape, file):
-        """Save YOLO detections to a txt file in normalized coordinates in a specific format."""
+        """
+        Save YOLO detections to a txt file in normalized coordinates in a specific format.
+
+        Args:
+            predn (torch.Tensor): Predictions in the format (x1, y1, x2, y2, conf, class).
+            save_conf (bool): Whether to save confidence scores.
+            shape (tuple): Shape of the original image.
+            file (Path): File path to save the detections.
+        """
         from ultralytics.engine.results import Results
 
         Results(
@@ -283,7 +390,13 @@ class DetectionValidator(BaseValidator):
         ).save_txt(file, save_conf=save_conf)
 
     def pred_to_json(self, predn, filename):
-        """Serialize YOLO predictions to COCO json format."""
+        """
+        Serialize YOLO predictions to COCO json format.
+
+        Args:
+            predn (torch.Tensor): Predictions in the format (x1, y1, x2, y2, conf, class).
+            filename (str): Image filename.
+        """
         stem = Path(filename).stem
         image_id = int(stem) if stem.isnumeric() else stem
         box = ops.xyxy2xywh(predn[:, :4])  # xywh
@@ -299,7 +412,15 @@ class DetectionValidator(BaseValidator):
             )
 
     def eval_json(self, stats):
-        """Evaluates YOLO output in JSON format and returns performance statistics."""
+        """
+        Evaluate YOLO output in JSON format and return performance statistics.
+
+        Args:
+            stats (Dict): Current statistics dictionary.
+
+        Returns:
+            (Dict): Updated statistics dictionary with COCO/LVIS evaluation results.
+        """
         if self.args.save_json and (self.is_coco or self.is_lvis) and len(self.jdict):
             pred_json = self.save_dir / "predictions.json"  # predictions
             anno_json = (

ultralytics/models/yolo/model.py

@@ -93,7 +93,7 @@ class YOLOWorld(Model):
 
     def set_classes(self, classes):
         """
-        Set classes.
+        Set the model's class names for detection.
 
         Args:
             classes (List(str)): A list of categories i.e. ["person"].
@@ -106,6 +106,5 @@ class YOLOWorld(Model):
         self.model.names = classes
 
         # Reset method class names
-        # self.predictor = None  # reset predictor otherwise old names remain
         if self.predictor:
             self.predictor.model.names = classes

ultralytics/models/yolo/obb/predict.py

@@ -11,29 +11,34 @@ class OBBPredictor(DetectionPredictor):
     """
     A class extending the DetectionPredictor class for prediction based on an Oriented Bounding Box (OBB) model.
 
-    Example:
-        ```python
-        from ultralytics.utils import ASSETS
-        from ultralytics.models.yolo.obb import OBBPredictor
-
-        args = dict(model="yolo11n-obb.pt", source=ASSETS)
-        predictor = OBBPredictor(overrides=args)
-        predictor.predict_cli()
-        ```
+    This predictor handles oriented bounding box detection tasks, processing images and returning results with rotated
+    bounding boxes.
+
+    Attributes:
+        args (namespace): Configuration arguments for the predictor.
+        model (torch.nn.Module): The loaded YOLO OBB model.
+
+    Examples:
+        >>> from ultralytics.utils import ASSETS
+        >>> from ultralytics.models.yolo.obb import OBBPredictor
+        >>> args = dict(model="yolo11n-obb.pt", source=ASSETS)
+        >>> predictor = OBBPredictor(overrides=args)
+        >>> predictor.predict_cli()
     """
 
     def __init__(self, cfg=DEFAULT_CFG, overrides=None, _callbacks=None):
-        """Initializes OBBPredictor with optional model and data configuration overrides."""
+        """Initialize OBBPredictor with optional model and data configuration overrides."""
         super().__init__(cfg, overrides, _callbacks)
         self.args.task = "obb"
 
     def construct_result(self, pred, img, orig_img, img_path):
         """
-        Constructs the result object from the prediction.
+        Construct the result object from the prediction.
 
         Args:
-            pred (torch.Tensor): The predicted bounding boxes, scores, and rotation angles.
-            img (torch.Tensor): The image after preprocessing.
+            pred (torch.Tensor): The predicted bounding boxes, scores, and rotation angles with shape (N, 6) where
+                the last dimension contains [x, y, w, h, confidence, class_id, angle].
+            img (torch.Tensor): The image after preprocessing with shape (B, C, H, W).
             orig_img (np.ndarray): The original image before preprocessing.
             img_path (str): The path to the original image.
 

ultralytics/models/yolo/obb/train.py

@@ -11,14 +11,18 @@ class OBBTrainer(yolo.detect.DetectionTrainer):
     """
     A class extending the DetectionTrainer class for training based on an Oriented Bounding Box (OBB) model.
 
-    Example:
-        ```python
-        from ultralytics.models.yolo.obb import OBBTrainer
-
-        args = dict(model="yolo11n-obb.pt", data="dota8.yaml", epochs=3)
-        trainer = OBBTrainer(overrides=args)
-        trainer.train()
-        ```
+    Attributes:
+        loss_names (Tuple[str]): Names of the loss components used during training.
+
+    Methods:
+        get_model: Return OBBModel initialized with specified config and weights.
+        get_validator: Return an instance of OBBValidator for validation of YOLO model.
+
+    Examples:
+        >>> from ultralytics.models.yolo.obb import OBBTrainer
+        >>> args = dict(model="yolo11n-obb.pt", data="dota8.yaml", epochs=3)
+        >>> trainer = OBBTrainer(overrides=args)
+        >>> trainer.train()
     """
 
     def __init__(self, cfg=DEFAULT_CFG, overrides=None, _callbacks=None):

ultralytics/models/yolo/obb/val.py

@@ -14,14 +14,29 @@ class OBBValidator(DetectionValidator):
     """
     A class extending the DetectionValidator class for validation based on an Oriented Bounding Box (OBB) model.
 
-    Example:
-        ```python
-        from ultralytics.models.yolo.obb import OBBValidator
-
-        args = dict(model="yolo11n-obb.pt", data="dota8.yaml")
-        validator = OBBValidator(args=args)
-        validator(model=args["model"])
-        ```
+    This validator specializes in evaluating models that predict rotated bounding boxes, commonly used for aerial and
+    satellite imagery where objects can appear at various orientations.
+
+    Attributes:
+        args (Dict): Configuration arguments for the validator.
+        metrics (OBBMetrics): Metrics object for evaluating OBB model performance.
+        is_dota (bool): Flag indicating whether the validation dataset is in DOTA format.
+
+    Methods:
+        init_metrics: Initialize evaluation metrics for YOLO.
+        _process_batch: Process batch of detections and ground truth boxes to compute IoU matrix.
+        _prepare_batch: Prepare batch data for OBB validation.
+        _prepare_pred: Prepare predictions with scaled and padded bounding boxes.
+        plot_predictions: Plot predicted bounding boxes on input images.
+        pred_to_json: Serialize YOLO predictions to COCO json format.
+        save_one_txt: Save YOLO detections to a txt file in normalized coordinates.
+        eval_json: Evaluate YOLO output in JSON format and return performance statistics.
+
+    Examples:
+        >>> from ultralytics.models.yolo.obb import OBBValidator
+        >>> args = dict(model="yolo11n-obb.pt", data="dota8.yaml")
+        >>> validator = OBBValidator(args=args)
+        >>> validator(model=args["model"])
     """
 
     def __init__(self, dataloader=None, save_dir=None, pbar=None, args=None, _callbacks=None):
@@ -34,7 +49,7 @@ class OBBValidator(DetectionValidator):
         """Initialize evaluation metrics for YOLO."""
         super().init_metrics(model)
         val = self.data.get(self.args.split, "")  # validation path
-        self.is_dota = isinstance(val, str) and "DOTA" in val  # is COCO
+        self.is_dota = isinstance(val, str) and "DOTA" in val  # check if dataset is DOTA format
 
     def _process_batch(self, detections, gt_bboxes, gt_cls):
         """
@@ -51,13 +66,11 @@ class OBBValidator(DetectionValidator):
             (torch.Tensor): The correct prediction matrix with shape (N, 10), which includes 10 IoU (Intersection over
                 Union) levels for each detection, indicating the accuracy of predictions compared to the ground truth.
 
-        Example:
-            ```python
-            detections = torch.rand(100, 7)  # 100 sample detections
-            gt_bboxes = torch.rand(50, 5)  # 50 sample ground truth boxes
-            gt_cls = torch.randint(0, 5, (50,))  # 50 ground truth class labels
-            correct_matrix = OBBValidator._process_batch(detections, gt_bboxes, gt_cls)
-            ```
+        Examples:
+            >>> detections = torch.rand(100, 7)  # 100 sample detections
+            >>> gt_bboxes = torch.rand(50, 5)  # 50 sample ground truth boxes
+            >>> gt_cls = torch.randint(0, 5, (50,))  # 50 ground truth class labels
+            >>> correct_matrix = OBBValidator._process_batch(detections, gt_bboxes, gt_cls)
 
         Note:
             This method relies on `batch_probiou` to calculate IoU between detections and ground truth bounding boxes.
@@ -66,7 +79,7 @@ class OBBValidator(DetectionValidator):
         return self.match_predictions(detections[:, 5], gt_cls, iou)
 
     def _prepare_batch(self, si, batch):
-        """Prepares and returns a batch for OBB validation."""
+        """Prepare batch data for OBB validation with proper scaling and formatting."""
         idx = batch["batch_idx"] == si
         cls = batch["cls"][idx].squeeze(-1)
         bbox = batch["bboxes"][idx]
@@ -79,7 +92,7 @@ class OBBValidator(DetectionValidator):
         return {"cls": cls, "bbox": bbox, "ori_shape": ori_shape, "imgsz": imgsz, "ratio_pad": ratio_pad}
 
     def _prepare_pred(self, pred, pbatch):
-        """Prepares and returns a batch for OBB validation with scaled and padded bounding boxes."""
+        """Prepare predictions by scaling bounding boxes to original image dimensions."""
         predn = pred.clone()
         ops.scale_boxes(
             pbatch["imgsz"], predn[:, :4], pbatch["ori_shape"], ratio_pad=pbatch["ratio_pad"], xywh=True
@@ -87,7 +100,7 @@ class OBBValidator(DetectionValidator):
         return predn
 
     def plot_predictions(self, batch, preds, ni):
-        """Plots predicted bounding boxes on input images and saves the result."""
+        """Plot predicted bounding boxes on input images and save the result."""
         plot_images(
             batch["img"],
             *output_to_rotated_target(preds, max_det=self.args.max_det),
@@ -98,7 +111,7 @@ class OBBValidator(DetectionValidator):
         )  # pred
 
     def pred_to_json(self, predn, filename):
-        """Serialize YOLO predictions to COCO json format."""
+        """Convert YOLO predictions to COCO JSON format with rotated bounding box information."""
         stem = Path(filename).stem
         image_id = int(stem) if stem.isnumeric() else stem
         rbox = torch.cat([predn[:, :4], predn[:, -1:]], dim=-1)
@@ -115,7 +128,7 @@ class OBBValidator(DetectionValidator):
             )
 
     def save_one_txt(self, predn, save_conf, shape, file):
-        """Save YOLO detections to a txt file in normalized coordinates in a specific format."""
+        """Save YOLO detections to a txt file in normalized coordinates using the Results class."""
         import numpy as np
 
         from ultralytics.engine.results import Results
@@ -131,7 +144,7 @@ class OBBValidator(DetectionValidator):
         ).save_txt(file, save_conf=save_conf)
 
     def eval_json(self, stats):
-        """Evaluates YOLO output in JSON format and returns performance statistics."""
+        """Evaluate YOLO output in JSON format and save predictions in DOTA format."""
         if self.args.save_json and self.is_dota and len(self.jdict):
             import json
             import re

ultralytics/models/yolo/pose/predict.py

@@ -8,19 +8,26 @@ class PosePredictor(DetectionPredictor):
     """
     A class extending the DetectionPredictor class for prediction based on a pose model.
 
-    Example:
-        ```python
-        from ultralytics.utils import ASSETS
-        from ultralytics.models.yolo.pose import PosePredictor
-
-        args = dict(model="yolo11n-pose.pt", source=ASSETS)
-        predictor = PosePredictor(overrides=args)
-        predictor.predict_cli()
-        ```
+    This class specializes in pose estimation, handling keypoints detection alongside standard object detection
+    capabilities inherited from DetectionPredictor.
+
+    Attributes:
+        args (namespace): Configuration arguments for the predictor.
+        model (torch.nn.Module): The loaded YOLO pose model with keypoint detection capabilities.
+
+    Methods:
+        construct_result: Constructs the result object from the prediction, including keypoints.
+
+    Examples:
+        >>> from ultralytics.utils import ASSETS
+        >>> from ultralytics.models.yolo.pose import PosePredictor
+        >>> args = dict(model="yolo11n-pose.pt", source=ASSETS)
+        >>> predictor = PosePredictor(overrides=args)
+        >>> predictor.predict_cli()
     """
 
     def __init__(self, cfg=DEFAULT_CFG, overrides=None, _callbacks=None):
-        """Initializes PosePredictor, sets task to 'pose' and logs a warning for using 'mps' as device."""
+        """Initialize PosePredictor, set task to 'pose' and log a warning for using 'mps' as device."""
         super().__init__(cfg, overrides, _callbacks)
         self.args.task = "pose"
         if isinstance(self.args.device, str) and self.args.device.lower() == "mps":
@@ -31,19 +38,25 @@ class PosePredictor(DetectionPredictor):
 
     def construct_result(self, pred, img, orig_img, img_path):
         """
-        Constructs the result object from the prediction.
+        Construct the result object from the prediction, including keypoints.
+
+        This method extends the parent class implementation by extracting keypoint data from predictions
+        and adding them to the result object.
 
         Args:
-            pred (torch.Tensor): The predicted bounding boxes, scores, and keypoints.
-            img (torch.Tensor): The image after preprocessing.
-            orig_img (np.ndarray): The original image before preprocessing.
-            img_path (str): The path to the original image.
+            pred (torch.Tensor): The predicted bounding boxes, scores, and keypoints with shape (N, 6+K*D) where N is
+                the number of detections, K is the number of keypoints, and D is the keypoint dimension.
+            img (torch.Tensor): The processed input image tensor with shape (B, C, H, W).
+            orig_img (np.ndarray): The original unprocessed image as a numpy array.
+            img_path (str): The path to the original image file.
 
         Returns:
             (Results): The result object containing the original image, image path, class names, bounding boxes, and keypoints.
         """
         result = super().construct_result(pred, img, orig_img, img_path)
+        # Extract keypoints from prediction and reshape according to model's keypoint shape
         pred_kpts = pred[:, 6:].view(len(pred), *self.model.kpt_shape) if len(pred) else pred[:, 6:]
+        # Scale keypoints coordinates to match the original image dimensions
         pred_kpts = ops.scale_coords(img.shape[2:], pred_kpts, orig_img.shape)
         result.update(keypoints=pred_kpts)
         return result

ultralytics/models/yolo/pose/train.py

@@ -10,16 +10,29 @@ from ultralytics.utils.plotting import plot_images, plot_results
 
 class PoseTrainer(yolo.detect.DetectionTrainer):
     """
-    A class extending the DetectionTrainer class for training based on a pose model.
+    A class extending the DetectionTrainer class for training YOLO pose estimation models.
 
-    Example:
-        ```python
-        from ultralytics.models.yolo.pose import PoseTrainer
+    This trainer specializes in handling pose estimation tasks, managing model training, validation, and visualization
+    of pose keypoints alongside bounding boxes.
 
-        args = dict(model="yolo11n-pose.pt", data="coco8-pose.yaml", epochs=3)
-        trainer = PoseTrainer(overrides=args)
-        trainer.train()
-        ```
+    Attributes:
+        args (Dict): Configuration arguments for training.
+        model (PoseModel): The pose estimation model being trained.
+        data (Dict): Dataset configuration including keypoint shape information.
+        loss_names (Tuple[str]): Names of the loss components used in training.
+
+    Methods:
+        get_model: Retrieves a pose estimation model with specified configuration.
+        set_model_attributes: Sets keypoints shape attribute on the model.
+        get_validator: Creates a validator instance for model evaluation.
+        plot_training_samples: Visualizes training samples with keypoints.
+        plot_metrics: Generates and saves training/validation metric plots.
+
+    Examples:
+        >>> from ultralytics.models.yolo.pose import PoseTrainer
+        >>> args = dict(model="yolo11n-pose.pt", data="coco8-pose.yaml", epochs=3)
+        >>> trainer = PoseTrainer(overrides=args)
+        >>> trainer.train()
     """
 
     def __init__(self, cfg=DEFAULT_CFG, overrides=None, _callbacks=None):