@w3h/material-color-utilities
Version:
Algorithms and utilities that power the Material Design 3 (M3) color system, including choosing theme colors from images and creating tones of colors; all in a new color space.
132 lines (131 loc) • 5.62 kB
TypeScript
/**
* @license
* Copyright 2021 Google LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { ViewingConditions } from './viewing_conditions.js';
/**
* CAM16, a color appearance model. Colors are not just defined by their hex
* code, but rather, a hex code and viewing conditions.
*
* CAM16 instances also have coordinates in the CAM16-UCS space, called J*, a*,
* b*, or jstar, astar, bstar in code. CAM16-UCS is included in the CAM16
* specification, and should be used when measuring distances between colors.
*
* In traditional color spaces, a color can be identified solely by the
* observer's measurement of the color. Color appearance models such as CAM16
* also use information about the environment where the color was
* observed, known as the viewing conditions.
*
* For example, white under the traditional assumption of a midday sun white
* point is accurately measured as a slightly chromatic blue by CAM16. (roughly,
* hue 203, chroma 3, lightness 100)
*/
export declare class Cam16 {
readonly hue: number;
readonly chroma: number;
readonly j: number;
readonly q: number;
readonly m: number;
readonly s: number;
readonly jstar: number;
readonly astar: number;
readonly bstar: number;
/**
* All of the CAM16 dimensions can be calculated from 3 of the dimensions, in
* the following combinations:
* - {j or q} and {c, m, or s} and hue
* - jstar, astar, bstar
* Prefer using a static method that constructs from 3 of those dimensions.
* This constructor is intended for those methods to use to return all
* possible dimensions.
*
* @param hue
* @param chroma informally, colorfulness / color intensity. like saturation
* in HSL, except perceptually accurate.
* @param j lightness
* @param q brightness; ratio of lightness to white point's lightness
* @param m colorfulness
* @param s saturation; ratio of chroma to white point's chroma
* @param jstar CAM16-UCS J coordinate
* @param astar CAM16-UCS a coordinate
* @param bstar CAM16-UCS b coordinate
*/
constructor(hue: number, chroma: number, j: number, q: number, m: number, s: number, jstar: number, astar: number, bstar: number);
/**
* CAM16 instances also have coordinates in the CAM16-UCS space, called J*,
* a*, b*, or jstar, astar, bstar in code. CAM16-UCS is included in the CAM16
* specification, and is used to measure distances between colors.
*/
distance(other: Cam16): number;
/**
* @param argb ARGB representation of a color.
* @return CAM16 color, assuming the color was viewed in default viewing
* conditions.
*/
static fromInt(argb: number): Cam16;
/**
* @param argb ARGB representation of a color.
* @param viewingConditions Information about the environment where the color
* was observed.
* @return CAM16 color.
*/
static fromIntInViewingConditions(argb: number, viewingConditions: ViewingConditions): Cam16;
/**
* @param j CAM16 lightness
* @param c CAM16 chroma
* @param h CAM16 hue
*/
static fromJch(j: number, c: number, h: number): Cam16;
/**
* @param j CAM16 lightness
* @param c CAM16 chroma
* @param h CAM16 hue
* @param viewingConditions Information about the environment where the color
* was observed.
*/
static fromJchInViewingConditions(j: number, c: number, h: number, viewingConditions: ViewingConditions): Cam16;
/**
* @param jstar CAM16-UCS lightness.
* @param astar CAM16-UCS a dimension. Like a* in L*a*b*, it is a Cartesian
* coordinate on the Y axis.
* @param bstar CAM16-UCS b dimension. Like a* in L*a*b*, it is a Cartesian
* coordinate on the X axis.
*/
static fromUcs(jstar: number, astar: number, bstar: number): Cam16;
/**
* @param jstar CAM16-UCS lightness.
* @param astar CAM16-UCS a dimension. Like a* in L*a*b*, it is a Cartesian
* coordinate on the Y axis.
* @param bstar CAM16-UCS b dimension. Like a* in L*a*b*, it is a Cartesian
* coordinate on the X axis.
* @param viewingConditions Information about the environment where the color
* was observed.
*/
static fromUcsInViewingConditions(jstar: number, astar: number, bstar: number, viewingConditions: ViewingConditions): Cam16;
/**
* @return ARGB representation of color, assuming the color was viewed in
* default viewing conditions, which are near-identical to the default
* viewing conditions for sRGB.
*/
toInt(): number;
/**
* @param viewingConditions Information about the environment where the color
* will be viewed.
* @return ARGB representation of color
*/
viewed(viewingConditions: ViewingConditions): number;
static fromXyzInViewingConditions(x: number, y: number, z: number, viewingConditions: ViewingConditions): Cam16;
xyzInViewingConditions(viewingConditions: ViewingConditions): number[];
}