Metacat

<style>

 h5 { margin-left: 12px; }

</style>

        <h5> <a name="wms"> Web Mapping Server </a> </h5>

   <p style="margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US">	The OpenGIS consortium has defined a standard for requesting maps, the Web Mapping Service or WMS standard. WMS servers accept a common set of parameters via http, render the spatial dataset into an appropriate image and deliver it back to the client. </p>

   <p> For Metacat, we chose to go with GeoServer, a WMS-capable application written in Java. Geoserver (and the Geotools library upon which it depends) are seamlessly integrated into the metacat servlet context. This allows all of the Geoserver/Geotools functionality to be accessible to all of metacat and allows easier deployment than if it were distributed seperately. The downside to this approach is that upgrading geoserver later becomes slightly more complicated.</span></p>

   <p style="margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US"> Geoserver comes with a default configuration that is already aware of the spatial cache and a world countries base layer. In order to configure existing data and add new data sources, geoserver comes with an web-based configuration utility. It is available at http://your.server/context/geoserver.jsp </span></p>

   <p style="margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US"> Geoserver has lots of built in functionality and can support a wide variety of vector GIS data sources. These data sources can be styled using SLDs and can be made available via open distribution standards such as WMS and WFS. For our purposes, it mainly outputs Images (via WMS) but can be used to output raw vector data in the form of GML or KML.</span></p>

   <p style="margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US"> There are several issues with geoserver tha users should be aware of. The version of Geoserver (1.4) used by Metacat does not support raster input dataset (ie satellite imagery or digital elevation models). For distributing rasters, we recommend UMN Mapserver be set up independently. Geoserver, though it offers a web configuration interface, is lacking in several key areas and you may still have to hand-edit some XML files in order to customize your WMS server. </span></p>

   <p style="margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US">	The main function of mabuilder is to act as a front-end to WMS services. The WMS layers are configured through a Web Map Context document (typically found in the skin directory under spatial/context.xml). This context document (or WMC) can define the initial extent of the map, the ordering and visibility of layers and, of course, the source and name of the WMS layer.</span></p>

   <p style="margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US">	Mapbuilder provides several interface components or widgets (map, box zooms, layer list, "select location" dropdown, scalebar, coordinates, info query) that make it easy to deploy highly-functional web mapping applications with minimal coding. There are three main configuration files you need to work with in order to customize the map interface: The context document discussed above, the mapbuilder configuration file (typically under spatial/config.xml) which defined the widgets and their behavior and finally the html file (typically spatial/map.html) which loads the mapbuilder javascript library and places the widgets in your html layout.</span></p>

   <p style="margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US">	For integration with metacat, we built a custom mapbuilder widget, the AOIMetacat Query, which allows you to click query the map, either by box or point, and call the metacat spatial_query action. </span></p>

   <p style="margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US">	The cleanest way to integrate a mapbuilder interactive map with any page in your application is to simply create an iframe element with the src pointing to a standalone map.html. </span></p>

 <h5> Initial Installation </h5>

 <p style="margin-bottom:12pt"><span lang="en-US">To install the spatial option, choose a version of metacat &gt;= 1.7.0. You'll want to ensure that </span><span style="font-style:italic" lang="en-US">runSpatialOption</span><span lang="en-US"> is set to </span><em>true</em><span lang="en-US"> in lib/metacat.properties before you build. Running the spatial option is <em> true </em> by default so, unless you explicitly set it to be false, the spatial option will install and run automatically when you install metacat.</span></p>

 <h5>How do I configure the layout of the html mapping interface?</h5>

   The layout of the map components is defined in the spatial/map.html file within the skin's directory. It is a simple tabular layout and the map components are abstracted into "widgets", blocks with a specific id, which can be reorganized within the table. For deeper customization you can modify the web map context document (spatial/context.xml) and the mapbuilder config file (spatial/config.xml).

   <h5> How can I change the lat/long display to degree-minutes-seconds ? </h5>

   <h5>How can I configure the size and initial extent of the map?</h5>

  The map's initial extent is defined in the web map context document for each skin. To change the map size and/or initial extent, edit the following lines:

<pre>

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

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

</pre>

  Where the width and height are the image size in pixels and the minx/maxx represent the range of longitudes and miny/maxy reprsent the range of latitudes.

   <h5>How do I configure the "select location" dropdown to contain different predefined locations?</h5>

 The locations data are held in a file called "named_locations.xml" in your skin's spatial directory. This defines each location as a gml:featureMember. Within each featureMember, you can edit the gml:name and gml:coordinates fields to edit or add new locations.

   <h5>Can I use a different web mapping interface?</span></h5>

<p>Certainly. Since our mapping server conforms to the WMS standard, you can develop a map interface using any WMS client application. There are many of WMS clients ranging from desktop GIS applications (ArcGIS, QGIS, JUMP, UDig) to javascript web mapping frameworks (openlayers, mapbender, mapbuilder) and anyone of them could be used to build a novel spatial application from the metacat wms.</p>

<p> There is an experimental version of OpenLayers (a tiled, google-maps-esque web interface) included with Metacat spatial. This can be accessed at http://your.server/context/style/common/spatial_templates/openlayers1/map.html. Keep in mind that this is experimental and not supported as an official interface.

   <h5>How do I configure the styling and classification of the data?</h5>

  The datasets are styled through the use of Styled Layer Descriptors (SLD). The default SLDs used for the data points and data bounding boxes are in {context}/data/styles and named <em> data_points_style.sld </em> and <em> data_bounds_style.sld </em> respectively. 

