Metacat

Metacat's Use of Geoserver

==========================

GeoServer 1.4.0, an open source Web Mapping Service (WMS) written in Java, is 

bundled with Metacat and can be used to render spatial data as web-deliverable 

maps (see figure). Metacat uses Community MapBuilder (a pure HTML and JavaScript 

application that uses AJAX and XSLT) to provide a web-based user interface for 

interacting with the generated maps. You can use any WMS-compatible client 

(e.g., ArcGIS, QGIS, JUMP, UDig, OpenLayers, Mapbender, Map Builder). Please 

note the mapping functionality is only supported for Metacat servlets running 

under Tomcat 6 or later. 

IMPORTANT: Regardless of whether you plan on using the mapping functionality 

you should, for security purposes, configure GeoServer so that it doesn't 

use the default password. For instructions, please see 

Geoserver Password Configuration.

.. figure:: images/screenshots/image051.jpg

   :align: center

   A map generated by Metacat's GeoServer. Points and "bounding boxes" 

   represent the geographic extent of datasets stored in the KNB Metacat repository.

GeoServer supports a wide variety of vector GIS data sources, which can be 

styled using Styled Layer Descriptors (SLDs) and output as images (the default) 

or raw vector data (GML or KML).

Currently, GeoServer can be used with the following limitations:

* The GeoServer will only map documents that are publicly available. This is 

  because the mapping server's support for permissions control is not as 

  fine-grained as Metacat's.

* The GeoServer can only access documents that conform to one chosen schema. 

  This is because only one set of xpaths can be defined in the Metacat properties.

* GeoServer 1.4, the version bundled with Metacat, does not support raster 

  input (e.g., satellite imagery or digital elevation models). We suggest 

  setting up UMN Mapserver if you aim to serve raster data. 

Metacat developers plan to continue extending and improving Metacat's mapping 

capabilities. If you are interested in contributing to those efforts, or if 

you are interested in learning more about the architecture and future plans for 

the mapping software.

Installing and Configuring

--------------------------

Metacat's GeoServer is automatically installed when Metacat is installed. If 

you do NOT wish to run GeoServer, set the runSpatialOption property in the 

