# The &marble; Handbook

Torsten Rahn

    &Torsten.Rahn.mail;

Dennis Nienhüser

    earthwings@gentoo.org

2005 2006 2007 &Torsten.Rahn;
2010 Dennis Nienhüser
&FDLNotice;
2010-05-27
0.10

&marble; is a geographical atlas and a virtual desktop globe which lets you quickly explore other places on our home planet. You can use &marble; to look up places, to easily create maps, measure distances and to retrieve detail information about locations that you have just heard about in the news or on the Internet. The user interface is clean, simple and easy to use.

KDE education earth globe geography marble

## Introduction

&marble; logo
&marble; logo

Welcome to &marble;, a small interactive globe and geographical atlas that puts the world at your fingertips. Just like a real atlas or a conventional globe &marble; allows you to freely move across its map and lookup places. Furthermore &marble; allows you to zoom in and have many different views on the surface of the Earth. In its default configuration &marble; offers 11 different views: Atlas, OpenStreetMap, Satellite View, Earth at Night, Historical Map 1689, Moon, Plain Map, Precipitation (December), Precipitation (July), Temperature (December) and Temperature (July).

&marble; comes with a small database of more than 12,000 locations (cities, mountains, volcanoes) which can be searched for and which are partially integrated with the popular Internet encyclopedia Wikipedia. Additionally you can measure distances using &marble; between multiple measure points which can be set freely.

&marble; is free software and licensed under the &GNU; Lesser General Public License.

## &marble; quick start guide: Navigation

Here is &marble; the first time you run it, either with Applications Edutainment Science Desktop Globe Marble from the &kmenu; or with &Alt;F2 and entering `marble` into the field.

&marble; main window
&marble; main window

On the right you can see a topographical map of our beautiful home planet. To allow for better orientation the map offers a scale bar in the lower left corner as well as a windrose on the top right. To navigate and to control the view you can use the tools on the Navigation tab at the left: Press the arrow buttons to rotate the globe. The Up and Down arrow buttons will tilt the earth axis back and forth. The Left and Right arrow buttons will make the earth spin around its physical axis.

You can accomplish the same behavior by pressing the &LMB; somewhere on the globe and by moving the mouse while keeping the &LMB; pressed. Using this drag and drop style navigation will allow you to adjust the viewing angle much easier and more precisely. The cursor keys on your keyboard offer another alternative way to quickly change directions.

Zoom in and out by moving the vertical slider up and down. If your mouse has got a mouse wheel you can use that one instead - or you just hold the &LMB; and the &RMB; down both at once while moving the mouse up and down. Changing the zoom level step by step can be done via the Zoom In and Zoom Out buttons which are placed above and below the zoom slider (or using the + and - keys on your keyboard).

Depending on the map's resolution zooming in will provide you with more detail. Smaller cities will appear and using the topographic map you might notice that coastlines are provided as vector graphics.

In case you should get lost you can always reset the viewing angle and zoom level back to the point where we started off: Just hit the Home button (or the Home button on your keyboard). To set a home location click with the &RMB; on a location in the maps and select Set Home Location in the context menu.

A click onto the status bar using the &RMB; offers a menu which lets you customize the appearance of the status bar. You can show the position, altitude, the current tile level and a progress indicator that displays the status of the map data download.

## Choosing different map views for &marble;

&marble; comes with 11 different views: Atlas, OpenStreetMap, Satellite View, Earth at Night, Historical Map 1689, Moon, Plain Map, Precipitation (December), Precipitation (July), Temperature (December) and Temperature (July). You can choose among these by pressing the Map View tab on the bottom of &marble;'s toolbox:

&marble; map views
&marble; Map Views

- Atlas: A classic topographic map. It uses vector lines ( "MicroWorldDataBase II" ) to mark coastlines, country borders &etc; and bitmap graphics ( "SRTM30" ) to create the height relief.

- OpenStreetMap: A global roadmap created by the OpenStreetMap (OSM) project. OSM is an open community which creates free editable maps. The OSM data was rendered using Mapnik.

- Satellite View: Earth as seen from Space. The map is based on NASA's beautiful "Blue Marble Next Generation" pictures. Credits: NASA’s Earth Observatory

- Earth at Night: This image of Earth’s city lights was created with data from the Defense Meteorological Satellite Program (DMSP) Operational Linescan System (OLS).

- Historical Map 1689: A historical world map from the year 1689 created by G. van Schagen in Amsterdam.

