Color Class for JS

使用new Color()或Color()建立一個色彩物件。

基礎使用：

var white_1 = new Color( "rgb", 255, 255, 255, 255 );
 // 建立alpha值100%的RGB模式的白色
 // alpha 值的範圍隨模式而異

var white_2 = new Color( "cmyk" );
 // 建立一個CMYK色彩，缺少的欄位會補上最低值(0)，alpha預設為最高值

var black = Color();
 // 建立黑色，new可以省略，字串參數無法辨識或不存在時會採用RGB模式
 // 第一個可辨識的字串(模式、數字或可被解析的字串)會被採用
 
var gray = Color( "0.5" );
 // 使用數字字串會自動採用灰階模式，"0.5"會建立濃度為50%的灰階色彩

字串解析：

var gray = Color( "#333333" );
 // 建立hex等於#333333的灰色，接受3碼或6碼的hex值
 
var blue = Color( "rgba( 0, 0, 255, 1 )" );
 // 從css的rgba代碼建立一個藍色

var xyz = Color( "xyz( 50, 50, 50 )" );
 // 也支援其他色彩模式的輸入，需注意hsla的alpha值域與css的不同

var lch = Color( "lch, 100, 50, 60" );
 // 逗號或空格分隔的字串會自動轉換為參數引入

⨳ 無法解析時會傳回RGB模式的黑色，但有些包含空格與數值的字串可能會產生灰階物件。

主要有兩個方法可以進行轉換：

<color>.<color_model>()

<color>.to( color_model, truncation = default_step )

模式名稱為小寫，除了11種色彩模式外，轉換還支援hex跟css模式。

⨳ 兩者在.to()的情況下會輸出字串且不會改變原物件。

範例

var red = new Color( 255 ); // 建立RGB模式的紅色

var cmyk_red = red.cmyk();
 // 取得CMYK模式的紅色，這不會影響原始的red物件

red.to( "hsv" );
 // 把red轉換成HSV模式，會自動將數值進行轉換並以模式預設的階段取整
 // 因為轉換可能存在數值誤差，來回轉換數值可能會不一致

var not_in_srgb = Color( "lab", 100, 100, -50 ); // 看起來像是粉紅色
not_in_srgb.to( "rgb", 0 );
 // 使用階段參數設定取整的數值階段，0則不會進行取整，可減低誤差
 // 如果轉換後超過值域，將會被設為最大/最小值

var not_in_srgb = Color( "lab", 100, 30, -80 ); // 可能是某種淡藍色
not_in_srgb.to( "rgb", false );
 // 使用boolean作為階段參數時可以控制是否取整
 // 無法保證輸出數值會是該模式下的合法數值，但可以將轉換誤差降至最低

red.hex(); // #FF0000
red.to("css"); // rgb( 255, 0, 0 )
 // 除了hsl模式外都會轉成rgb，alpha值不為最大值時會輸出成rgba/hsla

⨳ 將色彩轉換成灰階時會隨來源模式使用不同的轉換。

每個物件都有快速取得各項數值的方式，基本上依照色彩模式的名稱與順序，例如RGB模式中可使用<rgb>.r或是<rgb>[0]來存取紅色數值。

⨳ alpha值不能用array的方式存取。

var xyz = Color( "xyz", 50, 80, 60 ); // 淡藍綠色

xyz.x = 10; // x值將會被設為10
xyz[2] = xyz.x + 5; // z值將會被設為15
xyz.y -= 10; // y值將會被設為70

以色彩值名稱取值時會傳回一個參照回色彩物件的Key類別實體，這個實體會保存該色彩值當下的數值(但不會隨著更新)。使用這個Key實體可以更新色彩實體的數值。擁有<key>.value跟<key>.ratio等屬性

⨳ 由於會建立對原始色彩物件的參照，在記憶體操作上會比較複雜。

var lab = Color( "lab", 50, 60, 10 ); // 酒紅色

