@planet-matrix/mobius-model 0.5.0 → 0.6.0

package/src/color/rgb/parse.ts

@@ -0,0 +1,302 @@
+import { internalAssertAlpha } from "../internal.ts"
+import {
+  createHslColorValue,
+  createHsvColorValue,
+  createSrgbColorValue,
+} from "./construct.ts"
+import {
+  hslColorValueToSrgbColorValue,
+  hsvColorValueToSrgbColorValue,
+} from "./convert.ts"
+import {
+  internalExpandShortHex,
+  internalHexPattern,
+  internalParsePercentUnit,
+  internalParseRgbChannel,
+} from "./internal.ts"
+
+import type {
+  HslColorValue,
+  HsvColorValue,
+  SrgbColorValue,
+} from "../types.ts"
+
+/**
+ * 判断输入是否为合法的十六进制颜色字符串。
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = isHexColorString("#F0A")
+ *
+ * // Expect: false
+ * const example2 = isHexColorString("#12")
+ * ```
+ */
+export const isHexColorString = (input: string): boolean => {
+  return internalHexPattern.test(input.trim())
+}
+
+/**
+ * 将十六进制颜色字符串解析为 sRGB 颜色值对象。
+ *
+ * @example
+ * ```
+ * // Expect: { red: 255, green: 0, blue: 170, alpha: 1 }
+ * const example1 = hexColorStringToSrgbColorValue("#F0A")
+ *
+ * // Expect: { red: 17, green: 34, blue: 51, alpha: 0.2667 }
+ * const example2 = hexColorStringToSrgbColorValue("#11223344")
+ * ```
+ */
+export const hexColorStringToSrgbColorValue = (input: string): SrgbColorValue => {
+  const normalizedInput = input.trim()
+  if (isHexColorString(normalizedInput) === false) {
+    throw new TypeError("Invalid hex color input")
+  }
+
+  const hex = normalizedInput.startsWith("#") ? normalizedInput.slice(1) : normalizedInput
+  const expandedHex = hex.length === 3 || hex.length === 4 ? internalExpandShortHex(hex) : hex
+  const red = Number.parseInt(expandedHex.slice(0, 2), 16)
+  const green = Number.parseInt(expandedHex.slice(2, 4), 16)
+  const blue = Number.parseInt(expandedHex.slice(4, 6), 16)
+  const alpha = expandedHex.length === 8
+    ? Number((Number.parseInt(expandedHex.slice(6, 8), 16) / 255).toFixed(4))
+    : 1
+
+  return createSrgbColorValue({ red, green, blue, alpha })
+}
+
+const internalParseRgbParts = (input: string, allowAlpha: boolean): SrgbColorValue => {
+  const rgbMatch = /^rgba?\((.*)\)$/i.exec(input)
+  if (rgbMatch === null) {
+    throw new TypeError("Invalid color string input")
+  }
+
+  const partsSource = rgbMatch[1]
+  if (partsSource === undefined) {
+    throw new TypeError("Invalid color string input")
+  }
+
+  const parts = partsSource.split(",").map(part => part.trim())
+  if (allowAlpha === true && parts.length !== 4) {
+    throw new TypeError("Invalid RGBA color string input")
+  }
+
+  if (allowAlpha === false && parts.length !== 3) {
+    throw new TypeError("Invalid RGB color string input")
+  }
+
+  const [redPart = "", greenPart = "", bluePart = "", alphaPart] = parts
+  const red = internalParseRgbChannel(redPart, "red")
+  const green = internalParseRgbChannel(greenPart, "green")
+  const blue = internalParseRgbChannel(bluePart, "blue")
+  const alpha = allowAlpha === true ? Number(alphaPart) : 1
+
+  return createSrgbColorValue({ red, green, blue, alpha })
+}
+
+/**
+ * 将 `rgb(r, g, b)` 字符串解析为 sRGB 颜色值对象。
+ *
+ * @example
+ * ```
+ * // Expect: { red: 51, green: 102, blue: 153, alpha: 1 }
+ * const example1 = rgbColorStringToSrgbColorValue("rgb(51, 102, 153)")
+ *
+ * // Expect: { red: 0, green: 0, blue: 0, alpha: 1 }
+ * const example2 = rgbColorStringToSrgbColorValue("rgb(0, 0, 0)")
+ * ```
+ */
+export const rgbColorStringToSrgbColorValue = (input: string): SrgbColorValue => {
+  return internalParseRgbParts(input.trim(), false)
+}
+
+/**
+ * 将 `rgba(r, g, b, a)` 字符串解析为 sRGB 颜色值对象。
+ *
+ * @example
+ * ```
+ * // Expect: { red: 51, green: 102, blue: 153, alpha: 0.5 }
+ * const example1 = rgbaColorStringToSrgbColorValue("rgba(51, 102, 153, 0.5)")
+ *
+ * // Expect: { red: 255, green: 255, blue: 255, alpha: 1 }
+ * const example2 = rgbaColorStringToSrgbColorValue("rgba(255, 255, 255, 1)")
+ * ```
+ */
+export const rgbaColorStringToSrgbColorValue = (input: string): SrgbColorValue => {
+  return internalParseRgbParts(input.trim(), true)
+}
+
+const internalParseHslParts = (input: string, allowAlpha: boolean): HslColorValue => {
+  const hslMatch = /^hsla?\((.*)\)$/i.exec(input)
+  if (hslMatch === null) {
+    throw new TypeError("Invalid color string input")
+  }
+
+  const partsSource = hslMatch[1]
+  if (partsSource === undefined) {
+    throw new TypeError("Invalid color string input")
+  }
+
+  const parts = partsSource.split(",").map(part => part.trim())
+  if (allowAlpha === true && parts.length !== 4) {
+    throw new TypeError("Invalid HSLA color string input")
+  }
+
+  if (allowAlpha === false && parts.length !== 3) {
+    throw new TypeError("Invalid HSL color string input")
+  }
+
+  const [huePart = "", saturationPart = "", lightnessPart = "", alphaPart] = parts
+  const hue = Number(huePart)
+  const saturation = internalParsePercentUnit(saturationPart, "saturation")
+  const lightness = internalParsePercentUnit(lightnessPart, "lightness")
+  const alpha = allowAlpha === true ? Number(alphaPart) : 1
+  internalAssertAlpha(alpha)
+
+  return createHslColorValue({ hue, saturation, lightness, alpha })
+}
+
+/**
+ * 将 `hsl(h, s%, l%)` 字符串解析为 HSL 颜色值对象。
+ *
+ * @example
+ * ```
+ * // Expect: { hue: 210, saturation: 0.5, lightness: 0.4, alpha: 1 }
+ * const example1 = hslColorStringToHslColorValue("hsl(210, 50%, 40%)")
+ *
+ * // Expect: { hue: 330, saturation: 0.5, lightness: 0.4, alpha: 1 }
+ * const example2 = hslColorStringToHslColorValue("hsl(-30, 50%, 40%)")
+ * ```
+ */
+export const hslColorStringToHslColorValue = (input: string): HslColorValue => {
+  return internalParseHslParts(input.trim(), false)
+}
+
+/**
+ * 将 `hsla(h, s%, l%, a)` 字符串解析为 HSL 颜色值对象。
+ *
+ * @example
+ * ```
+ * // Expect: { hue: 210, saturation: 0.5, lightness: 0.4, alpha: 0.5 }
+ * const example1 = hslaColorStringToHslColorValue("hsla(210, 50%, 40%, 0.5)")
+ *
+ * // Expect: { hue: 0, saturation: 0, lightness: 1, alpha: 1 }
+ * const example2 = hslaColorStringToHslColorValue("hsla(0, 0%, 100%, 1)")
+ * ```
+ */
+export const hslaColorStringToHslColorValue = (input: string): HslColorValue => {
+  return internalParseHslParts(input.trim(), true)
+}
+
+const internalParseHsvParts = (input: string, allowAlpha: boolean): HsvColorValue => {
+  const hsvMatch = /^hsva?\((.*)\)$/i.exec(input)
+  if (hsvMatch === null) {
+    throw new TypeError("Invalid color string input")
+  }
+
+  const partsSource = hsvMatch[1]
+  if (partsSource === undefined) {
+    throw new TypeError("Invalid color string input")
+  }
+
+  const parts = partsSource.split(",").map(part => part.trim())
+  if (allowAlpha === true && parts.length !== 4) {
+    throw new TypeError("Invalid HSVA color string input")
+  }
+
+  if (allowAlpha === false && parts.length !== 3) {
+    throw new TypeError("Invalid HSV color string input")
+  }
+
+  const [huePart = "", saturationPart = "", valuePart = "", alphaPart] = parts
+  const hue = Number(huePart)
+  const saturation = internalParsePercentUnit(saturationPart, "saturation")
+  const value = internalParsePercentUnit(valuePart, "value")
+  const alpha = allowAlpha === true ? Number(alphaPart) : 1
+  internalAssertAlpha(alpha)
+
+  return createHsvColorValue({ hue, saturation, value, alpha })
+}
+
+/**
+ * 将 `hsv(h, s%, v%)` 字符串解析为 HSV 颜色值对象。
+ *
+ * @example
+ * ```
+ * // Expect: { hue: 210, saturation: 0.6667, value: 0.6, alpha: 1 }
+ * const example1 = hsvColorStringToHsvColorValue("hsv(210, 66.67%, 60%)")
+ *
+ * // Expect: { hue: 30, saturation: 0.5, value: 0.6, alpha: 1 }
+ * const example2 = hsvColorStringToHsvColorValue("hsv(390, 50%, 60%)")
+ * ```
+ */
+export const hsvColorStringToHsvColorValue = (input: string): HsvColorValue => {
+  return internalParseHsvParts(input.trim(), false)
+}
+
+/**
+ * 将 `hsva(h, s%, v%, a)` 字符串解析为 HSV 颜色值对象。
+ *
+ * @example
+ * ```
+ * // Expect: { hue: 210, saturation: 0.6667, value: 0.6, alpha: 0.5 }
+ * const example1 = hsvaColorStringToHsvColorValue("hsva(210, 66.67%, 60%, 0.5)")
+ *
+ * // Expect: { hue: 0, saturation: 0, value: 1, alpha: 1 }
+ * const example2 = hsvaColorStringToHsvColorValue("hsva(0, 0%, 100%, 1)")
+ * ```
+ */
+export const hsvaColorStringToHsvColorValue = (input: string): HsvColorValue => {
+  return internalParseHsvParts(input.trim(), true)
+}
+
+/**
+ * 将异构颜色字符串归一化为 sRGB 颜色值对象。
+ *
+ * 这是一个面向最终显示层的归一化入口。它会有意把十六进制、RGB、HSL 与 HSV
+ * 等不同语义层的字符串统一折叠为 sRGB；如果调用方需要保留输入本身的颜色语义，
+ * 应改用对应的专用解析函数。
+ *
+ * @example
+ * ```
+ * // Expect: { red: 51, green: 102, blue: 153, alpha: 1 }
+ * const example1 = colorStringToSrgbColorValue("#336699")
+ *
+ * // Expect: { red: 51, green: 102, blue: 153, alpha: 1 }
+ * const example2 = colorStringToSrgbColorValue("hsl(210, 50%, 40%)")
+ * ```
+ */
+export const colorStringToSrgbColorValue = (input: string): SrgbColorValue => {
+  const normalizedInput = input.trim()
+  if (normalizedInput.startsWith("#") || isHexColorString(normalizedInput) === true) {
+    return hexColorStringToSrgbColorValue(normalizedInput)
+  }
+
+  if (normalizedInput.toLowerCase().startsWith("rgba(")) {
+    return rgbaColorStringToSrgbColorValue(normalizedInput)
+  }
+
+  if (normalizedInput.toLowerCase().startsWith("rgb(")) {
+    return rgbColorStringToSrgbColorValue(normalizedInput)
+  }
+
+  if (normalizedInput.toLowerCase().startsWith("hsla(")) {
+    return hslColorValueToSrgbColorValue(hslaColorStringToHslColorValue(normalizedInput))
+  }
+
+  if (normalizedInput.toLowerCase().startsWith("hsl(")) {
+    return hslColorValueToSrgbColorValue(hslColorStringToHslColorValue(normalizedInput))
+  }
+
+  if (normalizedInput.toLowerCase().startsWith("hsva(")) {
+    return hsvColorValueToSrgbColorValue(hsvaColorStringToHsvColorValue(normalizedInput))
+  }
+
+  if (normalizedInput.toLowerCase().startsWith("hsv(")) {
+    return hsvColorValueToSrgbColorValue(hsvColorStringToHsvColorValue(normalizedInput))
+  }
+
+  throw new TypeError("Invalid color string input")
+}

