Disclaimer

Installation

• Either you download one of the binaries from this page or from the sourceforge project page (click on the sourceforge button on the left of this page) or you get the source and compile it yourself. You can get the source from the sourceforge CVS. To compile it, you need to have the QT library installed. Then type (in the clientQT-directory, where the earth3d.pro file is)
  
  qmake earth3d.pro
  make
  
  to create the "earth3d"-binary. Start it with
  
  ./earth3d
  
  

Startup

• after startup, wait some seconds and then open the list on the left of the screen and load a view of the earth by double clicking it.
  

Mouse Navigation

• Click and drag the earth
• Use the mouse wheel to zoom in and out
• Use the middle button to look around
• On the right button you have a context menu
  

Keyboard Navigation

• To use these keys the focus must be on the 3D view. So you have to left-click once into the 3D area in the right part of the window before you can use these keys.
• A - Forward
• Y, Z - Backward
• S - Stop
• Cursor keys to roll and tilt
• X - turn left
• C - turn right
• PageUp - Up
• PageDown - Down
• F - Toggle fullscreen (but when you toggle back to non-fullscreen mode, be aware, that most function in the context menu (right mousebutton on the 3D-Window) will not work correctly)
  

Development of new visuals

• Maptree (a body mapped with a tree of textures, normally a sphere with a planet texture)
• POI (Point of Interest, points marked with small, clickable icons and a label)
• Scene (a hierarchical XML description of a textured scene containing multiple objects, used e.g. for the cloud layer or the small earth view in the corner of the window)

Example

In this example I will show how to add a new visual that displays a sphere at the coordinates 0N 0E. I will start with a patch file that shows what needs to be changed:

diff -uNr c2/clientQT/draw/treeDrawFactory.cpp c3/clientQT/draw/treeDrawFactory.cpp
--- c2/clientQT/draw/treeDrawFactory.cpp	2004-08-20 17:26:55.000000000 +0200
+++ c3/clientQT/draw/treeDrawFactory.cpp	2005-10-24 21:02:55.938611601 +0200
@@ -10,6 +10,7 @@
 #include "drawScene.h"
 #include "formview.h"
 #include "moveToPositionEvent.h"
+#include "treeDrawTest.h"
 
 using namespace std;
 
@@ -192,6 +193,9 @@
     if (type == QString("gpsmark")) {
       newDraw = tagGeometryGpsMark(geometryNode, newDraw);
     }
