## Colors

The purpose of the colors section is to define a color table - a set of rgb values that are accessed by an index. Before we discuss the structure of the colors section, here is some preliminary information:

- When we speak of rgb values, we are referring to values expressed in this form:

  [ red_value green_value blue_value ]

  Where each value is within the range: 0 <= value <= 255

  Here are some common colors and their associated rgb values:

  Color Name | RGB Values
  --- | ---
  red | [255 0 0] |
  green | [0 255 0] |
  blue | [0 0 255] |
  black | [0 0 0] |
  white | [255 255 255] |
  cyan | [0 255 255] |
  magenta | [255 0 255] |
  yellow | [255 255 0] |

- In general, a color table is just a set of rgb values organized by index. Here is a sample color table as an example:

  Color Table Index | RGB Value
  --- | ---
  0 | [255 0 0]
  1 | [0 0 255]
  2 | [255 0 0]
  3 | [0 0 255]
  4 | [255 0 0]
  5 | [0 0 255]
  6 | [255 0 0]
  7 | [0 0 255]
  8 | [255 0 0]
  9 | [0 0 255]

  This color table consists of a total of 10 entries (indices 0 => 9) and contains a series of alternating red and blue values. You access the colors by selecting the appropriate index, for this example:

  color_table[3] = [0 0 255] (blue)
  color_table[8] = [255 0 0] (red)

## Structure of the colors section

The colors section consists of one more more define subsections. The general format is as follows:

       colors {
          define {
             ...
          }
          define {
             ...
          }
        }

The define command marks the start of one or more color table entries. The define command can also take an optional argument as in:

       colors {
          define(10) {
             ...
          }
       }

The argument indicates the starting color index for the rgb values defined within the define section. If this argument is not supplied, the color table index just begins where the last define section left off. If a define has no argument and it is the first define, the starting index will be zero.

Within the define command, there are three types of subcommands:

1. RGB color definition
2. repeat command
3. gradient command

#### RGB color definition

Here is an example showing three single color definitions

       colors {
          define {
             [0 255 0] [0 0 0] [255 0 0]
          }
       }

The resulting color table would look like:

          color_table_entry[0] = (0, 255, 0)
          color_table_entry[1] = (0, 0, 0)
          color_table_entry[2] = (255, 0, 0)

#### The repeat command

The repeat command requests that everything within it be duplicated a certain number of times. Here is an example:

       colors {
          define {
             repeat(2) { [0 0 0] }
             repeat(2) {
                repeat(3) {
                   [255 255 255]
                }
                [255 0 0]
             }
          }
       }

As you can see, the repeat command can be nested. In this example, the resulting color table would be:

       color_table_entry[0] = (0, 0, 0)
       color_table_entry[1] = (0, 0, 0)
       color_table_entry[2] = (255, 255, 255)
       color_table_entry[3] = (255, 255, 255)
       color_table_entry[4] = (255, 255, 255)
       color_table_entry[5] = (255, 0, 0)
       color_table_entry[6] = (255, 255, 255)
       color_table_entry[7] = (255, 255, 255)
       color_table_entry[8] = (255, 255, 255)
       color_table_entry[9] = (255, 0, 0)

#### The gradient command

The gradient command is useful for filling in a color table with a smooth transition between specified colors, consider:

       colors {
          define {
             [0 0 0] [0 0 51] [0 0 102] [0 0 153] [0 0 204] [0 0 255]
          }
       }

This effect could be expressed using a gradient as in:

       colors {
          define {
             gradient(6) { [0 0 0] [0 0 255] }
          }
       }

The 6 indicates that a total of 6 color table entries will be created and the starting color will be black ([0 0 0]), the ending color blue ([0 0 255]).

The gradient can also handle more than 2 colors, for example:

       colors {
          define {
             gradient(11) { [0 0 0] [0 0 255] [0 0 0] }
          }
       }

