Introduction

In this tutorial, we will guide you through the process of creating a map theme based on tiled images, where these images are used as a texture for the earth and are available in different resolutions for each zoom level.

The basic steps you have to take are as follows:

Create a new folder for your map theme

You must first decide whether you want your map theme to be visible for all users or only for the local user. Depending on your decision, the table below tells the path for you new map theme:

Path for Map Theme
OS	Linux	Windows
all users	/usr/share/apps/marble/data/maps/earth/$YourMapTheme	c:\Programs\Marble\data\maps\earth\%yourmaptheme%
local	~/.local/share/marble/data/maps/earth/$YourMapTheme	c:\users\%username%\local\.marble\data\maps\earth\%yourmaptheme%

Create the Root Image

Inside $YourMapTheme, create a sub sub folder named "0/0" (mkdir -p 0/0).

Figure out the file format of the tiles and create an image with the correct file extension in the sub sub folder you just created. The content of the image is not important but make sure that the file extension is in lower case and that its dimension matches those of the tiles.

Create the Preview Image

The preview image will show up in the map view of the navigation panel.

Create an image in $youmaptheme, e.g. preview.png.

Create a DGML file describing your map theme

Save the following template into a file named $YourMapTheme.dgml inside the $YourMapTheme folder.

<?xml version="1.0" encoding="UTF-8"?>
<dgml xmlns="http://edu.kde.org/marble/dgml/2.0">
    <document>
        <head>
            <name>$YourMapName</name>
            <target>earth</target>
            <theme>$YourMapTheme</theme>
            <icon pixmap="$PreviewImage"/>
            <visible>true</visible>
            <description><![CDATA[$YourMapDescription]]></description>
            <zoom>
                <discrete> true </discrete>
                <minimum> 900 </minimum>
                <maximum> 3500 </maximum>
            </zoom>
        </head>

        <map bgcolor="#000000">
            <canvas/>
            <target/>
            <!-- insert layers here -->
        </map>

        <settings>
            <property name="coordinate-grid">
                <value>true</value>
                <available>true</available>
            </property>
            <property name="overviewmap">
                <value>true</value>
                <available>true</available>
            </property>
            <property name="compass">
                <value>true</value>
                <available>true</available>
            </property>
            <property name="scalebar">
                <value>true</value>
                <available>true</available>
            </property>
        </settings>

        <legend>
            <section name="coordinate-grid" checkable="true" connect="coordinate-grid" spacing="12">
                <heading>Coordinate Grid</heading>
            </section>
        </legend>
    </document>
</dgml>

Create some metadata for your theme

Replace the following variables inside the DGML file:

$YourMapTheme
The folder name of your new theme.
$YourMapName
The that name will show up in the map view.
$YourMapDescription
The description that will appear in a tool tip and may contain HTML formatting.
$PreviewImage
The file name of the preview image you before.

Define the Main Texture Layer

Add this snippet inside the <map> tag in the dgml file and replace the variables according to the instructions below.

<layer name="$YourMapTheme" backend="texture" >
    <!-- Schedule a re-download of tiles which are older than one year,
         that is 31536000 seconds. -->
    <texture name="map" expire="31536000" >
        <sourcedir format="$FileExtension"> earth/$YourMapTheme </sourcedir>
        <storageLayout levelZeroColumns="1" levelZeroRows="1" maximumTileLevel="19" mode="$IndexingScheme" />
        <projection name="$Projection" />
        <downloadUrl protocol="http" host="$Host" path="$Path" query="$Query" />
    </texture>
</layer>

$YourMapTheme
Since this is the main layer, Marble requires this layer to be named the same as the map theme.
$FileExtension
The file extension you figured out when creating the root image.

The remaining variables provide information about the remote server. Since there seems to be no common agreement of how tiles are layed out on different web services, Marble provides many options. Thus, this topic needs some explaination.

In the <downloadUrl> tag, you specify how Marble will request tiles from the remote server. The $Host, $Path, and $Query variables are used to create request URLs.

A key variable is $IndexingScheme, since it needs to fit the tile indexing scheme on the server. There are several indexing schemes Marble supports:

Marble
OpenStreetMap
Appends <zoomLevel>/<x>/<y>.$FileExtenstion to $Path.
Custom
Marble will substitute the following variables anywhere in the $Path and $Query variables:
- {zoomLevel}
- {x}
- {y}
WMS (Web Map Service) - not yet available

Replace the following variables according to the instruction above:

$IndexingScheme
$Projection
URL parameters: $Host, $Path, $Query