[mapserver-commits] r10766 - trunk/docs/en/output

svn at osgeo.org svn at osgeo.org
Fri Nov 26 16:03:48 EST 2010


Author: assefa
Date: 2010-11-26 13:03:48 -0800 (Fri, 26 Nov 2010)
New Revision: 10766

Added:
   trunk/docs/en/output/kml_output.txt
Log:
kml documentation

Added: trunk/docs/en/output/kml_output.txt
===================================================================
--- trunk/docs/en/output/kml_output.txt	                        (rev 0)
+++ trunk/docs/en/output/kml_output.txt	2010-11-26 21:03:48 UTC (rev 10766)
@@ -0,0 +1,317 @@
+.. _kml_output:
+
+======================================================================
+Kml Output
+======================================================================
+
+:Last Updated: 2010/11/26
+:Authors: Dvaid Kana (david.kana at gmail.com)
+:Authors: Thomas.Bonfort (thomas.bonfort at gmail.com)
+:Authors: Yewondwossen Assefa (yassefa at dmsolutions.ca)
+:Authors: Michael Smith (michael.smith at usace.army.mil)
+:Version: MapServer 6.0
+:Id: $
+
+Introduction
+-------------------------------------------------------------------------------
+
+This purpose of this docuement is to describethe KML/KMZ output support in 
+MapServer 6.0.
+
+The main goal of the KML driver is to generate KML output used mainly by Google 
+Earth application.
+
+
+General Functionnality
+-------------------------------------------------------------------------------
+
+Kml support is provided by using a kml or kmz  image type in the map file. Output 
+can then be generated using MapServer cgi (example mode=map) or through a WMS request.
+
+
+
+Output format
+-------------------------------------------------------------------------------
+
+The default name of the output format is kml or kmz, and this name can be used to set 
+the imagetype parameter in the map file.
+
+The format can also be defined in the map file:
+
+::
+
+  OUTPUTFORMAT
+    NAME kml
+    DRIVER "KML"
+    MIMETYPE "application/vnd.google-earth.kml+xml"
+    IMAGEMODE RGB
+    EXTENSION "kml"    
+    FORMATOPTION 'ATTACHMENT=gmap75.kml'  #name of kml file returned
+  END
+
+  OUTPUTFORMAT
+    NAME kmz
+    DRIVER "KMZ"
+    MIMETYPE "application/vnd.google-earth.kmz"
+    IMAGEMODE RGB
+    EXTENSION "kmz"    
+    FORMATOPTION 'ATTACHMENT=gmap75.kmz'  #name of kmz file returned
+  END
+
+
+Build
+-------------------------------------------------------------------------------
+
+- On windows: there is a flag KML in nmake.opt
+- On Linux: --with-kml
+- AGG driver is necessary for the kml driver
+- To be able to get kmz support, MapServer needs to be build aginst GDAL 1.8
+
+
+Map
+-------------------------------------------------------------------------------
+
+In terms for Kml object, the MapServer KML output will produce a <Document> element to include all the layers that are part of the MapServer map file. Features supported for the Document are:
+
+
++------------------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Document element | Supported | MapServer equivalence/Notes                                                                                                                                                                                                                                                                                                                                      |
++==================+===========+==================================================================================================================================================================================================================================================================================================================================================================+
+| name             | Yes       | Name in the map file                                                                                                                                                                                                                                                                                                                                             |
++------------------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| visibility       | No        | Can be supported if needed. Default is 1                                                                                                                                                                                                                                                                                                                         |
++------------------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| open             | No        | Can be supported if needed. Default is 0                                                                                                                                                                                                                                                                                                                         |
++------------------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| address          | No        | Could be supported for example using ows_address if available                                                                                                                                                                                                                                                                                                    |
++------------------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| AdressDetails    | No        |                                                                                                                                                                                                                                                                                                                                                                  |
++------------------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| phoneNumber      | No        | Could be supported using ows_contactvoicetelephone is available                                                                                                                                                                                                                                                                                                  |
++------------------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Snippet          | No        |                                                                                                                                                                                                                                                                                                                                                                  |
++------------------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| description      | No        |                                                                                                                                                                                                                                                                                                                                                                  |
++------------------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| AbstractView     | No        |                                                                                                                                                                                                                                                                                                                                                                  |
++------------------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| TimePrimitive    | No        |                                                                                                                                                                                                                                                                                                                                                                  |
++------------------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| styleURL         | No        |                                                                                                                                                                                                                                                                                                                                                                  |
++------------------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| StyleSelector    | Yes       | Style element will be supported. All different styles from the layers will be stored here and referenced from the folders using a styleUrl.In addition to the Styles related to features, there is a ListStyle element added at the document level. This allows to control the way folders are presented.See Layers section (styleUrl) setting for more details. |
++------------------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Region           | No        |                                                                                                                                                                                                                                                                                                                                                                  |
++------------------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Metadata         | No        |                                                                                                                                                                                                                                                                                                                                                                  |
++------------------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ExtendedData     | No        |                                                                                                                                                                                                                                                                                                                                                                  |
++------------------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+
+Layers
+-------------------------------------------------------------------------------
+
+Each layer of the MapServer map file will be inside a Kml <Folder> element.  
+Supported Folder elements are:
+
++-------------------------------------------------------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Folder element                                              | Supported | MapServer equivalence/Notes                                                                                                                                                            |
++=============================================================+===========+========================================================================================================================================================================================+
+| name                                                        | Yes       | Name of the layer. If not available the name will be Layer concatenated with the layer's index (Layer1)                                                                                |
++-------------------------------------------------------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| visibility                                                  | Yes       | Always set to 1                                                                                                                                                                        |
++-------------------------------------------------------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| open                                                        | No        | Default is 0                                                                                                                                                                           |
++-------------------------------------------------------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| atom:authoratom:linkaddressAddressDetailsphoneNumberSnippet | No        |                                                                                                                                                                                        |
++-------------------------------------------------------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| description                                                 | No        | Could be supported using ows_description                                                                                                                                               |
++-------------------------------------------------------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| AbstarctView                                                | No        |                                                                                                                                                                                        |
++-------------------------------------------------------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| TimePrimitive                                               | No        |                                                                                                                                                                                        |
++-------------------------------------------------------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| styleUrl                                                    | Yes       | The user  can use the kml_folder_display layer or map level metedata to choose a setting. Possible values are  'check' (default), 'radioFolder', 'checkOffOnly', 'checkHideChildren'.  |
++-------------------------------------------------------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| RegionMetadataExtendedData                                  | No        |                                                                                                                                                                                        |
++-------------------------------------------------------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+Each element in the Layer will be inside a Kml <Placemark> element. As described in the Kml reference : « A Placemark is a Feature with associated Geometry. In Google Earth, a Placemark appears as a list item in the Places panel. A Placemark with a Point has an icon associated with it that marks a point on the Earth in the 3D viewer. (In the Google Earth 3D viewer, a Point Placemark is the only object you can click or roll over. Other Geometry objects do not have an icon in the 3D viewer. To give the user something to click in the 3D viewer, you would need to create a MultiGeometry object that contains both a Point and the other Geometry object.) »
+
+For Polygon and Line layers, when a feature is associated with a label, a MultiGeometry element containing a point geometry and the geometry of the feature is created. The point feature will be located in the middle of the polygon or line
+
+::
+
+  <Folder>
+      <name>park</name>
+      <visibility>1</visibility>
+      <styleUrl>#LayerFolder_check</styleUrl>
+      <Placemark>
+        <name>Ellesmere Island National Park Reserve</name>
+        <styleUrl>#style_line_ff787878_w4.0_polygon_ff00ffc8_label_ff0000ff</styleUrl>
+        <MultiGeometry>
+          <Polygon>
+            <outerBoundaryIs>
+              <LinearRing>
+                <coordinates>
+          	…
+           <Point>
+            <coordinates>
+	-70.86810858,82.12291871
+	</coordinates>
+          </Point>
+        </MultiGeometry>
+      </Placemark>
+  </Folder>
+
+
+Supported Features in the Placemark element are:
+
++-------------------+-----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Palcemark element | Supported | MapServer equivalence/Notes                                                                                                                                                                                                          |
++-------------------+-----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| name              | Yes       | Label attached with the feature. If there is no label a default name is assigned using the layer name and the shape id (ex. park.1)                                                                                                  |
++-------------------+-----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| visibility        | No        | Is is by default set to true                                                                                                                                                                                                         |
++-------------------+-----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| open              | No        |                                                                                                                                                                                                                                      |
++-------------------+-----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| address           | No        |                                                                                                                                                                                                                                      |
++-------------------+-----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| AddessDetails     | No        |                                                                                                                                                                                                                                      |
++-------------------+-----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| phoneNumber       | No        |                                                                                                                                                                                                                                      |
++-------------------+-----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Snippet           | No        | This is a short description the feature. If needed It could be supported.                                                                                                                                                            |
++-------------------+-----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| description       | Yes       | This information is what appears in the description balloon when the user clicks on the feature. The <description> element supports plain text as well as a subset of HTML formatting elements.Two ways of defining the description: |
++-------------------+-----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| AbstractView      | No        |                                                                                                                                                                                                                                      |
++-------------------+-----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| TimePrimitive     | No        |                                                                                                                                                                                                                                      |
++-------------------+-----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| styleUrl          | Yes       | Refers to a Style defined in the Document                                                                                                                                                                                            |
++-------------------+-----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| StyleSelector     | No        |                                                                                                                                                                                                                                      |
++-------------------+-----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Region            | No        |                                                                                                                                                                                                                                      |
++-------------------+-----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Metadata          | No        |                                                                                                                                                                                                                                      |
++-------------------+-----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Geometry          | Yes       | Depends on the layer type                                                                                                                                                                                                            |
++-------------------+-----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+
+General notes on layers
+~~~~~~~~~~~~~~~~~~~~~~~
+
+
+- Labelcache is turned off on each layer
+- Projection block should be set. If not set It will be assumed that the data is in lat/lon projection (a debug message will be sent to the user: Debug Message 1)
+- Possible to output vector layers as raster using metadata:  "KML_OUTPUTASRASTER" "true"
+- The user  can use the KML_FOLDER_DSIPLAY layer or map level metedata to choose a setting. Possible values are 'check' (default), 'radioFolder', 'checkOffOnly', 'checkHideChildren'.
+- The user can use metadata KML/OWS_DESCRIPTION or KML/OWS_INCLUDE_ITEMS to define the description attached to each feature.
+- The user can use metadata KML_ALTITUDEMODE to specify how altitude components in the <coordinates> element are interpreted. Possible values are: absolute, relativeToGround, clampToGround. http://code.google.com/apis/kml/documentation/kmlreference.html#altitudemode
+- The user can use metedata KML_EXTRUDE to specify whether to connect the LinearRing to the ground. http://code.google.com/apis/kml/documentation/kmlreference.html#tessellate
+- The user can use metedata KML_TESSELLATE to specify whether to allow the LinearRing to follow the terrain. http://code.google.com/apis/kml/documentation/kmlreference.html#extrude
+
+
+
+Point Layers
+~~~~~~~~~~~~
+
+- Each layer will be inside a Folder element. 
+- Each feature will be represented by a Placemark.
+- The  Geometry element for a Point layer would  be represented as a Point geometry element in Kml. Supported elements are:
+
+
+Line Layers
+~~~~~~~~~~~
+
+- Each layer will be inside a Folder element. 
+- Each feature in the layer would be represented by a Placemark.
+- If a label is attached to the line, the  Geometry element would  be represented as a MultiGeometry that includes a LineString element and a Point element representing the position of the label. If no label is attached to a feature, the Geometry element will be a LineString.
+
+Polygon Layers
+~~~~~~~~~~~~~~
+
+- Each layer will be inside a Folder element. 
+- Each feature will be represented by a Placemark.
+- If a label is attached to the polygon, the Geometry element would  be represented as a MultiGeometry that includes a Polygon element and a Point element representing the position of the label. 
+
+Annotation Layers
+~~~~~~~~~~~~~~~~~
+Not supported.
+
+Raster Layers
+~~~~~~~~~~~~~
+
+- Each layer will be inside a Folder element. 
+- A GroundOverlay feature is created for the layer, that includes  an href link to the raster image generated and LatLongBox for the extents (map extents).
+- The href is generated using the imagepath and imageurl settings in the map file.
+
+
+
+Styling
+-------------------------------------------------------------------------------
+
+As described in Section 4,  all different styles from the layers will be stored at the Document level and referenced from the folders using a styleUrl.
+
+Point Layers
+~~~~~~~~~~~~
+
+Point layers will be styled using the IconStyle styling element of kml. An image representing the symbol will be created and referenced from the IconStyle object.  If a label is attached to the point, a LabelStyle element will also be used. The LabelStyle will have the color parameter set.
+
+::
+
+  <Style id="style_label_ff0000ff_symbol_star_13.0_ff000000">
+      <IconStyle>
+        <Icon>
+          <href>>http://localhost/ms_tmp/4beab862_19bc_0.png</href>
+        </Icon>
+      </IconStyle>
+      <LabelStyle>
+        <color>ff0000ff</color>
+      </LabelStyle>
+  </Style>
+
+
+Line Layers
+~~~~~~~~~~~
+
+Line layers will be styled using the LineStyle styling element of kml. Color and width parameters of the LineStyle will be used.  If a label is attached to the layer, a LabelStyle element will also be used.
+
+
+Polygon Layers
+~~~~~~~~~~~~~~
+
+Polygon layers will be styled using the PolyStyle styling element of kml. Color parameter of the PolyStyle will be used. If an outline is defined in the map file, an addition LineStyle will be used.  If a label is attached to the layer, a LabelStyle element will also be used.
+
+
+Attributes
+-------------------------------------------------------------------------------
+
+As described in section on Layers,  two ways of defining the description:
+
+- kml/ows_description
+- kml/ows_include_items
+
+
+
+Coordinate system
+-------------------------------------------------------------------------------
+
+The map level projection should be set to epsg:4326. If not set, the driver will automatically set it. Layers are expected to have projection block if their projection is different from epsg:4326.
+
+
+Warning and Error Messages
+-------------------------------------------------------------------------------
+
+- When the projection of the map file is not set or is different from a a lat/lon projection, the driver automatically sets the projection to espg:4326. If the map is is debug mode, the following message is sent: « "KmlRenderer::checkProjection: Mapfile projection set to epsg:4326 »
+- If imagepath and imageurl are not set in the web object, the following message is sent in debug mode: « KmlRenderer::startNewLayer: imagepath and imageurl should be set in the web object »
+
+
+
+
+


Property changes on: trunk/docs/en/output/kml_output.txt
___________________________________________________________________
Added: svn:executable
   + *



More information about the mapserver-commits mailing list