Detectors¤

class BaseDetector(zdx.Base):
    """
    Abstract base class for detector models.

    Concrete detectors implement `model(...)` to transform input PSFs into
    detector-space outputs.

    ??? abstract "UML"
        ![UML](../../assets/uml/BaseDetector.png)
    """

    @abstractmethod
    def __call__(
        self: BaseDetector, psf: PSF, return_psf: bool = False
    ) -> Array | PSF:  # pragma: no cover
        pass

    def model(
        self: LayeredDetector,
        psf: PSF,
        return_psf: bool = False,
    ) -> Array | PSF:
        """
        Backwards compatibility method that invokes __call__.

        Delegates to the __call__ method.
        """
        return self(psf, return_psf)

class LayeredDetector(BaseDetector):
    """
    Applies a series of detector layers to an input PSF.

    ??? abstract "UML"
        ![UML](../../assets/uml/LayeredDetector.png)

    Attributes
    ----------
    layers: OrderedDict
        A series of `DetectorLayer` transformations to apply to the input PSF.
    """

    layers: OrderedDict

    def __init__(
        self: LayeredDetector,
        layers: list[DetectorLayer | tuple[str, DetectorLayer]],
    ):
        """
        Parameters
        ----------
        layers : list[DetectorLayer | tuple[str, DetectorLayer]]
            A list of DetectorLayer objects to apply to the input PSF. List entries
            can be tuples of (key, layer) to specify a key, else the key is taken as
            the class name of the layer.
        """
        self.layers = dlu.list2dictionary(layers, True, DetectorLayer)
        super().__init__()

    def __getattr__(self: LayeredDetector, key: str) -> Any:
        """
        Raises the individual layers via their keys.

        Parameters
        ----------
        key : str
            The key of the item to be searched for in the layers dictionary.

        Returns
        -------
        item : Any
            The item corresponding to the supplied key in the layers
            dictionary.
        """
        if key in self.layers.keys():
            return self.layers[key]
        for layer in list(self.layers.values()):
            if hasattr(layer, key):
                return getattr(layer, key)
        raise dlu.helpers.missing_attribute_error(
            self,
            key,
            list(self.layers.keys()),
        )

    def __call__(
        self: LayeredDetector,
        psf: PSF,
        return_psf: bool = False,
    ) -> Array | PSF:
        """
        Applies the detector layers to the input PSF.

        Parameters
        ----------
        psf : PSF
            The input PSF to be transformed.
        return_psf : bool = False
            Should the PSF object be returned instead of the PSF array?

        Returns
        -------
        result : Array | PSF
            If `return_psf` is False, returns the PSF array.
            If `return_psf` is True, returns the PSF object.
        """
        for _, layer in self.layers.items():
            psf = layer(psf)
        if return_psf:
            return psf
        return psf.data

    def insert_layer(
        self: LayeredDetector,
        layer: DetectorLayer | tuple[str, DetectorLayer],
        index: int,
    ) -> LayeredDetector:
        """
        Inserts a layer into the layers dictionary at a specified index. This function
        calls the list2dictionary function to ensure all keys remain unique. Note that
        this can result in some keys being modified if they are duplicates. The input
        'layer' can be a tuple of (key, layer) to specify a key, else the key is taken
        as the class name of the layer.

        Parameters
        ----------
        layer : DetectorLayer | tuple[str, DetectorLayer]
            The layer to be inserted.
        index : int
            The index at which to insert the layer.

        Returns
        -------
        detector : LayeredDetector
            The updated detector.
        """
        return self.set(
            "layers",
            dlu.insert_layer(self.layers, layer, index, DetectorLayer),
        )

    def remove_layer(self: LayeredDetector, key: str) -> LayeredDetector:
        """
        Removes a layer from the layers dictionary, specified by its key.

        Parameters
        ----------
        key : str
            The key of the layer to be removed.

        Returns
        -------
        detector : LayeredDetector
            The updated detector.
        """
        return self.set("layers", dlu.remove_layer(self.layers, key))