altametris.sara.yolo.detector
=============================

.. py:module:: altametris.sara.yolo.detector

.. autoapi-nested-parse::

   YOLO detector implementation.

   Provides inference interface for YOLO models with standardized
   input/output format and batch processing support.

   .. rubric:: Example

   >>> detector = YoloDetector(model_path="weights/best.pt", task="detect")
   >>> results = detector.predict(source="image.jpg", conf=0.25)



Attributes
----------

.. autoapisummary::

   altametris.sara.yolo.detector.logger


Classes
-------

.. autoapisummary::

   altametris.sara.yolo.detector.YoloDetector


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

.. py:data:: logger

.. py:class:: YoloDetector(model_path: Union[str, pathlib.Path], task: str = 'detect', device: str = 'auto', warmup: bool = True, **kwargs: Any)

   Bases: :py:obj:`altametris.sara.core.base_detector.BaseDetector`


   YOLO detector implementing BaseDetector interface.

   Provides inference capabilities with support for images, videos,
   and batch processing.

   :param model_path: Path to YOLO model weights
   :param task: YOLO task ("detect", "segment", "obb", "pose")
   :param device: Inference device
   :param warmup: Run warmup on initialization

   .. rubric:: Example

   >>> detector = YoloDetector(model_path="yolo11x.pt", device="cuda")
   >>> results = detector.predict("image.jpg", conf=0.5, imgsz=640)


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



   .. py:attribute:: task
      :value: 'detect'



   .. py:attribute:: model
      :type:  ultralytics.YOLO


   .. py:method:: _load_model(model_path: pathlib.Path, **kwargs: Any) -> None

      Load YOLO model from path.

      :param model_path: Path to model file
      :param \*\*kwargs: Additional loading arguments

      :raises ModelError: If model cannot be loaded



   .. py:method:: _validate_predict_params(conf: float, iou: float, imgsz: int) -> None

      Validate prediction parameters before inference.

      :param conf: Confidence threshold
      :param iou: IoU threshold
      :param imgsz: Image size

      :raises ConfigurationError: If parameters are invalid



   .. py:method:: predict(source: Union[str, pathlib.Path, numpy.typing.NDArray[numpy.uint8], PIL.Image.Image, List[Any]], conf: float = 0.25, iou: float = 0.45, imgsz: int = 640, verbose: bool = False, **kwargs: Any) -> Any

      Run inference on source.

      :param source: Input source (image path, array, PIL Image, or list)
      :param conf: Confidence threshold
      :param iou: IoU threshold for NMS
      :param imgsz: Input image size
      :param verbose: Verbose output
      :param \*\*kwargs: Additional inference arguments

      :returns: Ultralytics Results object(s)

      :raises ConfigurationError: If parameters (conf, iou, imgsz) are invalid
      :raises InferenceError: If prediction fails

      .. rubric:: Example

      >>> # Single image
      >>> results = detector.predict("image.jpg", conf=0.5)
      >>>
      >>> # Batch of images
      >>> results = detector.predict(["img1.jpg", "img2.jpg"], conf=0.5)
      >>>
      >>> # NumPy array
      >>> img : NDArray[np.uint8] = np.random.rand(640, 640, 3).astype(np.uint8)
      >>> results = detector.predict(img, conf=0.5)



   .. py:method:: predict_batch(sources: List[Union[str, pathlib.Path, numpy.typing.NDArray[numpy.uint8]]], batch_size: int = 32, **kwargs: Any) -> List[Any]

      Run batch inference on multiple sources.

      :param sources: List of input sources
      :param batch_size: Batch size for processing
      :param \*\*kwargs: Additional inference arguments

      :returns: List of results for each source

      .. rubric:: Example

      >>> images = ["img1.jpg", "img2.jpg", "img3.jpg"]
      >>> results = detector.predict_batch(images, batch_size=8)



   .. py:method:: warmup(iterations: int = 3, imgsz: int = 640) -> None

      Warmup model with dummy inference.

      :param iterations: Number of warmup iterations
      :param imgsz: Image size for warmup

      .. rubric:: Example

      >>> detector.warmup(iterations=5, imgsz=640)



   .. py:method:: get_names() -> dict[int, str]

      Get class names mapping.

      :returns: Dictionary mapping class IDs to names

      .. rubric:: Example

      >>> names = detector.get_names()
      >>> print(names[0])  # 'person'



   .. py:property:: num_classes
      :type: int


      Get number of classes.


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

      String representation.