+    if (type == QString("test")) {
+      newDraw = TreeDrawTest::tagGeometry(geometryNode, newDraw);
+    }
 	  
     /* Insert Draw into GraphicsObjectsContainer */
     if (newDraw) {
diff -uNr c2/clientQT/draw/treeDrawTest.cpp c3/clientQT/draw/treeDrawTest.cpp
--- c2/clientQT/draw/treeDrawTest.cpp	1970-01-01 01:00:00.000000000 +0100
+++ c3/clientQT/draw/treeDrawTest.cpp	2005-10-25 06:55:27.936483050 +0200
@@ -0,0 +1,27 @@
+#define GL_GLEXT_PROTOTYPES
+#include "draw/treeDrawTest.h"
+#include 
+#include 
+#include 
+
+TreeDrawTest::TreeDrawTest() {
+  printf("TreeDrawTest new\n");
+}
+
+void TreeDrawTest::draw(Point3D *viewer, bool viewculling, QGLWidget *widget, Point3D direction, int phase) {
+  if (phase!=2) return;
+
+  printf("TreeDrawTest\n");
+  glPushMatrix();
+
+  // put a sphere at 0N, 0E
+  glTranslatef(-1,0,0);
+  glutSolidSphere(0.1, 10, 10);
+
+  glPopMatrix();
+}
+
+Draw *TreeDrawTest::tagGeometry(QDomNode geometryNode, Draw *newDraw) {
+  printf("TreeDrawTest tag\n");
+  return(new TreeDrawTest());
+}
diff -uNr c2/clientQT/draw/treeDrawTest.h c3/clientQT/draw/treeDrawTest.h
--- c2/clientQT/draw/treeDrawTest.h	1970-01-01 01:00:00.000000000 +0100
+++ c3/clientQT/draw/treeDrawTest.h	2005-10-24 21:02:23.360348103 +0200
@@ -0,0 +1,18 @@
+#ifndef TREEDRAWTEST_H
+#define TREEDRAWTEST_H
+#include "treeDraw.h"
+#include 
+#include 
+#include 
+#include "imageList.h"
+
+class TreeDrawTest : public Draw {
+ public:
+  TreeDrawTest();
+
+  static Draw *tagGeometry(QDomNode geometryNode, Draw *newdraw);
+
+  virtual void draw(Point3D *viewer, bool viewculling, QGLWidget *widget, Point3D direction, int phase);
+};
+
+#endif
diff -uNr c2/clientQT/earth3d.pro c3/clientQT/earth3d.pro
--- c2/clientQT/earth3d.pro	2005-09-09 18:25:20.000000000 +0200
+++ c3/clientQT/earth3d.pro	2005-10-24 21:02:36.321065932 +0200
@@ -67,7 +67,7 @@
 # QMAKE_CXXFLAGS_DEBUG += -D EARTH3DDEBUG
 CONFIG	+= qt thread opengl warn_on release stl
 
-# LIBS	+= -lglut
+LIBS	+= -lglut
 # DEFINES	+= STATISTIC_NODECOUNT
@@ -122,6 +122,7 @@
 	tree/textureTreeNodeCore.cpp \
 	draw/draw.cpp \
 	draw/treeDraw.cpp \
+	draw/treeDrawTest.cpp \
 	draw/treeDrawSphere.cpp \
 	draw/treeDrawPOI.cpp \
 	draw/treeDrawPOISign.cpp \

(Download it here: treeDrawTest.patch download).

In case you do not know how to read a patch file, here is a short explanation:

In this patch file several files were compared, each section starting with "diff -uNr...". Lines that start with "+" have to be added, lines with "-" removed. The other lines are to find the location in the file where to add or remove the "+" and "-" lines. To apply the patch to the project, change into the "clientQT" directory and call "patch -p1 < treeDrawTest.patch".

Now back to the example: We will create a new visual with the geometry type "test" (this will be explained later). We will add two files, treeDrawTest.cpp and treeDrawTest.h.

Lets go through the patch file step by step:

• In the file draw/treeDrawFactory the new header file "treeDrawTest.h" is included and three lines are added to the XML parser. They look for a geometry tag with the type "test" and then call our new class.
• The file treeDrawTest.cpp is added. It is a minimal example that only consists of three functions:
  • An empty constructor.
  • A draw method. It gets the current viewpoint (viewer), if viewculling should be used, the QT OpenGL widget (widget), the direction in that the camera looks (direction) and the drawing phase. Normal objects should use phase 2 to draw themselves, otherwise they could confuse mouse navigation, which needs the correct Z values for earth's surface.
    This draw method moves the coordinate system to (-1,0,0) and draws a sphere with radius 0.1 and 10x10 slices using GLUT in the current color. The earth's radius is 1 so it will be on the surface at 0N 0E.
  • The tagGeometry method called in treeDrawFactory to parse the "test" geometry node of the XML document. In our case we will not parse it, but return always a new object of our class.
• The file treeDrawTest.h is added. It inherits our new class from Draw and adds the three methods we already know from treeDrawTest.cpp.
• The library "glut" and the file treeDrawTest.cpp are added to QT's project file.

That are all necessary code changes. To use it, you need two XML files you can load. I will explain them later. The interesting part is in geometry.mxml:

<geometry type="test" name="Test object">
</geometry>

This defines a geometry that will create our visual of type "test".

After applying these changes compile the executable with

qmake earth3d.pro
make

Now download the files service.sxml and geometry.mxml in a ZIP file (geom.zip) and extract them into one directory. Load the service.sxml using the "Add service" icon at the top left of the window. In the tree view on the left our "Test object" should appear. Load it by double clicking it. If you have also loaded a view of the earth you should get a view similar to this:

Using the server software

The server software can be used to integrate own maps. It is currently available as source via CVS. A windows binary was released on request on 29.11.2005 and is available from here: earth3d_server_windows_1.zip. Please also read the corresponding paragraph in the FAQ on www.earth3d.org.

The server is not intended to be used by normal users since it is only command line based. It needs the libtif, libxml2, libpng12 and QT to compile. The source code for the windows version (or the patches to allow the normal version to compile under windows). are not yet available.

Example how to use the server software: You start with an empty map. The lines to add the initial Blue Marble (NASA) data look like this: