I-X Map Tool - Addon Help |  | Based on I-X Technology AIAI, University of Edinburgh

The I-X Map Tool is based on the Open Source BBN OpenMap system.

The I-X Map Tool is an optional State Viewer and can be installed via two options. First, setting the parameter -state-viewer-class=StateViewMap (rather than the default StateViewTable class). This option is still being supported by the tool to keep it compatible with previous applications. Second, using the map-viewing whiteboards, which extends the object-viewing whiteboards approach. The configuration of both options are discussed in the final of this document

An object is displayed on the map if it has both of the following world state (effect) constraints:

- (latitude <object>) = <number> (number is a fixed point decimal number)
- (longitude <object>) = <number> (number is a fixed point decimal number)

In addition, optionally, the following map view related world state (effect) constraints can be given:

- (type <object>) = true
  which gives a type for the object which can be used for icon selection. See later.
- (geo-fixed <object>) = true
  which can be set for objects in the map to specify that their geographical locations are fixed. Thus, such objects cannot be dragged with the mouse and their latitude or longitude cannot be edited via the Map Tool.

### How Icons are Selected

Icons can be represented by gif, png or jpg images. According to the paths showed above, the relation object/icon follows the algorithm below:

IF there is an icon in the directory specified in map-object-icons parameter with the same name of the object (without the extension), this icon will be used.

ELSE IF the object has a "type" world state (effect) constraint for the object (e.g. type Buckingham=palace) AND there is an icon in the directory specified in map-object-icons parameter with the same name of the type value (in the example, palace), this icon will be used.

ELSE IF the map-default-icon parameter was specified, the related icon will be used.

ELSE the system will use its default icon.

### <props-file> Composition

This file is used to configure the map tool and its layers. The parameters that can be used to configure the map are:

- map.Latitude=<numeric value between -90 and 90> - latitude of the map's center;
- map.Longitude=<numeric value between -180 and 180> - longitude of the map's center;
- map.Scale=<numeric value> - initial scale of the map (1:scale);
- map.Width=<positive integer value> - width of the map tool's window;
- map.Height=<positive integer value> - height of the map tool's window;
- map.Projection=<pre-defined string> - projection type of the map. The available options are: mercator(default), cadrg, gnomonic and orthographic;
- map.BackgroundColor=<hexa value AARRGGBB where AA-transparency, RR-red, GG-green, BB- blue> - background color of the map area when all the layers are off;
- map.layers=<list of strings> - prefix of the layers that will be loaded by the map tool;
- map.startUpLayers=<list of strings> - prefix of the layers that will be initially visible. If this parameter is not specified, all the layers will be initially visible.

Each kind of layer has a particular set of parameter/value in the format <layer prefix>.<parameter>=<value>. The default map property file of the map tool shows a example of layer configuration.

    map.layers=world
    map.Latitude=0.0
    map.Longitude=0.0
    map.Scale=165000000.0
    map.Width=800
    map.Height=600

    world.class=com.bbn.openmap.layer.shape.ShapeLayer
    world.prettyName=World Map
    world.shapeFile=resources/map-default/map.shp
    world.spatialIndex=resources/map-default/map.ssx
    world.lineColor=ff000000
    world.fillColor=ff009900

The plug-in ix.ip2.map.JpgMapLayer can be used if the application needs to use a jpg figure as a map. In this case the map property file can be configured as the example below:

    map.layers=jpgmaplayer
    map.Latitude=17.0f                            # centre map latitude
    map.Longitude=39.0f                           # centre map longitude
    map.Scale=8000000.0f

    jpgmaplayer.class=com.bbn.openmap.plugin.PlugInLayer
    jpgmaplayer.prettyName=Binni Boundaries       # name to represent
    the layer

    jpgmaplayer.plugin=ix.ip2.map.JpgMapLayer
    jpgmaplayer.jpgPath=resources/map/binni.jpg   # path to the jpg file

    jpgmaplayer.selfSetting=true                  # if true, you do not need to
                                                  # set the parameters below

    jpgmaplayer.latLeftSuperior=25.0f             # top-left latitude
    jpgmaplayer.lonLeftSuperior=28.0f             # top-left longitude
    jpgmaplayer.latRightInferior=10.0f            # bottom-right latitude
    jpgmaplayer.lonRightInferior=48.0f            # bottom-right longitude

