@planet-matrix/mobius-model 0.4.0 → 0.6.0

package/src/color/rgb/convert.ts

@@ -0,0 +1,227 @@
+import {
+  internalRoundColorFloat,
+} from "../internal.ts"
+import {
+  internalGetLinearRgbChannelBySrgbChannel,
+  internalGetSrgbChannelByLinearRgbChannel,
+  internalNormalizeHslColorValue,
+  internalNormalizeHsvColorValue,
+  internalNormalizeLinearRgbColorValue,
+  internalNormalizeSrgbColorValue,
+} from "./internal.ts"
+
+import type {
+  HslColorValue,
+  HsvColorValue,
+  LinearRgbColorValue,
+  SrgbColorValue,
+} from "../types.ts"
+
+const internalGetHueByNormalizedRgbChannels = (red: number, green: number, blue: number, delta: number, max: number): number => {
+  if (delta === 0) {
+    return 0
+  }
+
+  let hue = 0
+
+  if (max === red) {
+    hue = 60 * (((green - blue) / delta) % 6)
+  } else if (max === green) {
+    hue = 60 * (((blue - red) / delta) + 2)
+  } else {
+    hue = 60 * (((red - green) / delta) + 4)
+  }
+
+  if (hue < 0) {
+    return hue + 360
+  }
+
+  return hue
+}
+const internalGetNormalizedRgbChannelsByHue = (hue: number, chroma: number): { red: number, green: number, blue: number } => {
+  const segment = hue / 60
+  const secondary = chroma * (1 - Math.abs((segment % 2) - 1))
+
+  if (segment >= 0 && segment < 1) {
+    return { red: chroma, green: secondary, blue: 0 }
+  }
+
+  if (segment >= 1 && segment < 2) {
+    return { red: secondary, green: chroma, blue: 0 }
+  }
+
+  if (segment >= 2 && segment < 3) {
+    return { red: 0, green: chroma, blue: secondary }
+  }
+
+  if (segment >= 3 && segment < 4) {
+    return { red: 0, green: secondary, blue: chroma }
+  }
+
+  if (segment >= 4 && segment < 5) {
+    return { red: secondary, green: 0, blue: chroma }
+  }
+
+  return { red: chroma, green: 0, blue: secondary }
+}
+
+/**
+ * 将 Linear RGB 颜色值转换为 sRGB 颜色值。
+ *
+ * @example
+ * ```
+ * // Expect: { red: 255, green: 0, blue: 0, alpha: 1 }
+ * const example1 = linearRgbColorValueToSrgbColorValue({ red: 1, green: 0, blue: 0, alpha: 1 })
+ *
+ * // Expect: { red: 188, green: 188, blue: 188, alpha: 0.5 }
+ * const example2 = linearRgbColorValueToSrgbColorValue({ red: 0.5, green: 0.5, blue: 0.5, alpha: 0.5 })
+ * ```
+ */
+export const linearRgbColorValueToSrgbColorValue = (color: LinearRgbColorValue): SrgbColorValue => {
+  const normalizedColor = internalNormalizeLinearRgbColorValue(color)
+
+  return internalNormalizeSrgbColorValue({
+    red: internalGetSrgbChannelByLinearRgbChannel(normalizedColor.red, "red"),
+    green: internalGetSrgbChannelByLinearRgbChannel(normalizedColor.green, "green"),
+    blue: internalGetSrgbChannelByLinearRgbChannel(normalizedColor.blue, "blue"),
+    alpha: normalizedColor.alpha,
+  })
+}
+
+/**
+ * 将 sRGB 颜色值转换为 Linear RGB 颜色值。
+ *
+ * @example
+ * ```
+ * // Expect: { red: 1, green: 0, blue: 0, alpha: 1 }
+ * const example1 = srgbColorValueToLinearRgbColorValue({ red: 255, green: 0, blue: 0, alpha: 1 })
+ *
+ * // Expect: { red: 0.215861, green: 0.215861, blue: 0.215861, alpha: 0.5 }
+ * const example2 = srgbColorValueToLinearRgbColorValue({ red: 128, green: 128, blue: 128, alpha: 0.5 })
+ * ```
+ */
+export const srgbColorValueToLinearRgbColorValue = (color: SrgbColorValue): LinearRgbColorValue => {
+  const normalizedColor = internalNormalizeSrgbColorValue(color)
+
+  return internalNormalizeLinearRgbColorValue({
+    red: internalGetLinearRgbChannelBySrgbChannel(normalizedColor.red),
+    green: internalGetLinearRgbChannelBySrgbChannel(normalizedColor.green),
+    blue: internalGetLinearRgbChannelBySrgbChannel(normalizedColor.blue),
+    alpha: normalizedColor.alpha,
+  })
+}
+
+/**
+ * 将 sRGB 颜色值转换为 HSL 颜色值。
+ *
+ * @example
+ * ```
+ * // Expect: { hue: 210, saturation: 0.5, lightness: 0.4, alpha: 1 }
+ * const example1 = srgbColorValueToHslColorValue({ red: 51, green: 102, blue: 153, alpha: 1 })
+ *
+ * // Expect: { hue: 0, saturation: 0, lightness: 0.501961, alpha: 1 }
+ * const example2 = srgbColorValueToHslColorValue({ red: 128, green: 128, blue: 128, alpha: 1 })
+ * ```
+ */
+export const srgbColorValueToHslColorValue = (color: SrgbColorValue): HslColorValue => {
+  const normalizedColor = internalNormalizeSrgbColorValue(color)
+  const red = normalizedColor.red / 255
+  const green = normalizedColor.green / 255
+  const blue = normalizedColor.blue / 255
+  const max = Math.max(red, green, blue)
+  const min = Math.min(red, green, blue)
+  const delta = max - min
+  const lightness = (max + min) / 2
+  const saturation = delta === 0 ? 0 : delta / (1 - Math.abs((2 * lightness) - 1))
+  const hue = internalGetHueByNormalizedRgbChannels(red, green, blue, delta, max)
+
+  return internalNormalizeHslColorValue({
+    hue: internalRoundColorFloat(hue),
+    saturation: internalRoundColorFloat(saturation),
+    lightness: internalRoundColorFloat(lightness),
+    alpha: normalizedColor.alpha,
+  })
+}
+
+/**
+ * 将 HSL 颜色值转换为 sRGB 颜色值。
+ *
+ * @example
+ * ```
+ * // Expect: { red: 51, green: 102, blue: 153, alpha: 1 }
+ * const example1 = hslColorValueToSrgbColorValue({ hue: 210, saturation: 0.5, lightness: 0.4, alpha: 1 })
+ *
+ * // Expect: { red: 128, green: 128, blue: 128, alpha: 1 }
+ * const example2 = hslColorValueToSrgbColorValue({ hue: 0, saturation: 0, lightness: 0.501961, alpha: 1 })
+ * ```
+ */
+export const hslColorValueToSrgbColorValue = (color: HslColorValue): SrgbColorValue => {
+  const normalizedColor = internalNormalizeHslColorValue(color)
+  const chroma = (1 - Math.abs((2 * normalizedColor.lightness) - 1)) * normalizedColor.saturation
+  const channels = internalGetNormalizedRgbChannelsByHue(normalizedColor.hue, chroma)
+  const match = normalizedColor.lightness - (chroma / 2)
+
+  return internalNormalizeSrgbColorValue({
+    red: Math.round((channels.red + match) * 255),
+    green: Math.round((channels.green + match) * 255),
+    blue: Math.round((channels.blue + match) * 255),
+    alpha: normalizedColor.alpha,
+  })
+}
+
+/**
+ * 将 sRGB 颜色值转换为 HSV 颜色值。
+ *
+ * @example
+ * ```
+ * // Expect: { hue: 210, saturation: 0.666667, value: 0.6, alpha: 1 }
+ * const example1 = srgbColorValueToHsvColorValue({ red: 51, green: 102, blue: 153, alpha: 1 })
+ *
+ * // Expect: { hue: 0, saturation: 0, value: 0.501961, alpha: 1 }
+ * const example2 = srgbColorValueToHsvColorValue({ red: 128, green: 128, blue: 128, alpha: 1 })
+ * ```
+ */
+export const srgbColorValueToHsvColorValue = (color: SrgbColorValue): HsvColorValue => {
+  const normalizedColor = internalNormalizeSrgbColorValue(color)
+  const red = normalizedColor.red / 255
+  const green = normalizedColor.green / 255
+  const blue = normalizedColor.blue / 255
+  const max = Math.max(red, green, blue)
+  const min = Math.min(red, green, blue)
+  const delta = max - min
+  const saturation = max === 0 ? 0 : delta / max
+  const hue = internalGetHueByNormalizedRgbChannels(red, green, blue, delta, max)
+
+  return internalNormalizeHsvColorValue({
+    hue: internalRoundColorFloat(hue),
+    saturation: internalRoundColorFloat(saturation),
+    value: internalRoundColorFloat(max),
+    alpha: normalizedColor.alpha,
+  })
+}
+
+/**
+ * 将 HSV 颜色值转换为 sRGB 颜色值。
+ *
+ * @example
+ * ```
+ * // Expect: { red: 51, green: 102, blue: 153, alpha: 1 }
+ * const example1 = hsvColorValueToSrgbColorValue({ hue: 210, saturation: 0.666667, value: 0.6, alpha: 1 })
+ *
+ * // Expect: { red: 128, green: 128, blue: 128, alpha: 1 }
+ * const example2 = hsvColorValueToSrgbColorValue({ hue: 0, saturation: 0, value: 0.501961, alpha: 1 })
+ * ```
+ */
+export const hsvColorValueToSrgbColorValue = (color: HsvColorValue): SrgbColorValue => {
+  const normalizedColor = internalNormalizeHsvColorValue(color)
+  const chroma = normalizedColor.value * normalizedColor.saturation
+  const channels = internalGetNormalizedRgbChannelsByHue(normalizedColor.hue, chroma)
+  const match = normalizedColor.value - chroma
+
+  return internalNormalizeSrgbColorValue({
+    red: Math.round((channels.red + match) * 255),
+    green: Math.round((channels.green + match) * 255),
+    blue: Math.round((channels.blue + match) * 255),
+    alpha: normalizedColor.alpha,
+  })
+}

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"