altametris.sara.yolo.model
==========================

.. py:module:: altametris.sara.yolo.model

.. autoapi-nested-parse::

   YOLO model implementation.

   Wrapper around Ultralytics YOLO with standardized Altametris interface.
   Supports YOLOv8 and YOLO11 for detection, segmentation, OBB, and pose tasks.

   .. rubric:: Example

   >>> model = YoloModel(version="11", task="detect", size="x", pretrained=True)
   >>> x = torch.randn(1, 3, 640, 640)
   >>> output = model(x)



Attributes
----------

.. autoapisummary::

   altametris.sara.yolo.model.logger


Classes
-------

.. autoapisummary::

   altametris.sara.yolo.model.YoloModel


Module Contents
---------------

.. py:data:: logger

.. py:class:: YoloModel(model_path: Optional[Union[str, pathlib.Path]] = None, version: str = '11', task: str = 'detect', size: str = 'x', pretrained: bool = False, device: str = 'auto', **kwargs: Any)

   Bases: :py:obj:`altametris.sara.core.base_model.BaseModel`


   YOLO model wrapper implementing BaseModel interface.

   Provides standardized interface for YOLO models from Ultralytics
   with support for multiple versions, tasks, and sizes.

   :param model_path: Path to existing model weights (optional)
   :param version: YOLO version ("11" or "v8")
   :param task: YOLO task ("detect", "segment", "obb", "pose", "classify")
   :param size: Model size ("n", "s", "m", "l", "x")
   :param pretrained: Load pretrained weights from Ultralytics
   :param device: Device for model ("cpu", "cuda", "mps", "auto")

   .. rubric:: Example

   >>> # Create from scratch
   >>> model = YoloModel(version="11", task="detect", size="x")
   >>>
   >>> # Load from weights
   >>> model = YoloModel(model_path="weights/best.pt")


   .. py:attribute:: SUPPORTED_VERSIONS
      :value: ['11', 'v8']



   .. py:attribute:: SUPPORTED_TASKS
      :value: ['detect', 'segment', 'obb', 'pose', 'classify']



   .. py:attribute:: SUPPORTED_SIZES
      :value: ['n', 's', 'm', 'l', 'x']



   .. py:attribute:: yolo
      :type:  ultralytics.YOLO


   .. py:method:: _validate_init_params(version: str, task: str, size: str, model_path: Optional[Union[str, pathlib.Path]], pretrained: bool) -> None

      Validate initialization parameters.



   .. py:method:: _get_model_name(version: str, task: str, size: str) -> str

      Generate Ultralytics model name.

      :param version: YOLO version
      :param task: Task type
      :param size: Model size

      :returns: Model name string (e.g., "yolo11x-seg.pt")



   .. py:method:: forward(x: torch.Tensor, **kwargs: Any) -> Any

      Forward pass through YOLO model.

      :param x: Input tensor (B, C, H, W)
      :param \*\*kwargs: Additional forward arguments

      :returns: Model output

      .. rubric:: Example

      >>> x = torch.randn(1, 3, 640, 640)
      >>> output = model(x)



   .. py:method:: load_weights(path: Union[str, pathlib.Path], **kwargs: Any) -> None

      Load weights from file.

      :param path: Path to weights file
      :param \*\*kwargs: Additional loading arguments

      :raises ModelError: If weights cannot be loaded



   .. py:method:: save_weights(path: Union[str, pathlib.Path], **kwargs: Any) -> None

      Save model weights in Ultralytics checkpoint format.

      This method uses the native Ultralytics save() API which creates
      a complete checkpoint file compatible with YOLO loading.

      :param path: Path to save weights
      :param \*\*kwargs: Additional saving arguments

      .. rubric:: Example

      >>> model.save_weights("weights/my_model.pt")

      .. note::

         The saved file is a complete Ultralytics checkpoint that can be
         reloaded with YoloModel(model_path=path) or YOLO(path).



   .. py:property:: names
      :type: dict[int, str]


      Get class names mapping.


   .. py:property:: task
      :type: str


      Get model task.


   .. py:property:: version
      :type: str


      Get YOLO version.


   .. py:method:: __repr__() -> str

      String representation.