[OpenLayers-Dev] new doc for OpenLayers

Jacolin yjacolin at free.fr
Wed Dec 31 09:34:08 EST 2008


Hi dev list,

Here is a rst file for an introduction about OpenLayers. All informations may 
not be correct, nor my english.

As you will see, this document could be a duplicate document with the  
spherical mercator doc ... but less complete.

I would like to know if you (and the community) are interesting to get more 
document from me, and if others people are working on such document and which 
topic (in order to avoid other duplicate works).

Best regards,

Y.
-------------- next part --------------
============
Introduction
============

.. contents::

Presentation
-------------
OpenLayers is a library written in JavaScript which allow you to develop easily and quiclky an indepandant map server client interface. It proposes by default loading data from OGC standards like WMS, WFS, from commercial Map Base Layer like Google, Yahoo, Virtual Earth, from various data format KML, GeoRSS, GML, etc. Among features available, you'll find zooming, panning, displaing data, layer tree, tiled layers and cache client side. TileCache allow you to cache server sider and will be presented later in this document.

OpenLayers is developed by an increasingly large community, and you can contact them via a mailing list or IRC. OpenLayers is a project hosted by OSGeo. The official site is located at http://openlayers.org.

You'll find a short documentation in English here: http://openlayers.org/doc/, the API doc is available here: http://dev.openlayers.org/docs/files/OpenLayers-js. html and there are a lot of examples here: http://openlayers.org/dev/doc/examples.html

*Objectifs of this chapter:*
* Know more about map and layer object ;
* Create your first map ;
* Add your own layer using a commercial base layer.

Installation
------------

There are two ways to use OpenLayers on its Web site. The first is to call the library by the JavaScript <script> tag:

.. code-block:: javascript

  <script src='http://openlayers.org/api/OpenLayers.js'></script>

Of course you can download the local library from the download page: http://trac.openlayers.org/wiki/HowToDownload

There are two presentations from the library. The first, known as sources of OpenLayers, consists of a file openlayers.js which calls all other files included in the tree of the library. The second version, a version built, but not in binary format, consists of building all the files into a single compressed file. The file size is small, but code is unreadable: any unnecessary space is removed during compression. The call for the library is made by the same way, but with reference to the page where it is called:

.. code-block:: javascript

  <script src='api/OpenLayers.js'></script>

You are now ready to use the library.

My first map
------------
The OpenLayers API uses mainly two objects this is not exactly true, but enougth for beginning): the //map// and //layers// objects. A Map object stores information on the map, its size, projection units, its scope, and so on. In a map, the data is displayed in the form of layers (//layers//). A //layers// object is a data source that defines how OpenLayers must recover the data and display them.


Setting
+++++++

Building an OpenLayers interface requires the addition of HTML code in your page. You can put a map where you want. Here is a simple example for creating a map with OpenLayers.

.. code-block:: html

  <html>
  <head>
    <title>OpenLayers Example</title>
      <script
      src="http://openlayers.org/api/OpenLayers.js"></script>
      </head>
      <body>
        <div style="width:100%; height:100%" id="map"></div>
  </body>
  </html>

To initialize a map in this interface, you must write a few lines of JavaScript code in the header of the page or in a map.js file for example. The file or the code should be placed after the insertion of the library OpenLayers. Generally, it creates a ''init()'' function which, put in the <body> tag initialize the map after loading the page.

.. code-block:: javascript

  var map;
  function init() {
    //creating map object
    map = new OpenLayers.Map('map');
    //creating a WMS layer
    var wms = new OpenLayers.Layer.WMS(
       "http://labs.metacarta.com/wms/vmap0", 
       {'layers':'basic'}
    );
    //adding wms layer to the map object
    map.addLayer(wms);
  }


Here is a full example:

.. code-block:: html

<html>
<head>
  <title>OpenLayers Example</title>
    <script src="http://openlayers.org/api/OpenLayers.js"></script>
    </head>
    <body>
      <div style="width:100%; height:100%" id="map"></div>
      <script defer="defer" type="text/javascript">
        var map = new OpenLayers.Map('map');
        var wms = new OpenLayers.Layer.WMS( "OpenLayers WMS", 
            "http://labs.metacarta.com/wms/vmap0", {layers: 'basic'} );
        map.addLayer(wms);
        map.zoomToMaxExtent();
      </script>

</body>
</html>


<html>
<script src="http://openlayers.org/api/OpenLayers.js"></script>
<div style="width:400px; height:200px" id="map"></div>
<script defer="defer" type="text/javascript">
        var map = new OpenLayers.Map('map');
        var wms = new OpenLayers.Layer.WMS( "OpenLayers WMS", 
            "http://labs.metacarta.com/wms/vmap0", {layers: 'basic'} );
        map.addLayer(wms);
        map.zoomToMaxExtent();
</script>
</html>

Add Google Maps Layers
++++++++++++++++++++++

Google uses a distorted projection which implies that others layers are not always overlaid correctly. Google uses a Spherical Mercator projection assuming that the earth is spherical (which is incorrect). Following this, for a large zoom a shift appears between the Google map and your data. You can reproject your data in another projections (see later), or define the spherial projection within the parameters of the map and set up a parameter in the Commercial base layer options. Here is the way to enable this in your map, first define your map options by using the following:

