KML write support

[elemoine]

This PR adds "write" support to the KML format. You can see it in action at http://erilem.net/ol3/kmlwrite/examples/kml.html.

Current limitations:

• The KML format's writeFeatures function does not transform the features' geometries. This means that the application developer needs to do the transform (to WGS84) by himself, as done in the kml example. This is consistent with the GeoJSON and GPX formats, which do not transform the data either. This problem should therefore be addressed separately, with an API that is consistent across feature formats.
• The KML format's writeFeatures function does not serialize feature properties that are not KML properties. For example a feature property named "description" will be serialized, while a property named "arbitraryname" won't. ExtendedData can be used in the future to address that limitation.

The code was written by @oterral and myself.

[bartvde]

I can't open up the output with Oxygen

[elemoine]

@bartvde thanks for testing @bartvde. We have encoding issues there.

[elemoine]

@bartvde, do you mind trying again?

[bartvde]

I can open up it now @elemoine

what XML schema is this supposed to validate against? It does not validate against KML 2.2 http://schemas.opengis.net/kml/2.2.0/ogckml22.xsd

[elemoine]

http://schemas.opengis.net/kml/2.2.0/ogckml22.xsd

Yes, that's the schema.

[bartvde]

then you should use:

xmlns="http://www.opengis.net/kml/2.2"

instead, but many validation errors, I assume this might be because of the extensions

[bartvde]

SystemID: /Users/bartvandeneijnden/Downloads/download (1).kml
Engine name: Xerces
Severity: error
Description: cvc-complex-type.2.4.a: Invalid content was found starting with element 'Style'. One of '{"http://www.opengis.net/kml/2.2":PlacemarkSimpleExtensionGroup, "http://www.opengis.net/kml/2.2":PlacemarkObjectExtensionGroup}' is expected.
Start location: 8:14
End location: 8:19
URL: http://www.w3.org/TR/xmlschema-1/#cvc-complex-type

SystemID: /Users/bartvandeneijnden/Downloads/download (1).kml
Engine name: Xerces
Severity: error
Description: cvc-complex-type.2.4.a: Invalid content was found starting with element 'gx:w'. One of '{"http://www.opengis.net/kml/2.2":BasicLinkSimpleExtensionGroup, "http://www.opengis.net/kml/2.2":BasicLinkObjectExtensionGroup}' is expected.
Start location: 12:26
End location: 12:30
URL: http://www.w3.org/TR/xmlschema-1/#cvc-complex-type

all errors look like the above 2

[bartvde]

Style goes before the geometry, so sequence should be:

        <Placemark>
            <name>Adelbodenstrasse</name>
            <styleUrl>#style-Secondary</styleUrl>            
            <Style>
                <IconStyle>
                    <Icon>
                        <href>https://maps.google.com/mapfiles/kml/pushpin/ylw-pushpin.png</href>
                    </Icon>
                    <hotSpot x="2" y="12" xunits="pixels" yunits="pixels"/>
                </IconStyle>
                <LineStyle>
                    <color>ff17e8ea</color>
                    <width>4</width>
                </LineStyle>
                <PolyStyle>
                    <color>ffffffff</color>
                </PolyStyle>
            </Style>
            <LineString>
                <coordinates>7.602502200000001,46.54975689999998,1
                    7.6023929,46.54962560000001,1</coordinates>
            </LineString>            
        </Placemark>

this gets rid of the first error, still need to look into the gx: one

[bartvde]

okay it validates fine against: https://developers.google.com/kml/schema/kml22gx.xsd which is what we need I guess since of the gx: tags, so only sequence of tags needs changing as mentioned above. I think we should output a reference to the schema as well to avoid confusion.

<kml xmlns="http://www.opengis.net/kml/2.2" xmlns:gx="http://www.google.com/kml/ext/2.2">
    <Document>
        <Placemark>
            <name>Adelbodenstrasse</name>
            <styleUrl>#style-Secondary</styleUrl>            
            <Style>
                <IconStyle>
                    <Icon>
                        <href>https://maps.google.com/mapfiles/kml/pushpin/ylw-pushpin.png</href>
                        <gx:w>32</gx:w>
                        <gx:h>32</gx:h>                        
                    </Icon>
                    <hotSpot x="2" y="12" xunits="pixels" yunits="pixels"/>
                </IconStyle>
                <LineStyle>
                    <color>ff17e8ea</color>
                    <width>4</width>
                </LineStyle>
                <PolyStyle>
                    <color>ffffffff</color>
                </PolyStyle>
            </Style>
            <LineString>
                <coordinates>7.602502200000001,46.54975689999998,1
                    7.6023929,46.54962560000001,1</coordinates>
            </LineString>            
        </Placemark>
    </Document>
