/docs/user/spatial_option.html - Annotate - Metacat - Ecoinformatics Redmine

metacat/docs/user/spatial_option.html @ 3124

-            perry
+<!--
-            perry
+  * spatial_option.html
             perry
-            perry
+  *      Authors: Matthew Perry
   *    Copyright: 2006 Regents of the University of California and the
-            perry
+  *               National Center for Ecological Analysis and Synthesis,
   *               and the University of New Mexico.
   *  For Details: http://www.nceas.ucsb.edu/
-            perry
+  *      Created: 2006 December 29
-            perry
+  *      Version:
   *    File Info: '$ '
+  *
+  *
 -->
 <HTML>
 <HEAD>
 <TITLE>Metacat Spatial Option</TITLE>
 <link rel="stylesheet" type="text/css" href="./default.css">
-            perry
+<style>
  h5 { margin-left: 12px; }
 </style>
-            perry
+</HEAD>
 <BODY>
   <table width="100%">
     <tr>
       <td class="tablehead" colspan="2">
         <p class="label">Metacat Spatial Option</p>
       </td>
       <td class="tablehead" colspan="2" align="right">
         <a href="./properties.html">Back</a> |
         <a href="./metacattour.html">Home</a> |
         <a href="./unimplem.html">Next</a>
       </td>
     </tr>
   </table>
   <h4>Introduction</h4>
 The Metacat spatial option enables you to query and visualize the geographic coverage of metacat documents.
 This document is intended to provide a high-level overview of the Metacat spatial functionality. It is primarily a resource for users and developers who want to understand the architecture before digging into the code to extend the existing functionality.
 <P>
 Although the spatial option is included with a Metacat installation (beginning with
 Metacat version 1.7.0), it is an extention to Metacat's functionality
 that may be used optionally.
 </P>
   <h4>Outline</h4>
  <ul>
    <li> <a href="#definitions">Defintion of Terms</a> </li>
    <li> <a href="#overview"> Overview of the major components </a>
       <ul>
         <li> <a href="#spatial_harvester"> Spatial Harvester </a> </li>
         <li> <a href="#wms"> Web Mapping Service </a> </li>
         <li> <a href="#spatial_query"> Spatial Query </a> </li>
         <li> <a href="#html_client"> HTML Mapping Client</a> </li>
       </ul>
    </li>
    <li> <a href="#install">Installing and Configuring the Spatial Option</a> </li>
    <li> <a href="#adding_data">Adding Other Spatial Datasets to the Web Map</a> </li>
    <li> <a href="#dev">Developers Notes</a> </li>
    <li> <a href="#future">Future Directions</a> </li>
  </ul>
   <h4> <a name="definitions">Definitions</a></h4>
 The following table defines a number of terms that are useful in discussing
 Harvester and its features.
   <br><br>
   <table border="1">
     <tr>
       <td><b>Term</b></td>
       <td><b>Definition</b></td>
     </tr>
     <tr>
       <td>Spatial Cache</td>
       <td>
           A cached version of the metacat documents representing their geographic coverages in a GIS-compatible data format; the ESRI Shapefile.
       </td>
     </tr>
     <tr>
       <td>Web Mapping Service (WMS)</td>
       <td>
          A standard interface specification for requesting spatial data as a web-deliverable map image. 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. The <a href="http://www.opengeospatial.org/standards/wms">WMS spec</a> was developed by the <a href="http://www.opengeospatial.org/">Open Geospatial Consortium</a>.
     </tr>
     <tr>
       <td>Bounding Box (BBOX)</td>
       <td>
           A Bounding Box is two sets of geographic coordinates representing the full geographic extent of an entity; the minimum lat/long (the lower-left) and the maximum lat/long (the upper-right).
       </td>
     </tr>
     <tr>
       <td>Spatial Dataset</td>
       <td>
         A collection of <em>spatial features</em> in a common datastore.
       </td>
     </tr>
     <tr>
       <td>Spatial Features</td>
       <td>
         Analagous to a "row" in a tabular dataset, a feature is an entity comprised of both tabular attributes and a <em>spatial geometry</em>.
       </td>
     </tr>
     <tr>
       <td>Spatial Geometry</td>
       <td>
         The geometry is a vector representation of an entities' geographic location. This can be a point (a single vertex), line (a series of vertices) or polygon (a series of vertices forming a closed area).
       </td>
     </tr>
     <tr>
       <td>Multi-Geometry</td>
       <td>
        A <em> Spatial geometry </em> represented by one or more geometry primitives (points,lines and polygons). For example a single species census (the <em> spatial feature </em>) might have mutltiple sample sites and could be represented as a multi-point geometry.
       </td>
     </tr>
