Client Views Map

The Map View is used to provide the user with a means of navigating geospatial data using a map.

ID

com.cohga.html.client.main.mapView

Sub-tags

Scales

A list of scales can be added to the map which will prevent the user from zooming to arbitrary scales, that it they'll be limited to the values provided by this list.

The list is provided in the map view as a list of <scale> values within the <scales>

or as a comma-separated list of values within the <scales>

Table of Contents

A map view may be associated with a Table Of Contents model to provide the user with a more user-friendly listing of the layers available in the map.

If no table of contents is linked explicitly with the map then Weave will create a generic one providing the user with a simple list of the available layers.

Extents

The administrator can set the initial extent (used when the client starts and when the user uses the ‘home extent' button), full extent (used when the user uses the 'full extent' button) and limit extent (used to restrict the users movement).

Note that these values can also be set in the defaults section of the client config, but the values set in the map view take precedence.

Coordinate Reference System

You can specify a default coordinate reference system that you wish to be used for the map. Obviously, it should be one that is supported by the map engine, and preferably (for performance reasons) the default for the map engine.

The default if not set will be EPSG:4326.

Map Controls

Keyboard

com.cohga.client.mapctrl.keyboard

Adds keyboard control to the map panel (when the map has focus) allowing the user to pan and zoom the map using the keyboard

Mouse wheel

com.cohga.client.mapctrl.navigation

Adds mouse wheel control to the map panel (when the map has focus) allowing the user to zoom in and out of the map using the mouse wheel

Scale Line

com.cohga.client.mapctrl.scaleLine

Display the current scale on the map as a line

Display the current scale on the map as a line

Scale

com.cohga.client.mapctrl.scale

Display the current scale on the map as text

Scale Bar

weave.mapctrl.scalebar

Display the current scale or scale text, or both on the map

Mouse Position

com.cohga.client.mapctrl.mousePosition

Display the current cursor position on the map

additional properties

Pan/Zoom Bar

com.cohga.client.mapctrl.panZoomBar

Add a control to the map to allow the user to directly pan and zoom the map

Zoom In/Out

com.cohga.client.mapctrl.zoomInOutPanel

Add simple zoom in and out buttons. This is a simpler alternative to the above Pan/Zoom bar.

Overview Map

com.cohga.client.mapctrl.overviewMap

Display an overview map on the map

additional properties

ratios

The ratio values are used to determine if the overview map extent should be changed.

From a coding perspective, we divide the current overview map resolution by the main map resolution and compare the values to the min and max resolutions to determine if the overview map should adjust its extent.

The appropriate values are dependent upon the scales set for the main map engine in the map view.
If you want to stop the zooming try setting minRatio to a large value and maxRatio to a small value.

Attribution

com.cohga.client.mapctrl.attribution

This control requires at least version 2.4.15.

Add the 'attribution' control then add an 'attribution' option to one or more client map engines.

Touch

com.cohga.client.mapctrl.touch

Enable touch navigation for the map panel.

Highlight

You can alter the style used to highlight an individual entity (only from 2.5.18 onward) by adding a highlight tag to the map view which has the following properties

Highlight

Vector

Marker

Map Engines

The map engine configures the actual source for the map image. Different types of map engines can be specified and and more than one map engine can be used.

Multiple map engines

A single map engine can represent a single map layer, for example the aerial photography from 1968, or multiple map layers, for example all of the vector data related to water utilities. They can also be combined in the client configuration so that multiple images are overlayed to combine the data from more than one map engine.

Example of using three map engine to display raster, vector and a separate selection layer.

Note that to properly use the above configuration you may also need to update your toc model or add an image slider. Also, there are issues with transparency that will need to be considered (especially if you're unlucky enough to have to support Internet Explorer 6).

A toc model suitable for the above map engine configuration would set the map engine for the selection and raster layers to the same engines as configured above, rather than leaving them assigned to the original map engine.

For example assuming that we previously had a single map engine, mapengine.main, that contained raster and vector layers and was also used to draw the selection. In this case the toc model and client config could be something like:

But if we wanted to switch to the client configuration with the three map engines then our toc model would become something like:

Which makes the default map engine mapengine.vector, and changed the selection layers map engine to mapengine.selection and the aerial photography switched to mapengine.raster.

Then on the client side, the map panel will now contain three separate map layers, one for each map engine, which may improve performance because it cuts down on the number of layers that must be drawn on the server when the user toggles a single layers visibility.

For example, the selection layers are drawn a lot quicker in the above example because when the selection is changed only the selection layers need to be redrawn, not all of the other layers that are now in the mapengine.vector layer.

Transparency and multiple map engines

This may also make it clearer as to why transparency is now an issue, previously all of the map layers were drawn on the map server at once and the map server knew how to overlay the individual layers to ensure that lower layers show through the transparency of higher layers, but now that overlaying is performed on the client, so if the client doesn't support transparency properly (IE6 with 8-bit PNG images) or if the map engine doesn't provide full transparency support (ArcIMS) then the map panel on the client can look terrible. Sometimes that can be resolved by switching the image generation to 24 or 32-bit PNG or disabling anti-aliasing.

The following 2 images show the difference between using a single map engine, where the map server is retrieving the data, generating a single map image, and sending that to the client for display, and multiple map engines, where multiple images are sent to the client where they're overlayed.

Open

In the above situation, since one map server is generating the map image it can produce the best image, making proper use of anti-aliasing and transparency, both full and partial. But because the image includes all map layers a change to any of the layers requires a whole new image to be drawn, which could mean that every map update is slow(er).

Open

In this situation, multiple map servers are generating the images, which means that a change to one of the layers will result in the request for a map image that has fewer layers to draw, which should result in quicker response times. Of course, this is the case if you're toggling the visibility of a single layer, if you're panning or zooming the map then the same number of map layers will need to be drawn, but there could still be a performance advantage if the map servers are running on multiple physical servers, or a server has spare capacity, since they'll be able to generate the map images at the same time (3 map servers generating 3 images with 2 layers each will be quicker than 1 map server generating 1 image with 6 layers).

The downside to this arrangement is that the map server can't optimise the final image, and further, if the map server doesn't support transparency properly then any anti-aliasing around transparent areas can look terrible. Also, some map engines (ArcIMS I'm looking at you) don't support partial transparency, so if you, for example, specify a 50% transparent yellow fill for a polygon layer and there are no layers below that layer then rather than producing a final image that has the area filled with a transparent yellow fill it will instead produce an opaque fill that is 50% yellow and 50% whatever the background colour is set to. This means that when you overlay the image on top of another image rather than getting the bottom image showing through with a yellow tint, you instead don't see the bottom image at all and just see the yellow/background colour image.

Opacity and multiple map engines

This is assuming that the top image doesn't have its opacity altered to be less than 100%, which is a different issue altogether.
Since the map engine can have its opacity set to less than 100% in the client configuration it's possible to overlay a map image from a map server that doesn't support transparency at all and still have the underlying map image show through, for example setting the opacity to 0.5 (50%) would show a mix of 50% of the underlying image and 50% of the top image. The problem here is that the overall image appears washed out.

The images below show combining a raster image with a vector image that properly supports transparency (generated by GeoServer) with the vector images' opacity set to 1 (100%)

+ =

compared to combining a raster image with a vector that doesn't support transparency, but this time with the vector opacity set to 0.5 (50%)

+ =

Image Slider

An alternative for when you have multiple overlayed map engines on the client is that you can use a slider to transition between layers. The image transition slider allows the user to dynamically adjust the opacity of a single map engine.

Two options when using a single image slider are that if you have map engines that support transparency then you can transition the underlying image and still have the overlaying image visible, or if you don't have full transparency support then you can use it to transition the overlaying image and completely replace the underlying image.

The following 3 images show an example when the transition slider is attached to a raster image map engine that's overlayed on top of a vector map engine that does not support transparency (this could also be reversed with the vector map engine on top and the transition slider attached to it to accomplish exactly the same thing). The top image shows the slider at 10%, the second at 50% and the third at 100% (when the slider is at 0% you'll only see the vector image).

You can see that the vector image is gradually replaced entirely by the raster image (the area where the two images intersect is what the client would expect to see). And you can imagine if the map engines were reversed, with the raster below the vector and the slider attached to the vector, then the process would be the same, but with the vector layer replacing the raster rather than the raster replacing the vector (since the vector image is opaque). If the map engines were reversed but the slider was still attached to the raster map engine then there would be no visible effect from the slider since the opaque vector image on top would be occluding the raster image anyway, regardless of its opacity.

The following 3 images show an example with the transition slider again attached to the raster image, but in this case, the raster map engine is below the vector map engine, but in this case, the vector map engine supports transparency, so as the slider progresses from 10% to 50% to 100% the vector layer is still visible and the raster that shows through the transparent parts of the vector image (and again when the slider is at 0% you'll only see the vector image).

In this case, the raster image is gradually exposed through the vector image. If this configuration was kept (vector on top, raster below and image slider attached to raster image) but the vector images' map server didn't support transparency then moving the slider would have no visible effect, since the layer would be hiding the raster layer no matter what opacity the raster layer is set to.

The simplest example of this is to transition between a vector and a raster layer

Here we've kept the map engine configuration in the client the same as we have in the earlier example but we've added the image trans slider to allow the user to fade in and out the vector image. This example assumes that the vector image is opaque, if it were transparent you could attach the slider to the raster image instead and you'd always have the vector image visible.

You may have noticed that the Photography layer has been removed from the toc model, which means that the only way for the user to view the aerial photography is to use the slider since it doesn't make a lot of sense to allow the user to toggle the display of the layer via the toc panel and also use the slider to change its visibility.

If you had multiple raster layers that you wish to attach to the slider you could create something like the following toc model

Then depending upon the ordering of the map engines in the client configuration, you can attach the slider to the vector or raster map engines while also giving the user the ability to choose which raster layer to display.

Client-side map engines

All of the map engines configured in the client in the previous examples use the Weave server to generate the map images on behalf of the client, that is the Weave client is communicating with the Weave server to generate the map images and the Weave server is calling the map engine to create the images which are then sent back to the client.

An alternative to this is to have the client directly call the map engine to generate the images and bypass the Weave server altogether. Unfortunately at this stage, ArcIMS and ArcGIS SOAP are NOT directly supported in this configuration but can be used if accessed via WMS, which is supported by the client.

One reason for doing this would be to improve performance as it removes the extra layer of interaction with the Weave server, but it does mean that the client will require direct access to the map engine, whereas previously since it was the Weave server that was supplying the client with the images no access was required to the actual map engine by the client. So while performance may improve security will decrease and configuration complexity will increase.

Another limitation of this method is that as far as the user is concerned there is only a single layer coming from the map engine, even if the image generated by the map engine is composed of multiple feature layers. This means that if you add multiple map engines to the client configuration all pointing to client-side map engines then the toc model must be set up to include a single layer entry for each engine, and the user can only display or hide the whole layer, not individual layers within the map engine.

One issue that arises when using a map engine that only the client knows about is when it comes time to generate a report with a map embedded in it. Currently, this requires a duplicate map engine to be configured for the server to use and the client map engine configuration setup to tell Weave that it should use this map engine when it needs to generate a map on the server.

So for example let's look at what we'd need to set up the client with a very simple WMS map engine

All we've done here is set the map engine type to wms (the default is 'weave') and provided it with the URL that it needs to access the server. From there the client will directly interact with the WMNS server and not Weave when it needs to draw a map image.

From here if we want the user to be able to generate a report containing a map then we need to alter the client map engine configuration to tell it how the server can access this map engine.

To do this we need to first add a new map engine configuration pointing to the WMS server then alter the client map engine configuration to point to this new map engine

Here we've created a new server-side map engine that reflects the map engine used by the client and then set up the client to tell the server to use this map engine when it needs to generate a map image. We've also restricted the layers available through that map service to a single layer. The id used for the layers is taken from the WMS map service, in the example URL I used 0:2 is the id for a 2005 aerial photography layer.

Tiled map engines

The client-side map stuff is all well and good but the best reason for using a client-side map engine is that the client can then use a tiled map service. This is a map service where the map is generated in smaller tiles rather than as a single whole image, this provides large advantages in performance because once an individual tile is cached in the client browser they don't need to download or generate that tile again, which results in significant speed improvements for the client compared to generating a complete map image each time the user alter the map display.

The downside to tiled map engines is that they are fixed images and the user can not turn on and off the display of sub-layers within the map image. Whilst this generally isn't an issue for aerial photography-type map images or some other raster-based layers it can be a problem with vector layers.

For example, if you have a map engine composed of three vector layers and you want to give the user the option to turn on and off the display of each of the layers individually you would need to generate 8 tile caches. One with no layers, three for when only one layer is visible, three for when the combinations of two layers are visible and one for when all layers are visible. If you wanted to add a new layer to the mix then you'd need 16 tile caches, another layer would mean 32 tile caches, I'm sure you can see where this is going.

For this reason, if you have a large number of vector layers and you want to provide the user with the ability to selectively display or hide some of the layers then you'll probably still need to use a non-tiled weave layer. But if you have a limited number of layers, wish to create a very simple map environment or just want to add a single raster layer then tiles may be an option.

The easiest (and least useful) way to set up a tile cache is to add the singleTile flag to a WMS client-side map engine and set it to false. This will tell the client to send requests to the WMS server asking for small tiles rather than a single large image. But unless the WMS map engine is specifically configured to handle requests for tiles the performance of this setup will be severely compromised.

Alternatively, the client map engine can be configured to use a specialized tile caching mechanism instead of WMS. This is where the map engine supplying the tiles is specifically designed and configured to supply image tiles rather than imposing this on a map engine that wasn't specifically designed for it like WMS.

Weave currently supports (at least) two different tiling mechanisms TileCache and TMS. These two tiling mechanisms use specially crafted URLs to determine which tile to fetch and mainly differ in the formatting of the URL.

Setting up and tiled map engine using one of these mechanisms is similar to the WMS map engine but the type should be tilecache or TMS, and both still require the url parameter.

In the case of the TileCache version it also requires a layername parameter. This is used when constructing the url and allows the same tile cache to server multiple sets of tiles.
You'll also notice that we set singleTile to false (which isn't really necessary since a tile cache layer already knows that it's generated using tiles) and changed the format (the default is image/png for TileCache tiles). For a TMS tile cache the layername isn't required

Depending upon the actual tile cache implementation used to provide the tiles there may be two options available, one to generate the tiles as requested and the other to pre-generate the tiles. The first option has the advantage that only the tiles actually viewed by the users are ever generated, thereby reducing disk storage, but the performance will be slow the first time the tiles are generated. The second option has the advantage that it's lightning fast right from the start, but has the disadvantage that the whole tile cache needs to be generated before it's available even those tiles that will never be seen by any users and therefore use more disk storage (up front, over time the other option can also result in large disk usage as most of the map areas are viewed).

It can take many hours of processing to pre-generate a tile cache and use hundreds of gigabytes of disk space, depending upon how large an area is covered and how many levels of tiles are generated.

Currently Weave provides commands to build TileCache formatted tile cache for any map engine supported by Weave.

Map Engine Options

Below is a list of the options that are available for use when setting up a map engine