chiropterist / kml-samples

Automatically exported from code.google.com/p/kml-samples
0 stars 0 forks source link

gx:drawOrder in KML ref docs incomplete #423

Open GoogleCodeExporter opened 9 years ago

GoogleCodeExporter commented 9 years ago
What is the full URL of the page with the documentation error?

https://developers.google.com/kml/documentation/kmlreference#gxdraworder

What is the URL of any downloadable example of this error?

See example posted here
http://code.google.com/p/earth-issues/issues/detail?id=198

Please provide a short description of the documentation error:

The gx:drawOrder element in the Google KML documentation only refers to line 
strings.

However, the gx:drawOrder element is actually implemented in Google Earth on 
Polygon, LinearRings, etc. in addition to LineStrings. In fact, the 
gx:drawOrder is an extension AbstractGeometrySimpleExtensionGroup meaning it 
can appear in any geometry including Points.

The documentation including examples of Polygon geometries need to reflect the 
correct scope of the gx:drawOrder element.

See related discussions:
https://groups.google.com/a/googleproductforums.com/forum/?fromgroups#!topic/ear
th/9jjO7GpknMo
https://groups.google.com/a/googleproductforums.com/forum/?fromgroups#!topic/ear
th/vINnIYg8Sws

A corrected revision of the documentation would be something like the following 
revision:

"An integer value that specifies the order for drawing multiple line strings, 
polygons, or linear rings. Non-point geometries drawn first may be partially or 
fully obscured by other geometries with a later draw order. This element may be 
required in conjunction with the <gx:outerColor> and <gx:outerWidth> elements 
in <LineStyle> and <PolyStyle> when dual-colored geometries cross each other."

Original issue reported on code.google.com by gjmath...@gmail.com on 10 May 2012 at 6:25

GoogleCodeExporter commented 9 years ago
Note the LineString syntax is incorrect.
https://developers.google.com/kml/documentation/kmlreference#linestring

gx:drawOrder element extends the AbstractGeometryType and must appear first 
before extrude, tessellate, etc.

<LineString id="ID">
  <!-- specific to LineString -->
  <gx:altitudeOffset>0</gx:altitudeOffset>  <!-- incorrect context -->
  <extrude>0</extrude>
  <tessellate>0</tessellate>
  <altitudeMode>clampToGround</altitudeMode> 
  <gx:drawOrder>0</gx:drawOrder>            <!-- incorrect context --> 
  <coordinates>...</coordinates>
</LineString>

Original comment by kml4earthguy on 11 May 2012 at 3:02

GoogleCodeExporter commented 9 years ago
The documentation has NOT been updated and still contains the error.

Original comment by gjmath...@gmail.com on 28 Feb 2015 at 3:30

GoogleCodeExporter commented 9 years ago
Status of this issue is NEW and it's almost 3 years old.

Only the order of the elements needs to be corrected in the Google KML 
Reference document to correct the error. The corrected order which validates to 
the XML Schemas is the following:

<LineString id="ID">
  <!-- specific to LineString -->
  <gx:altitudeOffset>0</gx:altitudeOffset>
  <gx:drawOrder>0</gx:drawOrder>            <!-- correct context --> 
  <extrude>0</extrude>
  <tessellate>0</tessellate>
  <altitudeMode>clampToGround</altitudeMode> 
  <coordinates>...</coordinates>
</LineString>

Original comment by kml4earthguy on 7 Mar 2015 at 3:57