-            perry
+    <tr>
       <td>Styled Layer Descriptor (SLD)</td>
       <td>
        Styled Layer Descriptors are an OGC standard for defining the filtering, classification and styling of datasets. They are essentially the configuration file which describes how to convert your raw spatial dataset into a cartographic product.
       </td>
     </tr>
     <tr>
       <td>Web Map Context (WMC)</td>
       <td>
        Web Map Context documents are an OGC standard for combining various WMS layers into a coherent map. WMC describes which wms servers and layers comprise the map, the layer order, the initial map extent, the requested image formats, etc. This is used by the HTML web map client to construct the interactive map.
       </td>
     </tr>
-            perry
+  </table>
   <h4><a name="overview">Overview Of the Major Components<a/></h4>
         <h5> <a name="spatial_harvester"> Spatial Harvester </a> </h5>
    <p style="margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US">	The Spatial Harvester component syncs the metacat database with the spatial cache (an ESRI shapefile which contains the geographic coverages of the documents). </span></p>
    <p style="margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US">	The Spatial Harvester is implemented entirely in Java using the Geotools library which allows manipulation of spatial datasets. In rough terms, a spatial dataset is a collection of Features which are comprised of a geometry (i.e. the geographic coverage) and associated attributes (i.e. the document's title).</span></p>
    <p dir="ltr" style="text-align:left;margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US">	There are a number of Java classes which, collectively, make up the spatial harvester functionality. They are found in the </span><span style="font-style:italic" lang="en-US">edu.ucsb.nceas.metacat.spatial</span><span lang="en-US"> package:</span></p>
    <ul>
     <li style="margin-bottom:12pt"><span lang="en-US">&nbsp;</span><span style="font-weight:bold" lang="en-US">SpatialDataset</span><span lang="en-US"> : Provides read/write access to the spatial cache.</span></li>
     <li style="margin-bottom:12pt"><span lang="en-US">&nbsp;</span><span style="font-weight:bold" lang="en-US">SpatialDocument</span><span lang="en-US"> : Represents the geographic coverage of a document as a Geotools Feature. </span></li>
     <li style="margin-bottom:12pt"><span lang="en-US">&nbsp;</span><span style="font-weight:bold" lang="en-US">SpatialFeatureSchema</span><span lang="en-US"> : A class of static memebers defining the properties of the spatial cache (location on the file system, attribute and geometry schemas, etc.)</span></li>
     <li style="margin-bottom:12pt"><span lang="en-US">&nbsp;</span><span style="font-weight:bold" lang="en-US">SpatialHarvester</span><span lang="en-US"> : The high-level interface for manipulating the spatial cache and initiating the harvesting process.</span>    </li>
    </ul>
    <p style="margin-bottom:12pt;margin-left:0pt;text-indent:0in"></p>
    <p style="margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US">	The spatial cache currently represents the geographic coverage of XML documents based on a bounding box. The four bounding coordinates (either latitudes or longitudes) can be specified in the metacat.properties file by their xpaths. For example, the geographic coverage of EML documents is defined as:</span></p>
 <pre>
 westBoundingCoordinatePath=geographicCoverage/boundingCoordinates/westBoundingCoordinate
 eastBoundingCoordinatePath=geographicCoverage/boundingCoordinates/eastBoundingCoordinate
 southBoundingCoordinatePath=geographicCoverage/boundingCoordinates/southBoundingCoordinate
 northBoundingCoordinatePath=geographicCoverage/boundingCoordinates/northBoundingCoordinate
 </pre>
    <p dir="ltr" style="text-align:left;margin-bottom:12pt;margin-left:0.1250in;text-indent:0in"></p>
    <p dir="ltr" style="text-align:left;margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US">	&nbsp;It is important to note that, at the moment, only one set of xpaths are defined in metacat.properties meaning only documents of the chosen schema can be accessed by the spatial harvester. Also note that, for performance reasons, the xpaths to the bounding coordinates must also appear in your indexPath (defined in build.properties).</span></p>
    <p dir="ltr" style="text-align:left;margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US">	The bounding coordinates are spatially cached in two ways: t</span><span lang="en-US">he centroid(s) of the bounding box(s) and the actual bounding box(es). These are stored as two seperate shapefiles with multi-point and multi-polygon geometry types respectively. By default, </span><span style="font-size:8pt;font-family:'Courier New'" lang="en-US">${tomcat_webapps_directory}/${context}/data/metacat_shps/</span><span style="font-size:8pt;font-family:'Courier New'" lang="en-US">data_points.shp</span><span lang="en-US"> is the storage location of the point cache while </span><span style="font-size:8pt;font-family:'Courier New'" lang="en-US">data_bounds.shp</span><span lang="en-US"> represents the polygon cache. </span></p>
    <p dir="ltr" style="text-align:left;margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US">	The bounding polygon is not relevant to every document as bounding coordinates are allowed to be of zero-area (ie west = = east and north = = south). In this case they are represented only as a point. In cases where no bounding coordinates are defined, the document is not represented at all in the spatial cache. Note that special care has been taken to account for cases where the bounding box crosses the international dateline or polar regions (at which point Cartesian calculations are invalid).</span></p>
    <p dir="ltr" style="text-align:left;margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US">	Because documents may have more than one geographic coverage, it is necessary to define the two spatial caches as </span><span style="font-style:italic" lang="en-US">multi</span><span lang="en-US">-point and </span><span style="font-style:italic" lang="en-US">multi</span><span lang="en-US">-polygon geometry types. This means that each feature's geometry field can contain a collection of one </span><span style="font-style:italic" lang="en-US">or more </span><span lang="en-US">primitive geometries.</span></p>
    <p style="margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US">	&nbsp;With the spatial option properly installed, the default metacat.properties setting is to set </span><span style="font-style:italic" lang="en-US">regenerateCacheOnRestart=true.</span><span lang="en-US"> This is very useful the first time you install metacat since it will generate the spatial cache from scratch when your servlet container is restarted. Depending on how many documents you have in your metacat database, this can take a considerable amount of time; several minutes in the case of a few thousand documents. For this reason, Metacat sets this property to <em>false</em> after the spatial cache has been generated the first time. This prevents the regeneration of the spatial cache every time you restart your servlet container. Note that if you upgrade or reinstall metacat, the spatial cache will be regenerated again.  </span></p>
    <p style="margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US">	Once the spatial cache has been generated, the Metacat servlet will keep the spatial cache in sync with the metacat database by triggering the spatial harvester on every insert, update or delete. This does not regenerate the whole spatial cache, instead simply updating features in the cache as needed. It is fairly quick and should not add more than 1/2 second to any given transaction. As mentioned earlier, all high-level interactions with the spatial cache are handled through the SpatialHarvester class. </span></p>
    <ul>
     <li style="margin-bottom:12pt"><span lang="en-US">	W</span><span lang="en-US">hen a document is deleted, the SpatialHarvester.addToDeleteQue() method is called directly from the Metacat Servlet. </span></li>
     <li style="margin-bottom:12pt"><span lang="en-US">	Inserts and updates are handled during the indexing process; after BuildIndex for a document has completed successfully (see </span><span style="font-style:italic" lang="en-US">DocumentImpl.java </span><span lang="en-US">) the SpatialHarvester.addToUpdateQue() method is invoked. The document is purged from the spatial cache (if updating) and the new document (or document revision) is added.</span>    </li>
    </ul>
    <p dir="ltr" style="text-align:left;margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US">	There is one very important note about document authentication. While metacat provides very fine-grained permissions control at the document level, the Web Mapping Server component does not. For this reason, only documents that are publicly readable (i.e. documents which match the following SQL query : </span><span style="font-size:9pt;font-family:'Courier New'" lang="en-US">select distinct docid from xml_access where principal_name = 'public' and perm_type = 'allow')</span><span lang="en-US">will be added to the spatial cache. </span><span lang="en-US">In the Future Directions section of this document, the potential for adding feature-level permissions to the WMS server are discussed.</span></p>
-            perry
+        <h5> <a name="wms"> Web Mapping Server </a> </h5>
             perry
    <p style="margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US">	The primary function of the Web Mapping Server component is to render the spatial cache as a web-deliverable map image. It is also responsible for rendering other geographic data to provide base maps or other auxillary map layers.</span></p>
-            perry
+   <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>
             perry
         <h5> <a name="spatial_query"> Spatial Query </a> </h5>
    <p style="margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US">	Displaying the spatial cache as a map is important but users also need to query the spatial cache in order to answer the question "What documents lie in this geographic region?". The functionality is invoked through the metacat servlet itself; there is a </span><span style="font-style:italic" lang="en-US">spatial_query </span><span lang="en-US">action for this purpose. An example spatial query would be:</span></p>
    <p dir="ltr" style="text-align:left;margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span style="font-size:8pt;font-family:'Courier New'" lang="en-US">http://localhost/knb/metacat?action=spatial_query&amp;xmin=-117.5&amp;xmax=-64&amp;ymin=3&amp;ymax=46&amp;skin=default</span></p>
    <p style="margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US">Where xmin, xmax, ymin and ymax represent the west, east, south and northern bounding coordinates respectively. This will return an html document listing (in the style of the specified skin) all documents whose geographic coverage intersect the given bounding box.</span></p>
    <p style="margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US">	The core functionality of the spatial query mechanism is found in the </span><span style="font-style:italic" lang="en-US">edu.ucsb.nceas.metacat.spatial.SpatialQuery</span><span lang="en-US"> class and, like the spatial harvester, relies heavily on the Geotools library. This class has a single method,</span><span style="font-style:italic" lang="en-US"> filterByBbox()</span><span lang="en-US">, which compares the bounding box to both the point and polygon cache. For each shapefile, the process requires two steps: First, filter the spatial cache for features whose bounding box overlaps the specified bounding coordinates; Second, iterate through the remaining features and perform an an actual geometric intersection. The second step, though more costly than comparing the bbox, is necessary because the feature's geometry may be a multi-geometry whose bounding box is large but whose component primitive geometries are scattered over that area. The end result is a vector of docids matching the spatial query.</span></p>
    <p style="margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US">	This docid list is then sent to DBQuery. Using a special constructor that takes a vector of docids, the DBQuery class is able to use the Docid override mechanism to perform an optimized query (for cases where the list of docids is already known).</span></p>
         <h5> <a name="html_client"> HTML Mapping Client</a> </h5>
    <p style="margin-bottom:12pt;margin-left:0pt;text-indent:0in"><span lang="en-US">	In order to provide a web-based user interface to the WMS and the spatial query functionality, Metacat relies on Community Mapbuilder. Mapbuilder is a pure HTML/javascript application which uses AJAX and XSLT on the client side to create a desktop-GIS-like environment for interacting with geographic data through a web browser.</span></p>
-            perry
+   <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>
             perry
 <h4> <a name="install">Installing and Configuring the Spatial Option</a> </h4>
-            perry
+ <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>
             perry
-            perry
+ <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>
-            perry
+      By default, the map display shows the cursors position in decimal degrees since this is the prefered format for many GPS/GIS applications. However, there may be cases where you need to report coordinates as degrees minutes-seconds. To do so, go into you skins spatial configuration file (usually ${skin.dir}/spatial/config.xml) and edit the CursorTrack widget as shown below:
        <pre>
         &lt;CursorTrack id="cursorTrack"&gt;
           &lt;mouseHandler&gt;mainMap&lt;/mouseHandler&gt;
           &lt;showDMS&gt;true&lt;/showDMS&gt;
           &lt;showLatLong&gt;true&lt;/showLatLong&gt;
         &lt;/CursorTrack&gt;
        </pre>
-            perry
+   <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>
     &lt;Window width="720" height="360" /&gt;
     &lt;BoundingBox SRS="EPSG:4326" minx="-180" miny="-90" maxx="180" maxy="90" /&gt;
 </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.
             perry
-            perry
+   <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>
   &lt;iframe scrolling="no" frameborder="0" width="736" height="520"
              src="/knb/style/common/spatial_templates/spatial1/map.html"&gt;
   &lt;/iframe&gt;
 </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".
             perry
 <h4> <a name="adding_data">Adding Other Spatial Datasets to the Web Map</a> </h4>
-            perry
+ <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>
             perry
-            perry
+<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>
             perry
-            perry
+ <h5> External WMS data sources </h5>
             perry
-            perry
+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).
-            perry
+<h4> <a name="dev">Developers Notes</a></h4>
-            perry
+ <h5>web.xml</h5>
             perry
