Marble/GeoGraphicsViewOverview

From KDE Community Wiki

GeoGraphicsView Overview

GeoGraphicsView is one of the central parts of the Marble API. Built on top of GeoPainter, it allows the user to interact with objects in a way that

  • provides items that are arranged and can be accessed in a scene-graph.
  • provides an API and design that is closely modelled after QGraphicsView.
  • has got a Qt Style API so that Qt developers get up to speed quickly.
  • has got a KML Style API so that people with GIS knowledge are quickly able to use it.

In opposite to QGraphicsView the GeoGraphicsView ...

  • is Latitude/Longitude/Altitude-based instead of focussing on pixel coordinates. This is reflected by the GeoGraphicsView API which avoid pixel based positioning and promotes lat-lon-alt-based geo coordinates instead.
  • Supports multiple Projections: GeoGraphicsView allows you to create items and display them according to the current projection used.
  • Is able to deal with the special properties of a geographic coordinate system: This includes the behaviour around the dateline as well as the behaviour around the poles and bounding rects.


As a result it's not feasible to use QGraphicsView directly to create the GeoGraphicsView for several reasons:

  • The basic QGraphicsView API promotes pixel based positioning which must be avoided in a GeoGraphicsView at all cost in order to ensure that the semantic remains intact and that performance doesn't get heavily decreased. As the QGraphicsView API can't be changed we need to recreate the API.
  • The QGraphicsView API relies on QPainter, while we need to use the GeoPainter for the GeoGraphicsView.
  • The positions inside QGraphicsView get stored as members which is error prone as this can easily result in severe position synchronisation problems.
  • The BspTree inside QGraphicsView is pixel based (2 coordinates) while we need a lat-lon-alt BspTree.
  • Some projections map a single lat-lon-alt coordinate to several pixel positions. This is not possible in QGraphicsView.


There has been talk with people from Qt Software about the issues above. Some of the differences can be reduced. Most differences however will remain due to the very different nature of the targeted use case. By reducing differences we can however make it easier for developers to learn and understand both systems. If QGraphicsView and GeoGraphicsView would reach a point where they are close enough to each other it could even be considered that GeoGraphicsView would reuse the QGraphicsView implementation internally. However right now this rather looks unlikely.

About GeoGraphicsItems and SceneGraphicsItems

Marble knows two types of MarbleGraphicsItems: some items, the GeoGraphicsItems, have a position in geo coordinates, and others, the ScreenGraphicsItems, simply hover in front (or possibly behind) of the globe independant from the globes position.

An example of a GeoGraphicsItem is a placemark. An example of a ScreenGraphicsItem are the FloatItems like the small compass, which resides in the upper right corner of the MarbleWidget by default. By the way, to make it a littlebit more complicated (at least for us), ScreenGraphicsItems can be children of any MarbleGraphicsItem with a position relative to the position of the parent item.

It doesn't make sense to try to put both in the same scene. Managing the GeoGraphicsItems could be done in a GeoGraphicsScene. This would work exactly as described above. The ScreenGraphicsItems could be managed in a ScreenGraphicsScene. Perhaps it is possible to use a QGraphicsScene for this. All these Items should be rendered to the same view, the MarbleGraphicsView.

Using QGraphicsScene could lead to some problems, most of them are due to the fact that Qt developers probably don't expect that somebody messes in different ways in their code compared to what it was designed for. Perhaps it could be possible to switch between these two options.


Some benefits of QGraphicsView for marble

Some of the main benefits that we would like to take advantage of from the Qt Graphics View Framework are:

  • Simplified input event model
  • QGraphicsItems "know" how to draw themselves

The QGraphicsView input model integrates the passing of mouse events based on the position of the mouse event, passing mouse events down through a stack of items and the ability to have a standard implementation of Drag and Drop.

If you are not familiar with the Qt Graphics View Framework check out its documentation.

Also a problem with the current way things are done in marble is that we have adopted a QVariant style Typing system for the GeoData classes. This is very effective ( and very fast ) for the current implementation of marble but does not allow for extension of the system by 3rd party developers for things like plugins. If we adopt the QGraphicsItem system then we will be passing pointers to objects around which will adhere to the C++ Run-Time Typing System and will not lose any Class/Inheritance information when passed around the Marble system (e.g. passing from the GeoParser to the model).