Work in progress: this documentation is still being written and reviewed. Check details against the source code.

YOLO object detection

Detect and annotate objects in supplied images with a lazily loaded Ultralytics model.

beambot.vision.detection.yolo_object_detection · Source

Perception and mapping · Guide · Symbol index

How it is used

Use get_detector() to reuse the module’s detector, then call detect() with a BGR image. Results include class, confidence, center, and bounding-box coordinates; annotate() draws those results on an image copy.

YoloDetectionParams controls inference thresholds and model selection. Construct YoloDetector directly when an independent model/device instance is needed. These helpers do not capture images or invoke robot motion.

Related data types:

  • YoloDetectionParams: Inference options including model path, confidence, IoU threshold, class filter, and detection limit.

Start here

Callable

Purpose

get_detector

Reuse the module-level detector when its configured model path matches, otherwise replace it.

YoloDetector.detect

Run object detection and return boxes sorted by descending confidence.

YoloDetector.annotate

Draw numbered boxes, confidence labels, and center points on a copy of an image.

Functions

get_detector()

Reuse the module-level detector when its configured model path matches, otherwise replace it.

Entry point · Source

get_detector(model_path: str=DEFAULT_MODEL) -> YoloDetector

Parameter

Meaning

model_path

Weight-file path or model name compared as a string.

Returns: YoloDetector singleton for the requested path. Weights remain lazy until detection is used.

Errors: No validation or loading is performed here.

Side effects: Reads or replaces the module singleton. A subsequent detect(image) with params=None retains the requested model path.

YoloDetector

Image detector that loads its model lazily and reuses it between calls. Callers supply BGR images; annotate() provides an optional visualization of returned boxes.

YoloDetector.detect()

Run object detection and return boxes sorted by descending confidence.

Method · Source

detect(
    self,
    image: np.ndarray,
    params: YoloDetectionParams | None = None,
) -> list[YoloDetection]

Parameter

Meaning

image

BGR image array passed directly to Ultralytics without color conversion.

params

Optional YoloDetectionParams. None retains the detector’s current model path and uses default inference thresholds. An explicit params.model_path can replace the model; confidence, iou_threshold, classes and max_detections are forwarded.

Returns: List of (class_name, confidence, center_x, center_y, x1, y1, x2, y2) tuples. Pixel coordinates are Python ints and confidence is float. Empty/no-box results give an empty list.

Errors: Model/inference/output-conversion errors propagate; the wrapper does not validate thresholds or image shape.

Side effects: May discard/reload the cached model when params.model_path changes and perform CPU/GPU inference. The supplied image is passed to the backend without a defensive copy.

YoloDetector.annotate()

Draw numbered boxes, confidence labels, and center points on a copy of an image.

Method · Source

annotate(self, image: np.ndarray, detections: list[YoloDetection]) -> np.ndarray

Parameter

Meaning

image

BGR array copied before drawing.

detections

Detection tuples in the order to number, normally from detect().

Returns: New annotated image array; the input image is not drawn on.

Errors: Tuple-shape and OpenCV drawing errors propagate.

Side effects: Allocates an image copy; performs no model loading or file write.

YoloDetector.__init__()

Store model/device preferences without loading weights.

Lifecycle · Source

__init__(self, model_path: str=DEFAULT_MODEL, device: str='')

Parameter

Meaning

model_path

Weight-file path or Ultralytics model name.

device

Device string used during model loading; empty leaves backend selection unchanged.

Returns: None; initializes the instance.

Errors: No validation or model loading occurs here.

Side effects: Stores preferences and sets _model=None.

Referenced in source (1)
  • get_detector — beambot.vision.detection.yolo_object_detection

Internal callbacks and helpers

YoloDetector._ensure_model()

Load weights once and optionally move the model to the constructor-selected device.

Internal helper · Source

_ensure_model(self)

Returns: None; the loaded model is stored on the instance.

Errors: Missing ultralytics raises RuntimeError. Weight lookup/loading/device errors propagate. A missing non-yolo-prefixed path is also checked under ~/.beambot/models.

Side effects: Imports Ultralytics and loads a model, which may download named weights and allocate CPU/GPU resources; logs model details.

Referenced in source (1)