< Queries

Export Plugins  >

10. Annotation and Redlining [plugin] (outline)

Imagine you want to draw some features (points, lines, polygons ...) in your map to show specific data and/or print it. The outline plugin is what you need.

It allows you to draw features and to annotate them with label texts.

It's also possible to use polygons shapes as a mask layer see "Mask mode". User can choose between mask or draw mode with radio buttons. See Section 10.2.1, “outline.ini” for more information.

Shapes colors and styles should be set with specific configuration in the mapfile (See Section 10.3, “Related Elements in Mapfile”).

The total area of the drawn polygons is displayed on the interface.

10.1. Client-side Configuration

10.1.1. outline.ini

Here are the options that can be set on the client:

  • multipleShapes: boolean, if true, the user is allowed to draw multiple shapes. That means that drawn features remain until browser session is closed. If false, will outline only one shape at a time, new feature simply erases / overrides currently drawn one. When he wants, the user can erase all the drawn feature by clicking on the "outline_clear" form button (default true).
  • labelMode: boolean, if true, user is asked to input a label text that is drawn to annotate drawn shape.
  • displayMeasures: boolean, if true, label text will contain surface or distance measure.
  • weightOutlinePoint: integer defining display order of the outline_point tool icon in toolbar (if not specified, default to 70). A negative weight disables the tool.
  • weightOutlineLine: see weightOutlinePoint (default to 71)
  • weightOutlineRectangle: see weightOutlinePoint (default to 72)
  • weightOutlinePoly: see weightOutlinePoint (default to 73)
  • weightOutlineCircle: see weightOutlinePoint (default to 74)

10.2. Server-side Configuration

10.2.1. outline.ini

Here are the options that can be set on the server:

  • pointLayer: defines the name of the mapserver LAYER set in the mapfile to display points.
  • lineLayer: defines the name of the mapserver LAYER set in the mapfile to display lines.
  • polygonLayer: defines the name of the mapserver LAYER set in the mapfile to display polygons. Note that rectangles are displayed as polygons.
  • maskColor: defines the RGB color of the mask. This color is used to fill the polygons outside's area. Drawn polys will appear as holes in a colored sheet, showing the map under. This parameter is optional and set by default to 255 255 255 (white).
  • areaFactor: defines an optional value for ratio by which the area is multiplied before it is returned to the client. For example, people can use it to convert square meters to square kilometers.
  • areaPrecision: defines an optional way to obtain a formatted area surface value.

    "{(int) nb decimal}#{(str) decimal separator}#{(str) thousand separator}"

    If areaPrecision is present in outline.ini (server_conf) without any parameters the following formatter will be apply : 2 decimal, .(dot) as decimal separator, " "(space) as thousand separator. which correspond to the areaPrecision = "2#.# ". It's better to double-quote your parameter, avoiding trouble by the ini parser if you want to use a space at the end. If you want a 4 decimal, with comma decimal separator, and single-quote for thousand separator you would change this to areaPrecision = "4#,#'" Note : this is absolutely not locales aware, you could only have one formater for all language your project support. Would perharps change with php6 version.
  • symbolPickerHilight = inversed|borderhilight: set the hilight mode to use in the SymbolPicker interface. See Section, “SymbolPicker”.
  • symbolSize: defines the size (in pixel) of the symbold images generated when using the symbolPicker. The value is used for width and height. The default value is 30.

10.3. Related Elements in Mapfile

10.3.1. Layers

Specific layers must be set in the mapfile in order to draw the shapes:

  NAME "cartoweb_point_outline"

  NAME "cartoweb_line_outline"

  NAME "cartoweb_polygon_outline"

Don't forget that layers names must be set in the server-side outline.ini file (See Section 10.2.1, “outline.ini”)

10.3.2. Labels

In case of using labels (i.e. labelMode set to true, see Section 10.1.1, “outline.ini”), a LABEL object is needed in the layers' class.


  NAME "cartoweb_point_outline"
      FONT Vera
      TYPE truetype
      COLOR 51 51 51
      SIZE 10

You will find more examples looking in the test.map file in server_conf directory.

10.4. GET Parameters

Creates outline drawing on-the-fly by passing a geometry type and one or more point coordinates via the URL.

10.4.1. Accepted Parameters

Parameters list

  • outline_point
  • outline_line
  • outline_poly
  • outline_circle
  • It is possible to describe several shapes, including of different types:
  • Customized labels may be linked to shapes using the following syntax:


If you do not want to have persistent outline, you can add the prevent_save_session parameter in the URL. For example:


This may be useful if you use the mode=image output:


10.5. The ToolPicker

10.5.1. What is the ToolPicker

The ToolPicker is a mini javascript framework used to display dynamically on screen several DHTML tools.

Some tools come pre-included:

  • ColorPicker : The ColorPicker allows the user to pick a color. He/she can either pick it from a gradient map, use RGB or HSL slider, input RGB or HSL values , input an hexadecial value or pick it from a preselected list of colors. The color value is then returned to the main page.
  • SymbolPicker : The SymbolPicker allows the user to pick a symbol in a predefined list of symbols. The symbols are generated off the .sym file on the serverside of CartoWeb. The symbol is then returned to the main page.

10.5.2. Installation

To use the ToolPicker in a project, simply enable it in your client.ini configuration file, by setting toolPickerOn = true.

The ToolPicker requires the corresponding script, css and template in the cartoclient.tpl file.

In the header :

<link rel="stylesheet" type="text/css" href="css/toolPicker.css" />

