1 // Copyright 2008, Google Inc. All rights reserved. 2 // 3 // Redistribution and use in source and binary forms, with or without 4 // modification, are permitted provided that the following conditions are met: 5 // 6 // 1. Redistributions of source code must retain the above copyright notice, 7 // this list of conditions and the following disclaimer. 8 // 2. Redistributions in binary form must reproduce the above copyright notice, 9 // this list of conditions and the following disclaimer in the documentation 10 // and/or other materials provided with the distribution. 11 // 3. Neither the name of Google Inc. nor the names of its contributors may be 12 // used to endorse or promote products derived from this software without 13 // specific prior written permission. 14 // 15 // THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED 16 // WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 17 // MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO 18 // EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 19 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 20 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 21 // OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 22 // WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 23 // OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 24 // ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25 26 // This file contains the declarations of some KML convenience functions. 27 28 #ifndef KML_CONVENIENCE_CONVENIENCE_H__ 29 #define KML_CONVENIENCE_CONVENIENCE_H__ 30 31 #include <vector> 32 #include "kml/base/vec3.h" 33 #include "kml/dom.h" 34 35 namespace kmlbase { 36 class DateTime; 37 } 38 39 namespace kmlconvenience { 40 41 // NOTE: this collection of convenience routines is expected to grow. 42 // NOTE: for now these are all in one file in alphabetical order. 43 44 // This creates a Data element with the given name and value and appends 45 // this to the Feature's ExtendedData. An ExtendedData is created in the 46 // Feature if one does not already exist. 47 void AddExtendedDataValue(const string& name, const string& value, 48 kmldom::FeaturePtr feature); 49 50 // Creates a <gx:AnimatedUpdate> with a <Change> to a Point Placemark of 51 // the specified target_id and coordinates as specified by vec3. 52 kmldom::GxAnimatedUpdatePtr CreateAnimatedUpdateChangePoint( 53 const string& target_id, const kmlbase::Vec3& vec3, double duration); 54 55 // Creates a simple Polygon Placemark from a LinearRing. 56 kmldom::PlacemarkPtr CreateBasicPolygonPlacemark( 57 const kmldom::LinearRingPtr& lr); 58 59 // Creates a <Camera> element with the specified fields. 60 kmldom::CameraPtr CreateCamera(double latitude, double longitude, 61 double altitude, double heading, double tilt, 62 double roll, int altitudemode); 63 64 // Creates a <coordinates> element filled with the lng, lat[, alt] tuples 65 // describing a great circle of radius around a point lat, lng. The 66 // antemeridian is not considered here. 67 kmldom::CoordinatesPtr CreateCoordinatesCircle(double lat, double lng, 68 double radius, size_t segments); 69 70 // This creates a Data element with the name and value specified: 71 // <Data name="NAME><value>VALUE</value></Data> 72 kmldom::DataPtr CreateDataNameValue(const string& name, 73 const string& value); 74 75 // Creates a <LookAt> element from the specified fields. 76 kmldom::LookAtPtr CreateLookAt(double latitude, double longitude, 77 double altitude, double heading, double tilt, 78 double range, int altitudemode); 79 80 // If the atts contains both a double "lat" and double "lon" then create 81 // a KML <Point> with <coordinates> set from these attributes. 82 kmldom::PointPtr CreatePointFromLatLonAtts(const char** atts); 83 84 // Create a <Point> with <coordinates> from the given Vec3. 85 kmldom::PointPtr CreatePointFromVec3(const kmlbase::Vec3& vec); 86 87 // This creates a Point coordinates set as indicated. 88 kmldom::PointPtr CreatePointLatLon(double lat, double lon); 89 90 // This is a convenience function to create a Point Placemark. 91 kmldom::PlacemarkPtr CreatePointPlacemark(const string& name, 92 double lat, double lon); 93 94 // Create a <Placemark> with the given <Point>, DateTime and <styleUrl>. 95 // A <TimeStamp> is created from the DateTime and <ExtendedData> fields are 96 // created for date and time. 97 kmldom::PlacemarkPtr CreatePointPlacemarkWithTimeStamp( 98 const kmldom::PointPtr& point, const kmlbase::DateTime& date_time, 99 const char* style_id); 100 101 // Create a Region with LatLonAltBox set to the given bounds and Lod 102 // set to the given values. This is a "2D" Region because no altitude 103 // mode is set which defaults the LatLonAltBox to clampToGround. 104 kmldom::RegionPtr CreateRegion2d(double north, double south, 105 double east, double west, 106 double minlodpixels, double maxlodpixels); 107 108 109 // Creates a <gx:FlyTo> element which has the specified <gx:duration> and the 110 // specified AbstractView. 111 kmldom::GxFlyToPtr CreateFlyTo(const kmldom::AbstractViewPtr& abstractview, 112 double duration); 113 114 // Creates a <gx:FlyTo> element which has the specified <gx:duration> and a 115 // an AbstractView. If the feature has a existing AbstractView it is used, 116 // otherwise a <LookAt> is computed from the spatial extents of the feature. The 117 // LookAt's altitude, heading and tilt are set to 0.0 and the altitudeMode is 118 // set to relativeToGroud. Returns NULL if the feature has no specified 119 // AbstractView and none can be computed. 120 // See kmlengine::ComputeFeatureLookAt for details of how the LookAt is 121 // generated. 122 kmldom::GxFlyToPtr CreateFlyToForFeature(const kmldom::FeaturePtr& feature, 123 double duration); 124 125 // Creates a <gx:Wait> with a <gx:duration> of the specified value. 126 kmldom::GxWaitPtr CreateWait(double duration); 127 128 // This gets the value of the given name from the ExtendedData/Data as 129 // described above. If there is no ExtendedData or no Data element with 130 // the given name false is returned. 131 bool GetExtendedDataValue(const kmldom::FeaturePtr& feature, 132 const string& name, 133 string* value); 134 135 // This sets the ExtendedData element of the feature to hold the given name 136 // value as a Data element as described above. NOTE: Any previous ExtendedData 137 // is delete from this feature. 138 void SetExtendedDataValue(const string& name, const string& value, 139 kmldom::FeaturePtr feature); 140 141 // Returns a simplification of coordinates elements. merge_tolerance specifies 142 // a distance (in meters) within which adjacent coordinates tuples will be 143 // merged. If set to 0, no merge will occur. 144 // For example, assume we have coordinates of: 145 // (0,0,0 0,0,0 2,2,2 5,5,5 6,6,6 9,9,9) 146 // where the first two coordinates elements are coincident. 147 // If SimplifyCoordinates is called with a merge_tolerance of 1.0, the 148 // coincident points will be elided and the returned coordinates will be: 149 // (0,0,0 2,2,2 5,5,5 6,6,6 9,9,9) 150 // Since a 1 x 1 degree square near the equator has a diagonal of around 151 // 157,147m, if SimplifyCoordinates is called with a merge 152 // tolerance of 160000 the points at (5,5,5 6,6,6) will also be elided and the 153 // returned coordinates will be: 154 // (0,0,0 2,2,2 5,5,5 9,9,9) 155 void SimplifyCoordinates(const kmldom::CoordinatesPtr& src, 156 kmldom::CoordinatesPtr dest, double merge_tolerance); 157 158 } // end namespace kmlconvenience 159 160 #endif // KML_CONVENIENCE_CONVENIENCE_H__ 161