Project

General

Profile

metacat / docs / user / metacat / source / geoserver.rst @ 8265

1
Metacat's Use of Geoserver
2
==========================
3

    
4
GeoServer 2.0.2, an open source Web Mapping Service (WMS) written in Java, is 
5
bundled with Metacat and can be used to render spatial data as web-deliverable 
6
maps. Metacat uses OpenLayers (http://openlayers.org/) to provide a web-based 
7
user interface for interacting with the generated maps. You can use any 
8
WMS-compatible client (e.g., ArcGIS, QGIS, JUMP, UDig, OpenLayers, Mapbender, 
9
Map Builder). 
10

    
11
IMPORTANT: Regardless of whether you plan on using the mapping functionality 
12
you should, for security purposes, configure GeoServer so that it doesn't 
13
use the default password. For instructions, please see 
14
Geoserver Configuration.
15

    
16
.. figure:: images/screenshots/image051.jpg
17
   :align: center
18
   
19
   A map generated by Metacat's GeoServer. Points and "bounding boxes" 
20
   represent the geographic extent of datasets stored in the KNB Metacat repository.
21

    
22
GeoServer supports a wide variety of vector GIS data sources, which can be 
23
styled using Styled Layer Descriptors (SLDs) and output as images (the default) 
24
or raw vector data (GML or KML).
25

    
26
Currently, GeoServer can be used with the following limitations:
27

    
28
* GeoServer will only map documents that are publicly available. This is 
29
  because the mapping server's support for permissions control is not as 
30
  fine-grained as Metacat's.
31

    
32
Metacat developers plan to continue extending and improving Metacat's mapping 
33
capabilities. If you are interested in contributing to those efforts, or if 
34
you are interested in learning more about the architecture and future plans for 
35
the mapping software, please contact the Metacat  development 
36
team  (metacat-dev@ecoinformatics.org).
37

    
38
Installing and Configuring
39
--------------------------
40
The GeoServer webapp should be installed as a sibling of Metacat. If you do 
41
NOT wish to run GeoServer, the deployment can be skipped, but any skins that 
42
use maps will not render correctly. (NOTE: Geoserver recommends using a PermGen 
43
space setting of at least 128MB.). 
44

    
45
Metacat comes with a pre-configured data directory to be used by GeoServer. 
46
This includes a world-countries base layer and a default configuration that 
47
is already aware of Metacat's spatial cache. The Metacat configuration interface 
48
is used to configure GeoServer to use this shared data directory. To further 
49
configure GeoServer, use the Web-based configuration utility, 
50
which is available at: http://your.server.com/context/geoserver.jsp 
51
(e.g., http://knb.ecoinformatics.org/metacat/geoserver.jsp). 
52

    
53
Common configuration tasks include:
54

    
55
* Adding a Map to a Web Page or Skin
56
* Configuring the Size and Initial Extent of the Map
57
* Configuring the Layout of the HTML Mapping Interface
58
* Configuring the "Select Location Drop-down Menu
59
* Configuring the Visual Portrayal of Geospatial Data (e.g., symbology and color)
60
* Adding Other Spatial Datasets to the Web Map
61

    
62
.. figure:: images/screenshots/image053.png
63
   :align: center
64
   
65
   GeoServer's Web-based administrative interface.
66

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

    
69
OpenLayers, which Metacat uses as the front-end for GeoServer's WMS service, 
70
provides interface components or "widgets" (e.g., the map, a box zoom, layer 
71
list, "Select Location" drop-down menu, scale bar, lat/long coordinates, and 
72
a query form) that make it easy to deploy web-based mapping applications with 
73
minimal coding.
74

    
75
OpenLayers has three main configuration files used to customize the map interface.
76
Default configurations are in::
77

    
78
  $METACAT/lib/style/common/spatial/
79
  
80
+----------------------------------+---------------+-------------------------------------------------------------+
81
| Document                         | Location      | Description                                                 |
82
+==================================+===============+=============================================================+
83
| The named location file          | locations.jsp | The list of pre-defined locations (name and lat/lon bounds) |
84
+----------------------------------+---------------+-------------------------------------------------------------+
85
| Main map rendering functions     | maps.js       | Defines the map, widgets and their behavior                 |
86
+----------------------------------+---------------+-------------------------------------------------------------+
87
| The rendered map and page layout | map.jsp       | Loads the map and controls the HTML layout of the widgets.  |
88
+----------------------------------+---------------+-------------------------------------------------------------+
89

    
90
NOTE: By default, the first time Metacat is restarted, it generates a 
91
"spatial cache" containing geographic information about documents in its 
92
repository. This default behavior is specified in lib/metacat.properties, 
93
where the regenerateCacheOnRestart parameter is set to true. The information 
94
in the spatial cache is stored in a GIS-compatible format (the ESRI Shapefile) 
95
and consists of the document name and its geographic coverage. When documents 
96
are inserted, deleted, and updated in the Metacat repository, Metacat 
97
automatically syncs the spatial cache to reflect the changes. Because 
98
generating the cache can take a considerable amount of time (several minutes 
99
in the case of a few thousand documents), Metacat resets the 
100
regenerateCacheOnRestart property to false after the spatial cache has been 
101
generated. Note that if you upgrade or reinstall Metacat, the spatial cache 
102
will be regenerated again.
103

    
104
Adding a Map to a Web Page or Skin
105
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
106
To add a map to a Web page, simply include the map interface using an iframe:: 
107

    
108
  <iframe scrolling="no" frameborder="0" width="780" height="420" 
109
          src="/metacat/style/common/spatial/map.jsp">
110
  </iframe>
111

    
112
The map URL, ``/metacat/style/common/spatial/map.jsp``, is 
113
the default map interface. If you plan to customize the map interface, copy
114
the map.jsp file into your skin's directory (either the default or 
115
customized skin directory). 
116

    
117
::
118

    
119
  cp -r style/common/spatial/map.jsp /style/skins/<myskin>/spatial
120

    
121
You can access the customized map with the URL: ``/metacat/style/skins/<myskin>/spatial/map.jsp`` 
122

    
123
Configuring the Size and Initial Extent of the Map
124
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
125
Before you configure the size and initial extent of the map, make sure that you 
126
have copied the map layout page into your skin's directory (See 
127
:doc:`configuration` for directions). Once the file has been copied, you can 
128
modify the map's initial extent in: ``${skin.dir}/spatial/map.jsp``.
129

    
130
To change the map's initial extent, edit the bounding box. The default is to 
131
show the entire globe. The ``initMap()`` function should also be given the skin 
132
name so that spatial search results can be correctly styled.
133

    
134
::
135

    
136
  <script type="text/javascript">
