@woosh/meep-engine 2.43.3 → 2.43.5

package/core/geom/3d/sphere/harmonics/sh3_dering_optimize_positive.js

@@ -0,0 +1,618 @@
+import { max2 } from "../../../../math/max2.js";
+import { mat3, vec3 } from "gl-matrix";
+import { array_copy } from "../../../../collection/array/copyArray.js";
+import { min2 } from "../../../../math/min2.js";
+import { assert } from "../../../../assert.js";
+
+/*
+@see https://github.com/Bestmaker602/olacziy/blob/212b64ea5f1856b390cdf7629801243f76a4466d/libs/ibl/src/CubemapSH.cpp
+ */
+
+/**
+ *
+ * @param {number[]} M 5x5 matrix
+ * @param {number[]} x vec5
+ * @return {number[]}
+ */
+function multiply_5d(M, x) {
+    return [
+        M[0] * x[0] + M[5] * x[1] + M[10] * x[2] + M[15] * x[3] + M[20] * x[4],
+        M[1] * x[0] + M[6] * x[1] + M[11] * x[2] + M[16] * x[3] + M[21] * x[4],
+        M[2] * x[0] + M[7] * x[1] + M[12] * x[2] + M[17] * x[3] + M[22] * x[4],
+        M[3] * x[0] + M[8] * x[1] + M[13] * x[2] + M[18] * x[3] + M[23] * x[4],
+        M[4] * x[0] + M[9] * x[1] + M[14] * x[2] + M[19] * x[3] + M[24] * x[4]
+    ];
+}
+
+
+/**
+ * returns n! / d!
+ * @param {number} n
+ * @param {number} d
+ * @return {number}
+ */
+function factorial(n, d = 1) {
+    let _d = max2(1, d);
+    let _n = max2(1, n);
+
+    let r = 1.0;
+
+    if (_n === _d) {
+        // intentionally left blank
+    } else if (_n > _d) {
+        for (; _n > _d; _n--) {
+            r *= _n;
+        }
+    } else {
+        for (; _d > _n; _d--) {
+            r *= _d;
+        }
+        r = 1.0 / r;
+    }
+    return r;
+}
+
+const F_PI = 3.14159265358979323846264338327950288;
+const F_2_PI = 0.636619772367581343075535053490057448;
+const F_2_SQRTPI = 1.12837916709551257389615890312154517;
+const F_SQRT2 = 1.41421356237309504880168872420969808;
+const F_SQRT1_2 = 0.707106781186547524400844362104849039;
+const M_SQRT_3 = 1.7320508076;
+
+/**
+ * SH scaling factors:
+ *  returns sqrt((2*l + 1) / 4*pi) * sqrt( (l-|m|)! / (l+|m|)! )
+ */
+function Kml(m, l) {
+    m = m < 0 ? -m : m;  // abs() is not constexpr
+    const K = (2 * l + 1) * factorial((l - m), (l + m));
+    return Math.sqrt(K) * (F_2_SQRTPI * 0.25);
+}
+
+/**
+ * compute Index of spherical harmonics coefficient
+ * @param {number} m
+ * @param {number} l
+ * @return {number}
+ */
+function SHindex(m, l) {
+    return l * (l + 1) + m;
+}
+
+/**
+ *
+ * @param {number[]} result
+ * @param {number} result_offset
+ * @param {number} numBands
+ */
+function Ki(result, result_offset, numBands) {
+    for (let l = 0; l < numBands; l++) {
+        result[SHindex(0, l) + result_offset] = Kml(0, l);
+        for (let m = 1; m <= l; m++) {
+            result[SHindex(m, l) + result_offset] =
+                result[SHindex(-m, l) + result_offset] = F_SQRT2 * Kml(m, l);
+        }
+    }
+}
+
+/**
+ * < cos(theta) > SH coefficients pre-multiplied by 1 / K(0,l)
+ * @param {number} l
+ * @returns {number}
+ */
+function computeTruncatedCosSh(l) {
+    if (l === 0) {
+        return F_PI;
+    } else if (l === 1) {
+        return 2 * F_PI / 3;
+    } else if ((l & 1) !== 0) {
+        return 0;
+    }
+
+    const l_2 = l / 2;
+    const A0 = ((l_2 & 1) ? 1.0 : -1.0) / ((l + 2) * (l - 1));
+    const A1 = factorial(l, l_2) / (factorial(l_2) * (1 << l));
+    return 2 * F_PI * A0 * A1;
+}
+
+/*
+ * Calculates non-normalized SH bases, i.e.:
+ *  m > 0, cos(m*phi)   * P(m,l)
+ *  m < 0, sin(|m|*phi) * P(|m|,l)
+ *  m = 0, P(0,l)
+ */
+function computeShBasis(SHb, result_offset, numBands, sx, sy, sz) {
+
+    /*
+     * TODO: all the Legendre computation below is identical for all faces, so it
+     * might make sense to pre-compute it once. Also note that there is
+     * a fair amount of symmetry within a face (which we could take advantage of
+     * to reduce the pre-compute table).
+     */
+
+    /*
+     * Below, we compute the associated Legendre polynomials using recursion.
+     * see: http://mathworld.wolfram.com/AssociatedLegendrePolynomial.html
+     *
+     * Note [0]: sz == cos(theta) ==> we only need to compute P(sz)
+     *
+     * Note [1]: We in fact compute P(sz) / sin(theta)^|m|, by removing
+     * the "sqrt(1 - sz*sz)" [i.e.: sin(theta)] factor from the recursion.
+     * This is later corrected in the ( cos(m*phi), sin(m*phi) ) recursion.
+     */
+
+    // s = (x, y, z) = (sin(theta)*cos(phi), sin(theta)*sin(phi), cos(theta))
+
+    // handle m=0 separately, since it produces only one coefficient
+    let Pml_2 = 0;
+    let Pml_1 = 1;
+    SHb[result_offset + 0] = Pml_1;
+    for (let l = 1; l < numBands; l++) {
+        const Pml = ((2 * l - 1.0) * Pml_1 * sz - (l - 1.0) * Pml_2) / l;
+        Pml_2 = Pml_1;
+        Pml_1 = Pml;
+        SHb[result_offset + SHindex(0, l)] = Pml;
+    }
+    let Pmm = 1;
+    for (let m = 1; m < numBands; m++) {
+        Pmm = (1.0 - 2 * m) * Pmm;      // See [1], divide by sqrt(1 - sz*sz);
+        Pml_2 = Pmm;
+        Pml_1 = (2 * m + 1.0) * Pmm * sz;
+        // l == m
+        SHb[result_offset + SHindex(-m, m)] = Pml_2;
+        SHb[result_offset + SHindex(m, m)] = Pml_2;
+        if (m + 1 < numBands) {
+            // l == m+1
+            SHb[result_offset + SHindex(-m, m + 1)] = Pml_1;
+            SHb[result_offset + SHindex(m, m + 1)] = Pml_1;
+            for (let l = m + 2; l < numBands; l++) {
+                const Pml = ((2 * l - 1.0) * Pml_1 * sz - (l + m - 1.0) * Pml_2) / (l - m);
+                Pml_2 = Pml_1;
+                Pml_1 = Pml;
+                SHb[result_offset + SHindex(-m, l)] = Pml;
+                SHb[result_offset + SHindex(m, l)] = Pml;
+            }
+        }
+    }
+
+    // At this point, SHb contains the associated Legendre polynomials divided
+    // by sin(theta)^|m|. Below we compute the SH basis.
+    //
+    // ( cos(m*phi), sin(m*phi) ) recursion:
+    // cos(m*phi + phi) == cos(m*phi)*cos(phi) - sin(m*phi)*sin(phi)
+    // sin(m*phi + phi) == sin(m*phi)*cos(phi) + cos(m*phi)*sin(phi)
+    // cos[m+1] == cos[m]*sx - sin[m]*sy
+    // sin[m+1] == sin[m]*sx + cos[m]*sy
+    //
+    // Note that (d.x, d.y) == (cos(phi), sin(phi)) * sin(theta), so the
+    // code below actually evaluates:
+    //      (cos((m*phi), sin(m*phi)) * sin(theta)^|m|
+    let Cm = sx;
+    let Sm = sy;
+    for (let m = 1; m <= numBands; m++) {
+        for (let l = m; l < numBands; l++) {
+            SHb[result_offset + SHindex(-m, l)] *= Sm;
+            SHb[result_offset + SHindex(m, l)] *= Cm;
+        }
+        const Cm1 = Cm * sx - Sm * sy;
+        const Sm1 = Sm * sx + Cm * sy;
+        Cm = Cm1;
+        Sm = Sm1;
+    }
+}
+
+/*
+ * utilities to rotate very low order spherical harmonics (up to 3rd band)
+ * @param {number[]} band1
+ * @param {number[]} M 3x3 matrix
+ * @returns {number[]}
+ */
+function rotateShericalHarmonicBand1(band1, M) {
+
+    // inverse() is not constexpr -- so we pre-calculate it in mathematica
+    //
+    //    constexpr float3 N0{ 1, 0, 0 };
+    //    constexpr float3 N1{ 0, 1, 0 };
+    //    constexpr float3 N2{ 0, 0, 1 };
+    //
+    //    constexpr mat3f A1 = { // this is the projection of N0, N1, N2 to SH space
+    //            float3{ -N0.y, N0.z, -N0.x },
+    //            float3{ -N1.y, N1.z, -N1.x },
+    //            float3{ -N2.y, N2.z, -N2.x }
+    //    };
+    //
+    //    const mat3f invA1 = inverse(A1);
+
+    const invA1TimesK = [
+        0, -1, 0,
+        0, 0, 1,
+        -1, 0, 0
+    ];
+
+    const R1OverK = [
+        -M[1], M[2], -M[0],
+        -M[4], M[5], -M[3],
+        -M[7], M[8], -M[6]
+    ];
+
+
+    mat3.scale(invA1TimesK, invA1TimesK, band1);
+
+
+    mat3.multiply(R1OverK, R1OverK, invA1TimesK );
+
+    return R1OverK;
+}
+
+/**
+ *  This projects a vec3 to SH2/k space (i.e. we premultiply by 1/k)
+ *  below can't be constexpr
+ * @return {number[]} vec5
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ */
+function project_v3_to_sh(x, y, z) {
+    return [
+        (y * x),
+        -(y * z),
+        1 / (2 * M_SQRT_3) * ((3 * z * z - 1)),
+        -(z * x),
+        0.5 * ((x * x - y * y))
+    ];
+}
+
+/**
+ *
+ * @param {number[]} band2 vec5
+ * @param {number[]} M mat3
+ * @return {*}
+ */
+function rotateShericalHarmonicBand2(band2, M) {
+    const n = F_SQRT1_2;
+
+    //  Below we precompute (with help of Mathematica):
+    //    constexpr float3 N0{ 1, 0, 0 };
+    //    constexpr float3 N1{ 0, 0, 1 };
+    //    constexpr float3 N2{ n, n, 0 };
+    //    constexpr float3 N3{ n, 0, n };
+    //    constexpr float3 N4{ 0, n, n };
+    //    constexpr float M_SQRT_PI = 1.7724538509f;
+    //    constexpr float M_SQRT_15 = 3.8729833462f;
+    //    constexpr float k = M_SQRT_15 / (2.0f * M_SQRT_PI);
+    //    --> k * inverse(mat5{project(N0), project(N1), project(N2), project(N3), project(N4)})
+    const invATimesK = [
+        0, 1, 2, 0, 0,
+        -1, 0, 0, 0, -2,
+        0, M_SQRT_3, 0, 0, 0,
+        1, 1, 0, -2, 0,
+        2, 1, 0, 0, 0
+    ];
+
+    // this is: invA * k * band2
+    // 5x5 matrix by vec5 (this a lot of zeroes and constants, which the compiler should eliminate)
+    const invATimesKTimesBand2 = multiply_5d(invATimesK, band2);
+
+    // this is: mat5{project(N0), project(N1), project(N2), project(N3), project(N4)} / k
+    // (the 1/k comes from project(), see above)
+    const ROverK =
+        project_v3_to_sh(M[0], M[1], M[2])                  // M * N0
+            .concat(project_v3_to_sh(M[6], M[7], M[8]))                  // M * N1
+            .concat(project_v3_to_sh(n * (M[0] + M[3]), n * (M[1] + M[4]), n * (M[2] + M[5])))     // M * N2
+            .concat(project_v3_to_sh(n * (M[0] + M[6]), n * (M[1] + M[7]), n * (M[2] + M[8])))     // M * N3
+            .concat(project_v3_to_sh(n * (M[3] + M[6]), n * (M[4] + M[7]), n * (M[5] + M[8])))      // M * N4
+    ;
+
+    // notice how "k" disappears
+    // this is: (R / k) * (invA * k) * band2 == R * invA * band2
+    const result = multiply_5d(ROverK, invATimesKTimesBand2);
+
+    return result;
+}
+
+/*
+ * SH from environment with high dynamic range (or high frequencies -- high dynamic range creates
+ * high frequencies) exhibit "ringing" and negative values when reconstructed.
+ * To mitigate this, we need to low-pass the input image -- or equivalently window the SH by
+ * coefficient that tapper towards zero with the band.
+ *
+ * We use ideas and techniques from
+ *    Stupid Spherical Harmonics (SH)
+ *    Deringing Spherical Harmonics
+ * by Peter-Pike Sloan
+ * https://www.ppsloan.org/publications/shdering.pdf
+ *
+ */
+function sincWindow(l, w) {
+    if (l === 0) {
+        return 1.0;
+    } else if (l >= w) {
+        return 0.0;
+    }
+
+    // we use a sinc window scaled to the desired window size in bands units
+    // a sinc window only has zonal harmonics
+    let x = ((F_PI) * l) / w;
+
+    x = Math.sin(x) / x;
+
+    // The convolution of a SH function f and a ZH function h is just the product of both
+    // scaled by 1 / K(0,l) -- the window coefficients include this scale factor.
+
+    // Taking the window to power N is equivalent to applying the filter N times
+    return Math.pow(x, 4);
+}
+
+/**
+ *
+ * @param {number[]|Float32Array} result sh3
+ * @param {number[]} sh input
+ * @param {number[]} M mat3
+ */
+function rotate_sh3_bands(result, sh, M) {
+
+    const b0 = sh[0];
+    const band1 = [sh[1], sh[2], sh[3]];
+    const b1 = rotateShericalHarmonicBand1(band1, M);
+    const band2 = [sh[4], sh[5], sh[6], sh[7], sh[8]];
+    const b2 = rotateShericalHarmonicBand2(band2, M);
+
+    result[0] = b0;
+
+    result[1] = b1[0];
+    result[2] = b1[1];
+    result[3] = b1[2];
+
+    result[4] = b2[0];
+    result[5] = b2[1];
+    result[6] = b2[2];
+    result[7] = b2[3];
+    result[8] = b2[4];
+}
+
+/**
+ *
+ * @param {number[]} input_sh3 sh3
+ * @returns {number}
+ */
+function shmin(input_sh3) {
+    // See "Deringing Spherical Harmonics" by Peter-Pike Sloan
+    // https://www.ppsloan.org/publications/shdering.pdf
+
+    const M_SQRT_PI = 1.7724538509;
+    const M_SQRT_3 = 1.7320508076;
+    const M_SQRT_5 = 2.2360679775;
+    const M_SQRT_15 = 3.8729833462;
+    const A = [
+        1.0 / (2.0 * M_SQRT_PI),    // 0: 0  0
+        -M_SQRT_3 / (2.0 * M_SQRT_PI),    // 1: 1 -1
+        M_SQRT_3 / (2.0 * M_SQRT_PI),    // 2: 1  0
+        -M_SQRT_3 / (2.0 * M_SQRT_PI),    // 3: 1  1
+        M_SQRT_15 / (2.0 * M_SQRT_PI),    // 4: 2 -2
+        -M_SQRT_15 / (2.0 * M_SQRT_PI),    // 5: 2 -1
+        M_SQRT_5 / (4.0 * M_SQRT_PI),    // 6: 2  0
+        -M_SQRT_15 / (2.0 * M_SQRT_PI),    // 7: 2  1
+        M_SQRT_15 / (4.0 * M_SQRT_PI)     // 8: 2  2
+    ];
+
+    // first this to do is to rotate the SH to align Z with the optimal linear direction
+    const dir = vec3.fromValues(-input_sh3[3], -input_sh3[1], input_sh3[2]);
+
+    vec3.normalize(dir, dir);
+
+    const z_axis = vec3.create();
+    vec3.negate(z_axis, dir);
+
+    const x_axis = vec3.create();
+    vec3.cross(x_axis, z_axis, vec3.fromValues(0, 1, 0));
+    vec3.normalize(x_axis, x_axis);
+
+    const y_axis = vec3.create();
+    vec3.cross(y_axis, x_axis, z_axis);
+
+    const M = mat3.create();
+    array_copy(x_axis, 0, M, 0, 3);
+    array_copy(y_axis, 0, M, 3, 3);
+    array_copy(dir, 0, M, 6, 3);
+
+    mat3.transpose(M, M);
+
+    const f = new Float32Array(9);
+
+    rotate_sh3_bands(f, input_sh3, M);
+    // here we're guaranteed to have normalize(float3{ -f[3], -f[1], f[2] }) == { 0, 0, 1 }
+
+
+    // Find the min for |m| = 2
+    // ------------------------
+    //
+    // Peter-Pike Sloan shows that the minimum can be expressed as a function
+    // of z such as:  m2min = -m2max * (1 - z^2) =  m2max * z^2 - m2max
+    //      with m2max = A[8] * std::sqrt(f[8] * f[8] + f[4] * f[4]);
+    // We can therefore include this in the ZH min computation (which is function of z^2 as well)
+    const m2max = A[8] * Math.sqrt(f[8] * f[8] + f[4] * f[4]);
+
+    // Find the min of the zonal harmonics
+    // -----------------------------------
+    //
+    // This comes from minimizing the function:
+    //      ZH(z) = (A[0] * f[0])
+    //            + (A[2] * f[2]) * z
+    //            + (A[6] * f[6]) * (3 * s.z * s.z - 1)
+    //
+    // We do that by finding where it's derivative d/dz is zero:
+    //      dZH(z)/dz = a * z^2 + b * z + c
+    //      which is zero for z = -b / 2 * a
+    //
+    // We also needs to check that -1 < z < 1, otherwise the min is either in z = -1 or 1
+    //
+    const a = 3 * A[6] * f[6] + m2max;
+    const b = A[2] * f[2];
+    const c = A[0] * f[0] - A[6] * f[6] - m2max;
+
+    const zmin = -b / (2.0 * a);
+    const m0min_z = a * zmin * zmin + b * zmin + c;
+    const m0min_b = min2(a + b + c, a - b + c);
+
+    const m0min = (a > 0 && zmin >= -1 && zmin <= 1) ? m0min_z : m0min_b;
+
+    // Find the min for l = 2, |m| = 1
+    // -------------------------------
+    //
+    // Note l = 1, |m| = 1 is guaranteed to be 0 because of the rotation step
+    //
+    // The function considered is:
+    //        Y(x, y, z) = A[5] * f[5] * s.y * s.z
+    //                   + A[7] * f[7] * s.z * s.x
+    const d = A[4] * Math.sqrt(f[5] * f[5] + f[7] * f[7]);
+
+    // the |m|=1 function is minimal in -0.5 -- use that to skip the Newton's loop when possible
+    let minimum = m0min - 0.5 * d;
+
+    if (minimum < 0) {
+        // We could be negative, to find the minimum we will use Newton's method
+        // See https://en.wikipedia.org/wiki/Newton%27s_method_in_optimization
+
+
+        let dz;
+        let z = -F_SQRT1_2;   // we start guessing at the min of |m|=1 function
+        do {
+            minimum = func_(z, a, b, c, d); // evaluate our function
+            dz = increment_(z, a, b, d); // refine our guess by this amount
+            z = z - dz;
+            // exit if z goes out of range, or if we have reached enough precision
+        } while (Math.abs(z) <= 1 && Math.abs(dz) > 1e-5);
+
+        if (Math.abs(z) > 1) {
+            // z was out of range
+            minimum = min2(func_(1, a, b, c, d), func_(-1, a, b, c, d));
+        }
+    }
+
+    return minimum;
+}
+
+/**
+ * this is the function we're trying to minimize
+ * @param {number} x
+ * @param {number} a
+ * @param {number} b
+ * @param {number} c
+ * @param {number} d
+ * @return {number}
+ */
+function func_(x, a, b, c, d) {
+    // first term accounts for ZH + |m| = 2, second terms for |m| = 1
+    return (a * x * x + b * x + c) + (d * x * Math.sqrt(1 - x * x));
+}
+
+/**
+ * This is func' / func'' -- this was computed with Mathematica
+ * @param {number} x
+ * @param {number} a
+ * @param {number} b
+ * @param {number} d
+ * @return {number}
+ */
+function increment_(x, a, b, d) {
+    return (x * x - 1) * (d - 2 * d * x * x + (b + 2 * a * x) * Math.sqrt(1 - x * x))
+        / (3 * d * x - 2 * d * x * x * x - 2 * a * Math.pow(1 - x * x, 1.5));
+}
+
+/**
+ *
+ * @param {number[]|Float32Array} f sh3
+ * @param {number} cutoff
+ * @param {number} numBands
+ */
+function windowing(f, cutoff, numBands) {
+    for (let l = 0; l < numBands; l++) {
+        const w = sincWindow(l, cutoff);
+        f[SHindex(0, l)] *= w;
+        for (let m = 1; m <= l; m++) {
+            f[SHindex(-m, l)] *= w;
+            f[SHindex(m, l)] *= w;
+        }
+    }
+    return f;
+}
+
+/**
+ *
+ * @param {number[]} output sh3
+ * @param {number} output_offset
+ * @param {number[]} input
+ * @param {number} input_offset
+ * @param {number} numBands
+ * @param {number} channel_count
+ * @param {number} cutoff
+ */
+function windowSH(output, output_offset, input, input_offset, numBands, channel_count, cutoff) {
+    assert.isNonNegativeInteger(channel_count, 'channel_count');
+    assert.greaterThan(channel_count, 0, 'channel_count must be greater than 0');
+
+    assert.greaterThanOrEqual(cutoff, 0, 'cutoff must be >= 0');
+
+    if (cutoff === 0) {
+        // auto windowing (default)
+
+        if (numBands > 3) {
+            // auto-windowing works only for 1, 2 or 3 bands
+            throw new Error("--sh-window=auto can't work with more than 3 bands. Disabling.");
+        }
+
+        cutoff = numBands * 4 + 1;// start at a large band
+        // We need to process each channel separately
+        const SH = new Float32Array(9);
+
+        for (let channel = 0; channel < channel_count; channel++) {
+
+            for (let i = 0; i < numBands * numBands; i++) {
+                SH[i] = output[output_offset + i * channel_count + channel];
+            }
+
+            // find a cut-off band that works
+            let l = numBands;
+            let r = cutoff;
+            for (let i = 0; i < 16 && l + 0.1 < r; i++) {
+                const m = 0.5 * (l + r);
+                if (shmin(windowing(SH, m, numBands)) < 0) {
+                    r = m;
+                } else {
+                    l = m;
+                }
+            }
+
+            cutoff = min2(cutoff, l);
+        }
+    }
+
+    array_copy(input, input_offset, output, output_offset, numBands * numBands * channel_count);
+
+    for (let l = 0; l < numBands; l++) {
+        let w = sincWindow(l, cutoff);
+
+        for (let i = 0; i < channel_count; i++) {
+            output[output_offset + SHindex(0, l) * channel_count + i] = w;
+        }
+
+        for (let m = 1; m <= l; m++) {
+            for (let i = 0; i < channel_count; i++) {
+                output[output_offset + SHindex(-m, l) * channel_count + i] *= w;
+                output[output_offset + SHindex(m, l) * channel_count + i] *= w;
+            }
+        }
+    }
+}
+
+/**
+ *
+ * @param {number[]} result
+ * @param {number} result_offset
+ * @param {number[]} harmonics
+ * @param {number} harmonics_offset
+ * @param {number} dimension_count
+ */
+export function sh3_dering_optimize_positive(result, result_offset, harmonics, harmonics_offset, dimension_count = 3) {
+    windowSH(result, result_offset, harmonics, harmonics_offset, 3, dimension_count, 0);
+}

