colors-basics.tex /size: 35 Kb    last modification: 2021-10-28 13:50
1% language=us runpath=texruns:manuals/colors
2
3\startcomponent colors-basics
4
5\environment colors-environment
6
7\usemodule[setups-basics] \loadsetups[i-color]
8
9\startchapter[title=Basics][color=darkred]
10
11\startsection[title=Color models]
12
13When you work with displays, and most of us do, the dominant color model is \RGB.
14As far as I know \CMYK\ electrowetting displays are still not in production and
15even there the \CMYK\ seems to have made place for \RGB\ (at least in promotion
16movies). This is strange since where \RGB\ is used in cases where colors are
17radiated, \CMYK\ shows up in reflective situations (and epub readers are just
18that). But \RGB\ and \CMYK\ being complementary is not the only difference:
19\CMYK\ has an explicit black channel, and as a consequence you cannot go from one
20to the other color space without loss.
21
22In print \CMYK\ is dominant but in order to get real good colors you can go with
23spot colors. The ink is not mixed with others but applied in more or less
24quantity. A mixture of spot colors and \CMYK\ is used too. You can combine spot
25colors into a so called multitone color. Often spot colors have names (for
26instance refering to Pantone) but they always have a specification in another
27color space in order to be shown on screen. Think of \quotation {gold} being a
28valid ink, but hard to render on screen, so some yellowish replacement is used
29there when documents get prepared on screen.
30
31In \CONTEXT\ all these models are supported, either or not at the same time. In \MKII\
32you had to turn on color support explicitly, if only because of the impact of the
33overhead on performance, but in \MKIV\ color is on by default. You can disable it
34with:
35
36\starttyping
37\setupcolors
38  [state=stop]
39\stoptyping
40
41The three mentioned models are controlled by keys, and by default we have set:
42
43\starttyping
44\setupcolors
45  [rgb=yes,
46   cmyk=yes,
47   spot=yes]
48\stoptyping
49
50Spot colors and their combinations in multitone colors are controlled by the same
51parameter. You can define colors in the \HSV\ color space but in the end these
52become and behave like \RGB.
53
54\stopsection
55
56\startsection[title=Using color]
57
58Normally you will use colors grouped. Most environments accept a \type {color}
59parameter (some have \type {textcolor} or similar longer names too). In a running
60text you can use:
61
62\starttyping
63\color[red]{This will show up red.}
64\stoptyping
65
66or:
67
68\starttyping
69\startcolor[red]
70    This will show up red.
71\stopcolor
72\stoptyping
73
74In case you don't want the grouping you can use:
75
76\starttyping
77\directcolor[red]
78\stoptyping
79
80You can even use:
81
82\starttyping
83\colored[r=0.5]{also red}
84\stoptyping
85
86In which case an anonymous color is used. An ungrouped variant of this is:
87
88\starttyping
89\directcolored[r=0.5]
90\stoptyping
91
92You will seldom use these direct variants, but they might come in handy when you
93write macros yourself where extra grouping starts interfering. In fact, it often
94makes sense to use a bit more abstraction:
95
96\startbuffer
97\definehighlight
98  [important]
99  [color=red]
100
101First \highlight[important]{or} second \important {or} third.
102\stopbuffer
103
104\typebuffer
105
106This gives: \inlinebuffer .
107
108\stopsection
109
110\startsection[title=Using \CMYK\ or \RGB]
111
112When you compare colors in different color spaces, you need to be aware of the
113fact that when a black component is used in \CMYK, conversion to \RGB\ might give
114the same results but going back from that to \CMYK\ will look different from the
115original. Also, \CMYK\ colors are often tuned for specific paper.
116
117\startbuffer
118\definecolor[demo:rgb:1][r=1.0,g=1.0]
119\definecolor[demo:rgb:2][r=1.0,g=1.0,b=0.5]
120\definecolor[demo:rgb:3][r=1.0,g=1.0,b=0.6]
121\definecolor[demo:cmy:1][y=1.0]
122\definecolor[demo:cmy:2][y=0.5]
123\definecolor[demo:cmy:3][y=0.4]
124\stopbuffer
125
126\typebuffer \getbuffer
127
128In these definitions we have no black component. In \in {figure}
129[color:rgb:cmyk:1] we see how these colors translate to the other color spaces.
130
131\startbuffer[compare]
132\startbuffer
133\definemeasure[demo][(\textwidth-2em)/3]
134\startcombination[3*2]
135    {\blackrule[width=\measure{demo},height=1cm,depth=0cm,color=demo:rgb:1]}{\infofont\colorcomponents{demo:rgb:1}}
136    {\blackrule[width=\measure{demo},height=1cm,depth=0cm,color=demo:rgb:2]}{\infofont\colorcomponents{demo:rgb:2}}
137    {\blackrule[width=\measure{demo},height=1cm,depth=0cm,color=demo:rgb:3]}{\infofont\colorcomponents{demo:rgb:3}}
138    {\blackrule[width=\measure{demo},height=1cm,depth=0cm,color=demo:cmy:1]}{\infofont\colorcomponents{demo:cmy:1}}
139    {\blackrule[width=\measure{demo},height=1cm,depth=0cm,color=demo:cmy:2]}{\infofont\colorcomponents{demo:cmy:2}}
140    {\blackrule[width=\measure{demo},height=1cm,depth=0cm,color=demo:cmy:3]}{\infofont\colorcomponents{demo:cmy:3}}
141\stopcombination
142\stopbuffer
143
144\startcombination[1*4]
145    {\setupcolors[rgb=yes,cmyk=yes]\getbuffer} {Both \RGB\ and \CMYK\ enabled}
146    {\setupcolors [rgb=no,cmyk=yes]\getbuffer} {Only \CMYK\ enabled.}
147    {\setupcolors [rgb=yes,cmyk=no]\getbuffer} {Only \RGB\ enabled.}
148    {\setupcolors  [rgb=no,cmyk=no]\getbuffer} {Both \RGB\ and \CMYK\ disabled.}
149\stopcombination
150\stopbuffer
151
152\startplacefigure[location=page,reference=color:rgb:cmyk:1,title={What happens when we disable color spaces.}]
153    \getbuffer[compare]
154\stopplacefigure
155
156\startbuffer
157\definecolor[demo:rgb:1][r=0.5,g=0.6,b=0.7]
158\definecolor[demo:rgb:2][r=0.5,g=0.6,b=0.7]
159\definecolor[demo:rgb:3][r=0.5,g=0.6,b=0.7]
160\definecolor[demo:cmy:1][c=0.5,m=0.4,y=0.3]
161\definecolor[demo:cmy:2][c=0.4,m=0.3,y=0.2,k=0.1]
162\definecolor[demo:cmy:3][c=0.3,m=0.2,y=0.1,k=0.2]
163\stopbuffer
164
165\typebuffer \getbuffer
166
167When we define the colors as above, you can see a difference between the \RGB\
168and \CMYK\ values, but also between a black component versus black distributed
169over the colorants. This is seen best in \in {figure} [color:rgb:cmyk:2] when we
170compare the first and third colors alongside. In \in {figure} [color:rgb:cmyk:3]
171you see the whole repertoire.
172
173\startplacefigure[reference=color:rgb:cmyk:2,title={The impact of black on a \CMYK\ color.}]
174\startMPcode
175    fill fullsquare xyscaled (TextWidth,25mm) withcolor \MPcolor{demo:cmy:3} ;
176    fill fullsquare xyscaled (TextWidth,20mm) withcolor \MPcolor{demo:cmy:1} ;
177    fill fullsquare xyscaled (TextWidth,10mm) withcolor \MPcolor{demo:cmy:3} ;
178    fill fullsquare xyscaled (TextWidth, 5mm) withcolor \MPcolor{demo:cmy:1} ;
179\stopMPcode
180\stopplacefigure
181
182\startplacefigure[reference=color:rgb:cmyk:3,title={What happens when we disable color spaces (black component).}]
183    \getbuffer[compare]
184\stopplacefigure
185
186\stopsection
187
188\startsection[title=Conversion]
189
190A conversion to gray happens when \RGB\ and \CMYK\ are both disabled. The following
191setting forces conversion. It disables both \RGB\ and \CMYK:
192
193\starttyping
194\setupcolors
195  [conversion=always]
196\stoptyping
197
198The default setting is \type {yes} which means that colors will be reduced to gray in
199the backend. This is an optimization which can result in slightly smaller output:
200
201\starttabulate[|l|c|l|]
202\NC          \NC \bf \# \NC \bf \PDF\ sequence                  \NC \NR
203\NC \bf cmyk \NC 23     \NC \tttf 0 0 0 0.5 k 0 0 0 0.5 K       \NC \NR
204\NC \bf rgb  \NC 29     \NC \tttf 0.5 0.5 0.5 rg 0.5 0.5 0.5 RG \NC \NR
205\NC \bf gray \NC 11     \NC \tttf 0.5 g 0.5 G                   \NC \NR
206\stoptabulate
207
208The conversion to gray is controlled by:
209
210\starttyping
211\setupcolors
212  [factor=yes]
213\stoptyping
214
215Like \type {conversion} the \type {factor} is a global setting. You can play with the factor values.
216The default (\type {yes}) uses the factors used by color television:
217
218\startformula
219    s = 0.30r + 0.59g + 0.11b
220\stopformula
221
222In \in {figure} [color:demo:gray] we demonstrate what happens when you use different
223values. Normally you won't change the defaults but for experimenting we do provide
224the option:
225
226\starttyping
227\setupcolors
228  [factor=0.20:0.40:0.40]
229\stoptyping
230
231There is one pitfall. Colors are finalized per page and as this is a backend
232feature the value current when a page is shipped out is used. An exception are
233\METAPOST\ graphics, as they have local resources and are finalized immediately.
234This is hardly a limitation because one will never set these numbers in the
235middle of a document.
236
237\starttexdefinition color:demo:gray:do
238    \definecolor[demo:rgb:0][r=0.5,g=0.6,b=0.7]
239  % \blackrule[width=4cm,height=1cm,color=demo:rgb:0]
240    \lower.4\strutdp\hbox\bgroup
241        \startMPcode
242            fill unitsquare xyscaled (.5TextWidth,.9LineHeight)
243                withcolor "demo:rgb:0";
244        \stopMPcode
245    \egroup
246\stoptexdefinition
247
248\starttexdefinition color:demo:gray #1#2#3
249    \NC \tttf #1 \NC \tttf #2  \NC \tttf #3 \NC
250        \setupcolors[factor={#1:#2:#3}]
251        \setupcolors[rgb=no,cmyk=no]
252        \texdefinition{color:demo:gray:do}
253        \setupcolors[factor=yes]
254    \NC \NR
255\stoptexdefinition
256
257\startplacefigure[reference=color:demo:gray,title={Color to gray conversion using factors.}]
258\starttabulate[|c|c|c|c|]
259\NC \bf r \NC \bf g \NC \bf b \NC \bf gray \NC \NR
260\NC       \NC       \NC       \NC \texdefinition{color:demo:gray:do} \NC \NR
261\texdefinition{color:demo:gray}{0.30}{0.59}{0.11}
262\texdefinition{color:demo:gray}{0.30}{0.11}{0.59}
263\texdefinition{color:demo:gray}{0.59}{0.30}{0.11}
264\texdefinition{color:demo:gray}{0.11}{0.30}{0.59}
265\texdefinition{color:demo:gray}{0.11}{0.59}{0.30}
266\texdefinition{color:demo:gray}{0.59}{0.11}{0.30}
267\texdefinition{color:demo:gray}{0.20}{0.40}{0.40}
268\texdefinition{color:demo:gray}{0.30}{0.60}{0.10}
269\texdefinition{color:demo:gray}{0.20}{0.30}{0.20}
270\texdefinition{color:demo:gray}{0.40}{0.40}{0.40}
271\stoptabulate
272\stopplacefigure
273
274\stopsection
275
276% let's take a break and watch: https://www.youtube.com/watch?v=baLrrW3El-M
277
278\startsection[title=Definitions]
279
280The mostly used color definition command is \type {\definecolor}. Here we define the
281primary colors:
282
283\startbuffer
284\definecolor [red]     [r=1]
285\definecolor [green]   [g=1]
286\definecolor [blue]    [b=1]
287\definecolor [yellow]  [y=1]
288\definecolor [magenta] [m=1]
289\definecolor [cyan]    [c=1]
290\stopbuffer
291
292\typebuffer \getbuffer
293
294These can be visualized as follows:
295
296\startbuffer
297\showcolorcomponents[red,green,blue,yellow,magenta,cyan,black]
298\stopbuffer
299
300\typebuffer \getbuffer
301
302Transparency is included in these tables but is, as already noted, in fact
303independent. It can be defined with a color:
304
305\startbuffer
306\definecolor [t:red]   [r=1,a=1,t=.5]
307\definecolor [t:green] [g=1,a=1,t=.5]
308\definecolor [t:blue]  [b=1,a=1,t=.5]
309\stopbuffer
310
311\typebuffer \getbuffer
312
313This time the transparency values show up too:
314
315\showcolorcomponents[t:red,t:green,t:blue]
316
317Because transparency is separated from color, we can define transparent behaviour
318as follows:
319
320\startbuffer
321\definecolor[t:only] [a=1,t=.5]
322\stopbuffer
323
324\typebuffer \getbuffer
325
326\startbuffer
327    \dontleavehmode
328    \blackrule[width=4cm,height=1cm,color=darkgreen]%
329    \hskip-2cm
330    \color[t:only]{\blackrule[width=4cm,height=1cm,color=darkred]}%
331    \hskip-2cm
332    \color[t:only]{\blackrule[width=4cm,height=1cm]}
333\stopbuffer
334
335\typebuffer
336
337We skip back to create an overlay, so we get:
338
339\startlinecorrection
340\getbuffer
341\stoplinecorrection
342
343In the section about transparency a bit more will be said about the relation between
344color and transparencies and how to cheat.
345
346As soon as you need to typeset something for professional printing, spot colors
347will show up so they are supported too. A spot color is not really a color but
348related to the substance that gets put on the paper. This can be ink but also
349something metallic, like silver, gold or some texture. In these cases we need
350something to represent it when not printed on a suitable device so again we end
351up with a color. This is reflected in the way spot colors are set up.
352
353\startbuffer
354\definecolor     [parentspot]               [r=.5,g=.2,b=.8]
355\definespotcolor [childspot-1] [parentspot] [p=.7,e=fancy]
356\definespotcolor [childspot-2] [parentspot] [p=.4]
357\stopbuffer
358
359\typebuffer \getbuffer
360
361The three colors, two of them are spot colors, show up as follows:
362
363\setupcolors[spot=yes]
364
365\showcolorcomponents[parentspot,childspot-1,childspot-2]
366
367The \type {p} is comparable to the \type {s} in gray scales. The \type {e}
368parameter can be used to specify a name for the color. In the \PDF\ file that
369name will become the separation name (a popular commercial naming scheme is
370Pantone).
371
372A combination of spotcolor is called a multitone color. These are defined as
373follows (we also define a few spotcolors and use transparency):
374
375\startbuffer
376\definespotcolor [spotone]   [darkred]   [p=1]
377\definespotcolor [spottwo]   [darkgreen] [p=1]
378
379\definespotcolor [spotone-t] [darkred]   [a=1,t=.5]
380\definespotcolor [spottwo-t] [darkgreen] [a=1,t=.5]
381
382\definemultitonecolor
383    [whatever]
384    [spotone=.5,spottwo=.5]
385    [b=.5]
386
387\definemultitonecolor
388    [whatever-t]
389    [spotone=.5,spottwo=.5]
390    [b=.5]
391    [a=1,t=.5]
392\stopbuffer
393
394\typebuffer \getbuffer
395
396\showcolorcomponents[spotone,spottwo,spotone-t,spottwo-t,whatever,whatever-t]
397
398Transparencies combine as follows:
399
400\startbuffer
401\blackrule[width=3cm,height=1cm,color=spotone-t]\hskip-1.5cm
402\blackrule[width=3cm,height=1cm,color=spotone-t]
403\stopbuffer
404
405\typebuffer
406
407\startlinecorrection
408\dontleavehmode\getbuffer
409\stoplinecorrection
410
411In case you want to specify colors in the \HSV\ color space, you can do that too.
412The hue parameter (\type {h}) is in degrees and runs from 0 upto 360 (larger
413values get divided). The saturation (\type {s}) and value (\type {v}) parameters
414run from 0 to 1. The \type {v} parameter is mandate. In \in {figure} [fig:hsv] we
415show what the last two variables do.
416
417\starttyping
418\definecolor[somecolor][h=125,s=0.5,v=0.8]
419\stoptyping
420
421\startMPextensions
422    vardef hsvcircle(expr s, v) =
423        image ( save p ; path p ; p := fullcircle ;
424            save l ; numeric l ; l := length(p)/360 ;
425            for i=0 upto 360 :
426                fill origin -- subpath (i*l,(i+1)*l) of p -- cycle withcolor hsvtorgb(i,s,v) ;
427            endfor ;
428        )
429    enddef;
430\stopMPextensions
431
432\startplacefigure[reference=fig:hsv,title={Four hsv color circle running from 0 to 360 degrees, with zero at the right.}]
433    \startcombination[4*1]
434        {\startMPcode draw hsvcircle(0.6,0.6) scaled 3cm ; \stopMPcode} {\tttf s=0.6 v=0.6}
435        {\startMPcode draw hsvcircle(0.4,0.6) scaled 3cm ; \stopMPcode} {\tttf s=0.4 v=0.6}
436        {\startMPcode draw hsvcircle(0.6,0.4) scaled 3cm ; \stopMPcode} {\tttf s=0.6 v=0.4}
437        {\startMPcode draw hsvcircle(0.4,0.4) scaled 3cm ; \stopMPcode} {\tttf s=0.4 v=0.4}
438    \stopcombination
439\stopplacefigure
440
441% \scratchdimen\dimexpr(\textwidth-118pt)/120\relax
442% \dontleavehmode \dostepwiserecurse{0}{359}{1}{%
443%     \definecolor[tempcolor][h=#1,s=0.6,v=0.6]%
444%     \blackrule[color=tempcolor,width=\scratchdimen,height=1ex,depth=1ex]%
445%     \hskip1pt
446% }
447
448If you need to use hexadecimal color specifications you can use these
449definitions:
450
451\starttyping
452\definecolor[mycolor][x=4477AA]
453\definecolor[mycolor][h=4477AA]
454\definecolor[mycolor][x=66]
455\definecolor[mycolor][#4477AA]
456\stoptyping
457
458The \type {#} is normally not accepted in \TEX\ source code but when you get the
459specification from elsewhere (e.g.\ \XML) it can be convenient.
460
461\stopsection
462
463\startsection[title=Freezing colors]
464
465We can clone colors and thereby overload color dynamically. You can however
466freeze colors via the setup option \type {expansion}.
467
468\startbuffer
469\definecolor[green]   [r=.5]{({\green green ->   red})}
470\definecolor[green]   [g=.5]{({\green green -> green})}
471\definecolor[green]   [blue]{({\green green ->  blue})}
472\definecolor[blue]     [red]{({\green green ->   red})}
473\setupcolors[expansion=yes]%
474\definecolor[blue]     [red]%
475\definecolor[green]   [blue]%
476\definecolor[blue]    [r=.5]{({\green green ->  blue})}
477\stopbuffer
478
479\typebuffer
480
481\start
482\definecolor[red]  [r=.5]%
483\definecolor[green][g=.5]%
484\definecolor[blue] [b=.5]%
485\getbuffer
486\stop
487
488\stopsection
489
490\startsection[title=Color groups]
491
492Nowadays we seldom use colorgroups but they are still supported. Groups are
493collections of distinctive colors, something we needed in projects where many
494graphics had to be made and consistency between text and image colors was
495important. The groups can be translated into similar collections in drawing
496programs used at that time.
497
498\startbuffer
499\definecolorgroup
500  [redish]
501  [1.00:0.90:0.90, % 1
502   1.00:0.80:0.80, % 2
503   1.00:0.70:0.70, % 3
504   1.00:0.55:0.55, % 4
505   1.00:0.40:0.40, % 5
506   1.00:0.25:0.25, % 6
507   1.00:0.15:0.15, % 7
508   0.90:0.00:0.00] % 8
509\stopbuffer
510
511\typebuffer \getbuffer
512
513The redish color is called by number:
514
515\startbuffer
516\blackrule[width=3cm,height=1cm,depth=0pt,color=redish:1]\quad
517\blackrule[width=3cm,height=1cm,depth=0pt,color=redish:2]\quad
518\blackrule[width=3cm,height=1cm,depth=0pt,color=redish:3]
519\stopbuffer
520
521\typebuffer
522
523The number of elements is normally limited and eight is about what is useful and
524still distinguishes good enough when printed in black and white.
525
526\startlinecorrection
527\dontleavehmode\getbuffer
528\stoplinecorrection
529
530\startlinecorrection
531\setupcolors[rgb=no,cmyk=no]\dontleavehmode\getbuffer
532\stoplinecorrection
533
534\stopsection
535
536\startsection[title=Palets]
537
538Color palets are handy when you want to use a set of (named) colors but
539also want to switch efficiently between different definitions:
540
541\startbuffer
542\definepalet
543  [standard]
544  [darkred=darkcyan,
545   darkgreen=darkmagenta,
546   darkblue=darkyellow]
547\stopbuffer
548
549\typebuffer \getbuffer
550
551The \type {\setuppalet} commands switches to a palet. When a requested color is
552not part of a palet, a regular lookup happens. This is used as:
553
554\startbuffer
555\blackrule[width=15mm,height=10mm,depth=0mm,color=darkred]\quad
556\blackrule[width=15mm,height=10mm,depth=0mm,color=darkgreen]\quad
557\blackrule[width=15mm,height=10mm,depth=0mm,color=darkblue]\quad
558\setuppalet[standard]%
559\blackrule[width=15mm,height=10mm,depth=0mm,color=darkred]\quad
560\blackrule[width=15mm,height=10mm,depth=0mm,color=darkgreen]\quad
561\blackrule[width=15mm,height=10mm,depth=0mm,color=darkblue]
562\stopbuffer
563
564\typebuffer
565
566\startlinecorrection
567\dontleavehmode \getbuffer
568\stoplinecorrection
569
570Here we use color names but often you end up with more symbolic names:
571
572\starttyping
573\definepalet
574  [standard]
575  [important=darkred,
576   notabene=darkgreen,
577   warning=darkyellow]
578\stoptyping
579
580As with the regular color commands, the palet mechanism is an old one but it is
581well integrated. Instead of inheriting you can also use definitions:
582
583\starttyping
584\definepalet
585  [standard]
586  [important={r=.5},
587   notabene={g=.5},
588   warning={r=.5,g=.5}]
589\stoptyping
590
591\stopsection
592
593\startsection[title=Transparency]
594
595We already discussed transparency as part of colors. In most cases we will choose
596type {normal} (or \type {1}) as transparency type, but there are more:
597
598\startluacode
599    local codes = table.swapped(attributes.transparencies.names)
600
601    context.startcolumns { n = 4 }
602    context.starttabulate ( { "|B||" }, { keeptogether = "no" } )
603    for i=0,#codes do
604        context.NC()
605        context(i)
606        context.NC()
607        context(codes[i])
608        context.NC()
609        context.NR()
610    end
611    context.stoptabulate()
612    context.stopcolumns()
613\stopluacode
614
615In \in {figure} [fig:transparency] we compare these variants. Not all are as
616effective as their effect depends on several factors. You can read more about it
617in the \PDF\ specification.
618
619\startMPextensions
620    vardef transdemo(expr b)  =
621        image ( save p ; path p ; p := fullcircle ;
622            save l ; numeric l ; l := length(p)/16 ;
623            if (b = 1) or (b = 3) :
624                fill fullcircle scaled 1.00 withcolor yellow ;
625                fill fullcircle scaled 0.80 withcolor red ;
626                fill fullcircle scaled 0.60 withcolor black ;
627                fill fullcircle scaled 0.40 withcolor white ;
628                fill fullcircle scaled 0.20 withcolor .5white ;
629            fi ;
630            if (b = 2) or (b = 3) :
631                for i=0 upto 15 :
632                    fill origin -- subpath (i*l,(i+1)*l) of p -- cycle
633                        withcolor red
634                        withtransparency (i,0.5) ;
635                    draw textext("\ttbf " & decimal i) ysized .04 shifted (.45,0) rotated (i*360/16 + 360/32) ;
636                endfor ;
637            fi ;
638        )
639    enddef;
640\stopMPextensions
641
642\startplacefigure[reference=fig:transparency,title={The differences between the transparency options. The center is explicitly filled with white.}]
643    \startcombination[3*1]
644        {\startMPcode draw transdemo(1) scaled 4cm ; \stopMPcode} {\tttf backgrounds used}
645        {\startMPcode draw transdemo(2) scaled 4cm ; \stopMPcode} {\tttf transparencies used}
646        {\startMPcode draw transdemo(3) scaled 4cm ; \stopMPcode} {\tttf transparency overlayed}
647    \stopcombination
648\stopplacefigure
649
650Colors and transparencies are coupled by definitions. We will explain this by
651some examples. When we say:
652
653\startbuffer
654\definecolor[clr1][r=.5]
655\stopbuffer
656
657\typebuffer \getbuffer
658
659A non|-|transparent color is defined and when we say:
660
661\startbuffer
662\definecolor[clr2][g=.5,a=1,t=.5]
663\stopbuffer
664
665\typebuffer \getbuffer
666
667We defined a color with a transparency. However, color and transparency get separated
668attributes. So when we nest them as in:
669
670\startbuffer
671\color[clr1]{\bf RED   \color[clr2] {GREEN}}
672\color[clr2]{\bf GREEN \color[clr1] {RED}  }
673\stopbuffer
674
675\typebuffer
676
677we get:
678
679\startlines \getbuffer \stoplines
680
681The transparency of the outer color is also applied to the inner color. If you
682don't want that, you explicitly need to set them:
683
684\startbuffer
685\definecolor[clr3][b=.5,a=1,t=1]
686\stopbuffer
687
688\typebuffer \getbuffer
689
690\startbuffer
691\color[clr1]{\bf RED   \color[clr2] {GREEN} \color[clr3]{BLUE} }
692\color[clr2]{\bf GREEN \color[clr1] {RED}   \color[clr2]{GREEN}}
693\color[clr3]{\bf BLUE  \color[clr1] {RED}   \color[clr2]{GREEN}}
694\stopbuffer
695
696\typebuffer
697
698we get:
699
700\startlines \getbuffer \stoplines
701
702If you define a transparent|-|only color, you get transparent black:
703
704\startbuffer
705\definecolor[clr4][a=1,t=.5]
706\stopbuffer
707
708\typebuffer \getbuffer
709
710So:
711
712\startbuffer
713\color[clr1]{\bf RED    \color[clr4] {RED}}
714\color[clr4]{\bf BLACK  \color[clr1] {RED}}
715\stopbuffer
716
717\typebuffer
718
719gives:
720
721\startlines \getbuffer \stoplines
722
723In addition to the already discussed definers and setters we also have a few
724special ones. Personally I never needed them but they are the for completeness.
725
726\startbuffer
727\definetransparency[tsp1][a=1,t=.5]
728\stopbuffer
729
730\typebuffer \getbuffer
731
732We apply this to some text:
733
734\startbuffer
735\color      [clr1]{\bf RED   \transparent[tsp1] {RED}   }
736\transparent[tsp1]{\bf BLACK \color      [clr1] {RED}   }
737\transparent[tsp1]{\bf BLACK \transparent[reset]{BLACK} }
738\stopbuffer
739
740\typebuffer
741
742and get:
743
744\startlines \getbuffer \stoplines
745
746We can also only switch color:
747
748\startbuffer
749\color[clr1]{\bf RED \color    [clr2] {GREEN}}
750\color[clr1]{\bf RED \coloronly[clr2] {GREEN}}
751\stopbuffer
752
753\typebuffer
754
755So the second line has no transparency:
756
757\startlines \getbuffer \stoplines
758
759The \typ {\starttransparent} and \type {\startcoloronly} commands are the
760complements of \typ {\transparent} and \typ {\coloronly}.
761
762\stopsection
763
764\startsection[title=Interpolation]
765
766You can define intermediate colors in a way comparable with \METAPOST\ \type
767{.5[red,green]} kind of specifications. Here are some examples:
768
769\startbuffer
770\definecolor [mycolor1] [.5(red,green)]
771\definecolor [mycolor2] [.8(red,green)]
772\definecolor [mycolor3] [.4(red,white)]
773\definecolor [mycolor4] [.4(white,red)]
774
775\showcolorcomponents[red,green,mycolor1,mycolor2,mycolor3,mycolor4]
776\stopbuffer
777
778\typebuffer \getbuffer
779
780An older method, still available is:
781
782\starttyping
783\defineintermediatecolor[mycolor5][0.5,red,green]
784\stoptyping
785
786A variation on this are complementary colors:
787
788\startbuffer
789\definecolor[mycolor1][.5(blue,red)]
790\definecolor[mycolor2][-.5(blue,red)]
791\definecolor[mycolor3][-(blue)]
792\definecolor[mycolor4][-(red)]
793
794\showcolorcomponents[blue,red,mycolor1,mycolor2,mycolor3,mycolor4]
795\stopbuffer
796
797\typebuffer \getbuffer
798
799\stopsection
800
801\startsection[title=PDF]
802
803Although it is not perfect, \PDF\ evolved in such a way that it will stay around
804for a while. One reason is that it has become a standard, or more precisely a set
805of standards. Depending on what variant you choose color support is limited.
806
807\startluacode
808
809local function state(v)
810    context.NC()
811    if v then
812        context("\\star")
813    end
814end
815
816context.starttabulate { "|l|c|c|c|c|c|" }
817context.NC() context.bold("format")
818context.NC() context.bold("gray")
819context.NC() context.bold("rgb")
820context.NC() context.bold("cmyk")
821context.NC() context.bold("spot")
822-------.NC() context.bold("multi")
823context.NC() context.bold("transparency")
824context.NC() context.NR()
825for name, data in table.sortedhash(lpdf.formats.data) do
826    context.NC() context.type(name)
827    state(data.gray_scale)
828    state(data.rgb_colors)
829    state(data.cmyk_colors)
830    state(data.spot_colors)
831 -- state(data.nchannel_colorspace)
832 -- state(data.calibrated_rgb_colors)
833 -- state(data.cielab_colors)
834    state(data.transparency)
835 -- state(data.include_intents)
836 -- state(data.internal_icc_profiles)
837 -- state(data.external_icc_profiles)
838    context.NR()
839end
840context.stoptabulate()
841
842\stopluacode
843
844When you have set the \type{format} with \type {\setupbackend} to one of the
845known formats mentioned in the previous table, the color conversions will
846automatically kick in.
847
848\stopsection
849
850\startsection[title=Unboxing]
851
852This paragraph is somewhat complex, so skip it when you don't feel comfortable
853with the subject or when you've never seen low level \CONTEXT\ code.
854
855Colors are implemented using attributes. Attributes behave like fonts. This means
856that they are kind of frozen once material is boxed. Consider that we define a
857box as follows:
858
859\startbuffer
860\setbox0\hbox{\bf default {\darkred red \darkgreen green} default}
861\stopbuffer
862
863\typebuffer \getbuffer
864
865What do you expect to come out the next code? In \MKII\ the \quote {default}
866inside the box will be colored yellow but the internal red and and green words
867will keep their color.
868
869\startbuffer
870\bf default {\darkyellow yellow {\box0} yellow} default
871\stopbuffer
872
873\typebuffer
874
875This is what we get in \MKIV: \start \inlinebuffer \stop
876
877When we use fonts switches we don't expect the content of the box to change. So,
878in the following the \quote {default} texts will {\em not} become bold.
879
880\startbuffer
881\setbox0\hbox{default {\sl slanted \bi bold italic} default}
882\stopbuffer
883
884\typebuffer \getbuffer
885
886\startbuffer
887default {\bf bold {\box0} bold} default
888\stopbuffer
889
890\typebuffer
891
892Now we get: \inlinebuffer .
893
894Redoing a box with a new font is sort of tricky as by then all kind of
895manipulations have been applied and the original inputs is long gone. But colors
896are easier to deal with and therefore in \MKIV\ we have a trick to make sure the
897outer color gets applied to the box:
898
899\startbuffer[enable]
900\enabledirectives % only mkiv
901  [attributes.inheritance]
902\stopbuffer
903
904\startbuffer
905default {\bf \darkyellow yellow {\attributedbox0} yellow} default
906\stopbuffer
907
908\typebuffer
909
910So, we get: \start\inlinebuffer[box]\inlinebuffer[enable]\space\inlinebuffer
911\stop. In \MKIV\ you need to enable inheritance first with:
912
913\typebuffer[enable]
914
915There is also an \type {\attributedcopy} macro. These macros signal the attribute
916resolver that this box is to be treated special.
917
918In \MKII\ we have a similar situation which is why we had the option (only used
919deep down in \CONTEXT) to encapsulate a bunch of code with
920
921\starttyping
922\startregistercolor[foregroundcolor]
923some macro code ... here foregroundcolor is applied ... more code
924\stopregistercolor
925\stoptyping
926
927This is for instance used in the \type {\framed} macro. First we package the
928content, foregroundcolor is not yet applied because the injected specials of
929literals can interfere badly, but by registering the colors the nested color
930calls are tricked into thinking that preceding and following content is colored.
931When packaged, we apply backgrounds, frames, and foregroundcolor to the whole
932result. Because nested colors were aware of the foregroundcolor they have
933properly reverted to this color when needed.
934
935In \MKIV\ the situation is reversed. Here we definitely need to set the
936foregroundcolor because otherwise attributes are not set. This is no problem
937because contrary to \MKII\ colors don't interfere (no extra nodes). We could have
938flushed the framed content using \type {\attributedbox}, but we don't want to
939enable inheritance by default because it comes with some overhead.
940
941{\em The \type {\attributedbox} command is considered obsolete. In \LMTX\ there
942is a \type {\recolorbox} command that recolors a box. Because these commands are
943probably never needed it made more sense to move the burden to a specific command
944than to add additional overhead to the whole color mechanism. My experience is
945that unboxing and copying is very rare in \CONTEXT.}
946
947\stopsection
948
949\startsection[title=Color intents]
950
951If we do this:
952
953\startbuffer
954\startoverlay
955    {\blackrule[color=darkred, height=2cm,width=4cm]}
956    {\blackrule[color=darkblue,height=1cm,width=3cm]}
957\stopoverlay
958\stopbuffer
959
960\typebuffer
961
962we get:
963
964\startlinecorrection
965\getbuffer
966\stoplinecorrection
967
968The blue rectangle is drawn on top of the red one. In print, normally the
969printing engine will make sure that there is no red below the blue. In case of
970transparent colors this is somewhat tricky because then we definitely want to see
971part of what lays below.
972
973You can control this process with the following commands:
974
975\starttyping
976\setupcolors
977  [intent=...]
978\stoptyping
979
980The default setting is \type {none} but you can set the intent to \type {overprint} or
981\type {knockout} as well. In a running text you can use the following commands:
982
983\starttyping
984\startcolorintent[overprint|knockout]
985    ...
986\stopcolorintent
987
988\startoverprint
989    ...
990\stopoverprint
991
992\startknockout
993    ...
994\stopknockout
995\stoptyping
996
997In practice you will probably seldom need to deal with this so best leave the defaults
998as they are.
999
1000\stopsection
1001
1002\startsection[title=Collections]
1003
1004Collections are predefined sets of colors. You find them in the files \type
1005{colo-imp-*.mkiv} and you can make such files yourself. When you define a color a
1006command is generated by default. When you load a collection, there is a danger
1007that you redefine commands unintended. For that reason most collections are
1008wrapped in:
1009
1010\starttyping
1011\startprotectedcolors
1012    % definitions
1013\stopprotectedcolors
1014\stoptyping
1015
1016This prevents commands being defined and assumes that colors are accessed by
1017using the \type {color} parameter of setup commands or in the text with:
1018
1019\starttyping
1020\color[somecolor]{this gets colored}
1021
1022\startcolor[somecolor]
1023    this gets colored
1024\stopcolorintent
1025\stoptyping
1026
1027The default set (\type {rgb}) is already preloaded with:
1028
1029\starttyping
1030\usecolors[rgb] % preloaded
1031\stoptyping
1032
1033You can get a list of colors with
1034
1035\startbuffer
1036\showcolor[rgb]
1037\stopbuffer
1038
1039\typebuffer
1040
1041This generates the list:
1042
1043\getbuffer
1044
1045These are the collections shipped with \CONTEXT. Some names are
1046
1047\starttabulate[|T||]
1048\NC crayola \NC crayon colors \NC \NR
1049\NC dem     \NC a demo set of groups and palets \NC \NR
1050\NC ema     \NC an old coming from an Emacs user \NC \NR
1051%NC pan     \NC a bunch of Pantone colors \NC \NR % can't be distributed
1052%NC pra     \NC colors used at \PRAGMA \NC \NR
1053\NC rainbow \NC a series of color groups by Alan \NC \NR
1054\NC ral     \NC a set often used in industry (from Germany) \NC \NR
1055\NC rgb     \NC a basic set of colors defined in the \RGB\ color space \NC \NR
1056%NC ros     \NC the roscolux color set used in theater and cinema lighting \NC \NR % probably can't be distributed
1057\NC x11     \NC (most of the) standard X11 \RGB\ colors \NC \NR
1058\stoptabulate
1059
1060You can look in these files to see what gets defined. Even if you don't use them
1061they might be illustrative,
1062
1063\stopsection
1064
1065\startsection[title=Text color]
1066
1067Setting the color of the running text is done with:
1068
1069\starttyping
1070\setupcolors
1071  [textcolor=darkgray]
1072\stoptyping
1073
1074If needed you can also set the \type {pagecolormodel} there but its default value
1075is \type {none} which means that it will obey the global settings.
1076
1077\stopsection
1078
1079\startsection[title=Tikz]
1080
1081In case you use the TikZ graphical subsystem you need to be aware of the the fact
1082that its color support is more geared towards \LATEX. There is glue code that
1083binds the \CONTEXT\ color system to its internal representation but there can
1084still be problems. For instance, not all color systems are supported so \CONTEXT\
1085will try to remap, but only when it knows that it has to do so. You can best not
1086mix colorspaces when you use TikZ. If you really want (and there is no real
1087reason to do so) you can say:
1088
1089\starttyping
1090\enabledirectives[colors.pgf]
1091\stoptyping
1092
1093and then (at the cost of some extra overhead) define colors as:
1094
1095\starttyping
1096\definecolor[pgfcolora][blue!50!green]
1097\definecolor[pgfcolorb][red!50!blue]
1098\stoptyping
1099
1100\stopsection
1101
1102\startsection[title=Implementation details]
1103
1104The low level implementation of colors in \MKIV\ is fundamentally different from
1105\MKII. In \MKIV\ something like this happens:
1106
1107\starttyping
1108one \color[red]{two} three
1109\stoptyping
1110
1111becomes (with grouping):
1112
1113\starttyping
1114one {<start color: red>two<stop color>} three
1115\stoptyping
1116
1117the start and stop points are in fact injections in the input: a special (for
1118\DVI) or literals (for \PDF) is inserted that turns the color on and off, but
1119also information is carried along about the state of color, so that we can
1120properly nest as well as pick up the current color after a page break. We never
1121had real problems with this mechanism but one had to keep in mind that injections
1122like this could interfere with typesetting. This mechanism didn't rely on the
1123engine for housekeeping, all was done at the \TEX\ end using so called marks.
1124
1125In \MKIV\ we use attributes. This means that the sequence now looks like:
1126
1127\starttyping
1128one {<set color attribute to red>two} three
1129\stoptyping
1130
1131The actual handling of color happens when a page is shipped out and there is no
1132interference with typesetting. The work is mostly done in \LUA.
1133
1134Colorspaces (\RGB, \CMYK, spot) were already supported in \MKII\ and of course
1135still are in \MKIV. However, the colorspace is now a more independent property.
1136At some point in \MKII\ we also implemented transparency as a property of a
1137color. In \MKIV\ transparency is still defined with a color but handled
1138independently. This means that where in \MKII\ color is just one axis, in \MKIV\
1139we have three: colorspace (model), color and transparency. This of course has a
1140bit of a performance and memory hit, but in practice a user won't notice it.
1141
1142\stopsection
1143
1144\startsection[title=Grouping]
1145
1146The \type {\color} and \type {\startcolor} command group their arguments. There might
1147be cases where this interferes with your intentions, for instance when you want to
1148set some variable and use its value later on.
1149
1150\startbuffer
11511 \scratchcounter=1
1152plus
11531 \advance \scratchcounter by 1
1154equals
1155\the\scratchcounter
1156\stopbuffer
1157
1158\typebuffer
1159
1160The summation works out okay: {\bf \inlinebuffer}.
1161
1162\startbuffer
1163\color[darkblue]{1 \scratchcounter=1}
1164plus
1165\color[darkblue]{1 \advance \scratchcounter by 1}
1166equals
1167\color[darkgreen]{\the\scratchcounter}
1168\stopbuffer
1169
1170\typebuffer
1171
1172Here the final result depends on the value of \type {\scratchcounter}:
1173{\scratchcounter 3 \bf \inlinebuffer}.
1174
1175\startbuffer
1176\start
1177    \pushcolor[darkblue]1 \scratchcounter=1 \popcolor
1178    plus
1179    \pushcolor[darkblue]1 \advance \scratchcounter by 1 \popcolor
1180    equals
1181    \pushcolor[darkgreen]\the\scratchcounter \popcolor
1182\stop
1183\stopbuffer
1184
1185\typebuffer
1186
1187Here we get: {\bf \inlinebuffer}. The \typ {\pushcolor} and \typ {\popcolor}
1188commands can be used nested which give a bot of overhead. The \typ {\savecolor}
1189and \typ {\restorecolor} commands are variants that don't stack. They are a bit
1190more efficient but if you use them nested you probably also will use some
1191grouping. Where the push||pop pair needs to be matched, the save||restore pair
1192doesn't impose that restriction.
1193
1194\stopsection
1195
1196\startsection[title=Commands]
1197
1198There are quite some commands that relate to colors but you probably only need
1199\typ {\definecolor}, \type {\color} and \typ {\startcolor} \unknown \typ
1200{\stopcolor}. Here we show the complete list. Some commands are redundant, for
1201instance \typ {\definenamedcolor} is the same as \typ {\definecolor}.
1202
1203\placeallsetups
1204
1205\stopsection
1206
1207\stopchapter
1208
1209\stopcomponent
1210