-            perry
+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.
             perry
-            perry
+ <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.
             perry
-            perry
+ 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).
-            perry
+<h4> <a name="future">Future Directions</a> </h4>
    <h5>Automatically handle spatial datasets</h5>
    <p style="margin-bottom:12pt">When users put spatial data into the Morpho system, it would be nice if we could automatically pull all the avialable metadata from the spatial dataset itself. </p>
    <p style="margin-bottom:12pt">On the metacat side, it might be worth trying to auto-detect spatial datasets and add them to the WMS service do that they could be displayed along with the metadata coverages. This is tricky since the styling of spatial data is intentionally seperated from the data itself; we'd have to have some sort of easy way to prompt the user for the classification and styling info and construct the appropriate SLDs. </p>
    <p style="margin-bottom:12pt">It's worth noting that, currently, one could do this manually. There is nothing, aside from editing a few configuration files, to prevent any Geotools-supported dataset from being displayed through the WMS map interface.</p>
    <p style="margin-bottom:12pt">For vector datasets, it would be possible to store the data directly in the database itself (This is a logical extension of the future work to put tabular data directly in a relational database). Postgresql has the PostGIS extensions to handle this so we would have to require postgresql if we went this route.</p>
    <h5>WMS bypass</h5>
    <p style="margin-bottom:12pt"> Filter which spatial cache features are displayed by access contraints, skin constraints and the current non-spatial query set. This would involve intercepting incoming WMS requests and appending a styled layer descriptor (SLD) with an OGC filter to prevent/allow certain docids. </p>
    <h5>SLD factory</h5>
