Map Engine

At least one Map Engine must be setup for the server to be able to generate and display map images for the client.

The map engine configuration is different depending upon which map engine you are connecting to.

Weave currently supports four map engines:

• WMS
• ArcIMS
• ArcGIS Server via Web Service

Drawing map selections

The drawing of the current selections on the map is performed in Weave by a separate bundle com.cohga.server.selection.impl. This way the map engine is kept as simple as possible, it just has to draw an image of a specific size, covering a specific area with a specific list of layers visible and the bundle takes care of drawing the selection on top of the returned image.

Because the selection drawing is handled by the same plugin it means that the configuration for every map engine is the same when it comes to selections.

Aside from altering the map image the selection bundle also alters the layer list for the map, it does this to add some virtual layers to the map description that represent the current selection, this way the selection display can be controlled by the user. The virtual layers represent the selection for the current layer, the selection for all layers and the selection for each selectable layer, see Table of Contents for more information.

Altering the selection drawing for a map engine is done by adding a selection tag to the map engine, with the simplest possible configuration disabling selection drawing all together, as follows:

  <wms:mapengine id="test">
    ...
    <selection>false</selection>
  </wms:mapengine>

Note: The namespace in the above example and following examples is wms, but the selection settings work for all map engines, WMS, ArcIMS and ArcGIS.

This will ensure that selections are never drawn on the map engine, effectively disabling the selection plugin for that map engine, this is particularly handy for overview maps.

Beyond that it's also possible to change some other settings that effect selection drawing.

Setting a maximum scale

The maximum scale beyond which selections won't be drawn can be set with the maxscale value.

  <wms:mapengine id="test">
    ...
    <selection>
      <maxscale>50000</maxscale>
    </selection>
  </wns:mapengine>

Limiting the drawing time

You can also limit the amount of time that is spent drawing the selection and limit the number of features that are ever drawn for the selection.

By setting a timeout value, in seconds, you can specify that once the plugin has spent that many seconds drawing features then it should stop, regardless of how many it has drawn. Currently the default is 10 seconds.

By setting a limit value you can specify that the plugin should draw a maximum of that many features. There is no default value.

  <wms:mapengine id="test">
    ...
    <selection>
      <limit>5000</limit>
      <timeout>5</timeout>
    </selection>
  </wms:mapengine>

Both of these settings can help ensure a speedy map response even if the user has a large number of selected features.

Other optimizations

Additionally, if you really want to tweak the performance of the selection rendering you can disable the smoothing of the drawing by turning off anti-aliasing, which may gain a few milliseconds. The default is to anti-alias the selection drawing.

  <wms:mapengine id="test">
    ...
    <selection>
      <antialiasing>false</antialiasing>
    </selection>
  </wms:mapengine>

The selected features are drawn in batches and you can alter the number of features that are drawn in each batch. The default batch size is 1000.
Increasing this value will will reduce the overhead that is required for each batch but sometimes there are limits on the underlying infrastructure (database or spatial engine) that limit the number of features that can be retrieved at once. You can try increasing this value and selecting more than that many features and see if the selection is still drawing. If it is then it is safe to use the new limit value, otherwise it should be reduced until a safe value is determined. There is little point in setting this value to more than the limit value, if it has been set.

  <wms:mapengine id="test">
    ...
    <selection>
      <batchsize>2500</batchsize>
    </selection>
  </wms:mapengine>

You can also gain a few more milliseconds by telling the selection drawing plugin to reuse the original image on which to draw the selection rather than creating a new one.
There are a large number of possible image formats (in regards to bits-per-pixel, colour palettes, transparency support, etc) that the underlying map engine can produce. By default, the selection drawing plugin will generate a new image of a known format and "draw" the original map image on it before drawing the selection on top. In this way, a consistent image format is produced at the end (this is mainly to handle problems experienced with earlier versions of Internet Explorer).

If the map engine that you are using produces images that are directly suitable for display in the browser then you can tell the selection drawing plugin to simply draw the selection on top of the original image and forward that on to the client. This is done by setting reuse to true. It is up to you to make sure that the image supports the correct transparency requirements and that it works in the browsers you want to support. 

  <wms:mapengine id="test">
    ...
    <selection>
      <reuse>true</reuse>
    </selection>
  </wms:mapengine>

Changing colours

The rendering of the selections can also be altered by adjusting the line and fill colours and transparency, the line widths, and the point symbology.

Because Weave can display selections for more than one entity at a time you can change the symbology for both the active entity and the inactive entities independently. This allows for the inactive selections to be drawn in a slightly less visible manner. If you wish to have the selections drawn the same regardless of the active entity then you don't need to include the active and inactive tags and just include one set of setting for each feature type (point, line and/or polygon).

This is done by adding a point, line and/or polygon tag to the selection tag.

selection

Properties

None

Sub-tags

Content

None

point

Properties

None

Sub-tags

Content

None

line

Properties

None

Sub-tags

Content

None

polygon

Properties

None

Sub-tags

Content

None

active/inactive

Properties

Sub-tags

None

Content

None

Notes

