bambuddy/backend/app/services/plate_detection.py

"""Build plate empty detection using OpenCV.

Analyzes camera frames to detect if there are objects on the build plate.
Uses calibration-based difference detection - compares current frame to
a reference image of the empty plate.
"""

from __future__ import annotations

import logging
import os
import re
from pathlib import Path

logger = logging.getLogger(__name__)

# Optional OpenCV import - feature disabled if not available
try:
    import cv2
    import numpy as np

    OPENCV_AVAILABLE = True
except ImportError:
    OPENCV_AVAILABLE = False
    logger.info("OpenCV not available - plate detection feature disabled")


def _get_calibration_dir() -> Path:
    """Get the calibration directory from settings (ensures persistence in Docker)."""
    from backend.app.core.config import settings

    return settings.plate_calibration_dir


_REFERENCE_FILE = re.compile(r"printer_(\d+)_(?:ref_\d+\.jpg|metadata\.json)")


def _reference_files() -> list[tuple[int, Path]]:
    directory = _get_calibration_dir()
    if not directory.is_dir():
        return []
    return [
        (int(m[1]), path) for path in directory.iterdir() if (m := _REFERENCE_FILE.fullmatch(path.name)) is not None
    ]


def _remove(path: Path) -> None:
    try:
        path.unlink()
    except OSError as e:
        logger.warning("Could not remove plate reference %s: %s", path, e)


def remove_printer_references(printer_id: int) -> None:
    """Remove a deleted printer's plate references (camera images of its bed).

    Named by printer id, so the next printer given the id (SQLite reuses it)
    would show them and compare its plate against them.
    """
    for owner, path in _reference_files():
        if owner == printer_id:
            _remove(path)


class PlateDetectionResult:
    """Result of plate detection analysis."""

    def __init__(
        self,
        is_empty: bool,
        confidence: float,
        difference_percent: float,
        message: str,
        debug_image: bytes | None = None,
        needs_calibration: bool = False,
        failure_reason: str | None = None,
    ):
        self.is_empty = is_empty
        self.confidence = confidence  # 0.0 to 1.0
        self.difference_percent = difference_percent  # How different from reference
        self.message = message
        self.debug_image = debug_image  # Optional annotated image for debugging
        self.needs_calibration = needs_calibration  # True if no reference image exists
        # Why the check could not run (no_camera_frame, decode_failed,
        # analysis_error, opencv_missing); None when it ran. is_empty is then
        # True only so that a print is not blocked.
        self.failure_reason = failure_reason

    def to_dict(self) -> dict:
        return {
            "is_empty": bool(self.is_empty),
            "confidence": float(round(self.confidence, 2)),
            "difference_percent": float(round(self.difference_percent, 2)),
            "message": self.message,
            "has_debug_image": self.debug_image is not None,
            "needs_calibration": bool(self.needs_calibration),
            "failure_reason": self.failure_reason,
        }


