1 2<<< WARNING: MOST OF THIS CONTENT IS NOT UP-TO-DATE >>> 3 4 5This file describes the design and structure of Marble 6 71. The main structure 8===================== 9 10Marble, the application, currently consists two main widgets: 11 - a MarbleWidget that contains the view of the world, and 12 - a MarbleControlBox that controls it. 13 14The MarbleWidget is a view for the model represented by the MarbleModel 15class, which contains all the data necessary for manipulating and 16displaying the map. 17 18 191.1 Library 20------------ 21 22The MarbleWidget is a very complex widget with lots of helper classes. 23MarbleWidget is contained in a library with just a few exported 24classes. Here we will present the exported classes of the library: 25 26 - MarbleWidget 27 - MarbleModel 28 - MarbleControlBox 29 30These classes comprise the main interface to the Marble library. 31 32 33 - PlacemarkModel 34 - KAtlasThemeSelectView 35 - LegendBrowser 36 - SearchListView 37 - (MarbleNavigator) 38 39These are mainly parts of the more complex MarbleControlBox. The 40individual controls inside MarbleControlBox can be used by themselves 41if you want to create a simpler user interface. 42 43NOTE: MarbleNavigator is currently not part of the library, but it 44 will be moved there before the next release. 45 46 47 - MapTheme 48 49This class contains a set of colors, an icon some other misc data that 50will control the appearance of the map. By defining a new MapTheme, 51you can give a new appearance of an already existing map. 52 53 54 - KAtlasAboutDialog (to be renamed into MarbleAboutDialog) 55 56This is a special utility class which displays some information about 57Marble, shows the authors and will also show the license in the 58future. 59 60 61 622. The World Model 63================== 64 65The model of the world consists of 3 different parts, which can be 66viewed as separate layers: 67 68 - A pixel based area that is split up into tiles. Depending on the 69 dataset, these tiles are produced from different data sources, 70 either from satellite scans or from photographs. The tiles are 71 stored in several different resolutions that are used in different 72 zoom levels. The tiles are automatically generated the first time 73 that the application is started, and are stored into 74 $HOME/.marble/data/maps. For packaging purposes or to offer the 75 same data to multiple users you can move these tiles into the 76 system directory where marble gets installed (e.g. 77 /usr/share/apps/marble/data/maps). 78 79 The main class of the tiles layer is the TextureMapper, which maps 80 a tiled texture onto the projected sphere. 81 82 - Vectors that represent different kinds of borders -- geographical 83 or political -- or features. Geographical borders can be 84 coastlines, islands or lakes, but also rivers. Political borders 85 are mostly countries, but also the states of the USA. Special 86 features include the grid of lines that show the latitude and 87 longitude as well as the tropics and arctics. 88 89 The main classes of the vectors are the GeoPolygon and the PntMap, 90 which contain the actual vectors, but also a bounding box 91 that specifies which area is being covered by each polygon. 92 93 - Points of interest, represented by the Placemark class. Right now 94 these are mostly cities, but also some mountains and sea deeps. 95 96 The Placemark has a somewhat arbitrary selection of properties 97 which comes from the Google Earth KML format. This will be 98 restructured in future versions. Another important class is the 99 PlacemarkContainer which collects a number of Placemarks into a 100 container, just like the name suggests. A third level is provided 101 by the PlacemarkManager class which manages several 102 PlacemarkContainers (currently just one) and also imports and 103 exports it to/from files in various file formats. 104 105 106For most maps, these 3 layers are just painted on top of each other in 107simple bottom top order. However, the Topographical Atlas View (the 108default view!) provides a special map in terms of composition: 109 110 The Topographical Atlas View "merges" the Texture (which contains 111 the digital elevation data) and a Vector Layer to create a 112 recolorized bumpmapped layer via the TextureColorizer class. 113 114All map views and their use of layers get specified in a *.dgml XML 115file. The source format for the Placemark layer is Google Earth's KML 116file format which gets parsed and cached into a temporary binary file 117(.cache) for faster follow-up reading. 118 119 1202.1 The Tile System 121------------------- 122 123 124FIXME: To be written... 125 126 1272.2 The Vector System 128--------------------- 129 130FIXME: To be written... 131 132FIXME: Explain the way nodes get filtered e.g. by ClipPainter. 133 134FIXME: Explain the differences between the GeoPolygon and the 135 ScreenPolygon, and how they interact. Also the PntMap and the 136 VectorMap. 137 138 1392.3 Placemarks 140-------------- 141 142FIXME: To be written... 143 144FIXME: Explain how Placemark labels are placed so they don't cover each 145other. 146 147 1483. The Painting Process 149======================= 150 151FIXME: To be written... 152 153 1544. Library 155========== 156 157This section describes the library in more detail than the overview 158above, including the internal classes that are not exported to the 159external applications. This section is for developers that want to 160develop Marble itself, and not just use the classes in his/her own 161application. 162 163 1644.1 The Basic Building Blocks 165----------------------------- 166 167Quaternion 168GeoDataPoint, GeoPolygon, PntMap 169ScreenPolygon, VectorMap 170 171 1724.2. Class Overview 173------------------- 174 175Here follows now a list of classes, their roles and how they interact. 176 177Basic classes 178- - - - - - - 179 180Quaternion A simple implementation of the mathematical concept 181 quaternion. 182 183GeoDataPoint A point on the earth, (lon, lat) 184GeoPolygon A path or polygon on the earth, consisting of a vector 185 of GeoDataPoints 186PntMap A collection of GeoPolygons ( QVector<GeoPolygon *> ) 187 FIXME: Rename and move from GeoPolygon.h into own file. 188 189ScreenPolygon A path or polygon on the screen. Uses screen 190 coordinates. Uses floats due to antialiasing. 191VectorMap A Vector of ScreenPolygons. 192 Rename FIXME 193GridMap The grid of lat-lon lines on the map. 194 Another Vector of ScreenPolygons. Perhaps it should 195 inherit or contain a VectorMap. 196 197Placemark A point on the earth with some additional data. Can be 198 selected and manipulated. Has a name. Today mostly 199 used for cities of different size. 200 At this point somewhat arbitrary in its choice of 201 properties. Contains (among others): 202 - Coordinate (GeoDataPoint) 203 - Role (QChar) -- city, capital, etc 204 - Population (int) 205 - Description (QString) 206 - Countrycode (QString) 207 - View stuff (selected, labelstring, boundingbox, etc) 208 209PlaceContainer A list of Placemarks ( QVector<Placemark *> ) 210 211 212Model / View 213- - - - - - - 214 215MarbleModel The main model. Contains (among others): 216 - MapTheme 217 - GridMap 218 - VectorComposer 219 - PlacemarkManager 220 - PlacemarkModel 221 222VectorComposer Manages the different vector sub-layers which consist 223 of coastlines, islands, lakes, glaciers, rivers 224 as well as borders for the countries and the US 225 States. These are all stored in PntMaps, one for each 226 type. FIXME: Change Name. 227 228MarbleWidget The view of a MarbleModel. 229 230 231Widgets 232------- 233KAtlasControl The main window. Contains a MarbleWidget and a 234 MarbleControlBox. 235 236 237Unsorted 238-------- 239 240class ClipPainter; 241class HttpFetchFile; 242class KAtlasAboutDialog : public QDialog, private Ui::katlasAboutDialog { 243class KAtlasCrossHair : public QObject { 244class MarbleDirs 245class KAtlasFlag : public QObject { 246class KAtlasMapScale : public QObject { 247class KAtlasThemeSelectView : public QListView { 248class KAtlasTileCreatorDialog : public QDialog, private Ui::KAtlasTileCreatorDialog { 249class KAtlasTileCreatorDialog: public Ui_KAtlasTileCreatorDialog {}; 250class KAtlasViewInputHandler; 251class KAtlasViewPopupMenu; 252class KAtlasWindRose : public QObject { 253class KAtlasXmlHandler : public QXmlDefaultHandler { 254class MapTheme : public QObject 255class MeasureTool; 256class PlaceFolder : public QVector<Placemark*> { 257class PlacemarkInfoDialog: public Ui_PlacemarkInfoDialog {}; 258class PlacemarkManager; 259class PlacemarkModel : public QAbstractListModel { 260class PlacemarkPainter : public QObject { 261class QAbstractItemModel; 262class QMenu; 263class QStandardItemModel; 264class SearchComboBox : public QComboBox { 265class SearchListView : public QListView { 266class TextureColorizer; 267class TextureLoader; 268class TextureMapper { 269class TextureTile; 270class TileCreator : public QObject { 271class TinyWebBrowser : public QTextBrowser { 272class katlasAboutDialog: public Ui_katlasAboutDialog {}; 273