``metacat.properties`` file (found in the source code's lib directory) to 

false before building and deploying Metacat. 

The GeoServer bundled with Metacat comes with a world-countries base layer 

and a default configuration that is already aware of Metacat's spatial cache. 

To further configure GeoServer, use its Web-based configuration utility, 

which is available at: http://your.server.com/context/geoserver.jsp 

(e.g., http://knb.ecoinformatics.org/knb/geoserver.jsp). 

Common configuration tasks include:

* Adding a Map to a Web Page or Skin

* Configuring the Size and Initial Extent of the Map

* Configuring the Layout of the HTML Mapping Interface

* Changing the Lat/Long Display to Degree-Minutes-Seconds

* Configuring the "Select Location Drop-down Menu

* Configuring the Visual Portrayal of Geospatial Data (e.g., symbology and color)

* Adding Other Spatial Datasets to the Web Map

.. figure:: images/screenshots/image053.jpg

   :align: center

   GeoServer's Web-based administrative interface.

Note: Some configurations may need to be made to the XML files as well.

Community Mabuilder, which Metacat uses as the front-end for GeoServer's WMS 

service, provides interface components or "widgets" (e.g., the map, a box zoom, 

layer list, "Select Location" drop-down menu, scale bar, lat/long coordinates, 

and a query form) that make it easy to deploy highly-functional Web mapping 

applications with minimal coding. The WMS layers are configured through a Web 

Map Context (WMC) document. This context document can be edited to customize 

the initial extent of the map, the ordering and visibility of layers and, of 

course, the source and name of the WMS layer.

Mapbuilder has three main configuration files used to customize the map 

interface (Table 5.1). If you plan to customize the map interface, you must 

use a source code distribution of Metacat. Default configurations are in::

  $METACAT/lib/style/common/spatial_templates/spatial1/

+--------------------------------+-------------+---------------------------------------------------------------------+

| Document                       | Location    | Description                                                         |

+================================+=============+=====================================================================+

| Web map context document (WMC) | context.xml | The WMC is used to customize the initial extent of the map,         |

|                                |             | the order of the map layers, and the source and name of each layer. |

+--------------------------------+-------------+---------------------------------------------------------------------+

| Mapbuilder configuration file  | context.xml | Defines the Mapbuilder widgets and their behavior                   |

+--------------------------------+-------------+---------------------------------------------------------------------+

| The Map file                   | map.html    | Loads the Mapbuilder JavaScript library and controls the            |

|                                |             | HTML layout of the widgets.                                         |

+--------------------------------+-------------+---------------------------------------------------------------------+

NOTE: By default, the first time Metacat is restarted, it generates a 

"spatial cache" containing geographic information about documents in its 

repository. This default behavior is specified in lib/metacat.properties, 

where the regenerateCacheOnRestart parameter is set to true. The information 

in the spatial cache is stored in a GIS-compatible format (the ESRI Shapefile) 

and consists of the document name and its geographic coverage. When documents 

are inserted, deleted, and updated in the Metacat repository, Metacat 

automatically syncs the spatial cache to reflect the changes. Because 

generating the cache can take a considerable amount of time (several minutes 

in the case of a few thousand documents), Metacat resets the 

regenerateCacheOnRestart property to false after the spatial cache has been 

generated. Note that if you upgrade or reinstall Metacat, the spatial cache 

will be regenerated again.

Adding a Map to a Web Page or Skin

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To add a map to a Web page, simply include the map interface using an iframe:: 

  <iframe scrolling="no" frameborder="0" width="736" height="520" 

          src="/knb/style/common/spatial_templates/spatial1/map.html">

  </iframe>

The map URL, ``/knb/style/common/spatial_templates/spatial1/map.html``, is 

the default map interface. If you plan to customize the map interface, copy 

the spatial1 directory into your skin's directory (either the default or 

customized skin directory). 

::

  cp -r style/common/spatial_templates/spatial1 /style/skins/<myskin>/spatial

You can access the customized map with the URL: ``/knb/style/skins/<myskin>/spatial/map.html`` 

Configuring the Size and Initial Extent of the Map

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Before you configure the size and initial extent of the map, make sure that you 

have copied the default spatial settings into your skin's directory (see :doc:`configuration`). 

Once the settings have been copied, you can modify the map's initial extent in 

the context settings: ``${skin.dir}/spatial/context.xml``. 

To change the map size and/or initial extent, edit the following lines::

  <Window width="720" height="360" />

  <BoundingBox SRS="EPSG:4326" minx="-180" miny="-90" maxx="180" maxy="90" />

Where ``width`` and ``height`` specify the map size in pixels, ``minx/maxx`` 

represent the range of longitudes and ``miny/maxy`` represent the range of latitudes. 

Configuring the Layout of the HTML Mapping Interface

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Before you configure the size and initial extent of the map, make sure that 

you have copied the default spatial settings into your skin's directory. 

Once the settings have been copied, you can modify the layout here: 

``${skin.dir}/spatial/map.html``.

``Map.html`` is a simple HTML file with a tabular layout. Map components are 

abstracted into "widgets", blocks with a specific id (e.g., locationsSelect 

and mainButtonBar), which can be reorganized within the table. 

To customize the map extent and appearance, modify the Web map context 

document (``context.xml``) and/or Mapbuilder's configuration file (``config.xml``). 

Both files are in the spatial directory inside the skins folder.

Changing the Lat/Long Display to Degree-Minutes-Seconds

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, the map display shows the cursor's position in decimal degrees 

(the preferred format for many GPS/GIS applications). To report coordinates as 

degrees minutes-seconds, edit the spatial configuration file:

1. If you have not already copied the default spatial settings into your skin's 

   directory, do so now

2. Open the ${skin.dir}/spatial/config.xml file.

3. Edit the CursorTrack widget so that the content is the following: 

::

  <CursorTrack id="cursorTrack">

     <mouseHandler>mainMap</mouseHandler>

     <showDMS>true</showDMS>

     <showLatLong>true</showLatLong>

  </CursorTrack>

4. Save and close the configuration file.

Configuring the "Select Location" Drop-down Menu

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Before you configure the menu items, make sure that you have copied the default 

spatial settings into your skin's directory. 

The locations that appear in the "Select Location" drop-down menu are specified 

in the ``${skin.dir}/spatial/named_locations.xml`` file. Each location is 

defined as a ``gml:featureMember``. Edit the featureMember's ``gml:name`` and 

``gml:coordinates`` fields to edit or add new locations. 

::

  <gml:featureMember>

     <locationDef>

          <gml:name>ACM Wilderness Field Station</gml:name>

          <spatialKeyword>

               <gml:location>

                    <gml:Envelope srsName="http://www.opengis.net/gml/srs/epsg.xml#4326">

                         <gml:coordinates>-91.956,47.87 -91.706,48.12</gml:coordinates>

                    </gml:Envelope>

               </gml:location>

          </spatialKeyword>

     </locationDef>

  </gml:featureMember> 

Configuring the Visual Portrayal of Geospatial Data (e.g., symbology and color)

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Geospatial data sets are styled through the use of Styled Layer Descriptors 

(SLD). The default SLDs used for the data points and data bounding boxes are in

``/lib/spatial/geoserver/data/styles/`` and are named data_points_style.sld and 

data_bounds_style.sld, respectively. 

You can find a more detailed tutorial on using SLD with GeoServer at::

  http://geoserver.org/display/GEOSDOC/SLD+Intro+Tutorial.

Adding Other Spatial Datasets to the Web Map

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you have vector GIS data sets, such as weather or topographical information, 

on your server that you'd like to include in the interactive map, you must 

first register the data set with GeoServer. After the data set has been 

registered, you can add the layer to the map. You can also add spatial layers 

that have been made publically available through WMS (There are hundreds of 

spatial data sets available. Check out wms-sites.com for good catalog). 

Instructions for adding publically available layers are included at the end 

of this section. 

To register the data set and add it to the map:

1. Point your browser to http://your.server/context/geoserver.jsp, log in to 

   GeoServer, and navigate to the "Data Stores" configuration page 

   under Config > Data > Stores. 

2. Create a new Shapefile and assign it a DataStore ID. The DataStore ID can 

   contain letters and numbers. It is just used internally, and should be 

   unique. Click New.

.. figure:: images/screenshots/image055.jpg

   :align: center

   Creating a new shapefile using GeoServers web-based administrative interface.

3. On the next screen, select the "metacat" namespace from the drop-down menu 

   and point to the GIS data file on the file system, relative to:

   ::

     {tomcat.dir}/webapps/{context}/

   The Description, if specified, is mostly used internally to provide other 

   administrators with information about the DataStore. Click Submit.

4. Navigate to the "Feature Type" configuration page under 

   Config > Data > Feature Type. Select your new data store from the 

   drop-down menu. Click New.

5. Style the layer using a style from the drop-down style menu, or click 

   "Create new SLD" to create a new Style object and corresponding SLD 

   (this option provides more control over the style). You should also define a 

   spatial reference system (SRS) number for the new layer. 

   Most lat/long data is "4326". If your data is in another projection,

   determine its spatial reference system using the help links provided. 

.. figure:: images/screenshots/image057.jpg

   :align: center

   GeoServer's FeatureType Editor. The Style and SRS settings discussed in step 5 are highlighted.

6. Click "Apply" and "Save" 

7. Try out the styled data set as a WMS layer using a URL like: 

   ::

     http://your.server/context/wms?VERSION=1.1.1&REQUEST=GetMap&SERVICE=WMS&LAYERS=metacat:newLayer&SRS=EPSG:4326&BBOX=-180,-90,180,90&WIDTH=720&HEIGHT=360&FORMAT=image/gif&STYLES=&TRANSPARENT=TRUE&UNIQUEID= 

   Where your.server/context is the name of your server and context (e.g., 

   http://knb.ecoinformatics.org/knb) and newLayer is the name of the new layer. 

   The other parameters control which part of the layer is displayed.

   If data is properly displayed, add the map to your map context document (Step 8).

8. Locate the Web map context document (usually {skin}/spatial/context.xml) and 

   open the file in a text editor.

9. Locate the Layer entry for an existing layer next to which you wish to stack 

   your layer (the first layers in the context are rendered at the bottom). 

10. Create a new Layer entry, by copying and pasting the existing entry for the 

    metacat data_points layer and editing the Layer Name and Title. The title 

    is displayed in the map legend. Note: if you'd like to use transparency, 

    leave the image format set to image/gif (IE pre-7 has trouble with PNG 

    transparency).

    ::

      <Layer queryable="0" hidden="0">

      <Server service="OGC:WMS" version="1.1.1"

      title="DatasetPoints">

        <OnlineResource xlink:type="simple" xlink:href="../../../../wms" />

      </Server>

      <Name>metacat:data_points</Name>

      <Title>Dataset Points</Title>

      <SRS>EPSG:4326</SRS>

      <FormatList>

        <Format current="1">image/gif</Format>

      </FormatList>

      </Layer>

11. Point your browser to the map interface. Your new layer should appear with 

    the existing ones.

Adding External Spatial Data Made Publically Available through WMS

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There are hundreds of sources of spatial data made publically available 

through WMS. (check out http://wms-sites.com for good catalog). To add these 

data sources to your map, locate your skin's context file 

(``${skin.dir}/spatial/context.xml``) and add a new Layer by copying and 

pasting an existing Layer and modifying as appropriate: modify the 

OnlineResourceURL, Name, Title and Style to match the WMS layer you'd like to 

use. See the mapbuilder Add WMS Tutorial for further details.

Spatial Queries

---------------

To find out which documents in the Metacat repository lie in a specified 

geographic region, query the spatial cache using Metacat's spatial_query action. 

Metacat can perform any query supported by the WFS/WMS standards.

An example of a spatial query string is::

  http://localhost/knb/metacat?action=spatial_query&xmin=-117.5&xmax=-64&ymin=3&ymax=46&skin=default

Where ``xmin``, ``xmax``, ``ymin`` and ``ymax`` represent the western, eastern, 

southern and northern bounding coordinates (the "bounding box"), respectively. 

The spatial query action returns all documents that overlap or that are 

contained inside the specified spatial coordinates. The result set is returned 

as HTML using the style of the specified skin (in this example, default).