.. code-block:: javascript

            var options = {
                projection: "EPSG:900913",
                units: "m",
                maxResolution: 156543.0339,
                maxExtent: new OpenLayers.Bounds(-20037508.34, -20037508.34,
                                                 20037508.34, 20037508.34)
            };


Projection definition for proj4 is following:

.. code-block:: bash

   +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0
   +k=1.0 +units=m +nadgrids=@null +no_defs

More information are available at [[http://proj.maptools.org/faq.html#sphere_as_wgs84|this page]]. For GeoServer:

.. code-block:: bash
     900913=PROJCS["WGS84 / Simple Mercator", GEOGCS["WGS 84",
     DATUM["WGS_1984", SPHEROID["WGS_1984", 6378137.0, 298.257223563]], 
     PRIMEM["Greenwich", 0.0], UNIT["degree", 0.017453292519943295], 
     AXIS["Longitude", EAST], AXIS["Latitude", NORTH]],
     PROJECTION["Mercator_1SP_Google"], 
     PARAMETER["latitude_of_origin", 0.0], PARAMETER["central_meridian", 0.0], 
     PARAMETER["scale_factor", 1.0], PARAMETER["false_easting", 0.0], 
     PARAMETER["false_northing", 0.0], UNIT["m", 1.0], AXIS["x", EAST],
     AXIS["y", NORTH], AUTHORITY["EPSG","900913"]]

The GeoServer release greater or equal to 1.5.4 doesn't need to add the projection definition to the configuration, already included in the configuration file.

Go back to OpenLayers, to add a Google base layer you have to add a ''layer'' object to your ''map'' object with the following method:

.. code-block:: javascript

new OpenLayers.Layer.Google(LayerName, options);


''options'' parameter is an array of options to be sent to the method. Available options are (read the OpenLayers API for OpenLayers.Layer.Google to get more information):
  * ''type'' : type of the commercial base layer, google here (normal, satellite, mixte) ;
  * ''sphericalMercator'' : is the projection is sphericalMercator? Set value to ''true''.

For the ''type'' parameter, choose one between:
    * G_NORMAL_MAP
    * G_SATELLITE_MAP
    * G_HYBRID_MAP

You have three constants that you can modify:
  * ''MIN_ZOOM_LEVEL'' : default value: 0 ;
  * ''MAX_ZOOM_LEVEL'' : default value: 19 ;
  * ''RESOLUTIONS''

For example:

.. code-block:: javascript

  var google = new OpenLayers.Layer.Google(
                 "Google Streets",
                 {type: G_NORMAL_MAP, 'sphericalMercator': true}
  );


.. important::

If you enable several type of Google layer (hybrid, default, satellite, for example), add your layers with the ''addlayers()'' method or you can have a shift between each Google baselayer. Example: ''map.addLayers ([google, hybrid, satellite]);''


If you wish to overlay a GML layer (or other) with a commecial baselayer (like Google), you *must* use the option '' 'sphericalMercator': true'', moreover you have to reproject your data in the correct projection, like this:

.. code-block:: bash

  ogr2ogr -f "ESRI Shapefile" -t_srs "+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0 +k=1.0 +units=m +nadgrids=@null 
  +no_defs" -s_srs "EPSG:4326" Mono2006_2.shp Mono2006_region.shp

If you are using OGR release greater or equal to 1.5.0, use the 'EPSG:900913' code directly to reproject your data.

Finally, for PostGIS this can be useful:

.. code-block:: sql

INSERT INTO spatial_ref_sys (srid,auth_name,auth_srid,srtext,proj4text) VALUES
(900913,'EPSG',900913,'PROJCS["Google Mercator", GEOGCS["WGS 84",DATUM["World Geodetic System 1984", SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]],AUTHORITY["EPSG","6326"]],PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], UNIT["degree", 0.017453292519943295], AXIS["Geodetic latitude", NORTH], AXIS["Geodetic longitude", EAST], AUTHORITY["EPSG","4326"]], PROJECTION["Mercator (1SP)", AUTHORITY["EPSG","9804"]], PARAMETER["semi_major", 6378137.0], PARAMETER["semi_minor", 6378137.0], PARAMETER["latitude_of_origin", 0.0], PARAMETER["central_meridian", 0.0], PARAMETER["scale_factor", 1.0], PARAMETER["false_easting", 0.0], PARAMETER["false_northing", 0.0], UNIT["m", 1.0], AXIS["Easting", EAST], AXIS["Northing", NORTH], AUTHORITY["EPSG","900913"]]','+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0 +k=1.0 +units=m +nadgrids=@null +no_defs');


*Get more information:*
* spherical_mercator.rst
* http://www.nabble.com/sphericalMercator-tf4625750.html#a13209474
* http://dev.openlayers.org/docs/files/OpenLayers/Layer/SphericalMercator-js.html
* http://trac.osgeo.org/gdal/ticket/1868: adding EPSG:900913 code to your EPSG file.

----
 --- //[[yjacolin at free.fr|Yves Jacolin]] 2008/07/17 21:45//


More information about the Dev mailing list