Overriding WMS Provider settings for MapGuide Open Source Consumption

If you wish, you can also download a PDF version of this document.

Configuration of feature sources within MapGuide Open Source is generally done using one of the open source (such as Web Studio or ​MapGuide Maestro) or proprietary (Autodesk MapGuide Studio) GUI's. Unfortunately, these applications currently do not provide a simple interface for overriding the configuration of WMS feature sources. Examples of these configuration options include:

• Image transparency
• Image format (png, jpeg, gif, etc)
• Image background color
• Coordinate system
• Displaying of multiple WMS layers in a single MapGuide layer

This document describes how to manually create a new FDO WMS configuration file, and load it for use in MapGuide

Configuration Document

This section describes how to create the configuration document for the MapGuide WMS feature source.

Get the Capabilities Document

Before anything can be done, you should get the WMS capabilities document for the service you want to interact with. This XML document contains the details of the services provided by the WMS service, such as coordinate systems, image formats, layers, and styles. To do obtain this file, start a web browser and go to the location

http://<WMSServiceAddress>?service=wms&request=GetCapabilities

Basic Configuration Document

This section describes a basic configuration document that configures and exposes a single WMS layer.

Copy the following XML to a text editor.

<?xml version="1.0" encoding="UTF-8"?>
<DataStore xmlns:fdo="http://fdo.osgeo.org/schemas" xmlns:gml="http://www.opengis.net/gml" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://fdo.osgeo.org/schemas" xsi:schemaLocation="http://fdo.osgeo.org/schemas FdoDocument.xsd">
  <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://fdo.osgeo.org/schemas/feature/WMS" xmlns:fdo="http://fdo.osgeo.org/schemas" xmlns:WMS="http://fdo.osgeo.org/schemas/feature/WMS" elementFormDefault="qualified" attributeFormDefault="unqualified">
    <xs:element name="%FeatureClassName%" type="WMS:%FeatureClassName%" abstract="false" substitutionGroup="gml:_Feature">
      <xs:key name="%FeatureClassName%Key">
        <xs:selector xpath=".//%FeatureClassName%"/>
        <xs:field xpath="Id"/>
      </xs:key>
    </xs:element>
    <xs:complexType name="%FeatureClassName%" abstract="false">
      <xs:complexContent>
        <xs:extension base="gml:AbstractFeatureType">
          <xs:sequence>
            <xs:element name="Id">
              <xs:simpleType>
                <xs:restriction base="xs:string">
                  <xs:maxLength value="256"/>
                </xs:restriction>
              </xs:simpleType>
            </xs:element>
            <xs:element name="Image" type="fdo:RasterPropertyType" fdo:defaultImageXSize="800" fdo:defaultImageYSize="600">
              <xs:annotation>
                <xs:appinfo source="http://fdo.osgeo.org/schemas">
                  <fdo:DefaultDataModel organization="Row" bitsPerPixel="32" tileSizeX="100" tileSizeY="100"/>
                </xs:appinfo>
              </xs:annotation>
            </xs:element>
          </xs:sequence>
        </xs:extension>
      </xs:complexContent>
    </xs:complexType>
  </xs:schema>
  <SchemaMapping provider="OSGeo.WMS.3.1" name="WMS" xmlns="http://fdowms.osgeo.org/schemas">
    <complexType name="%FeatureClassName%">
      <RasterDefinition name="Image">
        <Format>PNG</Format>
        <Transparent>true</Transparent>
        <BackgroundColor>0xFFFFFF</BackgroundColor>
        <Time>current</Time>
        <Elevation>0</Elevation>
        <SpatialContext>EPSG:4326</SpatialContext>
        <Layer name="%LayerName%">
          <Style/>
        </Layer>
      </RasterDefinition>
    </complexType>
  </SchemaMapping>
</DataStore>

Substitute %FeatureClassName% with a descriptive name of your choosing (do not use “.” in the name, and until you get this working it is best to keep it limited to ascii characters).

Substitute %LayerName% with the name of the WMS layer that you want to display. For example, if the following entry occurs in WMS capabilities document:

<Layer queryable="1" opaque="0" noSubsets="0">

<Name>theLayerName</Name>
<Title>The layer title</Title>

</Layer>

then substitute %LayerName% with theLayerName.

At the end of the document are the following configuration parameters that can be adjusted as appropriate:

• Format – used to specify the image type. The possible values here are in the WMS capabilities document in the GetMap section. Do not include the “image/” part of the format here. That is, if the desired format is specified in the WMS capabilities document as “image/png”, put “png” in the configuration document.
• Transparent – if the WMS Service supports transparency then specifying true here will make the background of the returned image transparent. This transparency is preserved in MapGuide so any layers that this WMS layer is placed over will show through the transparent regions.
• BackgroundColor – if the WMS Service supports specifying background colors, set the RGB value (e.g., 0xFFFFFF=white, 0x000000=black, 0x0000FF=blue, 0xFF0000=red, 0x00FF00=green), here for the color.
• Time – time value of the desired WMS layers.
• Elevation – elevation of the desired WMS layers.
• SpatialContext – the spatial reference system to be used for the map. The list of possible values here are described in the WMS capabilities document. Typically EPSG:4326 will work.
• Layer – the name of the layer and the style to apply to it. The list of possible styles is listed in the WMS capabilities document. For example, if “visual” was a possible style for the layer then <Style>visual</Style> could be added.