Details about configuration of others kinds of layers can be found in the OpenMap API in BBN OpenMap.

### Principal Functions

- Menu File/Refresh - reloads all the current icons;
- Menu View/Projection - changes the projection;
- Menu View/Select/All - Only available in the multi-views version. Uses the current map state to show all the objects that have latitude and longitude;
- Mouse click on the map area - returns the lat/lon position in the bottom bar;
- Mouse click (left button) on an empty area - opens a window to create a new object on the mouse position;
- Mouse press (left button) on a object - lists the set of attribute/value of this object. Choosing an attribute/value, a new window will open so that we can edit the value. If we choose the first line ( ADD option) another window is opened, enabling the addition of a new attribute/value to the object;
- Mouse click (centre button or Ctrl right button) on the map area - centralises the map in the new position.

### Map Tool Configuration

There are two ways to use the map tool. The first one is via the old map tool version, which can be initialised via the option "Map Tool", Tool Menu in the I-P2 Tools menu (Map Tool and Map Views). For this option we have the following parameters to be configured in the config file of each agent:

- state-viewer-class=ix.ip2.StateViewMap - sets the state viewer as map tool (required parameter if the application intends to use the old version of the map tool);
- map-properties=<props-file> - specifies the map property file. If such a file is not specified, a default set of parameters is used, representing the world map (optional parameter);
- map-object-icons=<directory - URL syntax> - specifies the directory that contains icons to be used for specific object names (optional parameter);
- map-type-icons=<directory - URL syntax> - specifies the directory that contains icons to be used for object types, if no object specific icon is available (optional parameter).
- map-default-icon=<image-file> - specifies the default icon to be used if no more specific object or type icon is available. A built in default icon is used otherwise. (optional parameter);

The second option to use the map tool (new version) has the following parameters:

- extension-classes=ix.ip2.MapViewExtension, ... - turn available the multiple map tool (required parameter);
- object-view-directory=<directory - URL syntax> - specifies the path to the directory where the views are defined (optional parameter);
- map-view-directory=<directory - URL syntax> - specifies the path to the directory where the map views properties are defined (optional parameter);
- map-view-default-properties=<props-file> - specifies the path to a default map view property file, which is used if a specific map-view-property is not defined to a view. If this parameter is not specified, a default map property will be used (optional parameter);
- map-object-icons=<directory - URL syntax> - specifies the directory that contains icons to be used for specific object names (optional parameter);
- map-type-icons=<directory - URL syntax> - specifies the directory that contains icons to be used for object types, if no object specific icon is available (optional parameter).
- map-default-icon=<image-file> - specifies the default icon to be used if no more specific object or type icon is available. A built in default icon is used otherwise. (optional parameter);

An important detail is that each view can be associated with a specific layer property file. For example, the first line of a view file could be defined as: <object-view name="City-level">, where "City-level" is the name of the view. So the tool will look for a file (inside the directory specified in map-view-directory called "City-level.props". If this file does not exist, a default property file (specified via the parameter map-view-default-properties) is used.
The principal advantage of this new version is that several windows can be open via the "File->New View Windows" and each of these windows can have a different initial state in terms of latitude/longitude or scale for example.

### How Views are Selected

Views are selected as detailed in follow:

IF there is a correspondent view property file in the directory specified in map-view-directory, such file will be used;

ELSE IF there is a default file specified in map-view-default-properties, such file will be used;

ELSE a default inbuilt property file, representing a world map, is used.

Clauirton Siebra, CISA/AIAI, University of Edinburgh
Updated: Mon Jun 26 17:05:25 2006