var l = lab.l; // l會是一個Key物件，且可以直接進行數值運算
l.value *= 2 // lab會變成[ 100, 60, 10 ]
l.ratio = 1.2345 // lab會變成超出了上限的[ 123.45, 60, 10 ]

l.truncate(); // 由於數值可能會在合法範圍外，此時可使用裁切方法
 // lab會變成[ 100, 60, 10 ]

Color( 12.34, 55, 66 ).r.truncate( 0.1 );
 // .truncate()接受一個階段參數，可以選擇裁切的最小階段
 // 會傳回數值為12.3的紅色Key物件，這會影響到原始的色彩物件

色彩物件也有數值處理的屬性與方法：

<color>.mode

<color>.modeWithoutKeys

<color>.array

<color>.arrayWithAlpha

<color>.ratio

<color>.ratioWithAlpha

<color>.truncate()

<color>.reverse()

範例

var luv = Color( "luv", 50, 30, 30, 0.5 ); // 半透明土色

luv.mode = "lab"; // 將luv變成lab模式，不會影響數值
luv.modeWithoutKeys = "luv"; // 變回luv模式，不產生 .l .u .v 三個屬性

var values = luv.array; // 傳回一個帶有luv三數值的array
luv.array = [ 0, 0, 0 ]; // luv會變成[ 0, 0, 0, 0.5 ]

values = luv.arrayWithAlpha;
 // values從[ 50, 30, 30 ]變成[ 0, 0, 0, 0.5 ]
luv.arrayWithAlpha = [ 50, 30, 30, 1 ] // luv變成不透明土色

var ratios = luv.ratio;
luv.ratioWithAlpha = ratios.concat(0.5); // luv變回半透明土色
 // 跟array一樣的操作模式，不過是以比例操作
 // 以色彩模式中該值的最小值為0，最大值為1，不會進行裁切

驗證色彩有兩種方法，一個是用<color>.in_scale屬性，他可以確認數值是否在範圍內；而<color>.validate()則會額外確認是否吻合階段。

var c1 = Color( -1 ),
    c2 = Color( 0.1 ),
    c3 = Color( 1 );

c1.in_scale; // false
c1.validate(); // false

c2.in_scale; // true
c2.validate(); // false

c3.in_scale; // true
c3.validate(); // true

其他的數值操作方法：

<color>.duplicate()

建立一個相同而無參照的色彩物件；

<color>.restore( <another color> )

複製另一個色彩的模式與數值；

<color>.compare_with( <another color>, strict_compare = false )

進行色彩的比較，會已裁切後的數值進行比較，開啟strict_compare則不會裁切。

<color>.distance( <another color>, no_adjustion = false  )

計算色彩的距離，會將距離數值調整約在0-1之間，使用no_adjustion則不進行調整。

色彩的調整有色相、彩度以及明度3種，請看以下範例：

色相

 // 色相 <color>.hue( value, color_model = "hsl" )
 // 支援名稱中有H的色彩模式，預設以HSL模式轉換
var red = Color( 255 ); // 純紅，色相為0度

red.hue( 180 ); // 轉180度變成青色

red.hue( "-50%" ); // 以%字串進行比例變換，減少50%的色相(180->90)

red.hue( 30, "lch" );
 // 以LCH模式轉30度，此時可能會轉到RGB無法呈現的色彩上
 // 此時會自動裁切到可呈現的範圍內，因此來回轉換可能會變成其他顏色
 // 轉換後的數值不一定會在階段上，但一定會在範圍內。

明度

 // 明度 <color>.lightness( value, color_model = "hsl" )
 // 支援名稱中有L跟V的色彩模式，預設以HSL模式轉換
var yellow = Color( 255, 255 ); // 純黃，HSL的明度為50

yellow.lightness( +30 ); // 增加30的HSL明度(50->80)

yellow.lightness( "10%" ); // 一樣可以用百分比(80->88)

yellow.lightness( -0.5 );
 // 當數值介於-1與1之間(不包含)時，將會被自動乘上最小值到最大值的距離
 // 因此-0.5乘上100等於-50(88->38)

