Leaves of Three Open Source Projects

Pixel Robot TODOs:
 

  ✔ Switch from int64_t to int32_t for coordinates? @done (25-03-26 12:43)
     I think int32_t will play nicer with QuickJS, and is big enough for
     anything we want to do. It would also allow us to pack coordinates
     into a struct, which (on x86-64) could be passed in a single register
     instead of two.

  ☐ OKLCH/LAB color space? <https://bottosson.github.io/posts/oklab/>
    ☐ rgb_color::mix() for OKLCH space
    ☐ color similarity for OKLAB/OKLCH spaces (in rgb_color.cpp)

  ☐ Inconsistency between go_to and frames.go_to...?
     Currently, the global next/go_to functions are *not* just wrappers around
     the Image methods; they are defined in src/js.cpp and call the functions
     in sketch.hpp. But we also have a go_to method on Image (frame_stack)
     which is separate.

     Note that frame_stack does not have a `next()` method, so we implement

        See also

           <http://nerdlypleasures.blogspot.com/2023/03/the-saga-of-color-brown-in-early-years.html?m=1>

     ☐ EGA 
        EGA uses the same 16-color palette as CGA, but has access to a 64-color
        palette. Artifact colors are not possible.

     ☐ 12-bit <https://iamkate.com/data/12-bit-rainbow/>

  Documentation:
    ✔ Convert documentation to LuaLaTeX @done (24-11-22 09:56)
       (in progress)

       ✔ Main conversion @done (24-10-29 09:19)

            RGBA = RGB,
            HSL,
            HSV,
            XYZ, 
            LAB,
            YIQ,
            YUV,
            YPBPR,
            OKLAB,
            OKLCH
        };

        void to_color_space(color_space space, float& x, float& y, float& z) const
        {
            switch(space) {
                case RGB:  x = r/255.0; y = g/255.0; z = b/255.0; return;

                case HSL: to_hsl(x,y,z); return;
                case HSV: to_hsv(x,y,z); return;
                case XYZ: to_xyz(x,y,z); return;
                case LAB: to_lab(x,y,z); return;
                case YIQ: to_yiq(x,y,z); return;
                case YUV: to_yuv(x,y,z); return;
                case YPBPR: to_YPbPr(x,y,z); return;
                case OKLAB: to_OKLAB(x,y,z); return;
                case OKLCH: to_OKLCH(x,y,z); return;
            }
        }

        /* to_*(c, x, y, z)
           Converts a RGB color to various other color spaces.
        */
        void to_hsl(float& h, float& s, float& l) const;
        void to_hsv(float& h, float& s, float& v) const;
        void to_xyz(float& x, float& y, float& z) const;
        void to_lab(float& l, float& a, float& b) const;
        void to_YPbPr(float& Y, float& Pb, float& Pr) const;
        void to_OKLAB(float& L, float& a, float& b) const;
        void to_OKLCH(float& L, float& C, float& H) const;

        /* to_yiq(y,i,q)
           Converts the color to the YIQ color space, used by NTSC (analog) 
           televisions. YIQ is useful for generating colors/gradients which 
           *look like* they came from a TV in the 1980s. 

           NOTE: After the transformation, the Y,I,Q components will be in these

        static rgb_color from_hsv(float h, float s, float v);
        static rgb_color from_hsl(float h, float s, float l);
        static rgb_color from_xyz(float x, float y, float z);
        static rgb_color from_lab(float l, float a, float b);
        static rgb_color from_yiq(float y, float i, float q);
        static rgb_color from_yuv(float y, float u, float v);
        static rgb_color from_YPbPr(float Y, float Pb, float Pr);
        static rgb_color from_OKLAB(float L, float a, float b);
        static rgb_color from_OKLCH(float L, float C, float h);

        static rgb_color from_color_space(
            color_space space,
            float x, float y, float z
        )
        {
            switch(space) {

                case HSL: return from_hsl(x,y,z);
                case HSV: return from_hsv(x,y,z);
                case XYZ: return from_xyz(x,y,z);
                case LAB: return from_lab(x,y,z);
                case YIQ: return from_yiq(x,y,z);
                case YUV: return from_yuv(x,y,z);
                case YPBPR: return from_YPbPr(x, y, z);
                case OKLAB: return from_OKLAB(x,y,z);
                case OKLCH: return from_OKLCH(x,y,z);
            }

            // This should be unreachable
            return rgb_color::hotpink();
        }

        /* Modifying colors

            Colors ... colors
        )
        {
            static_assert(sizeof...(Colors) > 0,
                "rgb_color::mix() must be passed at least one color parameter");

            if(space == color_space::HSL or space == color_space::HSV) {
                // TODO: This also for OKLCH.

                // In HSL/V space, we can't just average the components, because
                // hue is angular. So instead we exploit the fact that HSL/V
                // space can be viewed in 3D-space as a double-cone (HSL) or 
                // cone (HSV). So we can convert all the colors into a 
                // Cartesian 3D space (x,y,z), average there, and then convert
                // back into HSL/V. 

            cs = rgb_color::color_space::YIQ;
        else if(s == "lab")
            cs = rgb_color::color_space::LAB;
        else if(s == "yuv")
            cs = rgb_color::color_space::YUV;
        else if(s == "ypbpr")
            cs = rgb_color::color_space::YPBPR;
        else if(s == "oklab")
            cs = rgb_color::color_space::OKLAB;
        else if(s == "oklch")
            cs = rgb_color::color_space::OKLCH;
        else
            return false;

        return true;
    }

    /* color_similarity
       Names of the different color similarity methods we can use.
    */
    enum class color_similarity
    {
        RGB,
        WEIGHTED,
        CIE76,
        CIE94,
        HSV,
        HSL,
        XYZ,
        YIQ,
        YUV,
        YPBPR,
        OKLAB,
        OKLCH
    };

    inline bool from_string(const std::string& s, color_similarity& cs)
    {
        if(s == "rgb" or s == "rgba") 
            cs = color_similarity::RGB;
        else if(s == "weighted")

            cs = color_similarity::XYZ;
        else if(s == "yiq")
            cs = color_similarity::YIQ;
        else if(s == "yuv")
            cs = color_similarity::YUV;
        else if(s == "ypbpr")
            cs = color_similarity::YPBPR;
        else if(s == "oklab")
            cs = color_similarity::OKLAB;
        else if(s == "oklch")
            cs = color_similarity::OKLCH;
        else
            return false;

        return true;
    }

    /* distance(a,b,space)

#include <pixel_robot/js.hpp>
#include <pixel_robot/resource.hpp>
#include <pixel_robot/rgb_color.hpp>
#include <pixel_robot/sketch.hpp>

namespace probot {

    /* OKLAB/OKLCH conversion from/to sRGB
       This code is copied, basically unchanged, from 

            <https://bottosson.github.io/posts/oklab/>

       The original is in the public domain.
    */
    struct Lab {float L; float a; float b;};
    struct RGB {float r; float g; float b;};

    static Lab linear_srgb_to_oklab(RGB c) 
    {
        float l = 0.4122214708f * c.r + 0.5363325363f * c.g + 0.0514459929f * c.b;
        float m = 0.2119034982f * c.r + 0.6806995451f * c.g + 0.1073969566f * c.b;
        float s = 0.0883024619f * c.r + 0.2817188376f * c.g + 0.6299787005f * c.b;

        float l_ = cbrtf(l);
        float m_ = cbrtf(m);
        float s_ = cbrtf(s);

        return {
            0.2104542553f*l_ + 0.7936177850f*m_ - 0.0040720468f*s_,
            1.9779984951f*l_ - 2.4285922050f*m_ + 0.4505937099f*s_,
            0.0259040371f*l_ + 0.7827717662f*m_ - 0.8086757660f*s_,
        };
    }

    static RGB oklab_to_linear_srgb(Lab c) 
    {
        float l_ = c.L + 0.3963377774f * c.a + 0.2158037573f * c.b;
        float m_ = c.L - 0.1055613458f * c.a - 0.0638541728f * c.b;
        float s_ = c.L - 0.0894841775f * c.a - 1.2914855480f * c.b;

        float l = l_*l_*l_;
        float m = m_*m_*m_;
        float s = s_*s_*s_;

        return {
            +4.0767416621f * l - 3.3077115913f * m + 0.2309699292f * s,
            -1.2684380046f * l + 2.6097574011f * m - 0.3413193965f * s,
            -0.0041960863f * l - 0.7034186147f * m + 1.7076147010f * s,
        };
    }

    /* srgb_to_linear(r,g,b)
       Converts a sRGB color (components 0...255) to linear RGB (components
       0...1).
    */
    static void srgb_to_linear(float& r, float& g, float& b)
    {

        srgb_to_linear(red, green, blue);

        Y =  0.299 * red  + 0.587 * green + 0.114 * blue ;
        Pb = 0.564 * (blue - Y);
        Pr = 0.713 * (red - Y);
    }

    void rgb_color::to_OKLAB(float& L, float& a, float& b) const
    {
        float red = r, green = g, blue = b;
        srgb_to_linear(red, green, blue);

        Lab c = linear_srgb_to_oklab({ float(red), float(green), float(blue) });
        L = c.L;
        a = c.a;
        b = c.b;
    }

    void rgb_color::to_OKLCH(float& L, float& C, float& H) const
    {
        float a, b;
        to_OKLAB(L, a, b);

        C = std::sqrt(a*a + b*b);
        H = std::atan2(b, a);
    }

    rgb_color rgb_color::from_hsv(float h, float s, float v)
    {
        // Assumes h is degrees [0...360); s, v ∈ [0,1] 
        h = std::fmod(h, 360);

        if(s <= 0.0f) {

            saturate(b),
            255
        };
    }

    rgb_color rgb_color::from_YPbPr(float Y, float Pb, float Pr)
    {






        float b = Pb / 0.564 + Y; // by = B - Y       B = by - Y
        float r = Pr / 0.713 + Y; // ry = R - Y       R = ry - Y
        float g = Y - 0.299 * (Pr / 0.713) / 0.587 - 0.114 * (Pb / 0.564) / 0.587;

        linear_to_srgb(r, g, b);

        return rgb_color{
            saturate(r),
            saturate(g),
            saturate(b),
            255
        };
    }

    rgb_color rgb_color::from_OKLAB(float L, float a, float b)
    {
        struct RGB c = oklab_to_linear_srgb({L, a, b});
        linear_to_srgb(c.r, c.g, c.b);
        return rgb_color{ saturate(c.r), saturate(c.g), saturate(c.b) };
    }

    rgb_color rgb_color::from_OKLCH(float L, float C, float h)
    {
        Lab c = { 
            L, 
            C * std::cos(h),
            C * std::sin(h)
        };

        return from_OKLAB(c.L, c.a, c.b);
    }

    rgb_color rgb_color::mix(
        color_space space, 
        const std::vector<rgb_color>& colors
    )
    {
        if(colors.empty())