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 declaration of the Regionator class. See the 27 // comments in region_handler.h for details on programming and regionator.cc 28 // for details of the operation. 29 30 #ifndef KML_REGIONATOR_REGIONATOR_H__ 31 #define KML_REGIONATOR_REGIONATOR_H__ 32 33 #include <map> 34 #include <vector> 35 #include "kml/dom.h" 36 #include "kml/regionator/region_handler.h" 37 #include "kml/regionator/regionator_qid.h" 38 39 namespace kmlregionator { 40 41 typedef std::vector<kmldom::RegionPtr> region_vector_t; 42 43 // The Regionator class is the API to the "regionator" algorithm. 44 class Regionator { 45 public: 46 // A Regionator instance is created with a class derived from 47 // RegionHandler and a root Region. 48 Regionator(RegionHandler& rhandler, const kmldom::RegionPtr& region); 49 ~Regionator(); 50 // This method starts the "regionation". See region_handler.h for 51 // details on how this class calls out to the RegionHandler. 52 // The default output directory (output_directory == NULL) is the 53 // current working directory of the caller. Returns true when regionation 54 // has completed. Each generated KML file has a rel="up" link to the root 55 // KML file. The root KML file has a rel="self" link. See SetRootFilename 56 // for the name of the root KML file. Since data presented via Region-based 57 // NetworkLinks used in this manner compounds it is of interest to "reach up" 58 // all the way to the root upon discovering any descendant node. 59 bool Regionate(const char* output_directory); 60 61 // This method "regionates" using the given RegionHandler and region. The 62 // region is first aligned to the lowest level region in a quadtree rooted 63 // at n=180, s=-180, e=180, w=-180. All output files are saved to the 64 // given directory if a non-NULL pointer is supplied. Regionation progresses 65 // the same whether nor not an output directory is supplied. This also 66 // adds a <LookAt> to the root node for the bounds of the data set as 67 // described by the region used here. 68 static bool RegionateAligned(RegionHandler& rhandler, 69 const kmldom::RegionPtr& region, 70 const char* output_directory); 71 72 // By default, the resulting root filename will be "1.kml". Provide an 73 // override for that name with this method. This file is also added as the 74 // <atom:link> of every descendent kml. SetRootFilename(const char * filename)75 void SetRootFilename(const char *filename) { root_filename_ = filename; } 76 77 // This <Region>'s <LatLonAltBox> is used as the basis for the <LookAt> 78 // added to the root node of the generated hierarchy. Without this there 79 // is no explicit <LookAt>. SetNaturalRegion(const kmldom::RegionPtr & region)80 void SetNaturalRegion(const kmldom::RegionPtr& region) { 81 natural_region_ = region; 82 } 83 84 private: 85 kmldom::RegionPtr root_region_; 86 // This calls _Regionate() for the given child of the parent Region. 87 // This saves the child Region to the children vector if the child Region 88 // has data. 89 void Recurse(const kmldom::RegionPtr& parent, quadrant_t quadrant, 90 region_vector_t* children); 91 // This calls the RegionHandler for the given region. If the RegionHandler 92 // returns false from HasData() or NULL from GetFeature() this returns false 93 // signalling that this Region has no data. 94 bool _Regionate(const kmldom::RegionPtr& region); 95 RegionHandler& rhandler_; 96 // This returns the relative filename for the given Region. A parent KML 97 // file NetworkLink will look for a child with this name. 98 string RegionFilename(const kmldom::RegionPtr& region); 99 int region_count_; 100 std::map<string,int> qid_map_; 101 char* output_directory_; 102 const char* root_filename_; 103 kmldom::RegionPtr natural_region_; 104 }; 105 106 } // end namespace kmlregionator 107 108 #endif // KML_REGIONATOR_REGIONATOR_H__ 109