altametris.sara.yolo.utils¶

YOLO utility functions.

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

Example

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

Attributes¶

logger

Functions¶

`get_device`(→ str)	Get optimal device for YOLO inference/training.
`resolve_device_for_ultralytics`(→ str)	Convert Altametris device format to Ultralytics-compatible format.
`validate_imgsz`(→ Union[int, tuple[int, int]])	Validate image size parameter.
`validate_confidence`(→ float)	Validate confidence threshold.
`validate_iou`(→ float)	Validate IoU threshold.
`load_config`(→ Dict[str, Any])	Load and parse YAML configuration file.
`format_results`(→ Any)	Format YOLO results to specified format.
`get_model_info`(→ dict[str, Any])	Get information about a YOLO model file.
`calculate_metrics`(→ dict[str, Any])	Calculate metrics from YOLO results.

Module Contents¶

altametris.sara.yolo.utils.logger¶

altametris.sara.yolo.utils.get_device(device: str = 'auto') → str¶

Get optimal device for YOLO inference/training.

Parameters:: device – Device preference (“auto”, “cpu”, “cuda”, “mps”, or device index)
Returns:: Device string compatible with Ultralytics

Example

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

altametris.sara.yolo.utils.resolve_device_for_ultralytics(device: 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)

Parameters:: device – Device specification (str or int)
Returns:: Device string compatible with Ultralytics (e.g., ‘cpu’, ‘0’, ‘mps’)

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.

altametris.sara.yolo.utils.validate_imgsz(imgsz: int | tuple[int, int]) → int | tuple[int, int]¶

Validate image size parameter.

Parameters:: imgsz – Image size (single int or (height, width))
Returns:: Validated image size
Raises:: ConfigurationError – If image size is invalid

Example

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

altametris.sara.yolo.utils.validate_confidence(conf: float) → float¶

Validate confidence threshold.

Parameters:: conf – Confidence threshold
Returns:: Validated confidence
Raises:: ConfigurationError – If confidence is invalid

Example

>>> validate_confidence(0.5)  # 0.5

altametris.sara.yolo.utils.validate_iou(iou: float) → float¶

Validate IoU threshold.

Parameters:: iou – IoU threshold
Returns:: Validated IoU
Raises:: ConfigurationError – If IoU is invalid

Example

>>> validate_iou(0.45)  # 0.45

altametris.sara.yolo.utils.load_config(config_path: 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).

Parameters:: config_path – Path to YAML configuration file
Returns:: Dictionary containing parsed configuration
Raises:: TrainingError – If config file not found or invalid YAML

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']

altametris.sara.yolo.utils.format_results(results: Any, format: str = 'dict') → Any¶

Format YOLO results to specified format.

Parameters:

results – Ultralytics Results object
format – Output format (“dict”, “json”, “pandas”)

Returns:

Formatted results

Example

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

altametris.sara.yolo.utils.get_model_info(model_path: str | pathlib.Path) → dict[str, Any]¶

Get information about a YOLO model file.

Parameters:: model_path – Path to model file
Returns:: Model information dictionary

Example

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

altametris.sara.yolo.utils.calculate_metrics(results: Any, metric_type: str = 'auto') → dict[str, Any]¶

Calculate metrics from YOLO results.

Parameters:

results – Ultralytics Results object
metric_type – Type of metrics (“auto”, “detection”, “segmentation”) “auto” will auto-detect based on available attributes

Returns:

Dictionary of calculated metrics

Example

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