• Colours can be specified as either an RGB value, as decimal or hex (e.g., #ff0000), or as one of black, blue, cyan, darkgray, darkgrey, gray, grey, green, lightgray, lightgrey, magenta, orange, pink, red, white, yellow.
• The word 'colour' or 'color' and hyphens can be used in the property names, for example the following are all equivalent, 'strokecolour', 'strokecolor', 'stroke-colour' and 'stroke-color'.
• When setting line properties only the stroke settings are read.
• When setting polygon properties only stroke and fill settings are read.
• When setting point properties stroke, fill and marker settings are read.
• You don't need to include point, line and polygon unless you want to change all renderers, you only need to incldue the one(s) you want to change, and you only need to include the properties that you want to change from the defaults

<wms:mapengine id="test">
  ...
  <selection>
    <point>
      <active>
        <strokecolour>white</strokecolour>
        <strokewidth>1</strokewidth>
        <strokeopacity>0</strokeopacity>
        <fillcolour>cyan</fillcolour>
        <fillopacity>1</fillopacity>
        <mark>circle</mark>
        <marksize>12</marksize>
      </active>
      <inactive>
        <strokecolour>cyan</strokecolour>
        <strokewidth>2</strokewidth>
        <strokeopacity>1</strokeopacity>
        <fillcolour>white</fillcolour>
        <fillopacity>0</fillopacity>
        <mark>circle</mark>
        <marksize>12</marksize>
      </inactive>
    </point>
    <line>
      <active>
        <strokecolour>cyan</strokecolour>
        <strokewidth>3</strokewidth>
        <strokeopacity>0.75</strokeopacity>
      </active>
      <inactive>
        <strokecolour>#00ffff</strokecolour>
        <strokewidth>2</strokewidth>
        <strokeopacity>0.25</strokeopacity>
      </inactive>
    </line>
    <polygon>
      <active>
        <strokecolour>#00ffff</strokecolour>
        <strokewidth>3</strokewidth>
        <strokeopacity>0.75</strokeopacity>
        <fillcolour>#00ffff</fillcolour>
        <fillopacity>0.125</fillopacity>
      </active>
      <inactive>
        <strokecolour>#00ffff</strokecolour>
        <strokewidth>2</strokewidth>
        <strokeopacity>0.25</strokeopacity>
        <fillcolour>#00ffff</fillcolour>
        <fillopacity>0.025</fillopacity>
      </inactive>
    </polygon>
  </selection>
</wms:mapengine>

Drawing selections with a separate map engine

Sometimes, depending upon the configuration of the underlying map engine, drawing the selections on top of the map image may result in changes to the colours of the image. This is especially so if you are using an 8-bit image.

A workaround to this is to create a new map engine that is deployed specifically for drawing selections and also removing the selection drawing from the other map engine(s).

To do this you need to disable the selection drawing for your existing map engine and create a new one, then you add the new map engine to the client configuration.

For the moment the new selection map engine should be created based on the existing map engine that currently draws the selections, even though the underlying map engine (ArcIMS, WMS, etc) will never actually be called on to generate the image (when drawing the selection layer that is, it will still be called for drawing the original layers). In the future, specific configuration options may be made available for accomplishing the same thing.

The first thing to do is to create the new selection map engine.

    <wms:mapengine id="raster">
        <url>http://vmrunout:8080/geoserver/wms</url>
        <format>image/jpg</format>
        <transparent>false</transparent>
        <selection>false</selection> <!-- disable selections -->
    </wms:mapengine>

    <arcims:mapengine id="vector">
        <host>vmfadeout</host>
        <service>Vector</service>
        <format>image/png8</format>
        <selection>false</selection> <!-- disable selections -->
    </arcims:mapengine>

    <!-- new map engine based on 'Vector' map service -->
    <arcims:mapengine id="selection">
        <host>vmfadeout</host>
        <service>Vector</service>
        <format>image/png8</format>
        <transparent>true</transparent> <!-- obviously we need a transparent image -->
        <selection>
            <reuse>true</reuse> <!-- this may need to be false if you get a black background -->
            <!-- include any other selection options here -->
        </selection>
        <layers> <!-- filter layers so underlying map engine doesn't actually have any layers so will never draw anything -->
          <layer>dummy</layer>
        </layers>
    </arcims:mapengine>

Then we add the new map engine to the client configuration so that it is drawn on top of the existing layers.

    <client:config id="...">
        ...
        <view id="com.cohga.html.client.map.mapView">
            ...
            <mapengine id="raster">
                ....
            </mapengine>

            <mapengine id="vector">
                ....
            </mapengine>

            </mapengine id="selection">
                <options>
                    <selection>true</selection> <!-- tell the client map engine that this layer is for handing selections -->
                    <alpha>true</alpha>
                    <!-- include any other options here -->
                </options>
            </mapengine>
        </view>
    </client:config>

The final step is to switch the toc model to use the new selection map engine for the selection related entries by adding a mapengine tag to the Selection entry.

    <toc:model id="toc.manningham">
        <mapengine>vector</mapengine>
        <entry label="Selection" exclusive="true">
            <!-- use the selection map engine for every entry in here -->
            <mapengine>selection</mapengine>
            <entry layer="_selection.active" label="Active" checked="true"/>
            <entry layer="_selection.all" label="All" checked="false"/>
            <entry label="Selected" checked="false">
                <!-- individual selection layer here -->
                ...
            </entry>
        </entry>

        <!-- regular layer entries here -->
        ...

        <entry label="Raster" exclusive="true">
            <!-- use the raster map engine for every entry in here -->
            <mapengine>raster</mapengine>
            ...
        </entry>
    </toc:model>

At the moment there is an known issue that will stop the progress bar from showing when there are selections visible.