This would create the following color table:

       color_table_entry[0]  = (0, 0, 0)
       color_table_entry[1]  = (0, 0, 51)
       color_table_entry[2]  = (0, 0, 102)
       color_table_entry[3]  = (0, 0, 153)
       color_table_entry[4]  = (0, 0, 204)
       color_table_entry[5]  = (0, 0, 255)
       color_table_entry[6]  = (0, 0, 204)
       color_table_entry[7]  = (0, 0, 153)
       color_table_entry[8]  = (0, 0, 102)
       color_table_entry[9]  = (0, 0, 51)
       color_table_entry[10] = (0, 0, 0)

There are some restrictions on the gradient command:

1. There must be at least 2 color entries, so the following is not allowed:

              gradient(10) { [0 0 0] }

2. The number of color entries must not be larger than the size of the gradient. For this reason, this would not be legal:

              gradient(2) { [0 0 0] [255 0 0] [0 0 255] }

3. The repeat command is not permitted within a gradient

Here is an example colors section combining all the commands:

       colors {
          define {
             repeat(2) {
                [0 0 0] [255 255 255]
                repeat(3) {
                   gradient(6) { [0 0 0] [0 0 255] }
                }
             }
          }
       }

And here is the resulting color table:

       color_table_entry[0]  = (0, 0, 0)
       color_table_entry[1]  = (255, 255, 255)
       color_table_entry[2]  = (0, 0, 0)
       color_table_entry[3]  = (0, 0, 51)
       color_table_entry[4]  = (0, 0, 102)
       color_table_entry[5]  = (0, 0, 153)
       color_table_entry[6]  = (0, 0, 204)
       color_table_entry[7]  = (0, 0, 255)
       color_table_entry[8]  = (0, 0, 0)
       color_table_entry[9]  = (0, 0, 51)
       color_table_entry[10] = (0, 0, 102)
       color_table_entry[11] = (0, 0, 153)
       color_table_entry[12] = (0, 0, 204)
       color_table_entry[13] = (0, 0, 255)
       color_table_entry[14] = (0, 0, 0)
       color_table_entry[15] = (0, 0, 51)
       color_table_entry[16] = (0, 0, 102)
       color_table_entry[17] = (0, 0, 153)
       color_table_entry[18] = (0, 0, 204)
       color_table_entry[19] = (0, 0, 255)
       color_table_entry[20] = (0, 0, 0)
       color_table_entry[21] = (255, 255, 255)
       color_table_entry[22] = (0, 0, 0)
       color_table_entry[23] = (0, 0, 51)
       color_table_entry[25] = (0, 0, 102)
       color_table_entry[26] = (0, 0, 153)
       color_table_entry[27] = (0, 0, 204)
       color_table_entry[28] = (0, 0, 255)
       color_table_entry[29] = (0, 0, 0)
       color_table_entry[30] = (0, 0, 51)
       color_table_entry[31] = (0, 0, 102)
       color_table_entry[32] = (0, 0, 153)
       color_table_entry[33] = (0, 0, 204)
       color_table_entry[34] = (0, 0, 255)
       color_table_entry[35] = (0, 0, 0)
       color_table_entry[36] = (0, 0, 51)
       color_table_entry[37] = (0, 0, 102)
       color_table_entry[38] = (0, 0, 153)
       color_table_entry[39] = (0, 0, 204)
       color_table_entry[40] = (0, 0, 255)

As a final note, it is often useful to make a gradient that spans 360 entries so that the angle a complex variable makes with the origin (in degrees) can be used as an index into the color table values. An example would be the following:

       colors {
          define {
             gradient(361) { [0 0 0] [255 255 255] [0 0 0] }
          }
       }

Note that we use gradient(361) instead of gradient(360) - the reason is that when measuring degrees, 360 degrees is the same as 0 degrees. For this reason, we want to ensure that the color table entry associated with index 0 is the same as the entry associated with index 360. In order to accomplish this we need 361 entries (0 through 360 inclusive) rather than 360 as one might expect.