"""Public exception hierarchy for coupler_panel.

Catch :class:`CouplerError` for any algorithm failure that should be
surfaced to the user. Subclasses indicate what specifically went wrong so
callers can render targeted error messages.

Non-fatal data-quality issues are **not** raised; they are reported via
``CouplerMeasurement.quality_flags``.
"""

from __future__ import annotations


class CouplerError(Exception):
    """Base class for all errors raised by the coupler-panel pipeline."""


class InvalidPointCloudError(CouplerError):
    """Raised when the input point cloud is malformed or unreadable."""


class UnsupportedFormatError(InvalidPointCloudError):
    """Raised when the input file extension is not supported."""


class InsufficientPointsError(CouplerError):
    """Raised when the input has too few points to run the pipeline."""


class CADParseError(CouplerError):
    """Raised when the STP file cannot be parsed or has unexpected topology."""


class HoleDetectionError(CouplerError):
    """Raised when the four locating holes cannot be reliably detected."""


class RegistrationError(CouplerError):
    """Raised when 4-hole Kabsch registration fails (e.g. degenerate pairing)."""


class PlaneFitError(CouplerError):
    """Raised when the panel plane cannot be fitted (too few inliers, etc.)."""


__all__ = [
    "CouplerError",
    "InvalidPointCloudError",
    "UnsupportedFormatError",
    "InsufficientPointsError",
    "CADParseError",
    "HoleDetectionError",
    "RegistrationError",
    "PlaneFitError",
]