yellow.lightness( -100, "lab" );
 // 轉換不會作階段裁切，但會在上下限以內(38->0)
 // 不同色彩模式的明度值不同

彩度

 // 彩度 <color>.saturation( value, color_model = "hsl" )
 // 支援名稱中有S的色彩模式，預設以HSL模式轉換
 // 另外有 <color>.chroma( value, color_model = "lch" )的調整
var blue = Color( 0, 0, 255 ); // 藍色，彩度為100

blue.saturation( -20 ); // 基本使用跟明度相同(100->80)

blue.saturation( "-25%" ); // 轉換不會作階段裁切(80->60)

blue.saturation( 0.4 ); // 來回轉換誤差相對小(60->100)

blue.chroma( -50 ); // 以lch轉換較難預測結果

其他色彩調整

 // gamma調整 <color>.gamma( new_gamma, old_gamma = 2.2 )
 // 預設2.2為sRGB的gamma值
var g = Color( "0.7" ); // 灰階

g.gamma( 1.8, 2.2 ); // 調整到1.8

 // 白平衡調整 <color>.wb( referance_color )
var color = Color( 123, 45, 67 ); // 血色

color.wb( Color( 255 ) ); // 以紅色校正，變成青色

在混合方面大多數會轉換成RGB模式進行運算，再轉換回原始模式，提供了幾種功能：

<color>.under()

<color>.over()

<color>.mask_by()

<color>.expose_by()

<color>.add()

<color>.subtract()

<color>.threshold( color_1, color_2 = Color() )

<color>.noise( grayscale = false, alpha = 1 )

範例

var red = Color( 255, 0, 0 ),
    blue = Color( 0, 0, 255 )

var rob = red.over( blue ); // 紅色在藍色上面
var bor = red.under( blue ); // 藍色在紅色上面
var bmr = red.mask_by( blue ); // 以藍色過濾紅色
var reb = red.expose_by( blue ); // 以藍色重曝紅色
var rab = red.add( blue ); // 藍色加紅色(數值相加)，不會超過值域
var rsb = red.subtract( blue ); // 紅色減藍色(數值相減)，不會超過值域

var rsb = red.threshold( blue, blue );
 // 以數值作為限界去調整原始的顏色，最大最小值依每個數值而變
 // 以原始模式運算
 // 這會變成一個藍色
 
var nor = red.noise(); // 產生一個隨機的顏色，並把它疊在紅色上
 // grayscale參數可以選擇是否使用灰階色彩(true|false)
 // alpha參數決定隨機顏色的透明度(0-1)

依據選擇的顏色產生其他顏色。

色相

 // 接受.hue能使用的模式，預設為HSL模式
var color = Color( 123, 45, 67 ); // 血色

 // 產生互補色 <color>.complement( color_model = "hsl" )
color.complement(); // 產生有兩個顏色的array

 // 產生相近色 <color>.adjacent( color_model = "hsl" )
color.adjacent(); // 產生有兩個顏色的array

 // 產生三角色 <color>.triad( color_model = "hsl" )
color.triad(); // 產生有三個顏色的array

 // 產生對比色 <color>.light_contrast( color_model = "hsl" )
color.light_contrast(); // 產生一個看起來有分別的顏色

 // 依顏色產生對比色
 // <color>.contrast_with( color, color_model = "hsl" )
color.contrast_with( Color( 255, 255, 255 ).noise() );
 // 產生一個與兩個顏色都有分別的顏色

明度

 // 接受.lightness能使用的模式，預設為HSL模式
var color = Color( 123, 45, 67 ); // 血色

 // 產生互補色 <color>.shades( color_model = "hsl" )
color.shades();
 // 產生有四個顏色的array，分別減0、10%、30%、70%亮度
 // 對於明度低的色彩較無效果

CSS漸層

 // CSS有兩種漸層，線性與放射，相對的有兩個函式

 // Color.fn.css_linear_gradient( direction, colors, repeat = 0 )
var red = Color( 255, 0, 0 ),
    blue = Color( 0, 0, 255 ),
    green = Color( 0, 255, 0 );

