heygen-com/hyperframes · error · RangeError

A hue curve requires at least three points

Error message

A hue curve requires at least three points

What it means

compileHfHueCurve samples a periodic hue curve around the 0/360-degree circle. Unlike a flat color curve, periodic interpolation needs at least three control points so the spline has interior knots to wrap across the seam. The throw at line 177 rejects arrays with fewer than three points.

Source

Thrown at packages/core/src/colorGradingCurves.ts:177

    throw new RangeError(`A color curve supports at most ${HF_COLOR_CURVE_MAX_POINTS} points`);
  }
  if (points.some(([input]) => input < 0 || input > 1)) {
    throw new RangeError("Color curve inputs must be between 0 and 1");
  }
  if (points[0]?.[0] !== 0 || points[points.length - 1]?.[0] !== 1) {
    throw new RangeError("Color curves must include input endpoints 0 and 1");
  }
  return compileCurveSamples(points, size, (index) => index / (size - 1), 0, 1);
}

/** Samples a periodic hue curve without duplicating the 0/360-degree texel. */
export function compileHfHueCurve(
  points: readonly HfHueCurvePoint[],
  outputMin: number,
  outputMax: number,
  size = HF_COLOR_CURVE_LUT_SIZE,
): Float32Array {
  if (points.length < 3) throw new RangeError("A hue curve requires at least three points");
  if (points.length > HF_COLOR_CURVE_MAX_POINTS) {
    throw new RangeError(`A hue curve supports at most ${HF_COLOR_CURVE_MAX_POINTS} points`);
  }
  const sorted = [...points].sort((a, b) => a[0] - b[0]);
  for (let index = 0; index < sorted.length; index += 1) {
    const point = sorted[index];
    if (!point || point[0] < 0 || point[0] >= 360) {
      throw new RangeError("Hue curve inputs must be from 0 up to 360 degrees");
    }
    if (index > 0 && point[0] === sorted[index - 1]?.[0]) {
      throw new RangeError("Hue curve inputs must be unique");
    }
  }
  const before = sorted.slice(-2).map(([hue, delta]) => [hue - 360, delta] as const);
  const after = sorted.slice(0, 2).map(([hue, delta]) => [hue + 360, delta] as const);
  const periodic = [...before, ...sorted, ...after];
  validateCurvePoints(periodic, size);
  return compileCurveSamples(periodic, size, (index) => (index / size) * 360, outputMin, outputMax);

View on GitHub (pinned to c2996c8626)

Solutions

1. Provide at least three [hueDegrees, delta] points spread across the 0..<360 range.
2. For a no-op hue curve, supply three or more points with delta = 0 (e.g. [[0, 0], [180, 0], [359, 0]]).
3. Validate length upstream with validateHueCurve() from @hyperframes/parsers/color-grading-contract, which enforces the same 3..16 range.

Example fix

// before
compileHfHueCurve([], -1, 1);
compileHfHueCurve([[0, 0.1], [180, -0.1]], -1, 1);

// after — at least three points
compileHfHueCurve([[0, 0.1], [120, 0.0], [240, -0.1]], -1, 1);

function assertHueCurveMinPoints(points: readonly unknown[]): void {
  if (points.length < 3) {
    throw new Error(`Hue curve needs >= 3 points, got ${points.length}`);
  }
}

assertHueCurveMinPoints(points);
compileHfHueCurve(points, -1, 1);

function isHueCurveWithMinPoints(points: readonly unknown[]): points is [number, number][] {
  return Array.isArray(points) && points.length >= 3 && points.length <= 16;
}

try {
  compileHfHueCurve(points, -1, 1);
} catch (err) {
  if (err instanceof RangeError && err.message === 'A hue curve requires at least three points') {
    // fall back to an identity hue curve (>= 3 zero-delta points)
    compileHfHueCurve([[0, 0], [180, 0], [359, 0]], -1, 1);
  } else throw err;
}

When it happens

Trigger: Calling compileHfHueCurve(points, outputMin, outputMax) with points.length of 0, 1, or 2. Note: validateCurvePoints is only reached later (after sorting and the periodic padding), so length < 3 fails here first.

Common situations: Initializing a hue shift with a single default point; passing an empty array as a 'no-op' placeholder; downgrading a dense hue preset to two anchors expecting linear interpolation.

Related errors

• A hue curve supports at most ${HF_COLOR_CURVE_MAX_POINTS} po
• Hue curve inputs must be unique
• Invalid color grading for cell "${label}"
• Invalid color grading for cell "${cell.label}"
• Unknown media-treatment capability: ${id}

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/5561662912ca0007. Report an issue: GitHub.