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:: 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//spatial You can access the customized map with the URL: ``/knb/style/skins//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:: 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: :: mainMap true true 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. :: ACM Wilderness Field Station -91.956,47.87 -91.706,48.12 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). :: 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).