Chameleon Concepts

A Chameleon script is divided into a number of blocks. Most actions must be performed within the lone map block. Meta data and parameters for the map style must be set up outside of this block, as must any constants.

Within the map block, there will be specified a number of rendering blocks. Below is a simple example of a Chameleon script with a single map block containing a polygons block. Statements are used, within a block, to give commands to the Chameleon interpreter.

begin map
  clear brush<(192,192,255)>
  begin polygons
    render [land],brush<(255,255,192)>
  end polygons
end map

Statements are used to give commands to the Chameleon interpreter. They start with the command name and take a number of parameters. The parameters are written after the command name and are separated by commas. An example of a statement is the render statement. This command is available within certain blocks, and takes different parameters based on the context. Each statement is covered in detail in the statements section.

begin map
  clear brush<(192,192,255)>
  begin polygons
    render [land],brush<(255,255,192)>
  end polygons
end map

There are a number of different objects used in the map rendering process, such as colors, pens and fonts. Objects are passed as parameters to statements or other objects. With the exception of colors, these are all specified with the type of the object first, and the parameters to the object within angle brackets. Colors are specified between parentheses. See the color object for more detail.

For example: A white color would be declared as (255, 255, 255). An example of a black pen could be:

pen<(0,0,0), 1>

To ease the task of writing and maintaining a Chameleon script, objects can be assigned to variables. Variables are defined inside the map block and are prefixed with a ! character. The compiler will raise an error during compilation if an undeclared variable is used. An example of creating a variable is shown below.

begin map
  // Create two variables
  !blue = (192,192,255)
  !clearBrush = brush<!blue>

  // Clear the map
  clear !clearBrush
end map

It is also possible to perform inline arithmetic operations on variables:

pen<!Col, %Value + 6>

Constants can be set up for floating point values. These constants must be set up before the map block. Before the map block, however, they can be redefined as many times as desired. The constants are prefixed with a % character, and must be declared using the declare statement.

In the case of an if statement, a float can be treated as a boolean, where 0 represents false, and any other value represents true.

The example below declares a constant %pen_width and initializes it to 1. If the scale of the map is low enough then it resets the value to 3. This means it will draw thicker streets when the map is zoomed in closer.

declare %pen_width = 1
declare %thickScale = 37.5

// %scale is an intrinsic value, discussed below
if %scale < %thickScale
  %pen_width = 3
end if

begin map
  clear brush<(255,255,255)>
  begin streets
    render [all],pen<(0,0,0), %pen_width>
  end streets
end map

A parameter is a special type of value. Parameters can have their value set by the code that generates the map. They are exposed on the MapStyle object and can be set using MapStyle.SetParameter(). Parameters are declared just like other constant, except instead of declare, the parameter keyword is used instead. The default value if it is not specified is 0. For example:

parameter %draw_rail
begin map
  clear brush<(255,255,255)>
  if %draw_rail
    begin lines
      render [railways],pen<(0,0,0),1:railway>
    end lines
  end if
end map

A parameter that is exposed on a MapStyle object may have its value changed programmatically, and this value will persist for the lifetime of the object. It is possible to return a parameter to its default value, as set by the MapStyle, by calling the ClearParameter method.

As well as user defined constants, there are a number of intrinsic values that are set automatically for each run of the Chameleon script. The most important of these is %scale which contains the size of each pixel in meters for the current map. This allows the map to be drawn differently depending on the zoom level.

Meta data for the map style can be specified by using the property keyword and passing it a quoted string parameter. This value can then be retrieved programmatically. The property values have no meaning in GeoBase or Chameleon and are purely for meta data purposes. For example:

property name = "Example Style"
property description = "Just showing off properties"

Maps are drawn in two distinct passes. The first pass renders all the features from the blocks onto the map. All labels, shields, point features and one-way arrows are left until the second pass. After the first pass, control is handed to any Renderer objects to render their own information on the map. This is the PreLabelling pass. After this, control returns to the GeoBase map engine which places labels, shields and point features in priority order (highest first). If a suitable location can't be found for an item, that item will be skipped. After all labels, shields and point features are placed, one-way arrows are placed wherever they are required and can fit.

Finally, the Renderer objects are called twice more, once with the RenderMode set to Labelling, and again with RenderMode set to PostLabelling. After this the map is complete and the bitmap is returned or displayed on the MapCtrl.

Mask layers are used to detect collisions between labels. When a label is placed on the map it marks the appropriate section of its mask as unavailable. This allows future labels to determine if an area is available. There are two masks available for labels to use: Primary and Overlay. Labels use Primary by default, but, by specifying the Overlay option on the Label object, a label will use the Overlay mask. Labels drawn on the Overlay mask are able to collide with those drawn on the Primary mask (and vice versa), but are prevented from colliding with others on the Overlay mask.

Chameleon supports C-style comments:

// This type of comment only covers a single line
/* This type of comment continues
until closed off */

Any enumeration (enum) may be accessed using the following pattern:

Syntax: *Fully.Qualified.Enum:MemberName

Example: *Telogis.GeoBase.MapQuality:Perfect

Using Auxiliary Layers