Map Engine Selection

Selection Rendering Introduction

Originally in Weave the drawing of the current selection was always done as part of the rendering the map image, this was because originally there was only a single map layer on the client. In this situation each update of the map image included a step, on the server, where the current selection was drawn on top of the map image generated by the underlying map engine before passing the image back to the browser for display.

Once support for more than one map engine was available on the client this process was supplemented by configuring the client as such that the original map image was untouched and the current selection was drawn as a completely separate image, where both images were sent to the browser which displayed the selection image on top of the original map image.

This provided improved performance for the client since it no longer required and entire map redraw if just the selection was changed, and was all done through configuration. The configuration basically involved creating a dummy map engine, based on the original map engine, that never ended up drawing any of it's layers but instead went through the process outlined above of having the selection drawn on the (empty) image it generated.

But this was only ever a hack since it relied upon the use of a dummy map engine configured through guesswork.
Now however this dummy map engine can be replaced by a map engine specifically designed to draw a separate selection layer on top of other layer in the client browser, it's this map engine, the Selection Map Engine that is described here.

Configuration of the server map engine

The drawing of the current selections on the map is performed in Weave by a separate bundle com.cohga.server.map.selection. This way the other map engines are kept as simple as possible, just drawing an image of a specific size, covering a specific area with a specific list of layers visible.

Because all of 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.

Creating a selection map engine follows the same process as other map engines and just has a new namespace of its own when it comes to configuration, obviously the content of the configuration for the selection map engine is different since it serves a different purpose, but we explain that configuration here.

Basic configuration to setup a selection map engine on the server

<?xml version="1.0" encoding="UTF-8"?>

<config xmlns="urn:com.cohga.server.config#1.0" xmlns:selection="urn:com.cohga.server.map.selection#1.0">

  <selection:mapengine id="selection">
    <!-- Selection specific configuration if required -->
  </selection:mapengine>

</config>

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

Customising the selection map engine

Setting a maximum scale

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

Setting maximum scale for selections to be drawn at

  <selection:mapengine id="selection">
    <maxscale>50000</maxscale>
  </selection: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. As of Weave 2.5.28, it's possible to add a 's' or 'ms' suffix to the timeout value to specify if the units are seconds or milliseconds, e.g. <timeout>500ms</timeout>.

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

Setting time and selection size limits

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

Both of these setting 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.

Turning off antialiasing

  <selection:mapengine id="selection">
    <antialiasing>false</antialiasing>
  </selection:mapengine>

Also, since the selected features are drawn in batches 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's 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's safe to use the new limit value, otherwise it should be reduced until a safe value is determined. There's little point in setting this value to more than the limit value, if set.

Changing number of features rendered in each batch

  <selection:mapengine id="selection">
    <batchsize>2500</batchsize>
  </selection:mapengine>

Since there are a large number of possible image formats (in regards to bits-per-pixel, colour palettes, transparency support, etc) the selection drawing plugin will generate a new image of a known format and draw the selection on top, this way a consistent image format is produced at the end (this is mainly to handle problems experienced with earlier versions of Internet Explorer).

You can specify the default format for the images generated by the selection map engine with the format property.

Changing the format of the generated image

  <selection:mapengine id="selection">
      <format>image/png32</format>
  </selection:mapengine>

By default the selection map engine reports that it support 32 and 8 bit png and gif, with 32 bit png being the default if no format is specified.

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 an override tag (the override tag is optional as of version 1.3.3 of the bundle).

CSS style rendering properties

• 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 include the one(s) you want to change, and you only need to include the properties that you want to change from the defaults

Changing the basic rendering styles of point, lines and polygons

<selection:mapengine id="selection">
  <override>
    <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>
  </override>
</selection:mapengine>

Overriding selection drawing type for a specific entity

