Skip to content

Open source CapCut alternative.

TypeScript
11.6 KB
Raw Blame
/** A tone-curve control point: [input, output], both 0..255. */
export type CurvePoint = [number, number];

/** Per-channel tone curves; an absent channel is identity. */
export interface GradeCurves {
  m?: CurvePoint[];
  r?: CurvePoint[];
  g?: CurvePoint[];
  b?: CurvePoint[];
}

/** A color wheel's state: [dx, dy, luma], each -50..50. dx/dy is the puck's
 * position on the wheel (a chroma offset direction and strength); luma is the
 * per-range brightness trim. */
export type WheelTuple = [number, number, number];

/** The four wheels: lift (s), gamma (m), gain (h) and offset (o); an absent
 * wheel is neutral. */
export interface GradeWheels {
  s?: WheelTuple;
  m?: WheelTuple;
  h?: WheelTuple;
  o?: WheelTuple;
}

export type HslBand =
  | "red"
  | "orange"
  | "yellow"
  | "green"
  | "aqua"
  | "blue"
  | "purple"
  | "magenta";

/** A hue band's adjustments: [hueShift, saturation, luminance], each -50..50.
 * hueShift spans about ±30 degrees at full range. */
export type HslTuple = [number, number, number];

/** A preset layered over the manual adjustments. `amount` 0..1 scales the
 * preset toward neutral (default 1); `skin` keeps the preset's color shifts
 * off skin tones. Unknown ids render as neutral, so docs can carry presets
 * from newer catalogs without breaking. */
export interface GradePresetRef {
  id: string;
  amount?: number;
  skin?: boolean;
}

/** A library LUT applied to the clip before the grade. `id` is the library
 * asset id (`lut:<contentKey>`); `amount` 0..1 mixes the LUT's result with
 * its input (default 1). */
export interface GradeLutRef {
  id: string;
  amount?: number;
}

/** Per-clip color adjustments. Integer sliders, 0 = neutral; every field is
 * absent when neutral, so untouched clips carry nothing. */
export interface ColorGrade {
  brightness?: number; // -50..50 (legacy; stored docs only)
  contrast?: number; // -50..50
  saturation?: number; // -50..50
  exposure?: number; // -50..50 (±2 stops)
  temperature?: number; // -50..50, positive = warm (±100 mireds)
  tint?: number; // -50..50, negative = green, positive = magenta
  hue?: number; // -180..180 degrees (legacy; stored docs only)
  highlights?: number; // -50..50
  shadows?: number; // -50..50
  whites?: number; // -50..50
  blacks?: number; // -50..50
  brilliance?: number; // -50..50
  vibrance?: number; // -50..50
  fade?: number; // 0..50, lifted blacks
  sharpen?: number; // 0..50, spatial
  clarity?: number; // 0..50, spatial
  curves?: GradeCurves;
  wheels?: GradeWheels;
  hsl?: Partial<Record<HslBand, HslTuple>>;
  preset?: GradePresetRef;
  lut?: GradeLutRef;
}

/** Slider range for every grade parameter except hue. */
export const GRADE_MAX = 50;
export const GRADE_HUE_MAX = 180;

export type GradeBasicKey =
  | "exposure"
  | "contrast"
  | "highlights"
  | "shadows"
  | "whites"
  | "blacks"
  | "brilliance"
  | "fade"
  | "temperature"
  | "tint"
  | "saturation"
  | "vibrance";

/** The Basic tool's slider rows; the UI and the AI tool schema both derive
 * from this list. Legacy `brightness` and `hue` stay in the model and render
 * everywhere, surfaced by the UI only when a stored grade carries them.
 * `min` is 0 for the one-sided sliders. */
export const GRADE_BASIC_FIELDS: {
  key: GradeBasicKey;
  label: string;
  group: "light" | "color";
  min: number;
}[] = [
  { key: "exposure", label: "Exposure", group: "light", min: -GRADE_MAX },
  { key: "contrast", label: "Contrast", group: "light", min: -GRADE_MAX },
  { key: "highlights", label: "Highlights", group: "light", min: -GRADE_MAX },
  { key: "shadows", label: "Shadows", group: "light", min: -GRADE_MAX },
  { key: "whites", label: "Whites", group: "light", min: -GRADE_MAX },
  { key: "blacks", label: "Blacks", group: "light", min: -GRADE_MAX },
  { key: "brilliance", label: "Brilliance", group: "light", min: -GRADE_MAX },
  { key: "fade", label: "Fade", group: "light", min: 0 },
  { key: "temperature", label: "Temperature", group: "color", min: -GRADE_MAX },
  { key: "tint", label: "Tint", group: "color", min: -GRADE_MAX },
  { key: "saturation", label: "Saturation", group: "color", min: -GRADE_MAX },
  { key: "vibrance", label: "Vibrance", group: "color", min: -GRADE_MAX },
];