137
      function init() {
138
         var bounds = new OpenLayers.Bounds(-180,-90,180,90); 
139
         // make the map for this skin 
140
         initMap("<%=GEOSERVER_URL%>", "<%=SERVLET_URL%>", "default", bounds);
141
      }
142
  </script>
143

    
144
The size (height/width) of the map can be controlled by the ``#map`` CSS entry 
145
included in the ``map.jsp`` page.
146

    
147
Configuring the Layout of the HTML Mapping Interface
148
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
149
The size and initial extent of the map can be edited in : ${skin.dir}/spatial/map.jsp.
150

    
151
The map.jsp is a simple container that can be included in other more complex 
152
pages if desired. It contains the map, widgets and location dropdown list.
153

    
154
Configuring the "Select Location" Drop-down Menu
155
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
156
The locations that appear in the "Select Location" drop-down menu are specified 
157
in the ``locations.jsp`` file. The locations.jsp can be copied from the common 
158
spatial template into your skin directory. Each location is defined as an 
159
HTML ``<option/>`` tag. Edit the value and label to edit or add new locations.
160

    
161
::
162

    
163
  <option value="-149.725,68.475 -149.3254,68.725"> Arctic LTER (ARC)</option>
164

    
165
Configuring the Visual Portrayal of Geospatial Data (e.g., symbology and color)
166
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
167
Geospatial data sets are styled through the use of Styled Layer Descriptors 
168
(SLD). The default SLDs used for the data points and data bounding boxes are in
169
``/lib/spatial/geoserver/data/styles/`` and are named data_points_style.sld and 
170
data_bounds_style.sld, respectively. 
171

    
172
You can find a more detailed tutorial on using SLD with GeoServer in the GeoServer documentation::
173

    
174
  http://docs.geoserver.org/