Occasionally if you're using a spatial engine that does not support specific geometry types, point, line and polygon, but instead just a generic geometry type (this includes SQL Server) then you may need to tell the selection map engine what type of renderer to use for a particular entity. This is particularly important if you're seeing "Unable to make suitable draw style for ..." messages in the weave.log file (note that another page that may be relevant in this situation, and is probably a better solution is this page if you're using SQL Server)

This can be done by setting the geometry type for an entity as follows:

Overriding the rendering type for an entity

<selection:mapengine id="selection">
  <override>
    <entity id="property">polygon</entity>
    <entity id="road">line</entity>
    <entity id="trafficlight">point</entity>
  </override>
</selection:mapengine>

You can use point or multipoint, line, multiline, linestring or multilinestring, and polygon or multipolygon (all values will be accepted, but they'll be interpreted as 'point', 'line' or 'polygon' regardless).

This then sets the geometry type for the entities selection, and the renderer for that particular type will be used to draw the selections.

Completely overriding the selection drawing for a specific entity

It's also possible to specify the rendering directly for a specific entity by using the entity id instead of point, line or polygon, for example:

Overriding an entities rendering using CSS properties

<selection:mapengine id="selection">
  <override>
    <entity id="property">
      <active>
        <strokecolour>green</strokecolour>
        <strokewidth>3</strokewidth>
        <strokeopacity>0.75</strokeopacity>
        <fillcolour>green</fillcolour>
        <fillopacity>0.125</fillopacity>
      </active>
      <inactive>
        <strokecolour>green</strokecolour>
        <strokewidth>2</strokewidth>
        <strokeopacity>0.25</strokeopacity>
        <fillcolour>green</fillcolour>
        <fillopacity>0.025</fillopacity>
      </inactive>
    </entity>
  </override>
</selection:mapengine>

Advanced selection rendering

Additionally it's possible to specify the selection rendering using SLD (Styled Layer Descriptor).
This can be done either by specifying the SLD directly in the config file or by referencing a file containing the SLD from the config file.

Referencing a SLD file

<selection:mapengine id="selection">
  <override>
    <entity id="property">property.sld</entity>
  </override>
</selection:mapengine>

The contents of property.sld, which should be in the workspace directory, should contain valid SLD XML to describe the renderer to use for the property entity.

Alternatively the SLD can be embedded directly in the configuration file (but is not recommended)

Embedding a SLD file

<selection:mapengine id="selection">
  <override>
    <entity id="property"><![CDATA[
      <StyledLayerDescriptor version="1.0.0" xsi:schemaLocation="http://www.opengis.net/sld StyledLayerDescriptor.xsd" xmlns="http://www.opengis.net/sld" xmlns:ogc="http://www.opengis.net/ogc" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <NamedLayer>
          <Name>property</Name>
          <UserStyle>
          <!-- Rest of SLD content here -->
          </UserStyle>
        </NamedLayer>
      </StyledLayerDescriptor>
    ]]></entity>
  </override>
</selection:mapengine>

There's an open source tool that can be used to create SLD files available at AtlasStyler SLD editor.

Optional 'override' tag in definition

Additionally, the <override> tags are now optional.

The following two examples are equivalent:

Referencing a SLD file with override tag

<selection:mapengine id="selection">
  <override>
    <entity id="property">property.sld</entity>
  </override>
</selection:mapengine>

Referencing a SLD file without override tag

<selection:mapengine id="selection">
  <entity id="property">property.sld</entity>
</selection:mapengine>

Drawing selections with a separate map engine on the client

Using the selection map engine requires that we add the selection map engine to the client configuration so that it is drawn on top of the existing layers.

New 'selection' map engine added to client

    <client:config id="...">
        ...
        <view id="com.cohga.html.client.map.mapView">
            ...
            <mapEngine id="raster">
               <options>
                 <selection>false</selection>
                 <alpha>false</alpha>
               </options>
            </mapEngine>

            <mapEngine id="vector">
               <options>
                 <selection>false</selection>
                 <alpha>true</alpha>
               </options>
            </mapEngine>

            </mapEngine id="selection">
                <options>
                    <!-- tell the client map engine that this layer is for handing selections -->
                    <selection>true</selection>
                    <!-- ensure the the client knows that this map engine supports transparency -->
                    <alpha>true</alpha>
                </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.main">
        <!-- set the default map engine for entries that don't have one set -->
        <mapengine>vector</mapengine>

        <entry label="Selection" exclusive="true">
            <!-- change the map engine for every entry in this group to use the selection map engine-->
            <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>