imgutils.generic.yoloseg

YOLO Segmentation Module for Image Processing

This module provides functionality for YOLO-based segmentation models, allowing users to perform instance segmentation on images. It includes classes and functions for loading models from Hugging Face repositories, making predictions, and creating interactive demos.

The module supports both online and offline operations, with thread-safe model loading and execution. It handles various image formats and provides utilities for pre-processing and post-processing segmentation results.

YOLOSegmentationModel

class imgutils.generic.yoloseg.YOLOSegmentationModel(repo_id: str, hf_token: str | None = None)[source]

YOLO-based segmentation model loaded from Hugging Face repositories.

This class provides functionality for loading YOLO segmentation models from Hugging Face, making predictions, and creating interactive UIs for model demonstration.

Parameters:

repo_id (str) – Hugging Face repository ID containing the YOLO segmentation models.
hf_token (Optional[str]) – Hugging Face API token for accessing private repositories. If None, will try to use the HF_TOKEN environment variable.

__init__(repo_id: str, hf_token: str | None = None)[source]

Initialize a YOLO segmentation model.

Parameters:

repo_id (str) – Hugging Face repository ID containing the YOLO segmentation models.
hf_token (Optional[str]) – Hugging Face API token for accessing private repositories. If None, will try to use the HF_TOKEN environment variable.

clear()[source]

Clear all cached models and metadata.

This method resets the model cache, forcing new model loads on subsequent operations. It’s useful for freeing memory or when switching between different models.

launch_demo(default_model_name: str | None = None, default_conf_threshold: float = 0.25, default_iou_threshold: float = 0.7, server_name: str | None = None, server_port: int | None = None, **kwargs)[source]

Launch a Gradio demo for object detection.

This method creates and launches a Gradio demo that allows users to interactively perform object detection on uploaded images using the YOLO model.

Parameters:

default_model_name (Optional[str]) – The name of the default model to use. If None, the most recently updated model is selected.
default_conf_threshold (float) – Default confidence threshold for the demo. Default is 0.25.
default_iou_threshold (float) – Default IoU threshold for the demo. Default is 0.7.
server_name (Optional[str]) – The name of the server to run the demo on. Default is None.
server_port (Optional[int]) – The port to run the demo on. Default is None.
kwargs – Additional keyword arguments to pass to gr.Blocks.launch().

Raises:

EnvironmentError – If Gradio is not installed in the environment, or if in OFFLINE mode and no default_model_name is provided.

Example:

>>> model = YOLOSegmentationModel("username/repo_name")
>>> model.launch_demo(default_model_name="yolov8s-seg", server_name="0.0.0.0", server_port=7860)

make_ui(default_model_name: str | None = None, default_conf_threshold: float = 0.25, default_iou_threshold: float = 0.7)[source]

Create a Gradio-based user interface for object detection.

This method sets up an interactive UI that allows users to upload images, select models, and adjust detection parameters. It uses the Gradio library to create the interface.

Parameters:

default_model_name (Optional[str]) – The name of the default model to use. If None, the most recently updated model is selected.
default_conf_threshold (float) – Default confidence threshold for the UI. Default is 0.25.
default_iou_threshold (float) – Default IoU threshold for the UI. Default is 0.7.

Raises:

ImportError – If Gradio is not installed in the environment.
EnvironmentError – If in OFFLINE mode and no default_model_name is provided.

Example:

>>> model = YOLOSegmentationModel("username/repo_name")
>>> model.make_ui(default_model_name="yolov8s-seg")

property model_names: List[str]

Get the list of available model names in the repository.

This property performs a glob search in the Hugging Face repository to find all ONNX models. The search is thread-safe and implements caching to avoid repeated filesystem operations. Results are normalized to provide consistent path formats.

Returns:: List of available model names in the repository. Returns _OFFLINE list if offline mode is enabled or connection errors occur.
Return type:: List[str]

Perform segmentation prediction on an image.

Parameters:

image (ImageTyping) – Input image to perform segmentation on.
model_name (str) – Name of the model to use for prediction.
conf_threshold (float) – Confidence threshold for filtering detections (0.0-1.0).
iou_threshold (float) – IoU threshold for non-maximum suppression (0.0-1.0).
allow_dynamic (bool) – Whether to allow dynamic resizing of the input image.

Returns:

List of detections, each containing bounding box, class label, confidence score, and mask.

Return type:

List[Tuple[Tuple[int, int, int, int], str, float, numpy.ndarray]]

Raises:

ValueError – If the model type is unknown.

Example:

>>> model = YOLOSegmentationModel("username/repo_name")
>>> results = model.predict(
...     image="path/to/image.jpg",
...     model_name="yolov8s-seg",
...     conf_threshold=0.3
... )
>>> for bbox, label, confidence, mask in results:
...     print(f"Found {label} with confidence {confidence:.2f}")

yolo_seg_predict

imgutils.generic.yoloseg.yolo_seg_predict(image: str | PathLike | bytes | bytearray | BinaryIO | Image, repo_id: str, model_name: str, conf_threshold: float = 0.25, iou_threshold: float = 0.7, hf_token: str | None = None, **kwargs) → List[Tuple[Tuple[int, int, int, int], str, float, ndarray]][source]

Perform YOLO segmentation prediction using a model from Hugging Face.

This is a convenience function that creates a YOLOSegmentationModel instance and performs prediction in one step.

Parameters:

image (ImageTyping) – Input image to perform segmentation on.
repo_id (str) – Hugging Face repository ID containing the model.
model_name (str) – Name of the specific model to use.
conf_threshold (float) – Confidence threshold for filtering detections (0.0-1.0).
iou_threshold (float) – IoU threshold for non-maximum suppression (0.0-1.0).
hf_token (Optional[str]) – Hugging Face API token for accessing private repositories.
kwargs – Additional keyword arguments to pass to the predict method.

Returns:

List of detections, each containing bounding box, class label, confidence score, and mask.

Return type:

List[Tuple[Tuple[int, int, int, int], str, float, numpy.ndarray]]

Example:

>>> results = yolo_seg_predict(
...     image="path/to/image.jpg",
...     repo_id="username/repo_name",
...     model_name="yolov8s-seg",
...     conf_threshold=0.3
... )
>>> for bbox, label, confidence, mask in results:
...     print(f"Found {label} with confidence {confidence:.2f}")