175

    
176
Adding Other Spatial Datasets to the Web Map
177
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
178
If you have vector GIS data sets, such as weather or topographical information, 
179
on your server that you'd like to include in the interactive map, you must 
180
first register the data set with GeoServer. After the data set has been 
181
registered, you can add the layer to the map. You can also add spatial layers 
182
that have been made publically available through WMS (There are hundreds of 
183
spatial data sets available. Check out wms-sites.com for good catalog). 
184
Instructions for adding publically available layers are included at the end 
185
of this section. 
186

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

    
189
1. Point your browser to ``http://your.server/geoserver``, log in to GeoServer, 
190
   and navigate to the "Data Stores" configuration page under ``Data > Stores``. 
191
2. Create a new vector data source from a Shapefile in the "metacat" workspace.
192

    
193
.. figure:: images/screenshots/image055.png
194
   :align: center
195
   
196
   Creating a new shapefile using GeoServers web-based administrative interface.
197

    
198
3. The Description, if specified, is mostly used internally to provide other 
199
   administrators with information about the DataStore. Click Submit.
200
4. Navigate to the "Layers" configuration page under Data > Layers. 
201
   Add a new Layer from your new data source.
202
5. You should also define a spatial reference system (SRS) number for the new 
203
   layer. Most lat/long data is "4326". If your data is in another projection, 
204
   determine its spatial reference system using the help links provided.
205

    
206
.. figure:: images/screenshots/image057.png
207
   :align: center
208
   
209
   GeoServer's FeatureType configuration. The SRS settings discussed in step 5 are highlighted.
210

    
211
6. Style the layer using a style from the drop-down menu on the Publishing tab, 
212
   or create a new SLD to create a new style object and corresponding SLD 
213
   (this option provides more control over the style). 
214
7. Try out the styled data set as a WMS layer using a the Layer Preview.
215

    
216
.. figure:: images/screenshots/image058.png
217
   :align: center
218
   
219
   GeoServer's Layer Preview allows you to see an OpenLayer rendering of the new layer.
220

    
221
8. Copy the default ``map.js`` file that assembles the map in OpenLayers 
222
   (``style/common/spatial/map.js``) to your skin's spatial directory.
223
9. Edit the init() method to include your new layer in the map - either as an 
224
   overlay or as a base layer.
225
10. Point your browser to the map interface. Your new layer should appear with 
226
    the existing ones.
227

    
228
Adding External Spatial Data Made Publically Available through WMS
229
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
230
There are hundreds of sources of spatial data made publically available 
231
through WMS (check out http://wms-sites.com for a good catalog). To add these 
232
data sources to your map, add the layers in your skin's ``spatial/map.js`` file.
233

    
234
Spatial Queries
235
---------------
236
To find out which documents in the Metacat repository lie in a specified 
237
geographic region, query the spatial cache using Metacat's spatial_query action. 
238
Metacat can perform any query supported by the WFS/WMS standards.
239

    
240
An example of a spatial query string is::
241

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

    
244
Where ``xmin``, ``xmax``, ``ymin`` and ``ymax`` represent the western, eastern, 
245
southern and northern bounding coordinates (the "bounding box"), respectively. 
246
The spatial query action returns all documents that overlap or that are 
247
contained inside the specified spatial coordinates. The result set is returned 
248
as HTML using the style of the specified skin (in this example, default).
249