KMLPlacemark Object - Work with KML Placemarks

[ironfelix717]

KMLPlacemark Object
This object allows one to easily read/build KML placemarks in VBA. 4 types of placemarks are supported. Point, Path, Polygon, and Photo Overlay. Other types of placemarks are NOT supported. These include, MultiGeometry, Screen Overlays, etc. This object attempts to be in accordance with Google Earth's KML Reference.

This is a completely new project and should not be associated with a prior release of code regarding placemark generation here:
VBA Google Earth KML File Placemarks
The aforementioned project is preceded by this one and, although still a powerhouse in projects I run today, will no longer be supported.

GX namespace attributes are NOT supported. The object will handle this by stripping and converting GX namespace attributes to best-fit alternative's. See object breakdown. Additionally, attempts to resolve erroneous properties at runtime are made. For instance, if a user specifies an altitude, but provides 'ClampToGround' as the altitude mode, the object will re-assign the output to contain 'RelativeToGround'. Because of built-in error checking, the object is quite forgivable.

---

Placemark Types
The four supported placemark types are briefly described below:

Point: A simple point in space. Can have an altitude and be extended from the ground.

Path: A series of points connected by a line. Can have an altitude and be extended from the ground.

Polygon: Similar to a path, except the first coordinates and last coordinates must match. Order of the coordinates matter (clockwise vs ccw - see Google's docs).

Photo Overlay: Overlays an image onto the terrain. Can have an altitude. Requires NSEW coordinates. See google's docs.

---

Object Breakdown
The following describes methods and properties of the object.

.Load()         [Sub]       Load a placemark KML string into the object. Must be valid XML.
.Build()        [Func]      Assembles the KML placemark string from object properties.
                            Optional param 'FailOnError': when true will raise if internal or runtime error occurs.
.FormatCoords() [Func]      Formats or Deformats a coordinate string by stripping or appending the altitude value to each coordinate in the string set.
                                Generally not needed unless reading <coordinates> tag from a raw KML file.
.DebugString       [Prop]     Read only. Provides a list of internal errors or runtime errors detected in the object. The presence of a debug string does not guarantee an 
                                            error is fatal. It could be a warning that a property was re-assigned.  

.PlacemarkType   [Prop]     Enum KMLPlacemarkTypes. Reads/Assigns the placemark type. Supported options are: kPoint, kPath, kPolygon, kPhotoOverlay
                                screen overlay types and other non-conventional types are not supported with this object.
.PlacemarkName   [Prop]    Reads/Assigns the placemark name.
.Description     [Prop]    Reads/Assigns the placemark's description.
.StyleURL        [Prop]    Reads/Assigns the StyleURL property of the placemark.
.Coordinates     [Prop]    Reads/Assigns coordinates for the placemark. Note that by default coordinates should be formatted as
                             longitude , latitude ' and delimited by spaces. Should the user want to specify coordinates as a more traditional
                             order latitude,longitude, see .InvertCoordinates property. Coordinates provided should NOT include altitude as a third element.
                             See .FormatCoords() function. The order of coordinates matters with Polygons. See Google's docs to understand how coordinates should be                  provided. Again, the altitude should NEVER be specified in the string as a third element with this property.
.InvertCoordinates [Prop]   Flips the long/lat order of the coordinates in the output from .Build() to lat/long.
.Altitude          [Prop]   Reads/Assigns the Altitude of the placemark. This value is in METERS. Note that this property takes precedence
                                over the altitude mode. And if an erroneous altitudemode is specified or none at all, the object will
                                assign a default altitude mode.
AltitudeMode     [Prop]    Enum KMLAltitudeModes. Reads/Assigns the altitude mode of the placemark. Available options depend on the PlacemarkType.
                               If an erroneous altitudemode is specified, the object will re-assign the mode. GX namespace modes are not supported, such as 'RelativeToSeaFloor'.
                              
.Extended         [Prop]   Extrudes the placemark from it's altitude to it's origin (earth).
.PhotoIMG          [Prop]  href path of image file for photo overlay.
.PhotoColor         [Prop]  Hex color code to apply to image. Note that transparency of image overlays is handled with styles.
.PhotoRotate       [Prop]  Degrees of rotation of the photo overlay.

---

Usage Example:

Private Sub Example0()
'build a new placemark KML string
Dim P           As New KMLPlacemark

With P
    .PlacemarkName = "My Custom Placemark"
    .Description = "A placemark point"
    .PlacemarkType = kPoint
    .StyleURL = "MyStyle"
    .Coordinates = "-79.029020,33.50959"
    .Altitude = 500
    .AltitudeMode = kRelativeToGround
    Debug.Print .Build(True)
End With
End Sub

Private Sub Example1()
'READING A PLACEMARK INTO OBJECT...
Dim P           As New KMLPlacemark
Dim PString     As String

PString = _
"<GroundOverlay>" & _
"    <name>Untitled Image Overlay</name>" & _
"    <Icon>" & _
"        <href>Folder/202209172013.jpg</href>" & _
"        <viewBoundScale>0.75</viewBoundScale>" & _
"    </Icon>" & _
"    <LatLonBox>" & _
"        <north>57.092222</north>" & _
"        <south>55.030466</south>" & _
"        <east>-91.25794500000001</east>" & _
"        <west>-92.829263</west>" & _
"        <rotation>45</rotation>" & _
"    </LatLonBox>" & _
"</GroundOverlay>"

With P
    .Load PString, True
    Debug.Print P.PlacemarkName
    Debug.Print P.PlacemarkType
    Debug.Print P.Coordinates
    Debug.Print P.PhotoIMG
End With
End Sub

Credits
-- Developed by ironfelix717 Nov. 2022
Please reports bugs or issues in comments or dm.

ALSO SEE KMLFile Object

Thanks to all who helped with issues.
https://stackoverflow.com - great resource for MSXML2 related info
https://learn.microsoft.com/en-us/previous-versions/troubleshoot/msxml/list-of-xml-parser-versions
https://developers.google.com/kml/documentation/kml_tut
https://developers.google.com/kml/documentation

 

[ironfelix717]

1-10-23 - 2 small 'bugs' were found.

Both were present in the .Build() function. They are...

1.) The code would log a debug string of a warning indicating: ".Build(): Warning. End cord for path should match start cord. Ignored..."
When the path (linestring) placemark type does not require closed loop.

2.) The code would log a debug string when building a POLYGON but the debug message stated: ".Build(): Warning. End cord for path should match start cord. Ignored..." Which should be... ".Build(): Warning. End cord for polygon should match start cord. Ignored..."

Minor bugs that do not affect function output. Fixed in V2 attached.