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

   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]
      }
   }
   

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

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 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]
      }
   }
   

   colors {
      define {
         gradient(6) { [0 0 0] [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] }
      }
   }
   

   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)
   

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] }
            }
         }
      }
   }
   

   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)
   

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