Function project_to_hull

src/fl/gfx/rgbw_colorimetric.cpp.hpp:183–244

Project an out-of-hull target XYZ onto the achievable LED gamut (#2708, math-model gist §3). Returns true if a projection was applied, in which case `X_t` and `xy_t` are updated to the projected point at unit Y. When the target is already inside the full RGB triangle, returns false and leaves `X_t` / `xy_t` untouched. Algorithm matches the reference's `_strict_project_target_xyz_to_led_hull`: run

// 1.0 per sub-gamut, then pick the sub-gamut with smallest residual. Use
// the achieved chromaticity as the new target xy.
static bool project_to_hull(const ProfileCache& cache,
                            float X_t[3], float xy_t[2]) FL_NOEXCEPT {
    const float sum = X_t[0] + X_t[1] + X_t[2];
    if (sum < 1e-12f) return false;
    xy_t[0] = X_t[0] / sum;
    xy_t[1] = X_t[1] / sum;

    const DiodeProfile& p = *cache.profile;
    float bary[3];
    // Test the full RGB triangle (not the sub-gamut triangles) — a target
    // can be outside a single sub-gamut yet still inside the full hull.
    if (barycentric_xy(xy_t, p.xy_r, p.xy_g, p.xy_b, bary)
        && bary[0] >= -1e-9f && bary[1] >= -1e-9f && bary[2] >= -1e-9f) {
        return false;
    }

    struct Tri { const float* a; const float* b; const float* c; };
    const Tri tris[3] = {
        { cache.P_R, cache.P_G, cache.P_W },
        { cache.P_R, cache.P_B, cache.P_W },
        { cache.P_B, cache.P_G, cache.P_W },
    };
    float best_xyz[3] = {0, 0, 0};
    float best_residual = 1e30f;
    for (int k = 0; k < 3; ++k) {
        const Tri& tri = tris[k];
        const float M[3][3] = {
            { tri.a[0], tri.b[0], tri.c[0] },
            { tri.a[1], tri.b[1], tri.c[1] },
            { tri.a[2], tri.b[2], tri.c[2] },
        };
        float t[3], residual;
        nnls3(M, X_t, t, &residual);
        // Cap drive at full-scale per sub-gamut, matching the reference.
        float mt = t[0];
        if (t[1] > mt) mt = t[1];
        if (t[2] > mt) mt = t[2];
        if (mt > 1.0f) { const float inv = 1.0f / mt; t[0] *= inv; t[1] *= inv; t[2] *= inv; }
        float xyz[3];
        xyz[0] = M[0][0]*t[0] + M[0][1]*t[1] + M[0][2]*t[2];
        xyz[1] = M[1][0]*t[0] + M[1][1]*t[1] + M[1][2]*t[2];
        xyz[2] = M[2][0]*t[0] + M[2][1]*t[1] + M[2][2]*t[2];
        if (xyz[1] <= 1e-12f) continue;
        if (residual < best_residual) {
            best_residual = residual;
            best_xyz[0] = xyz[0]; best_xyz[1] = xyz[1]; best_xyz[2] = xyz[2];
        }
    }
    if (best_xyz[1] <= 1e-12f) {
        // All sub-gamut projections collapsed to zero — pathological
        // profile or extreme target. Leave the original X_t alone; the
        // strict solver will return false and the dispatch falls back.
        return false;
    }
    const float s2 = best_xyz[0] + best_xyz[1] + best_xyz[2];
    xy_t[0] = best_xyz[0] / s2;
    xy_t[1] = best_xyz[1] / s2;
    // Per reference, normalize Y to 1.0 for downstream routing. The full-chroma