Color API

1. Introduction

Many APIs on the Web platform need to be able to accept color input and provide color output in a format more structured than CSS <color> strings. Furthermore, authors often need to perform computations on color values, such as manipulating components in a variety of color spaces, computing color differences, evaluating whether color pairs have sufficient contrast, or interpolating two colors (regardless of what color space they are specified in).

The API presented in this document aims to address all of the common use cases, and provide extensibility points to enable more complex use cases to be expressed.

2. Color class

Color objects represent ...TBD

[Exposed=*]
interface Color {
  // Default constructor
  constructor(
    (CSSOMString or ColorSpace) colorSpace,
    sequence<double> coords,
    optional double alpha = 1
  );

  // Parse CSS color
  constructor(CSSOMString cssText);

  // Clone color instance or create from JSON-style object
  constructor((Color or CSSColorValue or ColorJSON) color);

  attribute ColorSpace colorSpace;
  attribute ObservableArray<double> coords;
  attribute double alpha;

  // Get/set coordinates (in this or other color spaces)
  double get((CSSOMString or ColorSpace) colorSpace, (CSSOMString or unsigned short) coord);
  double get((CSSOMString or unsigned short) coord);

  Color set(
    (CSSOMString or ColorSpace) colorSpace,
    (CSSOMString or unsigned short) coord,
    (double or relativeCoordCallback) value
  );
  Color set(
    (CSSOMString or unsigned short) coord,
    (double or relativeCoordCallback) value
  );
  Color set((CSSOMString or ColorSpace) colorSpace, object values);
  Color set(object values);

  // Convert to another color space
  Color to(CSSOMString colorspace);

  // Check whether a color is in gamut of a given color space
  boolean inGamut(optional CSSOMString colorspace);

  // Bring a color into gamut of a given colorspace
  Color toGamut(
    optional (CSSOMString or ColorSpace) colorSpace,
    optional ToGamutOptions options = {}
  );

  stringifier;

  ColorJSON toJSON();

  // Color difference
  double deltaE(Color color, optional DeltaEMethod method);
};

dictionary ToGamutOptions {
  coordReference? method = "lch.c";
};

dictionary coordReference {
  (CSSOMString or ColorSpace) colorSpace;
  CSSOMString name;
};

// TODO: we want authors to be able to extend this
// If we keep it an enum, the only way to add custom deltaE methods
// is a separate method.
enum DeltaEMethod {
  "76",    // fast, but limited accuracy
  "2000",  // slower, but accurate
};

dictionary ColorJSON {
  (CSSOMString or ColorSpace) colorSpace;
  sequence<double> coords;
  double alpha;
};

callback relativeCoordCallback = double (double coord);

3. ColorSpace class

[Exposed=*]
interface ColorSpace {
  readonly attribute CSSOMString name;
  readonly attribute ColorSpaceWhitePoint white;
  readonly attribute ColorSpace? base;
  readonly attribute sequence<CSSOMString> coords;

  constructor(CSSOMString name, ColorSpaceOptions options);

  // Register a ColorSpace object
  static undefined register(ColorSpace colorspace);

  // Creates a new ColorSpace object and registers it
  static ColorSpace create(CSSOMString name, ColorSpaceOptions options);

  // Array of names for all registered color spaces
  static readonly attribute FrozenArray<CSSOMString> names;

  // Lookup ColorSpace object by name
  static ColorSpace get((CSSOMString or ColorSpace) name);

  // Load ICC profile and create a ColorSpace object from it
  static Promise<ColorSpace> fromICCProfile((Response or CSSOMString) resource, ReducedColorSpaceOptions options);
};

// White point x and y chromaticities
interface ColorSpaceWhitePoint {
  constructor(double x, double y);

  readonly attribute double x;
  readonly attribute double y;

  static readonly attribute ColorSpaceWhitePoint D65;
  static readonly attribute ColorSpaceWhitePoint D50;
};

dictionary ReducedColorSpaceOptions {
  // Coordinate names and optional metadata
  record<DOMString, ColorSpaceCoordinate> coords;
};

dictionary ColorSpaceOptions : ReducedColorSpaceOptions {
  (ColorSpaceWhitePoint or object) white;

  inGamutCallback inGamut;

  // Base color space, if this is a transformation
  (CSSOMString or ColorSpace)? base;
  toBaseCallback toBase;
  fromBaseCallback fromBase;
};

dictionary ColorSpaceCoordinate {
  ColorSpaceCoordinateType? type = "number";

  // Gamut limits
  double? min;
  double? max;

  // Reference range
  double? refMin;
  double? refMax;
};

enum ColorSpaceCoordinateType { "angle", "number" };

callback inGamutCallback = boolean (sequence<double> coords);
callback toBaseCallback = sequence<double> (sequence<double> coords);
callback fromBaseCallback = sequence<double> (sequence<double> coords);

Color space coordinates must specify at least one of:

• type: "angle"

• min and max

• refMin and refMax

The ColorSpaceWhitePoint interface represents the xy chromaticity coordinates of a white point. For convenience, D50 and D65 are predefined as follows:

• ColorSpaceWhitePoint.D50 is set to new ColorSpaceWhitePoint(0.3457, 0.3585)

• ColorSpaceWhitePoint.D65 is set to new ColorSpaceWhitePoint(0.3127, 0.3290)

4. Algorithms

4.1. Getting and setting coordinates

The color.get() and color.set() methods allow authors to read/write coordinates in the current color space or even other color spaces. Color spaces can be provided either as a string (color space id) or a CoorSpace object. Coordinates can be specified either as a name, or as a numerical index.

color.set(coord, value) also accepts a value. If the value is a function, it is invoked immediately, with the result of color.get(coord) being passed as the first argument. If the result is a number, the corresponding coordinate is set to it.

4.2. Color space lookup

Color spaces can be looked up either by ColorSpace object, or by name. Implementations are expected to maintain an internal Map registry of color space names to objects, for fast lookups.

To look up a color space, follow the following steps:

1. If needle is a ColorSpace object, let needle = needle.name

2. If needle is a USVString, look up if there is an entry with that key in the internal Map of color names to ColorSpace objects.

3. Return the ColorSpace object, or null, if none is found

4.3. Converting between color spaces

To convert a color from color space A to color space B, perform the following steps:

1. If A.name === B.name, clone the color and return it

2. Let coords = A.toBase(color.coords). If A.base === B.name, return new Color(B, coords, color.alpha)

3. While A.base !== "xyz":

   1. Let coords = A.toBase(color.coords).

   2. If A.base === B.name, return new Color(B, coords, color.alpha)

   3. Otherwise, let A = ColorSpace.get(A.base)

4. Follow B’s base chain until "xyz" as well, and store the result in an array.

5. Starting from the end, let coords = B.fromBase(coords) on each of these colorspaces

6. Return new Color(B, coords, color.alpha)

Note: While this seems complicated in the general case, in virtually every real case the base chain has a length of max 3, so the algorithm would end very quickly.

4.4. Registering a color space

TBD. Should throw if base chain doesn’t resolve to "xyz" eventually. Should throw if name exists.

5. Security Considerations

There are no known security issues introduced by these features.

6. Privacy Considerations

There are no known privacy issues introduced by these features.