Once the substitutions have been made save the file.

Multiple WMS Layers in a Single MapGuide Layer

To get multiple WMS layers in a single MapGuide layer, it is enough to specify multiple Layer tags in the configuration document. When the resulting feature class (i.e., name substituted for %FeatureClassName%) is specified in a layer, the layer will display all of the specified WMS layers. The following XML snippet shows how the multiple layers are specified:

<RasterDefinition name="Image">
        <Format>PNG</Format>
        <Transparent>true</Transparent>
        <BackgroundColor>0xFFFFFF</BackgroundColor>
        <Time>current</Time>
        <Elevation>0</Elevation>
        <SpatialContext>EPSG:4326</SpatialContext>
        <Layer name="%LayerName1%">
          <Style/>
        </Layer>
        <Layer name="%LayerName2%">
          <Style/>
        </Layer>
        <Layer name="%LayerName3%">
          <Style/>
        </Layer>
</RasterDefinition>

The Layer section can be repeated as many times as required.

Specifying Multiple Feature Classes

A WMS service typically serves multiple layers. Using the basic configuration document approach above it is a lot of work to expose the layers because one feature source per WMS layer would need to be created. The following is an example of how to specify more than one feature class per MapGuide WMS feature source; a feature class corresponds to a set of WMS layers that can be displayed in a single MapGuide layer. Note that for each feature class, multiple WMS layers could also be specified as described in the Multiple WMS Layers in a Single MapGuide Layer section.

<?xml version="1.0" encoding="UTF-8"?>
<DataStore xmlns:fdo="http://fdo.osgeo.org/schemas" xmlns:gml="http://www.opengis.net/gml" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://fdo.osgeo.org/schemas" xsi:schemaLocation="http://fdo.osgeo.org/schemas FdoDocument.xsd">
  <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://fdo.osgeo.org/schemas/feature/WMS" xmlns:fdo="http://fdo.osgeo.org/schemas" xmlns:WMS="http://fdo.osgeo.org/schemas/feature/WMS" elementFormDefault="qualified" attributeFormDefault="unqualified">
    <xs:element name="%FeatureClassName%" type="WMS:%FeatureClassName%Type" abstract="false" substitutionGroup="gml:_Feature">
      <xs:key name="%FeatureClassName%Key">
        <xs:selector xpath=".//%FeatureClassName%"/>
        <xs:field xpath="Id"/>
      </xs:key>
    </xs:element>
    <xs:element name="%FeatureClassName2%" type="WMS:%FeatureClassName2%Type" abstract="false" substitutionGroup="gml:_Feature">
      <xs:key name="%FeatureClassName2%Key">
        <xs:selector xpath=".//%FeatureClassName2%"/>
        <xs:field xpath="Id"/>
      </xs:key>
    </xs:element>
    <xs:complexType name="%FeatureClassName%Type" abstract="false">
      <xs:complexContent>
        <xs:extension base="gml:AbstractFeatureType">
          <xs:sequence>
            <xs:element name="Id">
              <xs:simpleType>
                <xs:restriction base="xs:string">
                  <xs:maxLength value="256"/>
                </xs:restriction>
              </xs:simpleType>
            </xs:element>
            <xs:element name="Image" type="fdo:RasterPropertyType" fdo:defaultImageXSize="800" fdo:defaultImageYSize="600">
              <xs:annotation>
                <xs:appinfo source="http://fdo.osgeo.org/schemas">
                  <fdo:DefaultDataModel organization="Row" bitsPerPixel="32" tileSizeX="100" tileSizeY="100"/>
                </xs:appinfo>
              </xs:annotation>
            </xs:element>
          </xs:sequence>
        </xs:extension>
      </xs:complexContent>
    </xs:complexType>
    <xs:complexType name="%FeatureClassName2%Type" abstract="false">
      <xs:complexContent>
        <xs:extension base="gml:AbstractFeatureType">
          <xs:sequence>
            <xs:element name="Id">
              <xs:simpleType>
                <xs:restriction base="xs:string">
                  <xs:maxLength value="256"/>
                </xs:restriction>
              </xs:simpleType>
            </xs:element>
            <xs:element name="Image" type="fdo:RasterPropertyType" fdo:defaultImageXSize="800" fdo:defaultImageYSize="600">
              <xs:annotation>
                <xs:appinfo source="http://fdo.osgeo.org/schemas">
                  <fdo:DefaultDataModel organization="Row" bitsPerPixel="32" tileSizeX="100" tileSizeY="100"/>
                </xs:appinfo>
              </xs:annotation>
            </xs:element>
          </xs:sequence>
        </xs:extension>
      </xs:complexContent>
    </xs:complexType>
  </xs:schema>
  <SchemaMapping provider="OSGeo.WMS.3.1" name="WMS" xmlns="http://fdowms.osgeo.org/schemas">
    <complexType name="%FeatureClassName%Type">
      <RasterDefinition name="Image">
        <Format>PNG</Format>
        <Transparent>true</Transparent>
        <BackgroundColor>0xFFFFFF</BackgroundColor>
        <Time>current</Time>
        <Elevation>0</Elevation>
        <SpatialContext>EPSG:4326</SpatialContext>
        <Layer name="%LayerName%">
          <Style/>
        </Layer>
      </RasterDefinition>
    </complexType>
    <complexType name="%FeatureClassName2%Type">
      <RasterDefinition name="Image">
        <Format>PNG</Format>
        <Transparent>true</Transparent>
        <BackgroundColor>0xFFFFFF</BackgroundColor>
        <Time>current</Time>
        <Elevation>0</Elevation>
        <SpatialContext>EPSG:4326</SpatialContext>
        <Layer name="%LayerName2%">
          <Style/>
        </Layer>
      </RasterDefinition>
    </complexType>
  </SchemaMapping>
