Tutorials/Targeting a color

Why do we need it?
Sometimes you want to produce a color gradient starting at a certain color and ending at another one. This is easy if you know how many elements you're going to use in your gradient. Say we want to go from yellow (hue 60) through green to blue (hue 240):



The code puts 50 squares in a row, starting with h 60 (yellow) and adding 180/50 "hue steps" with every new square (since we have 50 steps and 240-60 = 180). Sometimes, however, you don't actually know beforehand you many elements your gradient will have. Imagine something like this: This will put a random number of squares in a row &mdash; we have no chance of knowing how many "hue steps" to add for each new one. There's just no single value that would work for every number of squares. If the number of squares is too low the gradient does not reach the target color. And if there are too many squares we end up going beyond it. Color targeting helps you to avoid the second of these.

How it works
Targeting colors is a two-step process. First you need to define what the target color is. This is done using the |hue num syntax (Note that |hue 60 does not actually set the target color to 60, but instead adds 60 to the current target color. We will see the effect of this later on). The second step is moving the current color towards the target color, for which the hue num| syntax is used: Its argument is a number between -1 and 1. Positive values move towards the target color in a counter-clockwise direction, negative values in a clockwise direction. The absolute value of the number specifies how far we move towards the target, so h -.15| will move the color 15% towards the target color in clockwise direction, whereas h .01| will move it 1% in counter-clockwise direction.

Thus the following code will produce a gradient from yellow to blue: If you render several variations of the code above you will notice a few things:


 * If the number of squares is too low, then we don't reach the target color, just as before. When you think about it, this is pretty obvious: ContextFree does not know how many boxes there will be when it creates each of them (just as you don't know how many there will be). Thus there's no 100% safe way to make sure the target color is reached if you use a random number of objects.
 * The color never goes beyond the target color, no matter how many boxes there are. However, there's a twist: The gradient is not distributed evenly across the squares &mdash; if you have a lot of boxes, most of them will be blue. This is because the color is moved a certain fraction of the remaining gap to the target each time: Say we start with a hue of 0 and a target of 100, and use h .05| to produce our gradient. The first box will get hue 0. For the next box, the color is moved 5% of (100 - 0) = 5% of 100 = 5, that is, the second box gets hue 5. The third box, however, does not get hue 10! The reason is that the color is moved 5% of (100 - 5) = 5% of 95 = 4.75. Thus the third box gets hue 9.75. The fourth box gets hue 14.2625, etc. Thus you actually never reach the target color &mdash; you just get closer and closer to it.

The following image shows the difference in color distribution: The upper gradient is produced using a fixed number of boxes and pre-calculated hue steps. The lower one is made using color targeting and a random number of boxes. Although both gradients have almost the same number of elements, the colors are distributed differently: The lower gradient contains more colors closer to the target color.



Now take a look at Guigui's targ in the gallery to see the effect of using |h num multiple times.

Finally, although all the examples used hue, color targeting is also possible for saturation, brightness and alpha. See the Shape adjustment page for more information.

Going back and forth
You can use color-targeting to create a gradient that oscillates randomly between two colors:



It works like this: At the beginning, the color is set to yellow (hue 60), the target to blue (hue 240) and the control is given to the FORWARD rules. These produce squares while moving the color towards blue. But from time to time they give over control to the BACKWARD rules. Before doing so, they subtract 180 from the target color, making yellow the new target. The BACKWARD rules then produce squares while moving the color towards yellow (note that they move around the color wheel in the opposite direction using a negative argument to hue num|). After a random amount of squares, control goes back to FORWARD after resetting the target to blue. Take a look at Crazy Gradients which uses this technique in two directions.