package/core/geom/3d/sphere/harmonics/sh3_sample_by_direction.js

@@ -0,0 +1,49 @@
+//
+
+/**
+ * Sample value from a 3-band spherical harmonic defined by 9 coefficients
+ *
+ * @see https://github.com/mrdoob/three.js/blob/d081c5a3501d272d19375fab1b01fedf9df29b22/src/math/SphericalHarmonics3.js#L55
+ * @see https://graphics.stanford.edu/papers/envmap/envmap.pdf
+ * @see https://www.ppsloan.org/publications/StupidSH36.pdf
+ * @param {number[]} result Result will be written here
+ * @param {number} result_offset
+ * @param {number[]} harmonics coefficients are read from here
+ * @param {number} harmonics_offset offset into coefficients array where to start reading the data
+ * @param {number} dimension_count number of encoded dimensions, this is essentially a shortcut for multiple harmonics being read at the same time, such as with RGB values
+ * @param {number[]} direction 3d vector read from here, we will read 3 values from here to sample spherical harmonic, direction is assumed to be normalized
+ * @param {number} direction_offset offset into direction array
+ */
+export function sh3_sample_by_direction(
+    result, result_offset,
+    harmonics, harmonics_offset,
+    dimension_count,
+    direction, direction_offset
+) {
+    const x = direction[direction_offset];
+    const y = direction[direction_offset + 1];
+    const z = direction[direction_offset + 2];
+
+    let channel_value;
+
+    for (let i = 0; i < dimension_count; i++) {
+
+        // band 0
+        channel_value = harmonics[harmonics_offset + i] * 0.282095;
+
+        // band 1
+        channel_value += harmonics[harmonics_offset + dimension_count + i] * 0.488603 * y;
+        channel_value += harmonics[harmonics_offset + dimension_count * 2 + i] * 0.488603 * z;
+        channel_value += harmonics[harmonics_offset + dimension_count * 3 + i] * 0.488603 * x;
+
+        // band 2
+        channel_value += harmonics[harmonics_offset + dimension_count * 4 + i] * 1.092548 * (x * y);
+        channel_value += harmonics[harmonics_offset + dimension_count * 5 + i] * 1.092548 * (y * z);
+        channel_value += harmonics[harmonics_offset + dimension_count * 6 + i] * 0.315392 * (3.0 * z * z - 1.0);
+        channel_value += harmonics[harmonics_offset + dimension_count * 7 + i] * 1.092548 * (x * z);
+        channel_value += harmonics[harmonics_offset + dimension_count * 8 + i] * 0.546274 * (x * x - y * y);
+
+        // write out
+        result[result_offset + i] = channel_value;
+    }
+}