export type GradeDetailKey = "sharpen" | "clarity";

/** The spatial controls: applied on the picture after the LUT, so they are
 * left out of the LUT and its key. */
export const GRADE_DETAIL_FIELDS: { key: GradeDetailKey; label: string; min: number }[] = [
  { key: "sharpen", label: "Sharpen", min: 0 },
  { key: "clarity", label: "Clarity", min: 0 },
];

/** The HSL tool's hue bands: chip swatch plus the band's center hue used by
 * the renderer's feathered band weights. */
export const HSL_BANDS: { id: HslBand; label: string; center: number; swatch: string }[] = [
  { id: "red", label: "Red", center: 0, swatch: "hsl(0 70% 55%)" },
  { id: "orange", label: "Orange", center: 30, swatch: "hsl(30 70% 55%)" },
  { id: "yellow", label: "Yellow", center: 60, swatch: "hsl(55 70% 55%)" },
  { id: "green", label: "Green", center: 120, swatch: "hsl(110 60% 45%)" },
  { id: "aqua", label: "Aqua", center: 180, swatch: "hsl(178 60% 50%)" },
  { id: "blue", label: "Blue", center: 240, swatch: "hsl(222 70% 55%)" },
  { id: "purple", label: "Purple", center: 285, swatch: "hsl(275 60% 55%)" },
  { id: "magenta", label: "Magenta", center: 330, swatch: "hsl(320 65% 55%)" },
];

/** The wheels, in the order the tool shows them. */
export const WHEEL_ZONES = ["s", "m", "h", "o"] as const;
export type WheelZone = (typeof WHEEL_ZONES)[number];

export const WHEEL_LABELS: Record<WheelZone, string> = {
  s: "Lift",
  m: "Gamma",
  h: "Gain",
  o: "Offset",
};

/** Every scalar slider with its range: [key, min, max]. */
export const GRADE_SCALAR_FIELDS: [keyof ColorGrade & string, number, number][] = [
  ["brightness", -GRADE_MAX, GRADE_MAX],
  ["contrast", -GRADE_MAX, GRADE_MAX],
  ["saturation", -GRADE_MAX, GRADE_MAX],
  ["exposure", -GRADE_MAX, GRADE_MAX],
  ["temperature", -GRADE_MAX, GRADE_MAX],
  ["tint", -GRADE_MAX, GRADE_MAX],
  ["hue", -GRADE_HUE_MAX, GRADE_HUE_MAX],
  ["highlights", -GRADE_MAX, GRADE_MAX],
  ["shadows", -GRADE_MAX, GRADE_MAX],
  ["whites", -GRADE_MAX, GRADE_MAX],
  ["blacks", -GRADE_MAX, GRADE_MAX],
  ["brilliance", -GRADE_MAX, GRADE_MAX],
  ["vibrance", -GRADE_MAX, GRADE_MAX],
  ["fade", 0, GRADE_MAX],
  ["sharpen", 0, GRADE_MAX],
  ["clarity", 0, GRADE_MAX],
];

export type GradeScalarKey =
  | "brightness"
  | "contrast"
  | "saturation"
  | "exposure"
  | "temperature"
  | "tint"
  | "hue"
  | "highlights"
  | "shadows"
  | "whites"
  | "blacks"
  | "brilliance"
  | "vibrance"
  | "fade"
  | "sharpen"
  | "clarity";

/** The scalar fields that bake into the LUT; sharpen and clarity are spatial. */
export const GRADE_LUT_SCALAR_KEYS: GradeScalarKey[] = GRADE_SCALAR_FIELDS.map(([k]) => k as GradeScalarKey).filter(
  (k) => k !== "sharpen" && k !== "clarity"
);

const clampRange = (v: unknown, min: number, max: number) => {
  const n = typeof v === "number" && Number.isFinite(v) ? v : 0;
  return Math.max(min, Math.min(max, n));
};

const CURVE_CHANNELS = ["m", "r", "g", "b"] as const;

/** Clamp a stored curve into shape: integer points inside 0..255, sorted by
 * input, one point per input; identity or degenerate curves become absent. */
function normalizeCurve(pts: unknown): CurvePoint[] | undefined {
  if (!Array.isArray(pts)) return undefined;
  const byInput = new Map<number, number>();
  for (const p of pts) {
    if (!Array.isArray(p) || p.length < 2) continue;
    const x = Math.max(0, Math.min(255, Math.round(Number(p[0]) || 0)));
    const y = Math.max(0, Math.min(255, Math.round(Number(p[1]) || 0)));
    byInput.set(x, y);
  }
  const out = [...byInput.entries()].sort((a, b) => a[0] - b[0]).map(([x, y]) => [x, y] as CurvePoint);
  if (out.length < 2) return undefined;
  if (out.every(([x, y]) => x === y)) return undefined;
  return out;
}