</kml>

[elemoine]

Thanks Bart. So do we need to change the xmlns?

[bartvde]

@elemoine yes it needs changing in order to validate, the following validates for me and which is what I would probably output:

<kml xmlns="http://www.opengis.net/kml/2.2" xmlns:gx="http://www.google.com/kml/ext/2.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.opengis.net/kml/2.2
    https://developers.google.com/kml/schema/kml22gx.xsd">
    <Document>
        <Placemark>
            <name>Adelbodenstrasse</name>
            <styleUrl>#style-Secondary</styleUrl>            
            <Style>
                <IconStyle>
                    <Icon>
                        <href>https://maps.google.com/mapfiles/kml/pushpin/ylw-pushpin.png</href>
                        <gx:w>32</gx:w>
                        <gx:h>32</gx:h>                        
                    </Icon>
                    <hotSpot x="2" y="12" xunits="pixels" yunits="pixels"/>
                </IconStyle>
                <LineStyle>
                    <color>ff17e8ea</color>
                    <width>4</width>
                </LineStyle>
                <PolyStyle>
                    <color>ffffffff</color>
                </PolyStyle>
            </Style>
            <LineString>
                <coordinates>7.602502200000001,46.54975689999998,1
                    7.6023929,46.54962560000001,1</coordinates>
            </LineString>            
        </Placemark>
    </Document>
</kml>

[probins]

writeFeatures function does not serialize feature properties that are KML properties

um, think you mean "...that are not KML properties"?

[elemoine]

um, think you mean "...that are not KML properties"?

Yes, I updated the comment. Thanks.

[elemoine]

@bartvde are you sure about the first url in the schemaLocation? It's not a reference to an xsd file.

[bartvde]

yes I'm sure that's the URI that the schema applies to see eg http://www.w3schools.com/schema/schema_schema.asp

[elemoine]

I see. That makes more sense now.

[elemoine]

Branch updated.

• 7fb3e58 adds an exampleNS.strToBase64 function that can convert utf8 strings to base64. The code is copied from mdn. This function is used in the kml example.
• 384f2a0 changes the attributes we set in the <kml> node to produce valid documents. Thanks @bartvde for your help on this.

http://erilem.net/ol3/kmlwrite/examples/kml.html is up-to-date.

[probins]

I'm wondering whether it makes sense to have an example, given that this will probably change because of the transform issue. I don't think any of the other formats have an example for write, do they?

[elemoine]

I'm wondering whether it makes sense to have an example, given that this will probably change because of the transform issue.

It will just slightly change.

I don't think any of the other formats have an example for write, do they?

No, but they probably should. I think it's good to have examples for features provided by the library. And in this case I see some value in having an example that shows how to make locally generated files downloadable (the <a download="map.kml"> stuff).

[elemoine]

this will not work in IE, see: 87ea5fa#diff-497c3a47c9cdc970f191c9e4e852833c

Thanks again Bart! Does this every node.setAttributeNS occurrences should be changed to ol.xml.setAttributeNS?

[bartvde]

no I think only the ones with the 'xmlns' prefix

[probins]

they probably should

I like the OL2 vector-formats example, where you could read/write in any of the supported formats. Useful for testing as well as being a demo

[oterral]

I've changed the node.setAttributeNS occurrences for xmlns attribute and reordering correctly placemark's child nodes.

The validation is now successfull with oxygen.

[bartvde]

great, I love valid XML ;-)

[oterral]

👍

[elemoine]

Thanks a lot @oterral. This looks good. I've updated http://erilem.net/ol3/kmlwrite/examples/kml.html. @bartvde please tell us if this is good to merge to you.

[bartvde]

I'll have a quick look now

[bartvde]

I wonder why the xsd is in here, since the xsd is not a (namespace) URI.

In other formats we have used schemaLocation: https://github.com/openlayers/ol3/blob/master/src/ol/format/wfsformat.js#L83:L89 instead

[elemoine]

Good point. I did things this way initially because I did not understand that part very well. I'll add a commit that mimics what's in the wfs format.

[bartvde]

Nice work guys, no more comments from me.

[elemoine]

Thanks for the thorough review. I'll add commits based on your review comments.

[elemoine]

I've just added new commits that take @bartvde's comments into account. I'll merge when Travis is all green.

[bartvde]

thanks for addressing this @elemoine