@texel/color 1.1.3 → 1.1.5

package/src/spaces/srgb.js

@@ -8,6 +8,11 @@ import {
 
 import { sRGBGammaToLinearVec3, sRGBLinearToGammaVec3 } from "./util.js";
 
+/**
+ * The sRGB color space in linear form, without a transfer function, aliased as <code>"srgb-linear"</code>.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const sRGBLinear = {
   id: "srgb-linear",
   toXYZ_M: linear_sRGB_to_XYZ_M,
@@ -16,6 +21,11 @@ export const sRGBLinear = {
   fromLMS_M: LMS_to_linear_sRGB_M,
 };
 
+/**
+ * The sRGB color space, with a transfer function, aliased as <code>"srgb"</code>. Inherits from the {@link sRGBLinear} color space.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const sRGB = {
   id: "srgb",
   base: sRGBLinear,
@@ -23,6 +33,11 @@ export const sRGB = {
   fromBase: sRGBLinearToGammaVec3,
 };
 
+/**
+ * A color gamut for the {@link sRGB} color space.
+ * @type {ColorGamut}
+ * @category gamuts
+ */
 export const sRGBGamut = {
   space: sRGB,
   coefficients: OKLab_to_linear_sRGB_coefficients,

package/src/spaces/util.js

@@ -1,5 +1,12 @@
 import { vec3 } from "../util.js";
 
+/**
+ * Converts a single sRGB gamma-corrected channel value to linear light (un-companded) form.
+ * @param {number} val - The sRGB gamma-corrected channel value in the range [0, 1].
+ * @returns {number} The linear light channel value.
+ * @method
+ * @category rgb
+ */
 export const sRGBGammaToLinear = (val) => {
   // convert a single channel value
   // where in-gamut values are in the range [0 - 1]
@@ -15,6 +22,13 @@ export const sRGBGammaToLinear = (val) => {
     : sign * Math.pow((abs + 0.055) / 1.055, 2.4);
 };
 
+/**
+ * Converts a single linear-light channel value to sRGB gamma-corrected form.
+ * @param {number} val - The linear-light channel value in the range [0, 1].
+ * @returns {number} The sRGB gamma-corrected channel value.
+ * @method
+ * @category rgb
+ */
 export const sRGBLinearToGamma = (val) => {
   // convert a single channel linear-light value in range 0-1
   // to gamma corrected form

package/src/spaces/xyz.js

@@ -28,20 +28,44 @@ export const D50_to_D65_M = [
   [0.012314014864481998, -0.020507649298898964, 1.330365926242124],
 ];
 
+/**
+ * Converts a color from XYZ with D65 whitepoint to XYZ with D50 whitepoint.
+ * @method
+ * @category xyz
+ * @param {Vector} XYZ - The input color in XYZ with D65 whitepoint.
+ * @param {Vector} [out=vec3()] - The output color in XYZ with D50 whitepoint.
+ * @returns {Vector} The converted color in XYZ with D50 whitepoint.
+ */
 export const XYZD65ToD50 = (XYZ, out = vec3()) =>
   transform(XYZ, D65_to_D50_M, out);
 
+/**
+ * Converts a color from XYZ with D50 whitepoint to XYZ with D65 whitepoint.
+ * @method
+ * @category xyz
+ * @param {Vector} XYZ - The input color in XYZ with D50 whitepoint.
+ * @param {Vector} [out=vec3()] - The output color in XYZ with D65 whitepoint.
+ * @returns {Vector} The converted color in XYZ with D65 whitepoint.
+ */
 export const XYZD50ToD65 = (XYZ, out = vec3()) =>
   transform(XYZ, D50_to_D65_M, out);
 
-// XYZ using D65 whitepoint
+/**
+ * XYZ color space with D65 whitepoint, aliased as <code>"xyz"</code>.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const XYZ = {
   id: "xyz", // xyz-d65
   toLMS_M: XYZ_to_LMS_M,
   fromLMS_M: LMS_to_XYZ_M,
 };
 
-// XYZ using D50 whitepoint
+/**
+ * XYZ color space with D50 whitepoint, aliased as <code>"xyz-d50"</code>.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const XYZD50 = {
   id: "xyz-d50",
   base: XYZ,

package/src/spaces.js

@@ -18,6 +18,13 @@ export * from "./spaces/rec2020.js";
 export * from "./spaces/a98-rgb.js";
 export * from "./spaces/prophoto-rgb.js";
 
+/**
+ * Returns a list of color spaces.
+ *
+ * @method
+ * @returns {ColorSpace[]} An array of color space objects.
+ * @category core
+ */
 export const listColorSpaces = () => {
   return [
     XYZ, // D65
@@ -39,6 +46,13 @@ export const listColorSpaces = () => {
   ];
 };
 
+/**
+ * Returns a list of color gamuts.
+ *
+ * @method
+ * @returns {ColorGamut[]} An array of color gamut objects.
+ * @category core
+ */
 export const listColorGamuts = () => {
   return [sRGBGamut, DisplayP3Gamut, Rec2020Gamut, A98RGBGamut];
 };

package/src/util.js

@@ -1,15 +1,60 @@
-const GAMUT_EPSILON = 0.000075;
-
+/**
+ * Clamps a value between a minimum and maximum value.
+ * @method
+ * @param {number} value The value to clamp.
+ * @param {number} min The minimum value.
+ * @param {number} max The maximum value.
+ * @returns {number} The clamped value.
+ * @category utils
+ */
 export const clamp = (value, min, max) => Math.max(Math.min(value, max), min);
 
+/**
+ * Linearly interpolates between two values.
+ * @method
+ * @param {number} min The start value.
+ * @param {number} max The end value.
+ * @param {number} t The interpolation factor between 0 and 1.
+ * @returns {number} The interpolated value.
+ * @category utils
+ */
 export const lerp = (min, max, t) => min * (1 - t) + max * t;
 
+/**
+ * Converts degrees to radians.
+ * @method
+ * @param {number} n The angle in degrees.
+ * @returns {number} The angle in radians.
+ * @category utils
+ */
 export const degToRad = (n) => (n * Math.PI) / 180;
 
+/**
+ * Converts radians to degrees.
+ * @method
+ * @param {number} n The angle in radians.
+ * @returns {number} The angle in degrees.
+ * @category utils
+ */
 export const radToDeg = (n) => (n * 180) / Math.PI;
 
+/**
+ * Constrains an angle to the range [0, 360).
+ * @method
+ * @param {number} angle The angle in degrees.
+ * @returns {number} The constrained angle.
+ * @category utils
+ */
 export const constrainAngle = (angle) => ((angle % 360) + 360) % 360;
 
+/**
+ * Converts a hex color string to an RGB array.
+ * @method
+ * @param {string} str The hex color string.
+ * @param {Vector} [out=vec3()] The output array.
+ * @returns {Vector} The RGB array.
+ * @category rgb
+ */
 export const hexToRGB = (str, out = vec3()) => {
   let hex = str.replace(/#/, "");
   if (hex.length === 3) {
@@ -26,12 +71,31 @@ export const hexToRGB = (str, out = vec3()) => {
   return out;
 };
 
+/**
+ * Converts an RGB array to a hex color string.
+ * @method
+ * @param {Vector} rgb The RGB array.
+ * @returns {string} The hex color string.
+ * @category rgb
+ */
 export const RGBToHex = (rgb) =>
   `#${rgb.map((n) => floatToByte(n).toString(16).padStart(2, "0")).join("")}`;
 
-/** @deprecated use RGBToHex */
+/**
+ * @method
+ * @deprecated Use RGBToHex instead.
+ * @category rgb
+ */
 export const RGBtoHex = RGBToHex;
 
+/**
+ * Checks if an RGB color is within the gamut.
+ * @method
+ * @param {Vector} lrgb The linear RGB array.
+ * @param {number} [ep=GAMUT_EPSILON] The epsilon value for comparison.
+ * @returns {boolean} True if the color is within the gamut, false otherwise.
+ * @category rgb
+ */
 export const isRGBInGamut = (lrgb, ep = GAMUT_EPSILON) => {
   const r = lrgb[0];
   const g = lrgb[1];
@@ -46,6 +110,14 @@ export const isRGBInGamut = (lrgb, ep = GAMUT_EPSILON) => {
   );
 };
 
+/**
+ * Clamps an RGB array to the range [0, 1].
+ * @method
+ * @param {Vector} rgb The RGB array.
+ * @param {Vector} [out=vec3()] The output array.
+ * @returns {Vector} The clamped RGB array.
+ * @category rgb
+ */
 export const clampedRGB = (rgb, out = vec3()) => {
   out[0] = clamp(rgb[0], 0, 1);
   out[1] = clamp(rgb[1], 0, 1);
@@ -53,6 +125,14 @@ export const clampedRGB = (rgb, out = vec3()) => {
   return out;
 };
 
+/**
+ * Converts xyY color space to XYZ color space.
+ * @method
+ * @param {Vector} arg The xyY array.
+ * @param {Vector} [out=vec3()] The output array.
+ * @returns {Vector} The XYZ array.
+ * @category xyz
+ */
 export const xyY_to_XYZ = (arg, out = vec3()) => {
   let X, Y, Z, x, y;
   x = arg[0];
@@ -70,6 +150,14 @@ export const xyY_to_XYZ = (arg, out = vec3()) => {
   return out;
 };
 
+/**
+ * Converts XYZ color space to xyY color space.
+ * @method
+ * @param {Vector} arg The XYZ array.
+ * @param {Vector} [out=vec3()] The output array.
+ * @returns {Vector} The xyY array.
+ * @category xyz
+ */
 export const XYZ_to_xyY = (arg, out = vec3()) => {
   let sum, X, Y, Z;
   X = arg[0];
@@ -87,29 +175,43 @@ export const XYZ_to_xyY = (arg, out = vec3()) => {
   return out;
 };
 
+/**
+ * Converts a float value to a byte value.
+ * @method
+ * @param {number} n The float value.
+ * @returns {number} The byte value.
+ * @category utils
+ */
 export const floatToByte = (n) => clamp(Math.round(255 * n), 0, 255);
 
-// Undocumented
-
+/**
+ * Creates a new vec3 array.
+ * @method
+ * @returns {Vector} The vec3 array.
+ * @category utils
+ */
 export const vec3 = () => [0, 0, 0];
 
-// export const normalizeHue = (hue) => ((hue = hue % 360) < 0 ? hue + 360 : hue);
-
-// in degrees
-// export const angle_delta = (angle1, angle2) => {
-//   const diff = ((angle2 - angle1 + 180) % 360) - 180;
-//   return diff < -180 ? diff + 360 : diff;
-// };
-
-// function shortAngleDistRad(a0, a1) {
-//   var max = Math.PI * 2;
-//   var da = (a1 - a0) % max;
-//   return ((2 * da) % max) - da;
-// }
-
+/**
+ * Calculates the delta angle between two angles.
+ * @method
+ * @param {number} a0 The first angle in degrees.
+ * @param {number} a1 The second angle in degrees.
+ * @returns {number} The delta angle in degrees.
+ * @category utils
+ */
 export const deltaAngle = (a0, a1) => {
   var da = (a1 - a0) % 360;
   return ((2 * da) % 360) - da;
 };
 
+/**
+ * Linearly interpolates between two angles.
+ * @method
+ * @param {number} a0 The start angle in degrees.
+ * @param {number} a1 The end angle in degrees.
+ * @param {number} t The interpolation factor between 0 and 1.
+ * @returns {number} The interpolated angle in degrees.
+ * @category utils
+ */
 export const lerpAngle = (a0, a1, t) => a0 + deltaAngle(a0, a1) * t;