altametris.sara.yolo.utils
==========================

.. py:module:: altametris.sara.yolo.utils

.. autoapi-nested-parse::

   YOLO utility functions.

   Helper functions for YOLO model configuration, validation,
   and common operations.

   .. rubric:: Example

   >>> device = get_device()
   >>> validate_imgsz(640)
   >>> conf = load_config("dataset.yaml")



Attributes
----------

.. autoapisummary::

   altametris.sara.yolo.utils.logger


Functions
---------

.. autoapisummary::

   altametris.sara.yolo.utils.get_device
   altametris.sara.yolo.utils.resolve_device_for_ultralytics
   altametris.sara.yolo.utils.validate_imgsz
   altametris.sara.yolo.utils.validate_confidence
   altametris.sara.yolo.utils.validate_iou
   altametris.sara.yolo.utils.load_config
   altametris.sara.yolo.utils.format_results
   altametris.sara.yolo.utils.get_model_info
   altametris.sara.yolo.utils.calculate_metrics


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

.. py:data:: logger

.. py:function:: get_device(device: str = 'auto') -> str

   Get optimal device for YOLO inference/training.

   :param device: Device preference ("auto", "cpu", "cuda", "mps", or device index)

   :returns: Device string compatible with Ultralytics

   .. rubric:: Example

   >>> device = get_device()  # "cuda" if available
   >>> device = get_device("cpu")  # "cpu"


.. py:function:: resolve_device_for_ultralytics(device: Union[str, int]) -> str

   Convert Altametris device format to Ultralytics-compatible format.

   Ultralytics does not support 'auto' device. It requires explicit
   device specification: 'cpu', '0', '1', etc.

   Conversion rules:
       - 'auto' -> 'cpu' (if no GPU) or '0' (if GPU available)
       - 'cuda' -> '0' (first GPU)
       - 'cuda:0' -> '0' (extract GPU index)
       - 'cpu' -> 'cpu' (unchanged)
       - 'mps' -> 'mps' (Apple Silicon)

   :param device: Device specification (str or int)

   :returns: Device string compatible with Ultralytics (e.g., 'cpu', '0', 'mps')

   .. rubric:: Example

   >>> resolve_device_for_ultralytics('auto')  # '0' if GPU, else 'cpu'
   >>> resolve_device_for_ultralytics('cuda')  # '0'
   >>> resolve_device_for_ultralytics('cuda:2')  # '2'

   .. note::

      This function checks actual GPU availability using torch.cuda.device_count()
      to avoid errors when CUDA is installed but no GPU is present.


.. py:function:: validate_imgsz(imgsz: Union[int, tuple[int, int]]) -> Union[int, tuple[int, int]]

   Validate image size parameter.

   :param imgsz: Image size (single int or (height, width))

   :returns: Validated image size

   :raises ConfigurationError: If image size is invalid

   .. rubric:: Example

   >>> validate_imgsz(640)  # 640
   >>> validate_imgsz((640, 640))  # (640, 640)


.. py:function:: validate_confidence(conf: float) -> float

   Validate confidence threshold.

   :param conf: Confidence threshold

   :returns: Validated confidence

   :raises ConfigurationError: If confidence is invalid

   .. rubric:: Example

   >>> validate_confidence(0.5)  # 0.5


.. py:function:: validate_iou(iou: float) -> float

   Validate IoU threshold.

   :param iou: IoU threshold

   :returns: Validated IoU

   :raises ConfigurationError: If IoU is invalid

   .. rubric:: Example

   >>> validate_iou(0.45)  # 0.45


.. py:function:: load_config(config_path: Union[str, pathlib.Path]) -> Dict[str, Any]

   Load and parse YAML configuration file.

   Supports both dataset configuration files (data.yaml) and
   training parameter files (train-params.yaml).

   :param config_path: Path to YAML configuration file

   :returns: Dictionary containing parsed configuration

   :raises TrainingError: If config file not found or invalid YAML

   .. rubric:: Example

   >>> # Load dataset config
   >>> dataset_config = load_config("data/detect/config.yml")
   >>> print(dataset_config['names'])
   {0: 'Chassis A', 1: 'Chassis C', ...}

   >>> # Load training params
   >>> train_params = load_config("data/detect/train-parameter-detect.yaml")
   >>> epochs = train_params['train']['epochs']


.. py:function:: format_results(results: Any, format: str = 'dict') -> Any

   Format YOLO results to specified format.

   :param results: Ultralytics Results object
   :param format: Output format ("dict", "json", "pandas")

   :returns: Formatted results

   .. rubric:: Example

   >>> formatted = format_results(results, format="dict")


.. py:function:: get_model_info(model_path: Union[str, pathlib.Path]) -> dict[str, Any]

   Get information about a YOLO model file.

   :param model_path: Path to model file

   :returns: Model information dictionary

   .. rubric:: Example

   >>> info = get_model_info("yolo11x.pt")
   >>> print(info["task"])  # "detect"


.. py:function:: calculate_metrics(results: Any, metric_type: str = 'auto') -> dict[str, Any]

   Calculate metrics from YOLO results.

   :param results: Ultralytics Results object
   :param metric_type: Type of metrics ("auto", "detection", "segmentation")
                       "auto" will auto-detect based on available attributes

   :returns: Dictionary of calculated metrics

   .. rubric:: Example

   >>> metrics = calculate_metrics(results)  # Auto-detect
   >>> print(metrics["mAP50"])