package/src/color/rgb/serialize.ts

@@ -0,0 +1,144 @@
+import {
+  createHslColorValue,
+  createHsvColorValue,
+  createSrgbColorValue,
+} from "./construct.ts"
+import {
+  internalFormatAlpha,
+  internalFormatHexByte,
+  internalFormatPercentUnit,
+} from "./internal.ts"
+
+import type {
+  HslColorValue,
+  HsvColorValue,
+  SrgbColorValue,
+} from "../types.ts"
+
+/**
+ * 将 sRGB 颜色值序列化为十六进制颜色字符串。
+ *
+ * @example
+ * ```
+ * // Expect: #336699
+ * const example1 = srgbColorValueToHexColorString({ red: 51, green: 102, blue: 153, alpha: 0.5 })
+ *
+ * // Expect: #33669980
+ * const example2 = srgbColorValueToHexColorString({ red: 51, green: 102, blue: 153, alpha: 0.5 }, { includeAlpha: true })
+ * ```
+ */
+export const srgbColorValueToHexColorString = (color: SrgbColorValue, options: { includeAlpha?: boolean } = {}): string => {
+  const normalizedColor = createSrgbColorValue(color)
+  const hex = [normalizedColor.red, normalizedColor.green, normalizedColor.blue]
+    .map(value => internalFormatHexByte(value))
+    .join("")
+
+  if (options.includeAlpha === true) {
+    const alphaByte = Math.round(normalizedColor.alpha * 255)
+    return `#${hex}${internalFormatHexByte(alphaByte)}`
+  }
+
+  return `#${hex}`
+}
+
+/**
+ * 将 sRGB 颜色值序列化为 `rgb(...)` 字符串。
+ *
+ * @example
+ * ```
+ * // Expect: rgb(51, 102, 153)
+ * const example1 = srgbColorValueToRgbColorString({ red: 51, green: 102, blue: 153, alpha: 0.5 })
+ *
+ * // Expect: rgb(0, 0, 0)
+ * const example2 = srgbColorValueToRgbColorString({ red: 0, green: 0, blue: 0, alpha: 1 })
+ * ```
+ */
+export const srgbColorValueToRgbColorString = (color: SrgbColorValue): string => {
+  const normalizedColor = createSrgbColorValue(color)
+  return `rgb(${normalizedColor.red}, ${normalizedColor.green}, ${normalizedColor.blue})`
+}
+
+/**
+ * 将 sRGB 颜色值序列化为 `rgba(...)` 字符串。
+ *
+ * @example
+ * ```
+ * // Expect: rgba(51, 102, 153, 0.5)
+ * const example1 = srgbColorValueToRgbaColorString({ red: 51, green: 102, blue: 153, alpha: 0.5 })
+ *
+ * // Expect: rgba(255, 255, 255, 1)
+ * const example2 = srgbColorValueToRgbaColorString({ red: 255, green: 255, blue: 255, alpha: 1 })
+ * ```
+ */
+export const srgbColorValueToRgbaColorString = (color: SrgbColorValue): string => {
+  const normalizedColor = createSrgbColorValue(color)
+  return `rgba(${normalizedColor.red}, ${normalizedColor.green}, ${normalizedColor.blue}, ${internalFormatAlpha(normalizedColor.alpha)})`
+}
+
+/**
+ * 将 HSL 颜色值序列化为 `hsl(...)` 字符串。
+ *
+ * @example
+ * ```
+ * // Expect: hsl(210, 50%, 40%)
+ * const example1 = hslColorValueToHslColorString({ hue: 210, saturation: 0.5, lightness: 0.4, alpha: 0.5 })
+ *
+ * // Expect: hsl(0, 0%, 100%)
+ * const example2 = hslColorValueToHslColorString({ hue: 0, saturation: 0, lightness: 1, alpha: 1 })
+ * ```
+ */
+export const hslColorValueToHslColorString = (color: HslColorValue): string => {
+  const normalizedColor = createHslColorValue(color)
+  return `hsl(${normalizedColor.hue}, ${internalFormatPercentUnit(normalizedColor.saturation)}%, ${internalFormatPercentUnit(normalizedColor.lightness)}%)`
+}
+
+/**
+ * 将 HSL 颜色值序列化为 `hsla(...)` 字符串。
+ *
+ * @example
+ * ```
+ * // Expect: hsla(210, 50%, 40%, 0.5)
+ * const example1 = hslColorValueToHslaColorString({ hue: 210, saturation: 0.5, lightness: 0.4, alpha: 0.5 })
+ *
+ * // Expect: hsla(0, 0%, 100%, 1)
+ * const example2 = hslColorValueToHslaColorString({ hue: 0, saturation: 0, lightness: 1, alpha: 1 })
+ * ```
+ */
+export const hslColorValueToHslaColorString = (color: HslColorValue): string => {
+  const normalizedColor = createHslColorValue(color)
+  return `hsla(${normalizedColor.hue}, ${internalFormatPercentUnit(normalizedColor.saturation)}%, ${internalFormatPercentUnit(normalizedColor.lightness)}%, ${internalFormatAlpha(normalizedColor.alpha)})`
+}
+
+/**
+ * 将 HSV 颜色值序列化为 `hsv(...)` 字符串。
+ *
+ * @example
+ * ```
+ * // Expect: hsv(210, 66.67%, 60%)
+ * const example1 = hsvColorValueToHsvColorString({ hue: 210, saturation: 0.6667, value: 0.6, alpha: 0.5 })
+ *
+ * // Expect: hsv(0, 0%, 100%)
+ * const example2 = hsvColorValueToHsvColorString({ hue: 0, saturation: 0, value: 1, alpha: 1 })
+ * ```
+ */
+export const hsvColorValueToHsvColorString = (color: HsvColorValue): string => {
+  const normalizedColor = createHsvColorValue(color)
+  return `hsv(${normalizedColor.hue}, ${internalFormatPercentUnit(normalizedColor.saturation)}%, ${internalFormatPercentUnit(normalizedColor.value)}%)`
+}
+
+/**
+ * 将 HSV 颜色值序列化为 `hsva(...)` 字符串。
+ *
+ * @example
+ * ```
+ * // Expect: hsva(210, 66.67%, 60%, 0.5)
+ * const example1 = hsvColorValueToHsvaColorString({ hue: 210, saturation: 0.6667, value: 0.6, alpha: 0.5 })
+ *
+ * // Expect: hsva(0, 0%, 100%, 1)
+ * const example2 = hsvColorValueToHsvaColorString({ hue: 0, saturation: 0, value: 1, alpha: 1 })
+ * ```
+ */
+export const hsvColorValueToHsvaColorString = (color: HsvColorValue): string => {
+  const normalizedColor = createHsvColorValue(color)
+  return `hsva(${normalizedColor.hue}, ${internalFormatPercentUnit(normalizedColor.saturation)}%, ${internalFormatPercentUnit(normalizedColor.value)}%, ${internalFormatAlpha(normalizedColor.alpha)})`
+}