class PlateDetector:
    """Detects if the build plate is empty using calibration-based difference detection."""

    # Default region of interest (ROI) as percentage of image dimensions
    # These define where the build plate typically appears in the camera view
    # Format: (x_start%, y_start%, width%, height%)
    DEFAULT_ROI = (0.15, 0.35, 0.70, 0.55)  # Center-lower portion of frame

    # Detection thresholds for difference detection
    # Using mean pixel difference (0-100% scale)
    # Small objects may only cause 1-2% mean difference
    DEFAULT_DIFFERENCE_THRESHOLD = 1.0
    DEFAULT_BLUR_SIZE = 21  # Gaussian blur kernel size (must be odd) - unused with edge detection

    def __init__(
        self,
        roi: tuple[float, float, float, float] | None = None,
        difference_threshold: float = DEFAULT_DIFFERENCE_THRESHOLD,
        blur_size: int = DEFAULT_BLUR_SIZE,
    ):
        """Initialize the plate detector.

        Args:
            roi: Region of interest as (x%, y%, w%, h%) - percentages of image size
            difference_threshold: Percentage of pixels that must differ to trigger "not empty"
            blur_size: Gaussian blur kernel size for noise reduction
        """
        if not OPENCV_AVAILABLE:
            raise RuntimeError("OpenCV is not installed. Install with: pip install opencv-python-headless")

        self.roi = roi or self.DEFAULT_ROI
        self.difference_threshold = difference_threshold
        self.blur_size = blur_size if blur_size % 2 == 1 else blur_size + 1  # Must be odd

    # Maximum number of reference images to store per printer
    MAX_REFERENCES = 5

    def _get_metadata_path(self, printer_id: int) -> Path:
        """Get the path to the metadata JSON file for a printer."""
        _get_calibration_dir().mkdir(parents=True, exist_ok=True)
        return _get_calibration_dir() / f"printer_{printer_id}_metadata.json"

    def _load_metadata(self, printer_id: int) -> dict:
        """Load metadata for a printer's references."""
        import json

        meta_path = self._get_metadata_path(printer_id)
        if meta_path.exists():
            try:
                with open(meta_path) as f:
                    return json.load(f)
            except (json.JSONDecodeError, OSError, KeyError, ValueError):
                pass
        return {"references": {}}

    def _save_metadata(self, printer_id: int, metadata: dict) -> None:
        """Save metadata for a printer's references."""
        import json

        meta_path = self._get_metadata_path(printer_id)
        with open(meta_path, "w") as f:
            json.dump(metadata, f, indent=2)

    def _get_reference_paths(self, printer_id: int) -> list[Path]:
        """Get all existing reference image paths for a printer."""
        _get_calibration_dir().mkdir(parents=True, exist_ok=True)
        paths = []
        for i in range(self.MAX_REFERENCES):
            path = _get_calibration_dir() / f"printer_{printer_id}_ref_{i}.jpg"
            if path.exists():
                paths.append(path)
        return paths

    def _rotate_references(self, printer_id: int) -> None:
        """Rotate references: delete oldest (0), shift others down."""
        # Delete slot 0
        slot0 = _get_calibration_dir() / f"printer_{printer_id}_ref_0.jpg"
        if slot0.exists():
            logger.info("Rotating references: removing oldest %s", slot0)
            slot0.unlink()
        # Shift others down
        for i in range(1, self.MAX_REFERENCES):
            old_path = _get_calibration_dir() / f"printer_{printer_id}_ref_{i}.jpg"
            new_path = _get_calibration_dir() / f"printer_{printer_id}_ref_{i - 1}.jpg"
            if old_path.exists():
                old_path.rename(new_path)

        # Also rotate metadata
        metadata = self._load_metadata(printer_id)
        refs = metadata.get("references", {})
        new_refs = {}
        for i in range(1, self.MAX_REFERENCES):
            if str(i) in refs:
                new_refs[str(i - 1)] = refs[str(i)]
        metadata["references"] = new_refs
        self._save_metadata(printer_id, metadata)

    def get_references(self, printer_id: int) -> list[dict]:
        """Get all references with metadata for a printer.

        Returns list of dicts with: index, label, timestamp, has_image
        """

        metadata = self._load_metadata(printer_id)
        refs = metadata.get("references", {})
        result = []

        for i in range(self.MAX_REFERENCES):
            path = _get_calibration_dir() / f"printer_{printer_id}_ref_{i}.jpg"
            if path.exists():
                ref_meta = refs.get(str(i), {})
                result.append(
                    {
                        "index": i,
                        "label": ref_meta.get("label", ""),
                        "timestamp": ref_meta.get("timestamp", ""),
                        "has_image": True,
                    }
                )

        return result

    def update_reference_label(self, printer_id: int, index: int, label: str) -> bool:
        """Update the label for a reference."""
        if index < 0 or index >= self.MAX_REFERENCES:
            return False

        path = _get_calibration_dir() / f"printer_{printer_id}_ref_{index}.jpg"
        if not path.exists():
            return False

        metadata = self._load_metadata(printer_id)
        if "references" not in metadata:
            metadata["references"] = {}
        if str(index) not in metadata["references"]:
            metadata["references"][str(index)] = {}

        metadata["references"][str(index)]["label"] = label
        self._save_metadata(printer_id, metadata)
        return True

    def delete_reference(self, printer_id: int, index: int) -> bool:
        """Delete a specific reference by index."""
        if index < 0 or index >= self.MAX_REFERENCES:
            return False

        path = _get_calibration_dir() / f"printer_{printer_id}_ref_{index}.jpg"
        if not path.exists():
            return False

        # Delete image
        logger.info("Deleting reference %s for printer %s: %s", index, printer_id, path)
        path.unlink()

        # Remove from metadata
        metadata = self._load_metadata(printer_id)
        refs = metadata.get("references", {})
        if str(index) in refs:
            del refs[str(index)]
        metadata["references"] = refs
        self._save_metadata(printer_id, metadata)

        # Shift remaining references down to fill the gap
        for i in range(index + 1, self.MAX_REFERENCES):
            old_img = _get_calibration_dir() / f"printer_{printer_id}_ref_{i}.jpg"
            new_img = _get_calibration_dir() / f"printer_{printer_id}_ref_{i - 1}.jpg"
            if old_img.exists():
                old_img.rename(new_img)
                # Also shift metadata
                if str(i) in refs:
                    refs[str(i - 1)] = refs[str(i)]
                    del refs[str(i)]

        metadata["references"] = refs
        self._save_metadata(printer_id, metadata)
        return True

    def get_reference_thumbnail(self, printer_id: int, index: int, max_size: int = 150) -> bytes | None:
        """Get a thumbnail of a reference image.

        Returns JPEG bytes or None if not found.
        """
        path = _get_calibration_dir() / f"printer_{printer_id}_ref_{index}.jpg"
        if not path.exists():
            return None

        try:
            img = cv2.imread(str(path))
            if img is None:
                return None

            # Calculate thumbnail size maintaining aspect ratio
            h, w = img.shape[:2]
            if w > h:
                new_w = max_size
                new_h = int(h * max_size / w)
            else:
                new_h = max_size
                new_w = int(w * max_size / h)

            thumb = cv2.resize(img, (new_w, new_h), interpolation=cv2.INTER_AREA)
            _, buffer = cv2.imencode(".jpg", thumb, [cv2.IMWRITE_JPEG_QUALITY, 80])
            return buffer.tobytes()
        except Exception as e:
            logger.error("Error creating thumbnail: %s", e)
            return None

    def _extract_roi(self, frame: np.ndarray) -> tuple[np.ndarray, int, int, int, int]:
        """Extract the region of interest from a frame.

        Returns:
            Tuple of (roi_frame, x_start, y_start, roi_width, roi_height)
        """
        height, width = frame.shape[:2]
        x_start = int(width * self.roi[0])
        y_start = int(height * self.roi[1])
        roi_width = int(width * self.roi[2])
        roi_height = int(height * self.roi[3])
        roi_frame = frame[y_start : y_start + roi_height, x_start : x_start + roi_width]
        return roi_frame, x_start, y_start, roi_width, roi_height

    def _preprocess_for_comparison(self, frame: np.ndarray) -> np.ndarray:
        """Preprocess a frame for comparison.

        Uses heavy blur to create "blob" representation - smooths out texture
        and noise while preserving large objects. Then normalizes brightness
        to reduce lighting sensitivity.
        """
        gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
        # Very heavy blur to smooth texture, keep only large shapes
        blurred = cv2.GaussianBlur(gray, (51, 51), 0)
        # Normalize to 0-255 range to reduce brightness sensitivity
        normalized = cv2.normalize(blurred, None, 0, 255, cv2.NORM_MINMAX)
        return normalized

    def calibrate(self, image_data: bytes, printer_id: int, label: str | None = None) -> tuple[bool, str, int]:
        """Calibrate by saving a reference image of the empty plate.

        Stores up to MAX_REFERENCES (5) images per printer. When all slots are full,
        the oldest reference is removed and others are shifted.

        Args:
            image_data: JPEG image data as bytes
            printer_id: Printer database ID
            label: Optional label for this reference (e.g., "High Temp Plate")

        Returns:
            Tuple of (success, message, index) where index is the slot used
        """
        from datetime import datetime

        try:
            # Decode image
            nparr = np.frombuffer(image_data, np.uint8)
            frame = cv2.imdecode(nparr, cv2.IMREAD_COLOR)

            if frame is None:
                return False, "Failed to decode image", -1

            # Get existing references count
            existing_refs = self._get_reference_paths(printer_id)
            num_existing = len(existing_refs)

            # If all slots are full, rotate (remove oldest)
            if num_existing >= self.MAX_REFERENCES:
                self._rotate_references(printer_id)
                num_existing = self.MAX_REFERENCES - 1

            # Save to next available slot
            slot_index = num_existing
            reference_path = _get_calibration_dir() / f"printer_{printer_id}_ref_{slot_index}.jpg"
            write_success = cv2.imwrite(str(reference_path), frame, [cv2.IMWRITE_JPEG_QUALITY, 95])

            if not write_success:
                logger.error("cv2.imwrite failed for %s", reference_path)
                return False, "Failed to save reference image", -1

            # Verify the file actually exists and has content
            if not reference_path.exists():
                logger.error("Reference image not found after save: %s", reference_path)
                return False, "Reference image not found after save", -1

            file_size = reference_path.stat().st_size
            if file_size < 1000:  # JPEG should be at least 1KB
                logger.error("Reference image too small (%s bytes): %s", file_size, reference_path)
                reference_path.unlink()  # Clean up invalid file
                return False, f"Reference image corrupted (only {file_size} bytes)", -1

            logger.info("Saved reference image: %s (%s bytes)", reference_path, file_size)

            # Save metadata
            metadata = self._load_metadata(printer_id)
            if "references" not in metadata:
                metadata["references"] = {}
            metadata["references"][str(slot_index)] = {
                "label": label or "",
                "timestamp": datetime.now().isoformat(),
            }
            self._save_metadata(printer_id, metadata)

            logger.info(
                f"Saved plate calibration reference {slot_index + 1}/{self.MAX_REFERENCES} for printer {printer_id}"
            )
            return True, f"Calibration saved ({slot_index + 1}/{self.MAX_REFERENCES} references)", slot_index

        except Exception as e:
            logger.exception("Error during plate calibration")
            # Don't expose exception details to user - log has full info
            error_type = type(e).__name__
            return False, f"Calibration error: {error_type}", -1

    def get_calibration_count(self, printer_id: int) -> int:
        """Get the number of calibration references for a printer."""
        return len(self._get_reference_paths(printer_id))

    def has_calibration(self, printer_id: int, plate_type: str | None = None) -> bool:
        """Check if a printer has any calibration reference images."""
        return len(self._get_reference_paths(printer_id)) > 0

    def analyze_frame(
        self, image_data: bytes, printer_id: int, plate_type: str | None = None, include_debug_image: bool = False
    ) -> PlateDetectionResult:
        """Analyze a camera frame to detect if the plate is empty.

        Compares the current frame to all calibration reference images and uses
        the best match (lowest difference) for the final result.

        Args:
            image_data: JPEG image data as bytes
            printer_id: Printer database ID (for reference lookup)
            plate_type: Unused - kept for API compatibility
            include_debug_image: If True, include annotated image in result

        Returns:
            PlateDetectionResult with analysis results
        """
        try:
            # Check for calibration
            reference_paths = self._get_reference_paths(printer_id)
            if not reference_paths:
                return PlateDetectionResult(
                    is_empty=True,  # Default to empty when not calibrated
                    confidence=0.0,
                    difference_percent=0.0,
                    message="No calibration - please calibrate with empty plate first",
                    needs_calibration=True,
                )

            # Decode current image
            nparr = np.frombuffer(image_data, np.uint8)
            current_frame = cv2.imdecode(nparr, cv2.IMREAD_COLOR)

            if current_frame is None:
                return PlateDetectionResult(
                    is_empty=True,
                    confidence=0.0,
                    difference_percent=0.0,
                    message="Failed to decode current image",
                    failure_reason="decode_failed",
                )

            # Extract ROI from current frame
            current_roi, x_start, y_start, roi_width, roi_height = self._extract_roi(current_frame)
            current_processed = self._preprocess_for_comparison(current_roi)

            # Compare against all references, find best match (lowest difference)
            best_difference_percent = float("inf")
            best_ref_idx = -1
            best_diff = None

            for idx, ref_path in enumerate(reference_paths):
                # Load reference image
                reference_frame = cv2.imread(str(ref_path), cv2.IMREAD_COLOR)
                if reference_frame is None:
                    continue

                # Ensure same dimensions
                if current_frame.shape != reference_frame.shape:
                    reference_frame = cv2.resize(reference_frame, (current_frame.shape[1], current_frame.shape[0]))

                # Extract ROI and preprocess
                reference_roi, _, _, _, _ = self._extract_roi(reference_frame)
                reference_processed = self._preprocess_for_comparison(reference_roi)

                # Calculate absolute difference
                diff = cv2.absdiff(current_processed, reference_processed)

                # Calculate mean difference as percentage
                mean_diff = np.mean(diff)
                difference_percent = (mean_diff / 255.0) * 100

                if difference_percent < best_difference_percent:
                    best_difference_percent = difference_percent
                    best_ref_idx = idx
                    best_diff = diff

            if best_ref_idx == -1:
                return PlateDetectionResult(
                    is_empty=True,
                    confidence=0.0,
                    difference_percent=0.0,
                    message="Failed to load any reference images - please recalibrate",
                    needs_calibration=True,
                )

            difference_percent = best_difference_percent

            # Determine if plate is empty (use best match)
            is_empty = difference_percent < self.difference_threshold

            # Calculate confidence
            if is_empty:
                # Higher confidence when very little difference
                confidence = 1.0 - min(1.0, difference_percent / self.difference_threshold)
            else:
                # Higher confidence when clearly different
                confidence = min(1.0, difference_percent / (self.difference_threshold * 2))

            # Generate message
            num_refs = len(reference_paths)
            if is_empty:
                message = (
                    f"Plate appears empty (difference: {difference_percent:.1f}%, ref {best_ref_idx + 1}/{num_refs})"
                )
            else:
                message = f"Objects detected on plate (difference: {difference_percent:.1f}%, best ref {best_ref_idx + 1}/{num_refs})"

            # Generate debug image if requested
            debug_image = None
            if include_debug_image and best_diff is not None:
                debug_frame = current_frame.copy()

                # Draw ROI rectangle
                cv2.rectangle(
                    debug_frame,
                    (x_start, y_start),
                    (x_start + roi_width, y_start + roi_height),
                    (0, 255, 0),
                    2,
                )

                # Create colored difference overlay
                # Red = areas that are different from reference
                # Amplify diff for visibility (multiply by 3, cap at 255)
                diff_amplified = np.minimum(best_diff * 3, 255).astype(np.uint8)
                diff_colored = cv2.cvtColor(diff_amplified, cv2.COLOR_GRAY2BGR)
                diff_colored[:, :, 0] = 0  # Remove blue
                diff_colored[:, :, 1] = 0  # Remove green
                # Red channel has the diff

                # Overlay difference on ROI
                roi_overlay = debug_frame[y_start : y_start + roi_height, x_start : x_start + roi_width]
                cv2.addWeighted(diff_colored, 0.5, roi_overlay, 0.5, 0, roi_overlay)

                # Add status text
                status_text = "EMPTY" if is_empty else "OBJECTS DETECTED"
                color = (0, 255, 0) if is_empty else (0, 0, 255)
                cv2.putText(debug_frame, status_text, (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, color, 2)
                cv2.putText(
                    debug_frame,
                    f"Diff: {difference_percent:.1f}% (ref {best_ref_idx + 1}/{num_refs})",
                    (10, 60),
                    cv2.FONT_HERSHEY_SIMPLEX,
                    0.7,
                    color,
                    2,
                )
                cv2.putText(
                    debug_frame,
                    f"Confidence: {confidence:.0%}",
                    (10, 90),
                    cv2.FONT_HERSHEY_SIMPLEX,
                    0.7,
                    color,
                    2,
                )

                # Encode debug image as JPEG
                _, buffer = cv2.imencode(".jpg", debug_frame, [cv2.IMWRITE_JPEG_QUALITY, 85])
                debug_image = buffer.tobytes()

            return PlateDetectionResult(
                is_empty=is_empty,
                confidence=confidence,
                difference_percent=difference_percent,
                message=message,
                debug_image=debug_image,
            )

        except Exception as e:
            logger.exception("Error analyzing frame for plate detection")
            return PlateDetectionResult(
                is_empty=True,  # Default to empty on error (don't block prints)
                confidence=0.0,
                difference_percent=0.0,
                message=f"Analysis error: {e!s}",
                failure_reason="analysis_error",
            )


async def capture_camera_image(
    printer_id: int,
    ip_address: str,
    access_code: str,
    model: str,
    external_camera_url: str | None = None,
    external_camera_type: str | None = None,
    use_external: bool = False,
    external_camera_snapshot_url: str | None = None,
) -> tuple[bytes | None, str]:
    """Capture an image from the printer camera.

    If there's an active camera stream, uses the buffered frame instead of
    creating a new connection (which would fail while stream is active).

    Returns:
        Tuple of (image_data, camera_source) or (None, error_message)
    """
    image_data: bytes | None = None
    camera_source = "unknown"

    # Try external camera first if requested and available
    if use_external and external_camera_url and external_camera_type:
        try:
            from backend.app.api.routes.camera import live_frame_for_capture
            from backend.app.services.external_camera import capture_frame

            # What this function's docstring already promised, but only the
            # built-in fallback below delivered: an external camera is
            # single-reader too, so capturing while a viewer watches fails
            # (#2707).
            defer, buffered = live_frame_for_capture(printer_id)
            if defer:
                if buffered:
                    image_data = buffered
                    camera_source = "external (buffered)"
                    logger.debug("Using buffered external frame for printer %s", printer_id)
            else:
                image_data = await capture_frame(
                    external_camera_url,
                    external_camera_type,
                    snapshot_url=external_camera_snapshot_url,
                )
                if image_data:
                    camera_source = "external"
                    logger.debug("Captured frame from external camera for printer %s", printer_id)
        except Exception as e:
            logger.warning("Failed to capture from external camera: %s", e)

    # Fall back to built-in camera
    if image_data is None:
        # First, check if there's an active stream with a buffered frame
        # This avoids blocking when camera viewer is open
        try:
            from backend.app.api.routes.camera import get_buffered_frame

            buffered = get_buffered_frame(printer_id)
            if buffered:
                image_data = buffered
                camera_source = "built-in (buffered)"
                logger.debug("Using buffered frame from active stream for printer %s", printer_id)
        except Exception as e:
            logger.debug("Could not get buffered frame: %s", e)

        # If no buffered frame, try to capture a new one
        if image_data is None:
            import tempfile

            from backend.app.services.camera import capture_camera_frame

            fd, tmp_name = tempfile.mkstemp(suffix=".jpg")
            os.close(fd)
            tmp_path = Path(tmp_name)
            tmp_path.chmod(0o600)

            try:
                success = await capture_camera_frame(ip_address, access_code, model, tmp_path, timeout=10)
                if success:
                    with open(tmp_path, "rb") as f:
                        image_data = f.read()
                    camera_source = "built-in"
                    logger.debug("Captured frame from built-in camera for printer %s", printer_id)
            finally:
                try:
                    tmp_path.unlink()
                except OSError:
                    pass  # Best-effort cleanup of temporary camera capture file

    return image_data, camera_source


async def check_plate_empty(
    printer_id: int,
    ip_address: str,
    access_code: str,
    model: str,
    plate_type: str | None = None,
    include_debug_image: bool = False,
    external_camera_url: str | None = None,
    external_camera_type: str | None = None,
    use_external: bool = False,
    roi: tuple[float, float, float, float] | None = None,
    external_camera_snapshot_url: str | None = None,
) -> PlateDetectionResult:
    """Check if the build plate is empty for a printer.

    Args:
        printer_id: Printer database ID
        ip_address: Printer IP address
        access_code: Printer access code
        model: Printer model string
        plate_type: Type of build plate for calibration lookup
        include_debug_image: If True, include annotated image in result
        external_camera_url: URL of external camera (if configured)
        external_camera_type: Type of external camera (mjpeg, rtsp, snapshot)
        use_external: If True, prefer external camera over built-in
        roi: Region of interest as (x%, y%, w%, h%) - percentages of image size

    Returns:
        PlateDetectionResult with analysis results
    """
    if not OPENCV_AVAILABLE:
        return PlateDetectionResult(
            is_empty=True,
            confidence=0.0,
            difference_percent=0.0,
            message="OpenCV not available - plate detection disabled",
            failure_reason="opencv_missing",
        )

    image_data, camera_source = await capture_camera_image(
        printer_id,
        ip_address,
        access_code,
        model,
        external_camera_url,
        external_camera_type,
        use_external,
        external_camera_snapshot_url=external_camera_snapshot_url,
    )

    if image_data is None:
        return PlateDetectionResult(
            is_empty=True,  # Default to empty on error
            confidence=0.0,
            difference_percent=0.0,
            message="Failed to capture camera frame from any source",
            failure_reason="no_camera_frame",
        )

    # Analyze the captured frame
    detector = PlateDetector(roi=roi)
    result = detector.analyze_frame(image_data, printer_id, plate_type, include_debug_image)

    # Add camera source to message
    result.message = f"[{camera_source}] {result.message}"

    return result


async def calibrate_plate(
    printer_id: int,
    ip_address: str,
    access_code: str,
    model: str,
    label: str | None = None,
    external_camera_url: str | None = None,
    external_camera_type: str | None = None,
    use_external: bool = False,
    external_camera_snapshot_url: str | None = None,
) -> tuple[bool, str, int]:
    """Calibrate plate detection by capturing a reference image of the empty plate.

    Args:
        printer_id: Printer database ID
        ip_address: Printer IP address
        access_code: Printer access code
        model: Printer model string
        label: Optional label for this reference (e.g., "High Temp Plate")
        external_camera_url: URL of external camera (if configured)
        external_camera_type: Type of external camera (mjpeg, rtsp, snapshot)
        use_external: If True, prefer external camera over built-in

    Returns:
        Tuple of (success, message, index)
    """
    if not OPENCV_AVAILABLE:
        return False, "OpenCV not available - plate detection disabled", -1

    image_data, camera_source = await capture_camera_image(
        printer_id,
        ip_address,
        access_code,
        model,
        external_camera_url,
        external_camera_type,
        use_external,
        external_camera_snapshot_url=external_camera_snapshot_url,
    )

    if image_data is None:
        return False, "Failed to capture camera frame for calibration", -1

    detector = PlateDetector()
    success, message, index = detector.calibrate(image_data, printer_id, label)

    if success:
        message = f"[{camera_source}] {message}"

    return success, message, index


def get_calibration_status(printer_id: int, plate_type: str | None = None) -> dict:
    """Get calibration status for a printer.

    Returns:
        Dict with calibration info including reference count
    """
    if not OPENCV_AVAILABLE:
        return {
            "available": False,
            "calibrated": False,
            "reference_count": 0,
            "max_references": 5,
            "message": "OpenCV not available",
        }

    detector = PlateDetector()
    calibrated = detector.has_calibration(printer_id)
    ref_count = detector.get_calibration_count(printer_id)

    if calibrated:
        message = f"Calibrated with {ref_count}/{detector.MAX_REFERENCES} reference(s)"
    else:
        message = "Not calibrated - please calibrate with empty plate"

    return {
        "available": True,
        "calibrated": calibrated,
        "reference_count": ref_count,
        "max_references": detector.MAX_REFERENCES,
        "message": message,
    }


def is_plate_detection_available() -> bool:
    """Check if plate detection feature is available (OpenCV installed)."""
    return OPENCV_AVAILABLE