You can find more a more detailed tutorial on using SLD with geoserver at : <a href="http://docs.codehaus.org/display/GEOSDOC/SLD+Intro+Tutorial"> http://docs.codehaus.org/display/GEOSDOC/SLD+Intro+Tutorial</a>.

   <h5>What versions of tomcat are supported?</h5>

   <p>The spatial functionality has only been tested on tomcat 5. The web.xml.tomcat4 distributed with metacat is no longer supported after Metacat 1.6.0 . If you <em>need</em> to use tomcat 4, you might be able to update this file to reflect the incorporation of geoserver (see web.xml.tomcat5) though we have no intention of supporting it's use.</p>

   <h5>How do I add the map to another page or metacat skin?</h5>

The map interface is held in a seperate html document and can be easily included in any html page through the use of an iframe :

<pre>

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

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

  </iframe>

</pre>

The map URL referenced here is the default, common spatial template for use in any skin. If you plan on doing any customization of the map interface, you should copy that spatial template into your skin's directory:

<pre>

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

</pre>

and access it with the url "/knb/style/skins/myskin/spatial/map.html".

 <h5> Adding your own spatial datasets </h5>

If you have other vector GIS datasets on your server that you'd like to include in the interactive map, there are two main tasks:<ul>

<li> Registering the dataset with geoserver </li> <li> Adding the layer to the web map context </li> </ul>

<h6> Registering your dataset with geoserver </h6>

There is a <a href="http://docs.codehaus.org/display/GEOSDOC/User+Tutorial+Shapefile"> geoserver tutorial </a> which covers the precise steps of adding a new layer via the web interface. The actual process will differ slightly depending on your configuration so we'll clarify and summarize the steps below:

<ol>

 <li>Creating a datastore (ie registering the raw data)</li>

  <ul>

    <li> Point your browser to http://your.server/context/geoserver.jsp, login and navigate to the "data stores" config page.</li>

    <li> Define your new shapefile datastore and point to the shp file on the filesystem (relative to {tomcat.dir}/webapps/{context}/ ). </li> 

    <li> Use the "metacat" namespace to describe your data </li>

  </ul>

 <li> Creating the feature type (ie registering the data as a recognizable layer)</li>

   <ul> 

     <li> You must define a spatial reference system number for each layer. Most lat/long data is "4326". If your data is in another projection, you'll have to determine its SRS using the help links provided. </li>

     <li> The dropdown list of styles provides some good default choices but to get more control over the styling, you'll need to create a new Style object and corresponding SLD. </li>

   </ul>

 <li> Testing </li>

   <ul>

    <li> Make sure you "Apply" and "Save" ! </li>

    <li> Try out the featureType as a WMS layer using a URL like:<br/>

      <span style="font-family:monospace; font-size:9pt;">http://your.server/context/wms?VERSION=1.1.1&REQUEST=GetMap&SERVICE=WMS&LAYERS=metacat:<strong>newLayer</strong>&SRS=EPSG:4326&BBOX=<strong>-180,-90,180,90</strong>&WIDTH=720&HEIGHT=360&FORMAT=image/gif&STYLES=&TRANSPARENT=TRUE&UNIQUEID= </span></li>

    <li> If this displays your data properly, it's time to add it to your map context document. </li></ul>

</ol>

<h6> Adding your layer to the web map context </h6>

  <ol>

   <li> Locate the web map context document (usually {skin}/spatial/context.xml) and open in a text editor </li>

   <li> Locate the Layer entry for an existing layer next to which you want your layer stacked (the first layers in the context are rendered at the bottom). </li>

   <li> Create a new Layer entry, copying an existing entry for the metacat data_points layer to use as an example. </li>

   <li> Edit the layer Name to reflect the name of your new feature type (ie metacat:newLayer ) </li>

   <li> Edit the Title; this will be displayed in the map legend. </li>

   <li> Special note about the image format: image/gif is the only option if you want transparency (since IE pre-7 has trouble with PNG transparency). image/jpeg is a good option for base layers.

   <li> Point your browser to the map interface using this context document and your layer should show up stacked with the others </li>

  </ol>

 <h5> External WMS data sources </h5>

There are hundreds of sources of spatial data made publically available through WMS. Check out <a href="http://wms-sites.com/"> wms-sites.com </a> for good catalog. In order to add these data sources to your map, locate your skin's context document and add a Layer as appropriate. Using an existing Layer as an example, modify the OnlineResourceURL, Name, Title and Style to match the WMS layer you're after. See the mapbuilder <a href="http://communitymapbuilder.org/display/MAP/Add+WMS+Tutorial"> Add WMS Tutorial</a> for further details.

 <h5> Raster Images </h5>

 The version of geoserver currently shipping with metacat (geoserver 1.4) does not support raster images as input data sources. We suggest setting up UMN Mapserver if you aim to serve raster data as a WMS. Note that once a WMS service is set up, the process of adding it to your map context is the same regardless of what WMS software is serving it. (ahhh the beauty of open standards).

 <h5>web.xml</h5>

The process of integrating geoserver with metacat involved merging the two web.xml documents. Special care must be taken to preserve the order of loading for various components in the geoserver stack. The web.xml.tomcat5 document is commented in the relevant places to indicate its purpose.

 <h5>Upgrading geoserver</h5>

Great care has been taken not to modify geoserver so heavily as to "fork" it. Any small changes made should be submitted to the geoserver development team or maintained as patches against released versions. 

 Still, upgrading geoserver is not as seamless as one might hope. Most notably, any changes in the geoserver web.xml will have to be integrated by hand into out metacat/geoserver hybrid web.xml.tomcat5 document. In addition, geoserver distributes some unneccesary files that have been cut from the metacat version. When upgrading geoserver, make sure any old files get deleted, new files get added to cvs (if they are needed) or removed (if superfluous).