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

Spincoater image detection

Classical pocket detection and YOLO segmentation for a red-painted spincoater chuck. Functions consume supplied flash-lit BGR images; the camera adapter performs acquisition. Segmentation weights are loaded lazily from the installed beambot package share directory.

beambot.vision.detection.spincoater_detection · Source

Perception and mapping · Guide · Symbol index

How it is used

The vision-task adapters acquire a Zivid 2D image and pass it to these detectors. detect_spincoater_pocket() uses color and shape filters; detect_spincoater_sample() uses segmentation weights loaded on first use. Both return image geometry, including the square-feature angle used by joint-6 target computation.

Inputs are supplied BGR images of the red-painted chuck. These functions perform image processing/inference only; acquisition and robot motion belong to their callers.

Start here

Callable	Purpose
detect_spincoater_pocket	Find a bright, low-saturation rectangular pocket inside the largest red chuck field.
detect_spincoater_sample	Run segmentation and fit a minimum-area rectangle to the highest-confidence sample mask in a result.

Functions

detect_spincoater_pocket()

Find a bright, low-saturation rectangular pocket inside the largest red chuck field.

Function · Source

detect_spincoater_pocket(
    image: np.ndarray,
    min_area: int = 1200,
    max_aspect: float = 1.25,
    min_solidity: float = 0.85,
) -> dict | None

Parameter	Meaning
image	Flash-lit BGR image with the chuck visible near the image center.
min_area	Minimum contour area in square pixels.
max_aspect	Strict upper bound on fitted rectangle aspect ratio.
min_solidity	Strict lower bound on contour area divided by convex-hull area.

Returns: First accepted contour in descending area order, as a dictionary with center_px, angle_mod90 (degrees in [0,90)), width/height (pixels), aspect, solidity, and area; or None.

Errors: Missing red field or no accepted bright contour returns None. Invalid images/OpenCV errors propagate; thresholds are not range-validated.

Side effects: Allocates masks and contour geometry without writing the input image.

detect_spincoater_sample()

Run segmentation and fit a minimum-area rectangle to the highest-confidence sample mask in a result.

Function · Source

detect_spincoater_sample(image: np.ndarray, confidence: float=0.3) -> dict | None

Parameter	Meaning
image	Flash-lit BGR image passed to the model.
confidence	Minimum inference confidence forwarded to Ultralytics; conventionally 0–1, without local range validation.

Returns: Dictionary containing center_px, angle_mod90, angle_raw, width, height, aspect, confidence, and mask_points; or None. The centroid uses polygon moments with rectangle-center fallback.

Errors: Results without masks or with fewer than four polygon points are skipped. It does not try lower-confidence masks from the same result after rejecting the best one. Model/inference/conversion errors propagate.

Side effects: May load cached weights and run CPU/GPU inference; no camera trigger, file write, or robot action.

Internal callbacks and helpers

_red_mask()

Combine two red HSV hue ranges around the OpenCV hue wraparound.

Internal helper · Source

_red_mask(hsv: np.ndarray) -> np.ndarray

Parameter	Meaning
hsv	OpenCV HSV image with hue in the 0–179 convention.

Returns: Combined uint8 mask from hue ranges 0–14 and 166–179, saturation at least 60, and value at least 40.

Errors: OpenCV errors propagate; input shape/type is not checked.

Side effects: Allocates masks; leaves the input unchanged.

Referenced in source (2)

• _locate_chuck — beambot.vision.detection.spincoater_detection
• detect_spincoater_pocket — beambot.vision.detection.spincoater_detection

_locate_chuck()

Find the largest cleaned red region and derive its centroid and a surrounding crop size.

Internal helper · Source

_locate_chuck(image: np.ndarray) -> tuple[int, int, int] | None

Parameter	Meaning
image	BGR image used to locate the red chuck field.

Returns: (center_x, center_y, half_roi_size) as pixel integers; half-size is at least 120. Returns None if no contour or its zeroth moment is zero.

Errors: OpenCV/image errors propagate.

Side effects: Creates HSV/morphology masks and contour data; no capture or model load.

Referenced in source (1)

• detect_spincoater_pocket — beambot.vision.detection.spincoater_detection

_get_sample_model()

Load the spincoater segmentation weights once, using a double-checked lock for concurrent first use.

Internal helper · Source

_get_sample_model()

Returns: Cached Ultralytics YOLO model.

Errors: RuntimeError if ultralytics is missing; FileNotFoundError if the installed beambot share directory lacks models/spincoater_sample_seg.pt. Package lookup and model construction errors propagate.

Side effects: On first load imports Ultralytics, resolves the installed beambot package share path, reads weights, allocates model resources and updates the singleton under _sample_model_lock.

Referenced in source (1)

• detect_spincoater_sample — beambot.vision.detection.spincoater_detection