</DataStore>

Creating a MapGuide WMS Feature Source

This section describes how to create a MapGuide WMS feature source that will be associated with the configuration document.

Creating the Feature Source Document

To create the feature source document, copy the follow XML to a text editor:

<?xml version="1.0" encoding="utf-8"?>
<FeatureSource xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:noNamespaceSchemaLocation="FeatureSource-1.0.0.xsd">
  <Provider>OSGeo.WMS</Provider>
  <Parameter>
    <Name>FeatureServer</Name>
    <Value>%WMSService%</Value>
  </Parameter>
  <ConfigurationDocument>config.xml</ConfigurationDocument>
</FeatureSource>

Replace the %WMSService% with the address of the WMS service. This corresponds to what goes in the Server field of the WMS feature source editor in Studio.

Save the file.

Creating the Feature Source in MapGuide

The next step is to upload the feature source document onto the MapGuide site. The steps to do this are as follows:

1. Start a web browser and go to the location http://<machinename>/mapguide/mapagent/index.html, where machinename is the location in which MapGuide is installed.
2. Click on the SetResource link in the left frame. A SETRESOURCE form will appear in the right frame.
3. In the Resource ID field, type the name of the resource that you want to create. Make sure that the name ends with .FeatureSource. The resource name is case-sensitive.
4. For the Content field, browse to the feature source XML document that was created in the “Create a feature source document” section.
5. Leave the Header field blank.
6. Click Submit on the SETRESOURCE form.
7. If you have not authenticated yet with the MapGuide site, a login dialog will appear. Enter the credentials of a MapGuide author or administrator user.

After completing the steps above, a blank web page will take the place of the SETRESOURCE form.

Note that you have not yet uploaded the configuration document, so this is an incomplete feature source and will not work.

Attaching the Configuration Document

This section describes how to attach the configuration document created above to the feature source.

1. Start a web browser and go to the location http://<machinename>/mapguide/mapagent/index.html, where machinename is the location in which MapGuide is installed. Figure 1 above shows how the web page should look.
2. Click on the SetResourceData link in the left frame. A SETRESOURCEDATA form will appear in the right frame.
3. In the Resource ID field, type the name of the resource to which you want to add the configuration document. This is the same feature source resource that you created above. The resource name is case sensitive.
4. Enter config.xml in the Data Name field.
5. Enter Stream in the Data Type field.
6. For the Data field, browse to the location of the configuration document that you created above.
7. Click Submit on the SETRESOURCEDATA form.
8. If you have not authenticated yet with the MapGuide site, a login dialog will come up. Enter the credentials of a MapGuide author or administrator user.

After completing the steps above, a blank web page will take the place of the SETRESOURCEDATA form.

It is generally a good idea to test your uploaded configuration document to ensure that it is valid. The best way to do this is to use the GETRESOURCEDATA operation. If the returned XML does not parse correctly, then you most likely had a problem with the XML that you tried to upload and will have to fix any syntax errors or typos and try again.

Use the Feature Source

After all of the above steps have been done, you can now start Studio and use the feature source to create layer definitions.

If Studio was running when you created the feature source you may have to refresh the site explorer to make it show up.

Example

Attached to this page are two XML files that demonstrate the Basic Configuration Document and resource document. In the configuration document, NASA_WMS_config_doc.xml, we have chosen a %FeatureClassName% of NASAWMSGlobalPan. In addition, the %LayerName% is global_mosaic as determined from ​http://wms.jpl.nasa.gov/wms.cgi?service=wms&request=GetCapabilities. Then, in NASA_WMS_resource_doc.xml, we are using the NASA WMS server for the %WMSService% parameter. From there, the resource document can be uploaded using the mapagent with a FeatureSource name of our choice, and then the configuration document applied to that resource.