"""
image - Plot raster or EPS images.
"""

from collections.abc import Sequence
from typing import Literal

from pygmt._typing import AnchorCode, PathLike
from pygmt.alias import Alias, AliasSystem
from pygmt.clib import Session
from pygmt.helpers import build_arg_list, fmt_docstring, use_alias
from pygmt.params import Box, Position
from pygmt.src._common import _parse_position


@fmt_docstring
@use_alias(G="bitcolor")
def image(  # noqa: PLR0913
    self,
    imagefile: PathLike,
    position: Position | Sequence[float | str] | AnchorCode | None = None,
    width: float | str | None = None,
    height: float | str | None = None,
    dpi: float | str | None = None,
    replicate: int | Sequence[int] | None = None,
    box: Box | bool = False,
    monochrome: bool = False,
    invert: bool = False,
    projection: str | None = None,
    region: Sequence[float | str] | str | None = None,
    frame: str | Sequence[str] | bool = False,
    verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
    | bool = False,
    panel: int | Sequence[int] | bool = False,
    perspective: float | Sequence[float] | str | bool = False,
    transparency: float | None = None,
    **kwargs,
):
    r"""
    Plot raster or EPS images.

    Reads an Encapsulated PostScript file or a raster image file and plot it on a map.
    The image can be scaled arbitrarily, and 1-bit raster images can be:

    - inverted, i.e., black pixels (on) become white (off) and vice versa.
    - colorized, by assigning different foreground and background colors.
    - made transparent where either the back- or foreground is painted.

    As an option, the user may choose to convert colored raster images to grayscale
    using TV's YIQ-transformation. For raster files, the user can select which color is
    made transparent. The user may also choose to replicate the image which, when
    preceded by appropriate clip paths, may allow larger custom-designed fill patterns
    to be implemented.

    Full GMT docs at :gmt-docs:`image.html`.

    $aliases
       - B = frame
       - D = position, **+w**: width/height, **+r**: dpi, **+n**: replicate
       - F = box
       - I = invert
       - J = projection
       - M = monochrome
       - R = region
       - V = verbose
       - c = panel
       - p = perspective
       - t = transparency

    Parameters
    ----------
    imagefile
        An Encapsulated PostScript (EPS) file or a raster image file. An EPS file must
        contain an appropriate BoundingBox. A raster file can have a depth of 1, 8, 24,
        or 32 bits and is read via GDAL.
    position
        Position of the GMT logo on the plot. It can be specified in multiple ways:

        - A :class:`pygmt.params.Position` object to fully control the reference point,
          anchor point, and offset.
        - A sequence of two values representing the x- and y-coordinates in plot
          coordinates, e.g., ``(1, 2)`` or ``("1c", "2c")``.
        - A :doc:`2-character justification code </techref/justification_codes>` for a
          position inside the plot, e.g., ``"TL"`` for Top Left corner inside the plot.

        If not specified, defaults to the Bottom Left corner of the plot (position
        ``(0, 0)`` with anchor ``"BL"``).
    width
    height
        Width (and height) of the image in plot coordinates (inches, cm, etc.). If
        ``height`` (or ``width``) is set to 0, then the original aspect ratio of the
        image is maintained. If ``width`` (or ``height``) is negative, the absolute
        value is used to interpolate image to the device resolution using the PostScript
        image operator. If neither dimensions nor ``dpi`` are set then revert to the
        default dpi [:gmt-term:`GMT_GRAPHICS_DPU`].
    dpi
        Set the dpi of the image in dots per inch, or append **c** to indicate this is
        dots per cm.
    replicate
        *nx* or (*nx*, *ny*).
        Replicate the (scaled) image *nx* times in the horizontal direction, and *ny*
        times in the vertical direction. If a single integer *nx* is given, *ny* = *nx*.
        [Default is (1, 1)].
    box
        Draw a background box behind the image. If set to ``True``, a simple rectangular
        box is drawn using :gmt-term:`MAP_FRAME_PEN`. To customize the box appearance,
        pass a :class:`pygmt.params.Box` object to control style, fill, pen, and other
        box properties.
    bitcolor : str or list
        [*color*][**+b**\|\ **f**\|\ **t**].
        Change certain pixel values to another color or make them transparent.
        For 1-bit images you can specify an alternate *color* for the
        background (**+b**) or the foreground (**+f**) pixels, or give no color
        to make those pixels transparent. Can be repeated with different
        settings. Alternatively, for color images you can select a single
        *color* that should be made transparent instead (**+t**).
    monochrome
        Convert color image to monochrome grayshades using the (television)
        YIQ-transformation.
    invert
        Invert 1-bit image before plotting, i.e., black pixels (on) become white (off)
        and vice versa. Ignored if used with color images.

        **Note**: There was an upstream GMT bug, so this feature may not work correctly
        for some 1-bit images for GMT<=6.6.0.
        See `PR #8837 <https://github.com/GenericMappingTools/gmt/pull/8837>`__.
    $projection
    $region
    $frame
    $verbose
    $panel
    $perspective
    $transparency
    """
    self._activate_figure()

    position = _parse_position(
        position,
        kwdict={"width": width, "height": height, "dpi": dpi, "replicate": replicate},
        default=Position((0, 0), cstype="plotcoords"),  # Default to (0,0) in plotcoords
    )

    # width is required when only height is given.
    if width is None and height is not None:
        width = 0

    aliasdict = AliasSystem(
        D=[
            Alias(position, name="position"),
            Alias(width, name="width", prefix="+w"),  # +wwidth/height
            Alias(height, name="height", prefix="/"),
            Alias(replicate, name="replicate", prefix="+n", sep="/", size=2),
            Alias(dpi, name="dpi", prefix="+r"),
        ],
        F=Alias(box, name="box"),
        M=Alias(monochrome, name="monochrome"),
        I=Alias(invert, name="invert"),
    ).add_common(
        B=frame,
        J=projection,
        R=region,
        V=verbose,
        c=panel,
        p=perspective,
        t=transparency,
    )
    aliasdict.merge(kwargs)

    with Session() as lib:
        lib.call_module(
            module="image", args=build_arg_list(aliasdict, infile=imagefile)
        )
