@planet-matrix/mobius-model 0.5.0 → 0.6.0

package/src/color/rgb/derive.ts

@@ -0,0 +1,303 @@
+import {
+  createLinearRgbColorValue,
+  createSrgbColorValue,
+} from "./construct.ts"
+import {
+  internalAssertColorUnit,
+  internalRoundColorFloat,
+} from "../internal.ts"
+import {
+  linearRgbColorValueToSrgbColorValue,
+  srgbColorValueToLinearRgbColorValue,
+} from "./convert.ts"
+
+import type {
+  LinearRgbColorValue,
+  SrgbColorValue,
+} from "../types.ts"
+
+const internalOpaqueBlackLinearRgbColorValue: LinearRgbColorValue = { red: 0, green: 0, blue: 0, alpha: 1 }
+const internalOpaqueWhiteLinearRgbColorValue: LinearRgbColorValue = { red: 1, green: 1, blue: 1, alpha: 1 }
+const internalOpaqueGrayLinearRgbColorValue: LinearRgbColorValue = { red: 0.5, green: 0.5, blue: 0.5, alpha: 1 }
+
+const internalMixNumber = (first: number, second: number, weight: number): number => {
+  return internalRoundColorFloat((first * (1 - weight)) + (second * weight))
+}
+const internalCompositeLinearRgbChannels = (foreground: number, background: number, foregroundAlpha: number, backgroundAlpha: number, outputAlpha: number): number => {
+  if (outputAlpha === 0) {
+    return 0
+  }
+
+  return internalRoundColorFloat(((foreground * foregroundAlpha) + (background * backgroundAlpha * (1 - foregroundAlpha))) / outputAlpha)
+}
+const internalMixSrgbColorValueWithLinearReference = (color: SrgbColorValue, referenceColor: LinearRgbColorValue, amount: number): SrgbColorValue => {
+  internalAssertColorUnit(amount, "amount")
+  const normalizedColor = createSrgbColorValue(color)
+
+  return linearRgbColorValueToSrgbColorValue(mixLinearRgbColorValues(
+    srgbColorValueToLinearRgbColorValue(normalizedColor),
+    referenceColor,
+    amount,
+  ))
+}
+
+/**
+ * 在 Linear RGB 层混合两个颜色值。
+ *
+ * `weight` 表示第二个颜色值的占比。
+ *
+ * @example
+ * ```
+ * // Expect: { red: 0.5, green: 0, blue: 0.5, alpha: 1 }
+ * const example1 = mixLinearRgbColorValues(
+ *   { red: 1, green: 0, blue: 0, alpha: 1 },
+ *   { red: 0, green: 0, blue: 1, alpha: 1 },
+ *   0.5,
+ * )
+ *
+ * // Expect: { red: 0.75, green: 0.75, blue: 0.75, alpha: 1 }
+ * const example2 = mixLinearRgbColorValues(
+ *   { red: 1, green: 1, blue: 1, alpha: 1 },
+ *   { red: 0, green: 0, blue: 0, alpha: 1 },
+ *   0.25,
+ * )
+ * ```
+ */
+export const mixLinearRgbColorValues = (first: LinearRgbColorValue, second: LinearRgbColorValue, weight = 0.5): LinearRgbColorValue => {
+  internalAssertColorUnit(weight, "weight")
+  const normalizedFirst = createLinearRgbColorValue(first)
+  const normalizedSecond = createLinearRgbColorValue(second)
+
+  return createLinearRgbColorValue({
+    red: internalMixNumber(normalizedFirst.red, normalizedSecond.red, weight),
+    green: internalMixNumber(normalizedFirst.green, normalizedSecond.green, weight),
+    blue: internalMixNumber(normalizedFirst.blue, normalizedSecond.blue, weight),
+    alpha: internalMixNumber(normalizedFirst.alpha, normalizedSecond.alpha, weight),
+  })
+}
+
+/**
+ * 在 sRGB 层混合两个颜色值。
+ *
+ * 该函数会沿合法路径 `sRGB -> Linear RGB -> mix -> sRGB` 计算。
+ *
+ * @example
+ * ```
+ * // Expect: { red: 188, green: 0, blue: 188, alpha: 1 }
+ * const example1 = mixSrgbColorValues(
+ *   { red: 255, green: 0, blue: 0, alpha: 1 },
+ *   { red: 0, green: 0, blue: 255, alpha: 1 },
+ *   0.5,
+ * )
+ *
+ * // Expect: { red: 255, green: 188, blue: 188, alpha: 1 }
+ * const example2 = mixSrgbColorValues(
+ *   { red: 255, green: 0, blue: 0, alpha: 1 },
+ *   { red: 255, green: 255, blue: 255, alpha: 1 },
+ *   0.5,
+ * )
+ * ```
+ */
+export const mixSrgbColorValues = (first: SrgbColorValue, second: SrgbColorValue, weight = 0.5): SrgbColorValue => {
+  internalAssertColorUnit(weight, "weight")
+  const normalizedFirst = createSrgbColorValue(first)
+  const normalizedSecond = createSrgbColorValue(second)
+  const mixedLinearRgbColorValue = mixLinearRgbColorValues(
+    srgbColorValueToLinearRgbColorValue(normalizedFirst),
+    srgbColorValueToLinearRgbColorValue(normalizedSecond),
+    weight,
+  )
+
+  return linearRgbColorValueToSrgbColorValue(mixedLinearRgbColorValue)
+}
+
+/**
+ * 将一个 Linear RGB 前景色合成到另一个 Linear RGB 背景色之上。
+ *
+ * 该函数在支线核心计算层直接执行 alpha 合成。
+ *
+ * @example
+ * ```
+ * // Expect: { red: 0.5, green: 0.5, blue: 1, alpha: 1 }
+ * const example1 = compositeLinearRgbColorValueOverBackground(
+ *   { red: 1, green: 1, blue: 1, alpha: 0.5 },
+ *   { red: 0, green: 0, blue: 1, alpha: 1 },
+ * )
+ *
+ * // Expect: { red: 1, green: 0, blue: 0, alpha: 1 }
+ * const example2 = compositeLinearRgbColorValueOverBackground(
+ *   { red: 1, green: 0, blue: 0, alpha: 1 },
+ *   { red: 0, green: 0, blue: 1, alpha: 1 },
+ * )
+ * ```
+ */
+export const compositeLinearRgbColorValueOverBackground = (foreground: LinearRgbColorValue, background: LinearRgbColorValue): LinearRgbColorValue => {
+  const normalizedForeground = createLinearRgbColorValue(foreground)
+  const normalizedBackground = createLinearRgbColorValue(background)
+  const outputAlpha = internalRoundColorFloat(
+    normalizedForeground.alpha + (normalizedBackground.alpha * (1 - normalizedForeground.alpha)),
+  )
+
+  return createLinearRgbColorValue({
+    red: internalCompositeLinearRgbChannels(
+      normalizedForeground.red,
+      normalizedBackground.red,
+      normalizedForeground.alpha,
+      normalizedBackground.alpha,
+      outputAlpha,
+    ),
+    green: internalCompositeLinearRgbChannels(
+      normalizedForeground.green,
+      normalizedBackground.green,
+      normalizedForeground.alpha,
+      normalizedBackground.alpha,
+      outputAlpha,
+    ),
+    blue: internalCompositeLinearRgbChannels(
+      normalizedForeground.blue,
+      normalizedBackground.blue,
+      normalizedForeground.alpha,
+      normalizedBackground.alpha,
+      outputAlpha,
+    ),
+    alpha: outputAlpha,
+  })
+}
+
+/**
+ * 将一个 sRGB 前景色沿合法路径合成到另一个 sRGB 背景色之上。
+ *
+ * 该函数会沿合法路径 `sRGB -> Linear RGB -> composite -> sRGB` 计算。
+ *
+ * @example
+ * ```
+ * // Expect: { red: 188, green: 188, blue: 255, alpha: 1 }
+ * const example1 = compositeSrgbColorValueOverBackground(
+ *   { red: 255, green: 255, blue: 255, alpha: 0.5 },
+ *   { red: 0, green: 0, blue: 255, alpha: 1 },
+ * )
+ *
+ * // Expect: { red: 255, green: 0, blue: 0, alpha: 1 }
+ * const example2 = compositeSrgbColorValueOverBackground(
+ *   { red: 255, green: 0, blue: 0, alpha: 1 },
+ *   { red: 0, green: 0, blue: 255, alpha: 1 },
+ * )
+ * ```
+ */
+export const compositeSrgbColorValueOverBackground = (foreground: SrgbColorValue, background: SrgbColorValue): SrgbColorValue => {
+  const normalizedForeground = createSrgbColorValue(foreground)
+  const normalizedBackground = createSrgbColorValue(background)
+
+  return linearRgbColorValueToSrgbColorValue(compositeLinearRgbColorValueOverBackground(
+    srgbColorValueToLinearRgbColorValue(normalizedForeground),
+    srgbColorValueToLinearRgbColorValue(normalizedBackground),
+  ))
+}
+
+/**
+ * 调整一个 sRGB 颜色值的透明度。
+ *
+ * @example
+ * ```
+ * // Expect: { red: 51, green: 102, blue: 153, alpha: 0.4 }
+ * const example1 = fadeSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, 0.4)
+ *
+ * // Expect: { red: 51, green: 102, blue: 153, alpha: 0 }
+ * const example2 = fadeSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, 0)
+ * ```
+ */
+export const fadeSrgbColorValue = (color: SrgbColorValue, alpha: number): SrgbColorValue => {
+  internalAssertColorUnit(alpha, "alpha")
+  const normalizedColor = createSrgbColorValue(color)
+
+  return createSrgbColorValue({
+    red: normalizedColor.red,
+    green: normalizedColor.green,
+    blue: normalizedColor.blue,
+    alpha,
+  })
+}
+
+/**
+ * 沿合法路径将一个 sRGB 颜色值向白色方向推进。
+ *
+ * @example
+ * ```
+ * // Expect: { red: 190, green: 198, blue: 212, alpha: 1 }
+ * const example1 = tintSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, 0.5)
+ *
+ * // Expect: { red: 51, green: 102, blue: 153, alpha: 1 }
+ * const example2 = tintSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, 0)
+ * ```
+ */
+export const tintSrgbColorValue = (color: SrgbColorValue, amount: number): SrgbColorValue => {
+  return internalMixSrgbColorValueWithLinearReference(color, internalOpaqueWhiteLinearRgbColorValue, amount)
+}
+
+/**
+ * 沿合法路径将一个 sRGB 颜色值向黑色方向推进。
+ *
+ * @example
+ * ```
+ * // Expect: { red: 35, green: 73, blue: 111, alpha: 1 }
+ * const example1 = shadeSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, 0.5)
+ *
+ * // Expect: { red: 51, green: 102, blue: 153, alpha: 1 }
+ * const example2 = shadeSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, 0)
+ * ```
+ */
+export const shadeSrgbColorValue = (color: SrgbColorValue, amount: number): SrgbColorValue => {
+  return internalMixSrgbColorValueWithLinearReference(color, internalOpaqueBlackLinearRgbColorValue, amount)
+}
+
+/**
+ * 沿合法路径将一个 sRGB 颜色值向中性灰方向推进。
+ *
+ * @example
+ * ```
+ * // Expect: { red: 141, green: 153, blue: 171, alpha: 1 }
+ * const example1 = toneSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, 0.5)
+ *
+ * // Expect: { red: 51, green: 102, blue: 153, alpha: 1 }
+ * const example2 = toneSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, 0)
+ * ```
+ */
+export const toneSrgbColorValue = (color: SrgbColorValue, amount: number): SrgbColorValue => {
+  return internalMixSrgbColorValueWithLinearReference(color, internalOpaqueGrayLinearRgbColorValue, amount)
+}
+
+/**
+ * 沿合法路径提高一个 sRGB 颜色值的亮度倾向。
+ *
+ * 该能力当前等价于向白色混合。
+ *
+ * @example
+ * ```
+ * // Expect: { red: 143, green: 160, blue: 186, alpha: 1 }
+ * const example1 = lightenSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, 0.25)
+ *
+ * // Expect: { red: 51, green: 102, blue: 153, alpha: 1 }
+ * const example2 = lightenSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, 0)
+ * ```
+ */
+export const lightenSrgbColorValue = (color: SrgbColorValue, amount: number): SrgbColorValue => {
+  return tintSrgbColorValue(color, amount)
+}
+
+/**
+ * 沿合法路径降低一个 sRGB 颜色值的亮度倾向。
+ *
+ * 该能力当前等价于向黑色混合。
+ *
+ * @example
+ * ```
+ * // Expect: { red: 44, green: 89, blue: 134, alpha: 1 }
+ * const example1 = darkenSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, 0.25)
+ *
+ * // Expect: { red: 51, green: 102, blue: 153, alpha: 1 }
+ * const example2 = darkenSrgbColorValue({ red: 51, green: 102, blue: 153, alpha: 1 }, 0)
+ * ```
+ */
+export const darkenSrgbColorValue = (color: SrgbColorValue, amount: number): SrgbColorValue => {
+  return shadeSrgbColorValue(color, amount)
+}