- Moon: A map of the moon. The map is based on data from the Clementine Moon mission (UVVIS Basemap Mosaic). Credits: NASA/SDIO, Courtesy USGS Astrogeology Research Program.

- Plain Map: A plain map. It uses vector lines to mark coastlines and country borders &etc;

- Precipitation (December): A map which shows the average precipitation in December.

- Precipitation (July): A map which shows the average precipitation (rain/snow/hail/etc) in July.

- Temperature (December): A map which shows the average temperature in December.

- Temperature (July): A map which shows the average temperature in July.

## Searching places using &marble;

&marble; comes with a small database of more than 12,000 cities ( from http://www.worldgazetteer.com ) and a few mountains and volcanoes. You can find a location by entering its name into the search line on the top of the toolbox. If you're unsure about the spelling (&marble; always uses the native name in latin letters) you can choose the location browser below the search line as well: A double click on the respective entry will instantly display the matching place on the map.

&marble; searching places
&marble; Searching Places

Once you found your city on the map you can click on its label or its symbol using the &LMB;. A popup menu will appear which allows you to retrieve more information about the city. This popup menu can also be used to find out the coordinates for any point on the globe as the coordinates always get displayed at the bottom of the popup menu. After clicking the name of the location on the popup menu a data sheet dialog will appear, like this:

&marble; Data Sheet
&marble; Data Sheet

On the first tab of the dialog some very basic data is provided, like the name, coordinates and flag of the country the place belongs to. In addition, population numbers for cities get shown, as well as the elevation for mountains. If your computer is connected to the Internet and if you're online &marble; will try to connect to the popular Internet encyclopedia Wikipedia. If a matching Wikipedia article is available &marble; will display it on the second tab of the dialog.

## Find your way with &marble;

Besides searching for places, &marble; can display possible routes between two or more of them. Do you want to plan a bicycle tour in the nearby wood? Need driving instructions to get to an address in a foreign city? Click on the Routing tab on the bottom of &marble;'s toolbox to start planning your trip.

### Creating a new Route

In the Routing tab you'll see two green buttons A and B. Enter the start address in the input field next to the A button, the route start input field. Press &Enter; or click on the Search button to find matching placemarks. A small progress animation will shorten your waiting time while the search is running. Using the search term Weavers Lane, London, the result will look similar to the screenshot below:

&marble; address search
&marble; Searching Addresses

Matching placemarks line up in the list below the input fields. They're also shown in the map. The first result is automatically selected as the route start. In the map, this position is indicated using the same A icon as the button next to the route start input field. If the first result is not your desired route start, click on any other result to make that the new start position. You can either click on it in the result list or on its icon in the map to achieve that. The currently chosen route start is always indicated using the A icon.

With the route start at hand, let's move on to enter the destination of our trip. The procedure is the same: Enter the destination address in the input field next to the B button, press &Enter; and select the desired item among the result list.

Did you notice that the Search button is now gone and replaced by a Get Directions button? &marble; is signalizing that all information needed to calculate a route has been entered correctly. Click on the Get Directions button to retrieve a suitable route now. If your destination search term is Sun Walk, London, the result will resemble this screenshot:

&marble; route result
&marble; Displaying a Route

If the start (or destination) position is already visible on the screen, you may find it more convenient to select it directly in the map. To do that, click on the A (or B) button next to the input field. Once clicked, the map input mode is activated: The next click on a position in the map will become the start (or end) of your trip. The mouse cursor turns into a cross to ease an accurate selection. The selected position will be included in the route and marked in the map. Please note that you need to clear any previous placemark using the Remove button right to the input field in order to be able to activate the map input mode. To abort the selection, either click on the button again or press &Esc;.

The best route to take depends on the type of vehicle you plan to use (if any). You can tell &marble; about this and other settings in the routing Options. Clicking on the Options next to the Get Directions button, you can choose between car, bicycle and pedestrian routing. Car routing is subdivided into a fastest and a shortest mode. The former minimizes the route duration and the latter minimizes the route length. Furthermore you can specify to avoid highways or toll roads (only applicable to car routing). Clicking on the Options link a second time hides the route preferences. Make sure to click on the Get Directions button to update the route after changing settings.

### Adjusting Routes

&marble; let's you modify several aspects of the route for fine-tuning: Change route options, insert via points, move or remove existing points. The modification of route options has been discussed in the previous section already; we'll concentrate on point management now.

Inserting via points is done by drag-and-drop in the map. Every time you move the mouse pointer above any part of the route (except above existing trip points), a green flag icon appears to indicate that it is possible to insert a via point. To start the insert operation, click with the &LMB;. Move the mouse pointer to the desired new position while keeping the &LMB; pressed. Blue lines from the neighboring via points to the new position will appear:

&marble; route adding via points
&marble; Inserting a via point

The new via point will be inserted between the existing neighbor via points once you release the &LMB;. At the same time the existing route is painted dotted to indicate that it contains outdated information. In the background, a new route is prepared which will replace the outdated one automatically.

It is also possible to add via points before the start or after the end of the route. To do that, follow the instructions above for inserting a new via point, but press &Ctrl; while moving the mouse. One blue line from the start or the end of the route appears. Its origin indicates where the new via point will be appended.

Existing via points can be moved freely across the map. Move the mouse pointer above a via point and drag it to its new location. Once released, the route will be updated automatically.

To exclude via points from the route, remove them. This can be done using either the Remove button next to the via point input field or by clicking with the &RMB; on the via point in the map. In the context menu, choose Remove this destination. To start an entirely new route, remove all via points.

### Exporting Routes

Routes planned in &marble; can be used in other applications or navigation devices which support gpx (GPS eXchange Format) or equivalent formats. If your navigation device does not support gpx directly, you can use a conversion utility like gpsbabel to convert a gpx file exported by &marble; to a suitable format.

The export of a route in &marble; is initiated from the routing context menu in the map. Click with the &RMB; on any point of the route in the map. In the context menu that appears, choose Export route...:

&marble; route export
&marble; Exporting a Route

Enter the desired filename in the upcoming save dialog. The filename extension should be gpx.

## Measuring distances with &marble;

As mentioned already &marble; always displays a dynamic scale bar on the lower left to estimate distances on the map. Together with the windrose in the top right corner these overlays are provided for better orientation. But there's more: &marble; allows you to measure distances between two or more points on earth. To do so click the respective points in correct order on the globe using the &RMB;. On each click a popup menu will appear which allows you to add a measure point (Add Measure Point) or to remove all measure points altogether (Remove Measure Points):

&marble; measuring
&marble; measuring distances

Once you have added at least two measure points, the total distance will be displayed in the top left corner of the map. &marble; will assume a spherical earth for all measurements which should be accurate enough for most cases.

## Download Map Regions

Pre-installed with a set of maps, &marble; is ready to use. When you zoom in at places, more detailed parts of the current map theme are downloaded in the background. This works excellent whenever an Internet connection is available. What to do, however, when traveling to a foreign city where no constant Internet connection is available to download maps? Plan ahead and download those map regions you are going to use.

To understand what needs to be downloaded to display certain parts of the map offline, let's briefly look into the concept of tiles which &marble; uses internally. A tile is an image which corresponds to a certain part of the map. Tiles are arranged by &marble; next to each other to form the map image that is displayed to you. Depending on the selected projection mode, tiles are arranged to form a rectangle (Flat Map Projection, left) or a sphere (Globe Projection, right):

&marble; projections
Tiles at Level 1 in Flat Map (left) and Globe Projection (right)

Zooming in at this view, more details need to be displayed. The tiles shown in the two screenshots above are too coarse then; &marble; automatically recognizes this and changes to the next tile level where images provide more details. This keeps going: The more you zoom in, the higher the tile level. The following sketch illustrates the different number of tiles (colored) corresponding to the same map region at different tile levels:

&marble; tile levels
Different Tile Levels in &marble;

When downloading a map region for offline usage, you need to download all tiles in the desired region for all tile levels you plan to use. Because of the connection between tile levels and zoom levels, you can think of it as downloading all tiles in the zoom levels you plan to use.

To accomplish this for a certain region, make that region visible in the screen by zooming and moving the Globe. Now open the Download Region... dialog in the File menu. Keep the Visible region option selected to download those tiles that correspond to the map region visible in the screen. Next, select the tile level range (zoom range) you wish to download. The first field corresponds to the smallest, the second field corresponds to the largest tile level that will be downloaded. Tile levels in between will be downloaded as well. &marble; shows how many tiles (images) need to be downloaded and updates this number whenever you change the region or tile level range.

&marble; Download Region dialog
&marble;'s Download Region dialog

The tile level corresponding to the current zoom level is shown in the status bar on the bottom. Please note that you may have to configure Marble to show that information: Click with the &RMB; on the status bar and select Show Tile Zoom Level.

Select OK to trigger the map region download. The progress bar of &marble; will show the download progress (if activated).

In case you do know the coordinates of the map region to download, you can enter them by clicking on the Specify region option. The map region visible in the screen will be ignored in that case.

You can keep using &marble; while the Download Region dialog is open. This is useful to queue several downloads for different regions or different tile ranges. Just select Apply instead of OK to trigger the map region download.

## Command Reference

### Menus and shortcut keys

#### The File Menu

&Ctrl;O File Open...

  Opens a map file.

&Ctrl;N File Download Maps...

  Displays the Get Hot New Stuff! dialog to download additional maps for &marble;, among others maps for Mars and Venus.

File Download Region...

  Displays the Download Region dialog to download map data in different zoom levels for offline usage. See Download Map Regions for details.

&Ctrl;S File Export Map...

  Exports a screenshot of &marble;'s map to an image file.

&Ctrl;P File Print...

  Prints a screenshot of &marble;'s map.

File Work Offline

  If this option is selected &marble; will no longer download map data from the Internet. The search feature gets restricted to the local database. New routes cannot be retrieved.

&Ctrl;Q File Quit

  Quits &marble;

#### The Edit Menu

&Ctrl;C Edit Copy Map

  Copies a screenshot of &marble;'s map to the global clipboard.

Edit Copy Coordinates

  Copies the current coordinates to the global clipboard.

#### The View Menu

View Current Location

  Toggle the display of the location page in the left panel. If a GPS device is connected with your computer, &marble; displays longitude and latitude of your current location.

View Crosshairs

  Toggle the display of a simple crosshair in the center of the map.

View Info Boxes

  In this submenu you can to lock the position of the infoboxes and show or hide the plugins you have enabled in the Plugins page of &marble;s configuration dialog.

View Online Services

  The Wikipedia plugin displays georeferenced Wikipedia articles as an icon on the map. A click onto the icon launches a browser window that displays the referenced site. The data is provided through a webservice via GeoNames.org. Likewise a Photos plugin currently provides photos via the FlickR photo sharing site

View Clouds

  Show real-time cloud cover. A real-time cloud map that gets updated every 3 hours. It uses GOES, METEOSAT, and GMS satellite imagery downloaded from the Geostationary Satellite Imagery page at Dundee University. Credits: Hari Nair, Xplanet Project

View Atmosphere

  Show the diffuse reflection of the atmosphere around the earth.

View Sun Control...

  Displays the Sun Control where you can set date and time, the simulation time speed, the Sun Shading and center the map on sun position.

#### The Settings Menu

Settings Show Toolbar

  Toggle the display of the toolbar.

Settings Show Statusbar

  Toggle the display of the status bar.

F9 Settings Show Navigation Panel

  Toggle the display of the navigation panel on the left side of the main window.

&Ctrl;&Shift;F Settings Full Screen Mode

  Switches between normal view and full screen view. In full screen view, the titlebar is hidden and the actual application window is resized to the entire screen.

Settings Configure &marble; Desktop Globe...

  Display the &marble; configuration dialog.

#### The Help Menu

&help.menu.documentation;

## Configuring &marble;

### View Configuration

The View configuration dialog
The View configuration dialog

Distance

  The unit that gets used to measure altitude, lengths and distances (⪚ km, mi, ft).

Angle

  Specifies the notation of angles in coordinates: By default the Degree-Minute-Second notation (⪚ 54°30'00" ) gets used. As an alternative you can choose decimal degrees (⪚ 54.5°).

Still image

  Specifies the map quality that gets displayed while there is no user input. Usually this allows for high map quality as speed is no concern.

Graphics system

  Specifies the graphics system - Native X11 or Raster (Software rendering) - that &Qt; uses to draw the map. Changing this setting might be a good idea if there are performance issues with the system's graphics drivers.

During animations

  Specifies the map quality that gets displayed during map animations (⪚ while dragging the globe). Especially on slow machines it is advisable to set this option to Low Quality as this will give better speed.

Place names

  Places often have different names in different languages. The label on the map can show the name in the user's language. Alternatively it can display the name in the official language and glyphs of that place.

Default map font

  The default font that gets used on the map.

### Navigation Configuration

The Navigation configuration dialog
The Navigation configuration dialog

Drag location

  While dragging the mouse there are two standard behaviors when dealing with a virtual globe: The location below mouse pointer will follow the cursor exactly: As a result ⪚ the north pole will not stay at the top which can lead to confusion. By default Marble makes sure that north is always up which results in a dragging behavior where the location below the mouse pointer slightly "detaches" from the cursor.

On Startup

  By default Marble will display the home location immediately after the application has started. As an alternative it can also show the last position that was active when the user left the application.

Animate voyage to the target

  When searching for a location Marble can either move instantly to the new location or it can show a travel animation from the previous place to the new place.

### Cache & Proxy Configuration

The Cache & Proxy configuration dialog
The Cache & Proxy configuration dialog

Cache

  There are two caches being used for &marble;: The physical memory which is needed to keep map data in the computer's memory. Increasing the value will make the application more responsive. The hard disc memory cache is used by download contents from the Internet (⪚ Wikipedia data or map data). Decrease this value if you want to save space on the hard disc and if high usage of the Internet is not an issue.

Proxy

  Proxy settings for your local intranet. Please leave empty if there is no proxy.

### Plugins Configuration

The Plugin Configuration widget is the place to activate (or deactivate) Info Boxes, Online Services and other plugins that affect the look of &marble;. Active plugins appear in the View menu where you can toggle their visibility.

The Plugins configuration dialog
The Plugins configuration dialog

Each plugin can be activated and deactivated using the checkbox on the left. Some plugins provide further configuration options which are accessible by clicking on the tool icon on the right.

Amateur Radio Aprs Plugin

  Retrieves data from the Automatic Packet Reporting System via the Internet, a file or a serial device. The position and status of data senders is displayed in the map and updated in real-time.

Compass

  Shows a compass in the map

Crosshairs

  Enable this to display a small crosshair in the center of the map.

GeoRenderer Plugin

  This plugin draws the map content (e.g. provided via a KML file).

Coordinate Grid

  A plugin that shows a coordinate grid.

Scale Bar

  This is a float item that provides a map scale.

Navigation

  Displays the mouse control to zoom and move as float item on the map.

Overview Map

  This is a float item that provides an overview map.

Photos

  Automatically downloads images from around the world in preference to their popularity.

Download Progress Indicator

  A pie chart on top of the map that shows the progress of ongoing downloads.

Stars Plugin

  A plugin that shows the Starry Sky.

Weather

  Downloads current weather information of cities and displays them in the map.

Wikipedia Articles

  Automatically downloads Wikipedia articles and shows them on the right position on the map.

## Questions and Answers

I cannot see my house on the map / Why should I use &marble; if there is Google Earth already?

&marble; aims to be a lightweight fast educational geographical browser that easily runs on any platform that is supported by &Qt;. While higher resolution maps would be nice to have they aren't necessary for every user and every use case (just like you don't use a full blown text processor each time you just need a simple editor). Also notice &marble; is free software and is based on data that can be freely redistributed in the same way that applies to Free Software.

Why is &marble; so fast although I don't have hardware acceleration enabled? / Why doesn't &marble; run smoothly on my expensive 3D graphics card?

Despite depicting the earth as a globe &marble; doesn't make use of any 3D hardware acceleration. This has the advantage of running at a decent speed on any platform and hardware supported by &Qt;. However it has the disadvantage that it doesn't run as smoothly as it could if it used hardware accelerated OpenGL. &marble; just uses plain 2D graphics and therefore requires a graphics adapter that is fast at drawing 2D graphics. We plan to add an optional OpenGL backend in the future.

Will I ever have to pay for &marble;?

No, never. But the authors always welcome feedback. &marble; is licensed under the LGPL, so you will never have to pay for this program.

How can I contribute?

&marble; is not only an application but also a Free Software project. As such it's easy to join: just contact us via the kde-edu mailing list (kde-edu@kde.org).

## Credits and License

&marble;

Program Copyright, 2005-2007 &Torsten.Rahn; &Torsten.Rahn.mail;

Contributors:

- &Torsten.Rahn; &Torsten.Rahn.mail;

- Inge Wallin inge@lysator.liu.se

&underFDL; &underLGPL;

## Installation

### How to obtain &marble;

&install.intro.documentation;

### Requirements

&marble; itself can be found on the &marble; home page and is part of the &kde;-Edu project

You can find a list of changes in the file `ChangeLog` in the distribution of &marble;.

### Compilation and Installation

&marble; can be compiled as a &Qt; 4-only version as well as featuring &kde; 4 support. To compile &marble; with &Qt; 4-only support check out &marble; from &kde; SVN into ~/marble and just do: `cmake -DQTONLY=ON ~/marble` and `sudo make install`. To compile &marble; with &kde; support check instructions on how to compile &kde; applications at &kde;'s TechBase.

&documentation.index;