-            perry
+   <p style="margin-bottom:12pt">Closely related to the WMS bypass implemetation, the SLD factory would be in charge of constructing the filter based on on the contraints mentioned above. In other words, it would construct a document specifying which docids were to appear in the map. Because it would have to generate this list of docids on every wms request, performance is a big concern. Likely we'll need to cache docid lists as session variables.</p>
             perry
-            perry
+  <p> There is currently a stub implementation of the SLD Factory servlet in <em>src/edu/ucsb/nceas/metacat/spatial/SldFactory.java</em>. It is functional except that it doesn't generate a dynamic list of allowable docids.  Assuming we can modify the SldFactory servlet to quickly generate a list of allowable docids based on stored session variables, applying this SLD to a WMS request is fairly easy and simply requires appending the URL of the sldfactory as an "SLD" parameter to the WMS GetMap request: </p>
    <pre> http://indus/knb/wms?REQUEST=GetMap&SERVICE=WMS....&SLD=http://indus.msi.ucsb.edu/knb/sldfactory?originalSld=data_points_style.sld</pre>
 <p> where data_points_style.sld is the original style document existing in <em>{context}/data/styles/</em>. The sldfactory servlet will construct a list of allowable docids, append those to the original sld as an ogc filter, an return a (modified) SLD document. There are two possibilities for implementing this:</p>
    <ol>
    <li>
      Mapbuilder (the WMS client in charge of constructing WMS request) can be told to append this SLD parameter through the use of the WMC config document. This would work for the skins but, alone, would not ensure that every WMS request were filtered since other clients could simply ommit the SLD parameter.
    </li>
    <li>
      An alternative, one that would ensure that EVERY wms request was filtered, would be to handle it all server side with a WMS bypass.
    </li>
    </ol>
