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