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

Vision task detector adapters

Select detector functions for VisionTaskStages. The DETECTORS dictionary maps marker, sample_roi, spincoater_pocket, and spincoater_sample to their adapters.

beambot.vision.vision_task_detection · Source

Perception and mapping · Guide · Symbol index

How it is used

VisionTaskStages calls get_detector() with the goal’s detector name, then passes a VisionTaskContext to the selected function. Marker and sample-ROI adapters return base-frame poses; spincoater adapters return image geometry for the joint-6 goal computer.

The DETECTORS table is the registration point for additional adapters. Keep acquisition and result format explicit: marker detection can reuse this engine’s cache or move through scan poses, while the current spincoater adapters always capture through Zivid.

Start here

Callable	Purpose
get_detector	Look up an exact detector name in the current dispatch table.
detect_marker	Use a cached marker pose first; otherwise choose multi-position or single-view marker detection.
detect_sample_roi	Ask the vision engine for a base-frame sample pickup pose near the goal’s anchor marker.
detect_spincoater_pocket	Capture a 2D image and run the spincoater pocket detector.
detect_spincoater_sample	Capture a 2D image and run the spincoater sample detector.

Functions

get_detector()

Look up an exact detector name in the current dispatch table.

Entry point · Source

get_detector(name: str)

Parameter	Meaning
name	One of marker, sample_roi, spincoater_pocket, or spincoater_sample.

Returns: The selected callable; it is not invoked here.

Errors: KeyError for unknown names, with the available names included in the message.

Side effects: None; no detector registration or capture occurs.

Referenced in source (1)

• VisionTaskStages.run — beambot.stages.vision_task_stages

detect_marker()

Use a cached marker pose first; otherwise choose multi-position or single-view marker detection.

Function · Source

detect_marker(ctx)

Parameter	Meaning
ctx	Vision context with vision engine, goal.tag_id/timeout, and optional scan_positions in joint radians.

Returns: A base_link PoseStamped or None. A cache hit returns immediately, even if scan positions were supplied.

Errors: Delegated detection/motion errors follow the VisionEngine behavior; this adapter adds no exception handler.

Side effects: May reuse stale process-local cache, capture images, update detection caches/TF, or move through scan poses when the multi-position path runs.

detect_sample_roi()

Ask the vision engine for a base-frame sample pickup pose near the goal’s anchor marker.

Function · Source

detect_sample_roi(ctx)

Parameter	Meaning
ctx	Vision context containing engine and goal fields tag_id, strategy, edge_inset_mm, and timeout.

Returns: PoseStamped in base_link, or None. An empty strategy becomes farthest_edge; zero inset is preserved.

Errors: Delegates failure handling to detect_and_transform_sample_roi(); no additional catch.

Side effects: Logs the request and can trigger camera acquisition and detection TF updates; this adapter itself adds no scan move.

detect_spincoater_pocket()

Capture a 2D image and run the spincoater pocket detector.

Function · Source

detect_spincoater_pocket(ctx)

Parameter	Meaning
ctx	Vision context used for Zivid capture and logging.

Returns: Detection dictionary with pocket geometry, angle, aspect, and solidity, or None.

Errors: A failed capture logs an error and returns None. Detector exceptions propagate.

Side effects: Triggers a physical camera capture and logs successful measurements; the sample path can lazily load YOLO weights.

detect_spincoater_sample()

Capture a 2D image and run the spincoater sample detector.

Function · Source

detect_spincoater_sample(ctx)

Parameter	Meaning
ctx	Vision context used for Zivid capture and logging.

Returns: Detection dictionary with sample geometry, angle, and confidence, or None.

Errors: A failed capture logs an error and returns None. Detector exceptions propagate.

Side effects: Triggers a physical camera capture and logs successful measurements; the sample path can lazily load YOLO weights.

Internal callbacks and helpers

_capture_2d_for_spincoater()

Capture a Zivid BGR image with a fixed 15-second budget.

Internal helper · Source

_capture_2d_for_spincoater(ctx)

Parameter	Meaning
ctx	Vision context whose engine supplies the ROS node and logger.

Returns: BGR array or None from camera.zivid.capture_2d().

Errors: Backend import and uncaught conversion errors propagate. Capture failures are represented by None.

Side effects: Lazily imports the Zivid helper, logs, and triggers /capture_2d regardless of the engine’s configured camera backend.

Referenced in source (2)

• detect_spincoater_pocket — beambot.vision.vision_task_detection
• detect_spincoater_sample — beambot.vision.vision_task_detection