package/src/color/types.ts

@@ -0,0 +1,57 @@
+/**
+ * 表示 XYZ 颜色值结构，使用 `x`、`y`、`z` 三个通道和 `alpha` 透明度通道。
+ */
+export type XyzColorValue = Readonly<{
+  x: number
+  y: number
+  z: number
+  alpha: number
+}>
+
+/**
+ * 表示基于 XYZ 颜色值计算得到的 `xy` 色度坐标结构。
+ */
+export type XyChromaticityValue = Readonly<{
+  x: number
+  y: number
+}>
+
+/**
+ * 表示 Linear RGB 颜色值结构，使用线性 `red`、`green`、`blue` 三个通道和 `alpha` 透明度通道。
+ */
+export type LinearRgbColorValue = Readonly<{
+  red: number
+  green: number
+  blue: number
+  alpha: number
+}>
+
+/**
+ * 表示 sRGB 颜色值结构，使用 `red`、`green`、`blue` 三个 8 位通道和 `alpha` 透明度通道。
+ */
+export type SrgbColorValue = Readonly<{
+  red: number
+  green: number
+  blue: number
+  alpha: number
+}>
+
+/**
+ * 表示 HSL 颜色值结构，使用 `hue`、`saturation`、`lightness` 和 `alpha` 四个通道。
+ */
+export type HslColorValue = Readonly<{
+  hue: number
+  saturation: number
+  lightness: number
+  alpha: number
+}>
+
+/**
+ * 表示 HSV 颜色值结构，使用 `hue`、`saturation`、`value` 和 `alpha` 四个通道。
+ */
+export type HsvColorValue = Readonly<{
+  hue: number
+  saturation: number
+  value: number
+  alpha: number
+}>

