# Copyright CNRS/Inria/UCA
# Contributor(s): Eric Debreuve (since 2020)
#
# eric.debreuve@cnrs.fr
#
# This software is governed by the CeCILL  license under French law and
# abiding by the rules of distribution of free software.  You can  use,
# modify and/ or redistribute the software under the terms of the CeCILL
# license as circulated by CEA, CNRS and INRIA at the following URL
# "http://www.cecill.info".
#
# As a counterpart to the access to the source code and  rights to copy,
# modify and redistribute granted by the license, users are provided only
# with a limited warranty  and the software's author,  the holder of the
# economic rights,  and the successive licensors  have only  limited
# liability.
#
# In this respect, the user's attention is drawn to the risks associated
# with loading,  using,  modifying and/or developing or reproducing the
# software by the user in light of its specific status of free software,
# that may mean  that it is complicated to manipulate,  and  that  also
# therefore means  that it is reserved for developers  and  experienced
# professionals having in-depth computer knowledge. Users are therefore
# encouraged to load and test the software's suitability as regards their
# requirements in conditions enabling the security of their systems and/or
# data to be ensured and,  more generally, to use and operate it in the
# same conditions as regards security.
#
# The fact that you are presently reading this means that you have had
# knowledge of the CeCILL license and that you accept its terms.

from typing import Final, Sequence

import numpy as nmpy
from im_tools_36.type.image import pix_value_h


array_t: Final = nmpy.ndarray


# TODO: deal with rgba images everywhere, maybe


def WithSuperimposedGrid(
    img: array_t,
    /,
    *,
    color: pix_value_h = 0,
    row_step: int = 4,
    col_step: int = 4,
    thickness: int = 1,
) -> array_t:
    """"""
    output = img.copy()

    if img.ndim == 2:
        if isinstance(color, Sequence):
            raise ValueError(
                f"Color must be a number, not a sequence, when image is two-dimensional"
            )
    elif img.ndim == 3:
        if img.shape[2] not in (3, 4):
            raise ValueError(
                f"{img.shape[2]}: Invalid length of 3rd image dimension; Must be 3 (RGB) or 4 (RGBA)"
            )
        if isinstance(color, Sequence):
            if color.__len__() != img.shape[2]:
                raise ValueError(
                    f"{color.__len__()}: Invalid number of color components; "
                    f"Must be {img.shape[2]} like the 3rd image dimension"
                )
        else:
            color = img.shape[2] * (color,)
    else:
        raise ValueError(
            f"{img.ndim}: Invalid number of image dimensions; Must be 2 (Grayscale) or 3 (RGB or RGBA)"
        )

    if isinstance(color, Sequence):
        color = nmpy.reshape(color, (1, 1, -1))

    for row in range(0, img.shape[0], row_step):
        output[row : (row + thickness), ...] = color
    for col in range(0, img.shape[1], col_step):
        output[:, col : (col + thickness), ...] = color

    return output