function normalizeTuple(t: unknown, max = GRADE_MAX): [number, number, number] | undefined {
  if (!Array.isArray(t)) return undefined;
  const out: [number, number, number] = [
    Math.round(clampRange(t[0], -max, max)),
    Math.round(clampRange(t[1], -max, max)),
    Math.round(clampRange(t[2], -max, max)),
  ];
  return out.some((v) => v !== 0) ? out : undefined;
}

export function isNeutralGrade(g: ColorGrade | undefined | null): boolean {
  return !g || normalizeGrade(g) === undefined;
}

/** True when the given Adjust tool holds a non-neutral value; drives the
 * panel's per-tool dirty dots. */
export function gradeToolDirty(
  g: ColorGrade | undefined | null,
  tool: "basic" | "curves" | "wheels" | "hsl" | "detail" | "lut"
): boolean {
  const n = normalizeGrade(g);
  if (!n) return false;
  if (tool === "curves") return !!n.curves;
  if (tool === "wheels") return !!n.wheels;
  if (tool === "hsl") return !!n.hsl;
  if (tool === "lut") return !!n.lut;
  if (tool === "detail") return GRADE_DETAIL_FIELDS.some((f) => n[f.key]);
  return GRADE_SCALAR_FIELDS.some(([k]) => k !== "sharpen" && k !== "clarity" && n[k as GradeScalarKey]);
}

/** Clamp to slider ranges, drop zeros and identity shapes; an all-neutral
 * grade becomes absent. Also the sanitizer for grades arriving as client
 * JSON. Preset and LUT ids are kept structurally — an id the running catalog
 * or library does not know renders as neutral instead of being stripped from
 * the doc. */
export function normalizeGrade(g: ColorGrade | undefined | null): ColorGrade | undefined {
  if (!g) return undefined;
  const out: ColorGrade = {};
  for (const [k, min, max] of GRADE_SCALAR_FIELDS) {
    const v = clampRange(g[k as GradeScalarKey], min, max);
    if (v !== 0) out[k as GradeScalarKey] = v;
  }
  if (g.curves && typeof g.curves === "object") {
    const curves: GradeCurves = {};
    for (const ch of CURVE_CHANNELS) {
      const c = normalizeCurve(g.curves[ch]);
      if (c) curves[ch] = c;
    }
    if (Object.keys(curves).length) out.curves = curves;
  }
  if (g.wheels && typeof g.wheels === "object") {
    const wheels: GradeWheels = {};
    for (const z of WHEEL_ZONES) {
      const w = normalizeTuple(g.wheels[z]);
      if (w) wheels[z] = w;
    }
    if (Object.keys(wheels).length) out.wheels = wheels;
  }
  if (g.hsl && typeof g.hsl === "object") {
    const hsl: Partial<Record<HslBand, HslTuple>> = {};
    for (const band of HSL_BANDS) {
      const t = normalizeTuple((g.hsl as Record<string, unknown>)[band.id]);
      if (t) hsl[band.id] = t;
    }
    if (Object.keys(hsl).length) out.hsl = hsl;
  }
  if (g.preset && typeof g.preset.id === "string" && g.preset.id) {
    const amount = Math.max(
      0,
      Math.min(1, typeof g.preset.amount === "number" && Number.isFinite(g.preset.amount) ? g.preset.amount : 1)
    );
    // Amount 0 is a preset turned all the way down, still applied — the tile
    // stays picked and the intensity slider can ride back up.
    out.preset = {
      id: g.preset.id,
      ...(amount !== 1 ? { amount } : {}),
      ...(g.preset.skin ? { skin: true } : {}),
    };
  }
  if (g.lut && typeof g.lut.id === "string" && g.lut.id) {
    const amount = Math.max(
      0,
      Math.min(1, typeof g.lut.amount === "number" && Number.isFinite(g.lut.amount) ? g.lut.amount : 1)
    );
    out.lut = { id: g.lut.id, ...(amount !== 1 ? { amount } : {}) };
  }
  return Object.keys(out).length ? out : undefined;
}

/** The grade without its spatial controls: what the LUT bakes. */
export function gradeWithoutDetail(g: ColorGrade | undefined | null): ColorGrade | undefined {
  const n = normalizeGrade(g);
  if (!n) return undefined;
  if (!n.sharpen && !n.clarity) return n;
  const out = { ...n };
  delete out.sharpen;
  delete out.clarity;
  return Object.keys(out).length ? out : undefined;
}