Module:Hct

模块文档  

--[[
  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.
]]

--[[
  This file has been modified. The original version is at
      https://github.com/material-foundation/material-color-utilities
]]

--[[
  A color system built using CAM16 hue and chroma, and L* from
  L*a*b*.

  Using L* creates a link between the color system, contrast, and thus
  accessibility. Contrast ratio depends on relative luminance, or Y in the XYZ
  color space. L*, or perceptual luminance can be calculated from Y.

  Unlike Y, L* is linear to human perception, allowing trivial creation of
  accurate color tones.

  Unlike contrast ratio, measuring contrast in L* is linear, and simple to
  calculate. A difference of 40 in HCT tone guarantees a contrast ratio >= 3.0,
  and a difference of 50 guarantees a contrast ratio >= 4.5.
]]


local utils = require('Module:Hct/ColorUtils');
local Cam16 = require('Module:Hct/Cam16');
local hctSolver = require('Module:Hct/HctSolver');


--[[
  HCT, hue, chroma, and tone. A color system that provides a perceptually
  accurate color measurement system that can also accurately render what colors
  will appear as in different lighting environments.
]]
local Hct = {};

-- private constructor 没有实现私有变量，请自行避免直接访问。
local function newHct(argb)
	local cam = Cam16.fromInt(argb);
	local o = {
		_hue = cam.hue,
		_chroma = cam.chroma,
		_tone = utils.lstarFromArgb(argb),
		_argb = argb,
	};
	setmetatable(o, {__index = Hct});
	return o;
end

-- private function
local function setInternalState(self, argb)
	local cam = Cam16.fromInt(argb);
	self._hue = cam.hue;
	self._chroma = cam.chroma;
	self._tone = utils.lstarFromArgb(argb);
	self._argb = argb;
end

--[[
  @param hue 0 <= hue < 360; invalid values are corrected.
  @param chroma 0 <= chroma < ?; Informally, colorfulness. The color
      returned may be lower than the requested chroma. Chroma has a different
      maximum for any given hue and tone.
  @param tone 0 <= tone <= 100; invalid values are corrected.
  @return HCT representation of a color in default viewing conditions.
]]
function Hct.from(hue, chroma, tone)
	return newHct(hctSolver.solveToInt(hue, chroma, tone));
end

--[[
  @param argb ARGB representation of a color.
  @return HCT representation of a color in default viewing conditions
]]
function Hct.fromInt(argb)
	return newHct(argb);
end

function Hct:toInt()
	return self._argb;
end

--[[
  A number, in degrees, representing ex. red, orange, yellow, etc.
  Ranges from 0 <= hue < 360.
]]
function Hct:getHue()
	return self._hue;
end

--[[
  @param newHue 0 <= newHue < 360; invalid values are corrected.
  Chroma may decrease because chroma has a different maximum for any given
  hue and tone.
]]
function Hct:setHue(newHue)
	setInternalState(self,
		hctSolver.solveToInt(newHue, self._chroma, self._tone)
	);
end

function Hct:getChroma()
	return self._chroma;
end

--[[
  @param newChroma 0 <= newChroma < ?
  Chroma may decrease because chroma has a different maximum for any given
  hue and tone.
]]
function Hct:setChroma(newChroma)
	setInternalState(self,
		hctSolver.solveToInt(self._hue, newChroma, self._tone)
	);
end

--[[ Lightness. Ranges from 0 to 100. ]]
function Hct:getTone()
	return self._tone;
end

--[[
  @param newTone 0 <= newTone <= 100; invalid valids are corrected.
  Chroma may decrease because chroma has a different maximum for any given
  hue and tone.
]]
function Hct:setTone(newTone)
	setInternalState(self,
		hctSolver.solveToInt(self._hue, self._chroma, newTone)
	);
end


return Hct;