Color.fn.css_linear_gradient( "to right", [ red, blue, green ] );
 // 將會產生一個向右間隔相等的紅藍綠漸層
 // 方向參數使用CSS設定
 
Color.fn.css_linear_gradient( "30deg", [ red, 0, blue, red ], 2 );
 // 將會產生一個30度角的紅綠漸層，紅在0，藍在66%，紅在100%，並重複1次
 // 每個顏色的位置為: 索引順序/(長度-1)
 // 要注意如果在array末端使用空值將會影響到重複次數

 // Color.fn.css_radial_gradient( position, colors, repeat = 0 )
Color.fn.css_radial_gradient( "", [ red, blue, green ] );
 // 放射狀的使用方式與線性相同
 // 形狀與位置參數請參考CSS使用

平均色

 // Color.fn.average( color_1, color_2, ... )
var red = Color( 255, 0, 0 ),
    blue = Color( 0, 0, 255 ),
    green = Color( 0, 255, 0 );

Color.fn.average( red, green, blue );
 // 將會對紅藍綠取平均，產生33%的灰色
 // 計算方式會隨著第一個顏色的色彩模式而變

除錯

 //  <color>.log(
 //     truncation = true,
 //     color_model = current_model,
 //     show_color_box = true )
Color( 255 ).log(); // 顯示RGB模式的紅色

Color( "cmyk" ).log( 0, "rgb", false );
 // 把CMYK的白色顯示於RGB模式，並且不顯示色彩方塊

序列化

 // <color>.serialize()
 // 將色彩輸出為array
var blue = Color( 0, 0, 255 );
var bar = blue.serialize(); // [ "rgb" , 0, 0, 255 ]

 // <color>.toString(
 //    with_alpha_ratio = false,
 //    letter_spacing = 0,
 //    spacing_character = " " )
 // 將色彩輸出為字串
var bs = blue.toString(); // "rgb( 0, 0, 255 )"

blue.toString( true, 3, "0" ); // "rgba( 000, 000, 255, 001 )"
 // 第一個參數決定是否輸出alpha值
 // 第二個參數決定數值的排版長度
 // 第三個參數決定排版填補的字元

建立物件

 // new Color.Set( color_1, color_2, ...,
 //    width = color_instances_number,
 //    height = ceil(color_instances_number/width) )

 // 讀取canvas的影像
 // Color.Set.fn.readImageData( ImageData )
var color_set = Color.Set.fn.readImageData(
    canvas.getContext("2d")
          .getImageData( 0, 0, canvas.width, canvas.height )
);

操作

color_set.adjust_size( 100, 100 );
 // <set>.adjust_size(width = length, height = ceil(length/width))
 // 調整影像長寬

color_set.get_colors();
 // <set>.get_colors( position = 0, length = all )
 // 取得色彩array

color_set.set_color( 0, Color( "#fff" ) );
 // <set>.set_color( position, color_instance )
 // 變更指標位置色彩

color_set.insert( [ Color( "#000" ) ], 0 )
 // <set>.insert( colors, position = after_the_last_color )
 // 插入色彩於指標位置，會增加影像長度

var color = color_set.average();
 // <set>.average()
 // 取得色彩平均值

var red = color_set.get_key_map( "r" );
 // <set>.get_key_map( key )
 // 取得單一色值的array

color_set.set_key_type( "g", red );
 // <set>.set_key_type( key, array )
 // 以array設定單一色值

輸出

var img = color_set.toImageData();
 // <set>.toImageData()
 // 輸出為ImageData，可以使用於canvas

var json = color_set.toString();
 // <set>.toString()
 // 輸出成JSON格式，可以用Color.Set.fn.parseString()解析

進階運算

var r_cm = color_set.get_key_contrast_map( "r" );
 // <set>.get_key_contrast_map( key )
 // 取得單一色值上每一點與平均值的差異值的array

var edge = color_set.edge_map();
 // <set>.edge_map()
 // 邊緣偵測

var analyse_obj = color_set.analyse();
 // <set>.analyse()
 // 色彩分析