package/src/color/xyz/analyze.ts

@@ -0,0 +1,80 @@
+import { createXyzColorValue } from "./construct.ts"
+import { internalRoundColorFloat } from "../internal.ts"
+
+import type {
+  XyChromaticityValue,
+  XyzColorValue,
+} from "../types.ts"
+
+const internalGetNormalizedXyzColorData = (color: XyzColorValue): { color: XyzColorValue, tristimulusSum: number } => {
+  const normalizedColor = createXyzColorValue(color)
+  const tristimulusSum = internalRoundColorFloat(normalizedColor.x + normalizedColor.y + normalizedColor.z)
+
+  return {
+    color: normalizedColor,
+    tristimulusSum,
+  }
+}
+
+/**
+ * 读取 XYZ 颜色值的相对亮度。
+ *
+ * 在当前模块约定下，`Y` 通道直接表示相对亮度。
+ *
+ * @example
+ * ```
+ * // Expect: 0.3
+ * const example1 = xyzColorValueToRelativeLuminance({ x: 0.25, y: 0.3, z: 0.4, alpha: 1 })
+ *
+ * // Expect: 0
+ * const example2 = xyzColorValueToRelativeLuminance({ x: 0, y: 0, z: 0, alpha: 1 })
+ * ```
+ */
+export const xyzColorValueToRelativeLuminance = (color: XyzColorValue): number => {
+  return createXyzColorValue(color).y
+}
+
+/**
+ * 读取 XYZ 颜色值的三刺激总量。
+ *
+ * 在当前模块约定下，结果等于 `x + y + z`。
+ *
+ * @example
+ * ```
+ * // Expect: 0.95
+ * const example1 = xyzColorValueToTristimulusSum({ x: 0.25, y: 0.3, z: 0.4, alpha: 1 })
+ *
+ * // Expect: 0
+ * const example2 = xyzColorValueToTristimulusSum({ x: 0, y: 0, z: 0, alpha: 1 })
+ * ```
+ */
+export const xyzColorValueToTristimulusSum = (color: XyzColorValue): number => {
+  return internalGetNormalizedXyzColorData(color).tristimulusSum
+}
+
+/**
+ * 读取 XYZ 颜色值对应的 `xy` 色度坐标。
+ *
+ * 当三刺激总量为 `0` 时，该结果没有定义，因此会抛出异常。
+ *
+ * @example
+ * ```
+ * // Expect: { x: 0.263158, y: 0.315789 }
+ * const example1 = xyzColorValueToXyChromaticityValue({ x: 0.25, y: 0.3, z: 0.4, alpha: 1 })
+ *
+ * // Expect: { x: 0.64, y: 0.33 }
+ * const example2 = xyzColorValueToXyChromaticityValue({ x: 0.412456, y: 0.212673, z: 0.019334, alpha: 1 })
+ * ```
+ */
+export const xyzColorValueToXyChromaticityValue = (color: XyzColorValue): XyChromaticityValue => {
+  const normalizedData = internalGetNormalizedXyzColorData(color)
+
+  if (normalizedData.tristimulusSum === 0) {
+    throw new RangeError("XYZ tristimulus sum must be greater than 0 to compute xy chromaticity")
+  }
+
+  return {
+    x: internalRoundColorFloat(normalizedData.color.x / normalizedData.tristimulusSum),
+    y: internalRoundColorFloat(normalizedData.color.y / normalizedData.tristimulusSum),
+  }
+}

