r"""Takes two :py:class:`Colour` s and returns the 'average' Colour.

    Args:
        colour1 (colourettu.Colour): a colour
        colour2 (colourettu.Colour): a second colour

    .. note::

        Uses the formula:

        \\[ r_{blended} = \\sqrt \\frac{r_1^2 + r_2^2}{2} \\]


        It is hown here for the red channel, but applied independantly to each
        of the red, green, and blue channels. The reason for doing it this way
        (rather than using a simple average) is that the brightness of the
        colours is stored in a logrythmic scale, rather than a linear one.

        For a fuller explaination, Minute Physics has released a great
        `YouTube video <https://youtu.be/LKnqECcg6Gw>`_.

    .. seealso:: :py:func:`Palette.blend`

def blend(colour1, colour2):
    r"""Takes two :py:class:`Colour` s and returns the 'average' Colour.

    Args:
        colour1 (colourettu.Colour): a colour
        colour2 (colourettu.Colour): a second colour

    .. note::

        Uses the formula:

        \\[ r_{blended} = \\sqrt \\frac{r_1^2 + r_2^2}{2} \\]


        It is hown here for the red channel, but applied independantly to each
        of the red, green, and blue channels. The reason for doing it this way
        (rather than using a simple average) is that the brightness of the
        colours is stored in a logrythmic scale, rather than a linear one.

        For a fuller explaination, Minute Physics has released a great
        `YouTube video <https://youtu.be/LKnqECcg6Gw>`_.

    .. seealso:: :py:func:`Palette.blend`
    """
    # raw docstring is needed so that MathJax will render in generated
    # documentation

    # gamma is the power we're going to use to do this conversion
    gamma = 2.0

    # start by normalizing values
    r_1 = colour1.red()/255.
    g_1 = colour1.green()/255.
    b_1 = colour1.blue()/255.
    r_2 = colour2.red()/255.
    g_2 = colour2.green()/255.
    b_2 = colour2.blue()/255.

    r_m = math.pow(((math.pow(r_1, gamma) + math.pow(r_2, gamma)) / 2), 1/gamma)
    g_m = math.pow(((math.pow(g_1, gamma) + math.pow(g_2, gamma)) / 2), 1/gamma)
    b_m = math.pow(((math.pow(b_1, gamma) + math.pow(b_2, gamma)) / 2), 1/gamma)

    c_m = Colour([r_m, g_m, b_m], normalized_rgb=True)

    return c_m