-            perry
+   <h5>Map configuration interface </h5>
    <p style="margin-bottom:12pt">Geoserver currently offers a nice web-based configuration but it is lacking a few key features and may be difficult for a novice GIS user. We may want to reinvent a custom geoserver configuration interface to</p>
    <ul>
     <li style="margin-bottom:12pt"><span lang="en-US">	D</span>efine the available datasets (ie editing the geoserver xml config files)</li>
     <li style="margin-bottom:12pt"><span lang="en-US">	Define</span> classification and styling (ie editing the SLDs)</li>
     <li style="margin-bottom:12pt"><span lang="en-US">	Define which layers get displayed in which map (ie editing the Mapbuilder WMCs)</span></li>
     <li style="margin-bottom:12pt"><span lang="en-US">	Picking a layout ( from a list of pre-configure mapbuilder templates)</span>    </li>
    </ul>
    <p style="margin-bottom:12pt;margin-left:0pt;text-indent:0in"> Ideally we could pull as much information as possible from the metadata and make the UI very intuitive. This does bring up issues of web-based admin access constraints and developing a subsytem to handle who has edit access to the map configuration.</p>
-            perry
+   <table> <tr>
       <td align="right">
         <a href="./properties.html">Back</a> |
         <a href="./metacattour.html">Home</a> |
         <a href="./unimplem.html">Next</a>
       </td>
    </tr> </table>
             perry
 </BODY>
 </HTML>

Project

General

Profile

Metacat