package/src/color/xyz/construct.ts

@@ -0,0 +1,19 @@
+import { internalNormalizeXyzColorValue } from "./internal.ts"
+
+import type { XyzColorValue } from "../types.ts"
+
+/**
+ * 构造一个 XYZ 颜色值对象。
+ *
+ * @example
+ * ```
+ * // Expect: { x: 0.25, y: 0.3, z: 0.4, alpha: 1 }
+ * const example1 = createXyzColorValue({ x: 0.25, y: 0.3, z: 0.4, alpha: 1 })
+ *
+ * // Expect: { x: 0, y: 0, z: 0, alpha: 0.5 }
+ * const example2 = createXyzColorValue({ x: 0, y: 0, z: 0, alpha: 0.5 })
+ * ```
+ */
+export const createXyzColorValue = (color: XyzColorValue): XyzColorValue => {
+  return internalNormalizeXyzColorValue(color)
+}

package/src/color/xyz/convert.ts

@@ -0,0 +1,71 @@
+import { internalNormalizeXyzColorValue } from "./internal.ts"
+import {
+  internalAssertAlpha,
+  internalAssertFinite,
+  internalRoundColorFloat,
+} from "../internal.ts"
+
+import type {
+  LinearRgbColorValue,
+  XyzColorValue,
+} from "../types.ts"
+
+const internalNormalizeLinearRgbColorValueForXyzConversion = (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,
+  }
+}
+
+/**
+ * 将 XYZ 颜色值转换为 Linear RGB 颜色值。
+ *
+ * @example
+ * ```
+ * // Expect: { red: 0.2, green: 0.4, blue: 0.6, alpha: 1 }
+ * const example1 = xyzColorValueToLinearRgbColorValue({ x: 0.333784, y: 0.3719, z: 0.621726, alpha: 1 })
+ *
+ * // Expect: { red: 1, green: 0, blue: 0, alpha: 1 }
+ * const example2 = xyzColorValueToLinearRgbColorValue({ x: 0.412456, y: 0.212673, z: 0.019334, alpha: 1 })
+ * ```
+ */
+export const xyzColorValueToLinearRgbColorValue = (color: XyzColorValue): LinearRgbColorValue => {
+  const normalizedColor = internalNormalizeXyzColorValue(color)
+
+  return internalNormalizeLinearRgbColorValueForXyzConversion({
+    red: internalRoundColorFloat((3.240_454_2 * normalizedColor.x) - (1.537_138_5 * normalizedColor.y) - (0.498_531_4 * normalizedColor.z)),
+    green: internalRoundColorFloat((-0.969_266 * normalizedColor.x) + (1.876_010_8 * normalizedColor.y) + (0.041_556 * normalizedColor.z)),
+    blue: internalRoundColorFloat((0.055_643_4 * normalizedColor.x) - (0.204_025_9 * normalizedColor.y) + (1.057_225_2 * normalizedColor.z)),
+    alpha: normalizedColor.alpha,
+  })
+}
+
+/**
+ * 将 Linear RGB 颜色值转换为 XYZ 颜色值。
+ *
+ * @example
+ * ```
+ * // Expect: { x: 0.333784, y: 0.3719, z: 0.621726, alpha: 1 }
+ * const example1 = linearRgbColorValueToXyzColorValue({ red: 0.2, green: 0.4, blue: 0.6, alpha: 1 })
+ *
+ * // Expect: { x: 0.412456, y: 0.212673, z: 0.019334, alpha: 1 }
+ * const example2 = linearRgbColorValueToXyzColorValue({ red: 1, green: 0, blue: 0, alpha: 1 })
+ * ```
+ */
+export const linearRgbColorValueToXyzColorValue = (color: LinearRgbColorValue): XyzColorValue => {
+  const normalizedColor = internalNormalizeLinearRgbColorValueForXyzConversion(color)
+
+  return internalNormalizeXyzColorValue({
+    x: internalRoundColorFloat((0.412_456_4 * normalizedColor.red) + (0.357_576_1 * normalizedColor.green) + (0.180_437_5 * normalizedColor.blue)),
+    y: internalRoundColorFloat((0.212_672_9 * normalizedColor.red) + (0.715_152_2 * normalizedColor.green) + (0.072_175 * normalizedColor.blue)),
+    z: internalRoundColorFloat((0.019_333_9 * normalizedColor.red) + (0.119_192 * normalizedColor.green) + (0.950_304_1 * normalizedColor.blue)),
+    alpha: normalizedColor.alpha,
+  })
+}

package/src/color/xyz/index.ts

@@ -0,0 +1,3 @@
+export * from "./construct.ts"
+export * from "./convert.ts"
+export * from "./analyze.ts"