package/src/color/rgb/index.ts

@@ -0,0 +1,6 @@
+export * from "./construct.ts"
+export * from "./convert.ts"
+export * from "./parse.ts"
+export * from "./serialize.ts"
+export * from "./analyze.ts"
+export * from "./derive.ts"

package/src/color/rgb/internal.ts

@@ -0,0 +1,208 @@
+import {
+  internalAssertAlpha,
+  internalAssertColorUnit,
+  internalAssertFinite,
+  internalRoundColorFloat,
+} from "../internal.ts"
+
+import type {
+  HslColorValue,
+  HsvColorValue,
+  LinearRgbColorValue,
+  SrgbColorValue,
+} from "../types.ts"
+
+/**
+ * 匹配模块支持的十六进制颜色字符串格式。
+ */
+export const internalHexPattern: RegExp = /^#?(?:[\da-fA-F]{3}|[\da-fA-F]{4}|[\da-fA-F]{6}|[\da-fA-F]{8})$/
+
+/**
+ * 断言一个 sRGB 通道值是合法的 8 位整数。
+ */
+export const internalAssertByte = (value: number, channelName: string): void => {
+  if (Number.isInteger(value) === false || value < 0 || value > 255) {
+    throw new RangeError(`Color channel ${channelName} must be an integer between 0 and 255`)
+  }
+}
+
+/**
+ * 将色相角度规范化到 `0` 到 `360` 之间，`360` 会被折叠为 `0`。
+ */
+export const internalNormalizeHue = (value: number): number => {
+  internalAssertFinite(value, "Color hue")
+
+  const normalizedValue = value % 360
+  if (normalizedValue < 0) {
+    return normalizedValue + 360
+  }
+
+  return normalizedValue
+}
+
+/**
+ * 规范化 Linear RGB 颜色值结构。
+ */
+export const internalNormalizeLinearRgbColorValue = (color: LinearRgbColorValue): LinearRgbColorValue => {
+  internalAssertFinite(color.red, "Color channel red")
+  internalAssertFinite(color.green, "Color channel green")
+  internalAssertFinite(color.blue, "Color channel blue")
+  internalAssertAlpha(color.alpha)
+
+  return {
+    red: color.red,
+    green: color.green,
+    blue: color.blue,
+    alpha: color.alpha,
+  }
+}
+
+/**
+ * 规范化 sRGB 颜色值结构。
+ */
+export const internalNormalizeSrgbColorValue = (color: SrgbColorValue): SrgbColorValue => {
+  internalAssertByte(color.red, "red")
+  internalAssertByte(color.green, "green")
+  internalAssertByte(color.blue, "blue")
+  internalAssertAlpha(color.alpha)
+
+  return {
+    red: color.red,
+    green: color.green,
+    blue: color.blue,
+    alpha: color.alpha,
+  }
+}
+
+/**
+ * 规范化 HSL 颜色值结构。
+ */
+export const internalNormalizeHslColorValue = (color: HslColorValue): HslColorValue => {
+  internalAssertColorUnit(color.saturation, "saturation")
+  internalAssertColorUnit(color.lightness, "lightness")
+  internalAssertAlpha(color.alpha)
+
+  return {
+    hue: internalNormalizeHue(color.hue),
+    saturation: internalRoundColorFloat(color.saturation),
+    lightness: internalRoundColorFloat(color.lightness),
+    alpha: color.alpha,
+  }
+}
+
+/**
+ * 规范化 HSV 颜色值结构。
+ */
+export const internalNormalizeHsvColorValue = (color: HsvColorValue): HsvColorValue => {
+  internalAssertColorUnit(color.saturation, "saturation")
+  internalAssertColorUnit(color.value, "value")
+  internalAssertAlpha(color.alpha)
+
+  return {
+    hue: internalNormalizeHue(color.hue),
+    saturation: internalRoundColorFloat(color.saturation),
+    value: internalRoundColorFloat(color.value),
+    alpha: color.alpha,
+  }
+}
+
+/**
+ * 将短格式十六进制颜色扩展为长格式。
+ */
+export const internalExpandShortHex = (input: string): string => {
+  return input.split("").map(char => `${char}${char}`).join("")
+}
+
+/**
+ * 将 8 位通道值格式化为两位十六进制字符串。
+ */
+export const internalFormatHexByte = (value: number): string => {
+  return value.toString(16).padStart(2, "0").toUpperCase()
+}
+
+/**
+ * 将浮点数格式化为适合颜色字符串的紧凑小数字符串。
+ */
+export const internalFormatAlpha = (value: number): string => {
+  return Number(value.toFixed(4)).toString()
+}
+
+/**
+ * 将 `0` 到 `1` 的单位值格式化为百分比数值字符串，不附带 `%` 符号。
+ */
+export const internalFormatPercentUnit = (value: number): string => {
+  internalAssertColorUnit(value, "unit")
+  return Number((value * 100).toFixed(2)).toString()
+}
+
+/**
+ * 将 RGB 字符串通道解析为合法的 8 位通道值。
+ */
+export const internalParseRgbChannel = (input: string, channelName: string): number => {
+  const value = Number(input)
+  internalAssertByte(value, channelName)
+  return value
+}
+
+/**
+ * 将百分比字符串解析为 `0` 到 `1` 之间的单位值。
+ */
+export const internalParsePercentUnit = (input: string, channelName: string): number => {
+  if (input.endsWith("%") === false) {
+    throw new TypeError(`Invalid ${channelName} percentage input`)
+  }
+
+  return internalRoundColorFloat(Number(input.slice(0, -1)) / 100)
+}
+
+/**
+ * 将 8 位 sRGB 通道值转换为线性光通道值。
+ */
+export const internalGetLinearRgbChannelBySrgbChannel = (value: number): number => {
+  internalAssertByte(value, "sRGB")
+  const normalizedValue = value / 255
+
+  if (normalizedValue <= 0.040_45) {
+    return internalRoundColorFloat(normalizedValue / 12.92)
+  }
+
+  return internalRoundColorFloat(((normalizedValue + 0.055) / 1.055) ** 2.4)
+}
+
+/**
+ * 将线性光通道值转换为 8 位 sRGB 通道值。
+ */
+export const internalGetSrgbChannelByLinearRgbChannel = (value: number, channelName: string): number => {
+  internalAssertFinite(value, `Linear RGB channel ${channelName}`)
+
+  if (value < 0 || value > 1) {
+    throw new RangeError(`Linear RGB channel ${channelName} must be between 0 and 1 to convert to sRGB`)
+  }
+
+  if (value <= 0.003_130_8) {
+    return Math.round(value * 12.92 * 255)
+  }
+
+  return Math.round(((1.055 * (value ** (1 / 2.4))) - 0.055) * 255)
+}
+
+/**
+ * 根据输入字符串稳定生成一个 sRGB 颜色值。
+ */
+export const internalGetStableSrgbColorValueByString = (input: string): SrgbColorValue => {
+  let codePointSum = 0
+
+  for (const char of input) {
+    const codePoint = char.codePointAt(0)
+    if (codePoint !== undefined) {
+      codePointSum = codePointSum + codePoint
+    }
+  }
+
+  return {
+    red: Math.round(Math.abs(Math.sin(codePointSum) * 255)),
+    green: Math.round(Math.abs(Math.sin(codePointSum + 1) * 255)),
+    blue: Math.round(Math.abs(Math.sin(codePointSum + 2) * 255)),
+    alpha: 1,
+  }
+}