In the body, preferably at the end :

{include file="toolPicker.tpl"}

10.5.3. ToolPicker Usage

The main ToolPicker function accepts 3 parameters, 2 are mandatory, the last is optional.

toolPicker( string tool_id_list, string tool_input_list [, string tool_output_list])


You can initialize one or more tools at once. The tool_id_list parameter is composed of one or more numerical values, separated by comma and enclosed by quotes (or simplequotes). Example: '2' or '1,4' or '3,2,1'

The order of the id influes on the order of the tool panels when displayed on screen.

tool_input_list and tool_output_list

The script needs an input value and will return an output value. The input value is retrieved from an html input element. In the same way the output value is returned to an html input element.

The script needs as many input element id as initialised tools. If two tools are initialised (parameter tool_id_list), tool_input_list must also contain two input id. Ids are separated by comma and enclosed by quotes (or simplequotes). Example: 'return_id_tool_4,return_id_tool_2'

The first input id corresponds to the first tool id in tool_id_list.

A different id can be specified if the element storing the output value must be different from the element storing the input value. The same rule applies to tool_input_list and tool_output_list.

See Section 10.5.5, “Examples of Usage”

Each tool also have some particularities: ColorPicker

When a color is selected, the script will set the css property background-color of a div in the template accordingly to the color picked.

The id of the div is based on the output element id (if it specified, if not, the input element id is used), to which a _d is added.

Example, if the input element id is return_color_12, the id of the div used to display the color will be return_color_12_d. SymbolPicker

When a symbol is selected, the script will set the css property background-image of a div in the template accordingly to the symbol picked.

The id of the div is based on the output element id (if it specified, if not, the input element id is used), to which a _d is added.

Example, if the input element id is return_symbol_12, the id of the div used to display the symbol will be return_symbol_12_d.

The SymbolPicker is used with CartoWeb outline plugin usually, but it also can be used without the plugin. Within the Outline Plugin

In CartoWeb server_conf/yourprojectname/outline.ini file defines a list of symbols to use. For each kind of symbols you want to use:

pointSymbols = "circle, square, star [, anyothersymbol, ... ]"

All these symbol names MUST BE defined in the .sym file in server_conf/yourprojectname/.

If you want to add language support for the symbol name, add the following parameter in server_conf/yourprojectname/outline.ini:

pointSymbols.labels = "symbolname1, symbolname2 [, anyothername, ... ]"

These names will be used to translate into the chosen language using the gettext functionnality. Add the corresponding translations in the server .po files. Without the Outline Plugin (Standalone Use)

If you do not use the outline plugin, you will need to set the following javaScript variable somewhere in your page:

<script type="text/javascript">
    var imgPath = 'path/to/symbol/images/';
    var symbolType = 'type/of/image/files/'; //jpeg, gif, png, whatever

    var symbolNamesArray = new Array("symbolfilename1","symbolfilename2" [,"othersymbolfilename", ...] );

    var symbolLabelArray = new Array("symbollabel1","symbollabel2" [,"othersymbollabel", ...] );

symbolNamesArray contains the list of filename to use for your images.

symbolLabelArray contains the list of label used on screen for the symbols.

Create your symbol images and put them in path/to/symbol/images/. You also need to create hilighted versions of your images, give them the same filename but add the suffix '_over'. Exemple: symbol_1.gif -> symbol_1_over.gif

Put them in the same folder. Symbol Hilight Mode

There are two modes to hilight the selected symbol in the SymbolPicker interface. You can select between border hilight and inverted image. border hilight simply use a css property to hilight the border of the selected symbol. inverted image need the php library GD to create an inverted version of the symbol, which is then used for the selected symbol.

The hiligh mode is set in the server_conf/outline.ini file:

  • symbolPickerHilight = inversed|borderhilight

10.5.4. ToolPicker Default Values

If the toolPicker is used with the Outline plugin, the default values for Color, OutlineColor, Transparency and Symbol are set in the mapfile.

The default layer name are cartoweb_point_outline, cartoweb_line_outline and cartoweb_polygon_outline

See Section 10.2.1, “outline.ini”

10.5.5. Examples of Usage


this will call the symbol picker (id 4), the input id is outline_point_symbol, and the output id will be outline_point_symbol too

toolPicker('1','outline_point_color', 'color_return')

this will call the color picker, the input id is outline_point_color, and the output id will be color_return

toolPicker('4,1','symbol_input,color_input', 'return_symbol,return_color')

this will call the symbol picker and the color picker, the input id is symbol_input for the first tool (here the symbol picker) and color_input for the second tool (color picker), and the output id will be return_symbol for the first tool and return_color for the second.

10.5.6. Creating New Tools

You can add new tools.

Add the new tool name in the toolArrayRef array at the begining of the script.

var toolArrayRef =  new Array( 'colorPicker', 

Create the following four functions, these functions can be empty.

function yourToolInit(inputValue) { ... }
function yourToolSetup() { ... }
function yourToolReturn() {
    return someValue;
function yourToolDisplay(targetElm) { ... }

The Init function is used to set the incoming values. It is always called when the ToolPicker starts. It receives the input value recovered from the main page.

The Setup function can be used to do all the actions you want.

The Return function is used to return a value to the main page.

The Display function is used to display something in the main page. It receives the id of the target element to use (something_d).

Add the following four function definitions:


These are needed because of the dynamic function call inside the framework, which do not use the eval() function to increase performances.

The width of the tool area available on screen is 245 pixel. Height is variable.

valid xhtml 1.0 valid css