Merge branch 'master' of git.savannah.gnu.org:/srv/git/emacs
[emacs.git] / lisp / color.el
blob6dbf3d55cbc0b53f0de5026b9fb0a621ab9b7225
1 ;;; color.el --- Color manipulation library -*- lexical-binding:t -*-
3 ;; Copyright (C) 2010-2017 Free Software Foundation, Inc.
5 ;; Authors: Julien Danjou <julien@danjou.info>
6 ;; Drew Adams <drew.adams@oracle.com>
7 ;; Keywords: lisp, faces, color, hex, rgb, hsv, hsl, cie-lab, background
9 ;; This file is part of GNU Emacs.
11 ;; GNU Emacs is free software: you can redistribute it and/or modify
12 ;; it under the terms of the GNU General Public License as published by
13 ;; the Free Software Foundation, either version 3 of the License, or
14 ;; (at your option) any later version.
16 ;; GNU Emacs is distributed in the hope that it will be useful,
17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 ;; GNU General Public License for more details.
21 ;; You should have received a copy of the GNU General Public License
22 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
24 ;;; Commentary:
26 ;; This package provides functions for manipulating colors, including
27 ;; converting between color representations, computing color
28 ;; complements, and computing CIEDE2000 color distances.
30 ;; Supported color representations include RGB (red, green, blue), HSV
31 ;; (hue, saturation, value), HSL (hue, saturation, luminance), sRGB,
32 ;; CIE XYZ, and CIE L*a*b* color components.
34 ;;; Code:
36 ;; Emacs < 23.3
37 (eval-and-compile
38 (unless (boundp 'float-pi)
39 (defconst float-pi (* 4 (atan 1)) "The value of Pi (3.1415926...).")))
41 ;;;###autoload
42 (defun color-name-to-rgb (color &optional frame)
43 "Convert COLOR string to a list of normalized RGB components.
44 COLOR should be a color name (e.g. \"white\") or an RGB triplet
45 string (e.g. \"#ff12ec\").
47 Normally the return value is a list of three floating-point
48 numbers, (RED GREEN BLUE), each between 0.0 and 1.0 inclusive.
50 Optional argument FRAME specifies the frame where the color is to be
51 displayed. If FRAME is omitted or nil, use the selected frame.
52 If FRAME cannot display COLOR, return nil."
53 ;; `colors-values' maximum value is either 65535 or 65280 depending on the
54 ;; display system. So we use a white conversion to get the max value.
55 (let ((valmax (float (car (color-values "#ffffffffffff")))))
56 (mapcar (lambda (x) (/ x valmax)) (color-values color frame))))
58 (defun color-rgb-to-hex (red green blue &optional digits-per-component)
59 "Return hexadecimal #RGB notation for the color specified by RED GREEN BLUE.
60 RED, GREEN, and BLUE should be numbers between 0.0 and 1.0, inclusive.
61 Optional argument DIGITS-PER-COMPONENT can be either 4 (the default)
62 or 2; use the latter if you need a 24-bit specification of a color."
63 (or digits-per-component (setq digits-per-component 4))
64 (let* ((maxval (if (= digits-per-component 2) 255 65535))
65 (fmt (if (= digits-per-component 2) "#%02x%02x%02x" "#%04x%04x%04x")))
66 (format fmt (* red maxval) (* green maxval) (* blue maxval))))
68 (defun color-complement (color-name)
69 "Return the color that is the complement of COLOR-NAME.
70 COLOR-NAME should be a string naming a color (e.g. \"white\"), or
71 a string specifying a color's RGB components (e.g. \"#ff12ec\")."
72 (let ((color (color-name-to-rgb color-name)))
73 (list (- 1.0 (nth 0 color))
74 (- 1.0 (nth 1 color))
75 (- 1.0 (nth 2 color)))))
77 (defun color-gradient (start stop step-number)
78 "Return a list with STEP-NUMBER colors from START to STOP.
79 The color list builds a color gradient starting at color START to
80 color STOP. It does not include the START and STOP color in the
81 resulting list."
82 (let* ((r (nth 0 start))
83 (g (nth 1 start))
84 (b (nth 2 start))
85 (r-step (/ (- (nth 0 stop) r) (1+ step-number)))
86 (g-step (/ (- (nth 1 stop) g) (1+ step-number)))
87 (b-step (/ (- (nth 2 stop) b) (1+ step-number)))
88 result)
89 (dotimes (_ step-number)
90 (push (list (setq r (+ r r-step))
91 (setq g (+ g g-step))
92 (setq b (+ b b-step)))
93 result))
94 (nreverse result)))
96 (defun color-hue-to-rgb (v1 v2 h)
97 "Compute hue from V1 and V2 H.
98 Used internally by `color-hsl-to-rgb'."
99 (cond
100 ((< h (/ 6.0)) (+ v1 (* (- v2 v1) h 6.0)))
101 ((< h 0.5) v2)
102 ((< h (/ 2.0 3)) (+ v1 (* (- v2 v1) (- (/ 2.0 3) h) 6.0)))
103 (t v1)))
105 (defun color-hsl-to-rgb (H S L)
106 "Convert hue, saturation and luminance to their RGB representation.
107 H, S, and L should each be numbers between 0.0 and 1.0, inclusive.
108 Return a list (RED GREEN BLUE), where each element is between 0.0 and 1.0,
109 inclusive."
110 (if (= S 0.0)
111 (list L L L)
112 (let* ((m2 (if (<= L 0.5)
113 (* L (+ 1.0 S))
114 (- (+ L S) (* L S))))
115 (m1 (- (* 2.0 L) m2)))
116 (list
117 (color-hue-to-rgb m1 m2 (mod (+ H (/ 3.0)) 1))
118 (color-hue-to-rgb m1 m2 H)
119 (color-hue-to-rgb m1 m2 (mod (- H (/ 3.0)) 1))))))
121 (defun color-complement-hex (color)
122 "Return the color that is the complement of COLOR, in hexadecimal format."
123 (apply 'color-rgb-to-hex (color-complement color)))
125 (defun color-rgb-to-hsv (red green blue)
126 "Convert RGB color components to HSV.
127 RED, GREEN, and BLUE should each be numbers between 0.0 and 1.0,
128 inclusive. Return a list (HUE SATURATION VALUE), where HUE is
129 in radians and both SATURATION and VALUE are between 0.0 and 1.0,
130 inclusive."
131 (let* ((r (float red))
132 (g (float green))
133 (b (float blue))
134 (max (max r g b))
135 (min (min r g b)))
136 (if (< (- max min) 1e-8)
137 (list 0.0 0.0 min)
138 (list
139 (/ (* 2 float-pi
140 (cond ((and (= r g) (= g b)) 0)
141 ((and (= r max)
142 (>= g b))
143 (* 60 (/ (- g b) (- max min))))
144 ((and (= r max)
145 (< g b))
146 (+ 360 (* 60 (/ (- g b) (- max min)))))
147 ((= max g)
148 (+ 120 (* 60 (/ (- b r) (- max min)))))
149 ((= max b)
150 (+ 240 (* 60 (/ (- r g) (- max min)))))))
151 360)
152 (if (= max 0) 0 (- 1 (/ min max)))
153 max))))
155 (defun color-rgb-to-hsl (red green blue)
156 "Convert RGB colors to their HSL representation.
157 RED, GREEN, and BLUE should each be numbers between 0.0 and 1.0,
158 inclusive. Return a list (HUE SATURATION LUMINANCE), where
159 each element is between 0.0 and 1.0, inclusive."
160 (let* ((r red)
161 (g green)
162 (b blue)
163 (max (max r g b))
164 (min (min r g b))
165 (delta (- max min))
166 (l (/ (+ max min) 2.0)))
167 (if (= delta 0)
168 (list 0.0 0.0 l)
169 (let* ((s (if (<= l 0.5) (/ delta (+ max min))
170 (/ delta (- 2.0 max min))))
171 (rc (/ (- max r) delta))
172 (gc (/ (- max g) delta))
173 (bc (/ (- max b) delta))
174 (h (mod
176 (cond
177 ((= r max) (- bc gc))
178 ((= g max) (+ 2.0 rc (- bc)))
179 (t (+ 4.0 gc (- rc))))
180 6.0) 1.0)))
181 (list h s l)))))
183 (defun color-srgb-to-xyz (red green blue)
184 "Convert RED GREEN BLUE colors from the sRGB color space to CIE XYZ.
185 RED, GREEN and BLUE should be between 0.0 and 1.0, inclusive."
186 (let ((r (if (<= red 0.04045)
187 (/ red 12.95)
188 (expt (/ (+ red 0.055) 1.055) 2.4)))
189 (g (if (<= green 0.04045)
190 (/ green 12.95)
191 (expt (/ (+ green 0.055) 1.055) 2.4)))
192 (b (if (<= blue 0.04045)
193 (/ blue 12.95)
194 (expt (/ (+ blue 0.055) 1.055) 2.4))))
195 (list (+ (* 0.4124564 r) (* 0.3575761 g) (* 0.1804375 b))
196 (+ (* 0.21266729 r) (* 0.7151522 g) (* 0.0721750 b))
197 (+ (* 0.0193339 r) (* 0.1191920 g) (* 0.9503041 b)))))
199 (defun color-xyz-to-srgb (X Y Z)
200 "Convert CIE X Y Z colors to sRGB color space."
201 (let ((r (+ (* 3.2404542 X) (* -1.5371385 Y) (* -0.4985314 Z)))
202 (g (+ (* -0.9692660 X) (* 1.8760108 Y) (* 0.0415560 Z)))
203 (b (+ (* 0.0556434 X) (* -0.2040259 Y) (* 1.0572252 Z))))
204 (list (if (<= r 0.0031308)
205 (* 12.92 r)
206 (- (* 1.055 (expt r (/ 2.4))) 0.055))
207 (if (<= g 0.0031308)
208 (* 12.92 g)
209 (- (* 1.055 (expt g (/ 2.4))) 0.055))
210 (if (<= b 0.0031308)
211 (* 12.92 b)
212 (- (* 1.055 (expt b (/ 2.4))) 0.055)))))
214 (defconst color-d65-xyz '(0.950455 1.0 1.088753)
215 "D65 white point in CIE XYZ.")
217 (defconst color-cie-ε (/ 216 24389.0))
218 (defconst color-cie-κ (/ 24389 27.0))
220 (defun color-xyz-to-lab (X Y Z &optional white-point)
221 "Convert CIE XYZ to CIE L*a*b*.
222 WHITE-POINT specifies the (X Y Z) white point for the
223 conversion. If omitted or nil, use `color-d65-xyz'."
224 (pcase-let* ((`(,Xr ,Yr ,Zr) (or white-point color-d65-xyz))
225 (xr (/ X Xr))
226 (yr (/ Y Yr))
227 (zr (/ Z Zr))
228 (fx (if (> xr color-cie-ε)
229 (expt xr (/ 3.0))
230 (/ (+ (* color-cie-κ xr) 16) 116.0)))
231 (fy (if (> yr color-cie-ε)
232 (expt yr (/ 3.0))
233 (/ (+ (* color-cie-κ yr) 16) 116.0)))
234 (fz (if (> zr color-cie-ε)
235 (expt zr (/ 3.0))
236 (/ (+ (* color-cie-κ zr) 16) 116.0))))
237 (list
238 (- (* 116 fy) 16) ; L
239 (* 500 (- fx fy)) ; a
240 (* 200 (- fy fz))))) ; b
242 (defun color-lab-to-xyz (L a b &optional white-point)
243 "Convert CIE L*a*b* to CIE XYZ.
244 WHITE-POINT specifies the (X Y Z) white point for the
245 conversion. If omitted or nil, use `color-d65-xyz'."
246 (pcase-let* ((`(,Xr ,Yr ,Zr) (or white-point color-d65-xyz))
247 (fy (/ (+ L 16) 116.0))
248 (fz (- fy (/ b 200.0)))
249 (fx (+ (/ a 500.0) fy))
250 (xr (if (> (expt fx 3.0) color-cie-ε)
251 (expt fx 3.0)
252 (/ (- (* fx 116) 16) color-cie-κ)))
253 (yr (if (> L (* color-cie-κ color-cie-ε))
254 (expt (/ (+ L 16) 116.0) 3.0)
255 (/ L color-cie-κ)))
256 (zr (if (> (expt fz 3) color-cie-ε)
257 (expt fz 3.0)
258 (/ (- (* 116 fz) 16) color-cie-κ))))
259 (list (* xr Xr) ; X
260 (* yr Yr) ; Y
261 (* zr Zr)))) ; Z
263 (defun color-srgb-to-lab (red green blue)
264 "Convert RGB to CIE L*a*b*."
265 (apply 'color-xyz-to-lab (color-srgb-to-xyz red green blue)))
267 (defun color-lab-to-srgb (L a b)
268 "Convert CIE L*a*b* to RGB."
269 (apply 'color-xyz-to-srgb (color-lab-to-xyz L a b)))
271 (defun color-cie-de2000 (color1 color2 &optional kL kC kH)
272 "Return the CIEDE2000 color distance between COLOR1 and COLOR2.
273 Both COLOR1 and COLOR2 should be in CIE L*a*b* format, as
274 returned by `color-srgb-to-lab' or `color-xyz-to-lab'."
275 (pcase-let*
276 ((`(,L₁ ,a₁ ,b₁) color1)
277 (`(,L₂ ,a₂ ,b₂) color2)
278 (kL (or kL 1))
279 (kC (or kC 1))
280 (kH (or kH 1))
281 (C(sqrt (+ (expt a₁ 2.0) (expt b₁ 2.0))))
282 (C(sqrt (+ (expt a₂ 2.0) (expt b₂ 2.0))))
283 (C̄ (/ (+ C₁ C₂) 2.0))
284 (G (* 0.5 (- 1 (sqrt (/ (expt7.0)
285 (+ (expt7.0) (expt 25 7.0)))))))
286 (a′₁ (* (+ 1 G) a₁))
287 (a′₂ (* (+ 1 G) a₂))
288 (C′₁ (sqrt (+ (expt a′₁ 2.0) (expt b₁ 2.0))))
289 (C′₂ (sqrt (+ (expt a′₂ 2.0) (expt b₂ 2.0))))
290 (h′₁ (if (and (= b₁ 0) (= a′₁ 0))
292 (let ((v (atan b₁ a′₁)))
293 (if (< v 0)
294 (+ v (* 2 float-pi))
295 v))))
296 (h′₂ (if (and (= b₂ 0) (= a′₂ 0))
298 (let ((v (atan b₂ a′₂)))
299 (if (< v 0)
300 (+ v (* 2 float-pi))
301 v))))
302 (ΔL′ (- L₂ L₁))
303 (ΔC′ (- C′₂ C′₁))
304 (Δh′ (cond ((= (* C′₁ C′₂) 0)
306 ((<= (abs (- h′₂ h′₁)) float-pi)
307 (- h′₂ h′₁))
308 ((> (- h′₂ h′₁) float-pi)
309 (- (- h′₂ h′₁) (* 2 float-pi)))
310 ((< (- h′₂ h′₁) (- float-pi))
311 (+ (- h′₂ h′₁) (* 2 float-pi)))))
312 (ΔH′ (* 2 (sqrt (* C′₁ C′₂)) (sin (/ Δh′ 2.0))))
313 (L̄′ (/ (+ L₁ L₂) 2.0))
314 (C̄′ (/ (+ C′₁ C′₂) 2.0))
315 (h̄′ (cond ((= (* C′₁ C′₂) 0)
316 (+ h′₁ h′₂))
317 ((<= (abs (- h′₁ h′₂)) float-pi)
318 (/ (+ h′₁ h′₂) 2.0))
319 ((< (+ h′₁ h′₂) (* 2 float-pi))
320 (/ (+ h′₁ h′₂ (* 2 float-pi)) 2.0))
321 ((>= (+ h′₁ h′₂) (* 2 float-pi))
322 (/ (+ h′₁ h′₂ (* -2 float-pi)) 2.0))))
323 (T (+ 1
324 (- (* 0.17 (cos (- h̄′ (degrees-to-radians 30)))))
325 (* 0.24 (cos (* h̄′ 2)))
326 (* 0.32 (cos (+ (* h̄′ 3) (degrees-to-radians 6))))
327 (- (* 0.20 (cos (- (* h̄′ 4) (degrees-to-radians 63)))))))
328 (Δθ (* (degrees-to-radians 30)
329 (exp (- (expt (/ (- h̄′ (degrees-to-radians 275))
330 (degrees-to-radians 25)) 2.0)))))
331 (Rc (* 2 (sqrt (/ (expt C̄′ 7.0) (+ (expt C̄′ 7.0) (expt 25.0 7.0))))))
332 (Sl (+ 1 (/ (* 0.015 (expt (- L̄′ 50) 2.0))
333 (sqrt (+ 20 (expt (- L̄′ 50) 2.0))))))
334 (Sc (+ 1 (* C̄′ 0.045)))
335 (Sh (+ 1 (* 0.015 C̄′ T)))
336 (Rt (- (* (sin (* Δθ 2)) Rc))))
337 (sqrt (+ (expt (/ ΔL′ (* Sl kL)) 2.0)
338 (expt (/ ΔC′ (* Sc kC)) 2.0)
339 (expt (/ ΔH′ (* Sh kH)) 2.0)
340 (* Rt (/ ΔC′ (* Sc kC)) (/ ΔH′ (* Sh kH)))))))
342 (defun color-clamp (value)
343 "Make sure VALUE is a number between 0.0 and 1.0 inclusive."
344 (min 1.0 (max 0.0 value)))
346 (defun color-saturate-hsl (H S L percent)
347 "Make a color more saturated by a specified amount.
348 Given a color defined in terms of hue, saturation, and luminance
349 \(arguments H, S, and L), return a color that is PERCENT more
350 saturated. Returns a list (HUE SATURATION LUMINANCE)."
351 (list H (color-clamp (+ S (/ percent 100.0))) L))
353 (defun color-saturate-name (name percent)
354 "Make a color with a specified NAME more saturated by PERCENT.
355 See `color-saturate-hsl'."
356 (apply 'color-rgb-to-hex
357 (apply 'color-hsl-to-rgb
358 (apply 'color-saturate-hsl
359 (append
360 (apply 'color-rgb-to-hsl
361 (color-name-to-rgb name))
362 (list percent))))))
364 (defun color-desaturate-hsl (H S L percent)
365 "Make a color less saturated by a specified amount.
366 Given a color defined in terms of hue, saturation, and luminance
367 \(arguments H, S, and L), return a color that is PERCENT less
368 saturated. Returns a list (HUE SATURATION LUMINANCE)."
369 (color-saturate-hsl H S L (- percent)))
371 (defun color-desaturate-name (name percent)
372 "Make a color with a specified NAME less saturated by PERCENT.
373 See `color-desaturate-hsl'."
374 (color-saturate-name name (- percent)))
376 (defun color-lighten-hsl (H S L percent)
377 "Make a color lighter by a specified amount.
378 Given a color defined in terms of hue, saturation, and luminance
379 \(arguments H, S, and L), return a color that is PERCENT lighter.
380 Returns a list (HUE SATURATION LUMINANCE)."
381 (list H S (color-clamp (+ L (/ percent 100.0)))))
383 (defun color-lighten-name (name percent)
384 "Make a color with a specified NAME lighter by PERCENT.
385 See `color-lighten-hsl'."
386 (apply 'color-rgb-to-hex
387 (apply 'color-hsl-to-rgb
388 (apply 'color-lighten-hsl
389 (append
390 (apply 'color-rgb-to-hsl
391 (color-name-to-rgb name))
392 (list percent))))))
394 (defun color-darken-hsl (H S L percent)
395 "Make a color darker by a specified amount.
396 Given a color defined in terms of hue, saturation, and luminance
397 \(arguments H, S, and L), return a color that is PERCENT darker.
398 Returns a list (HUE SATURATION LUMINANCE)."
399 (color-lighten-hsl H S L (- percent)))
401 (defun color-darken-name (name percent)
402 "Make a color with a specified NAME darker by PERCENT.
403 See `color-darken-hsl'."
404 (color-lighten-name name (- percent)))
406 (provide 'color)
408 ;;; color.el ends here