Design your map

Changing the style of the world

The look of eeGeo 3D Maps’ can be entirely customised. We provide the ability to complete change all of our textures to suit your applications needs. We provide a few out of the box examples to show you how to theme our World.

In this section:

Themes Overview

To change the look of our World, the platform supports ‘Themes’. A Theme is a specification of how the world should be visualised. There are many different settings that can be specified in a Theme. For instance, the textures that are applied to the buildings, roads, terrain etc are specified in a Theme along with the lighting and shadow settings for different times of day.

Here’s just some of the settings that a Theme can include:

  • Texture pages, for buildings, roads, rail, terrain, trees, water.
  • Lighting constants, for our key, back, fill and ambient lights.
  • The colour of the shadows cast by buildings.
  • The colour, altitude and density of the fog in the environment.
  • The colour and intensity of the glow emitted by roads at night.
  • Whether vehicles drive on the left or right hand side of a road
  • The texture, color and animation speed of the full screen overlays used in various weather effects.
  • A latitude and longitude, specifing the location on the planet where to apply the theme

Default Themes

The default Theme manifests provided with the platform give your app “out of the box” Themes for:

  • Different areas of the world such as; San Francisco, Japan, New York
  • Weather Conditions such as; snowy, foggy, rainy
  • Times of day such as: day, night, dusk, dawn
  • Seasonal variations such as: spring, summer, autumn, winter

Whilst, by default, the platform uses Themes to specify visuals for the categories in the above list, you can use Themes to achieve much more – including completely changing the style of the World.

The platform does the work of applying Themes to the world, but it is the App that decides which Theme is applied and when. For instance, an App might decide to apply different Themes based on the location of the camera. This would allow different areas of the to be a given a particular look. e.g. to make London look different to San Francisco. Another possibility is that the App could drive the choice of Theme based on user choice. For instance the App could present the user with a menu of different looks to choose from, much like choosing the wall paper image in a desktop operating system.


By default, the platform points to a default Theme Manifest file, with a URL of the form, where the version number changes from time to time as the default Themes are updated. This manifest file describes the default Theme configuration that Apps can choose to use without modification. In order to change the style of your app, you create your own manifest file, upload it somehwere, and direct your application to this manifest file instead of the default one provided by the platform.

Simply pass the URL to your theme manifest file when asked, i.e.:

If you wish to change themes, we strongly recommend starting with the platform default manifest Default Manifest file and working from there. The rest of this documentation explains the purpose of the settings that are specified in the Theme manifest.

Github Repositories

The manifests for the platform default Themes and the textures they reference are available in two Github Repositories.

You can use these as a starting point to develop your own visual style for your app to use. For the environment themes, simply upload them to a CDN, and point your Manifest to the appropriate URLs.

Theme States

When the App invokes a particular Theme, the platform will load all of the textures associated with that Theme into memory. The first time a Theme is loaded the textures will be loaded over the Internet using HTTP. On subsequent ocassions the Theme textures will be loaded from the platform’s cache in much the same as map data for a particular area is loaded from cache after it has been visited for the first time.

Because the loading of Themes can be time consuming, particularly when loading for the first time, the platform provides a mechanism to allow apps to organise their Theme data in such a way that the number of loads can be reduced. This mechanism is known as Theme States.

Each Theme is divided up into a number of named States. Each State is simply a block of visual settings that can be applied to world. When a Theme is loaded, all of the textures associated with that Theme, across all States are loaded into memory at once. The app is then free to switch between States within that Theme without incurring any load delay. In order to make best use of this feature, Apps should arrange their various visual settings into Themes and States in such a way that visual changes that occur frequently are specified as different States within a Theme. Visual changes that occur less frequently should be divided into seperate Themes.

The default Theme manifests provided with the platform are organised like this. Visual changes associated with particular areas of the world and seasons are specified as Themes because they change rarely (just 4 times a year in the case of seasons!). Visuals associated with different weather conditions and times of day change more frequently, so they are organised as seperate States within Themes. Consequently, the Theme manifest is organised something like this:

The second key driver for organising visual effects into States is to allow for smooth transitions between them. Following a Theme change, the new visuals are applied with a “hard switch” as soon as loading of the Theme data is complete. When changing between States within a Theme, the platform can perform an blended transition from one set of visuals to the other.

For instance, if “Day” and “Night” are specified as different States in the same Theme a change from “Day” to “Night” would result in a smooth transition of the lighting and texture settings over a few seconds.


The lighting can be controlled through the platform API, but the Themes can also configure lighting. We have four lights:

  • Key – A directional light, the light from the Sun, and also the direction in which shadows are cast
  • Back – A directional light, the inverse of the Key light
  • Fill – A directional light, from directly above, i.e. look directly up from the surface of the planet
  • Ambient – The ambient light

You can change the lighting values for each State in the Manifest, like so:

The values are R,G,B, in the range 0.0 – 1.0 i.e. full white would be [255/255=1.0,255/255=1.0,255/255=1.0]


As with lighting, fogging can be controlled through the platform API, but the Themes can also configure fogging on a per-state basis via the manifest file. The fogging parameters are as follows:

  • FogColor – The color of the fog, specified as an RGB array with each component in the range 0.0 – 1.0
  • FogIntensity – The “thickness” of the fog. A value of 0.0 signifies no fog.

The example below shows how fog parameters can be set for a particular State in a particular Theme.


The color of the shadows can be set on a per-State basis as follows:

The shadow color given in the manifest is subtractive, hence larger values give darker shadows.

Light Maps

The terrain tiles in the platform’s map data have a pre-computed light map associated with them. This light map represents the glow from building windows and street lights at night time.

The color and intensity of this light map can be set on per-State basis as follows:

Where LightMapColor gives the RGB color of the glow and LightMapIntensity specifies the “strength” of the glow. As before, RGB values are specifed in the range 0.0 – 1.0.

In cases where LightMapIntensity is 0.0, the terrain is rendered more efficiently as light maps can be omitted from the rendering process.


Themes can contain information about the different vehicle types that are present in the app.
There are 3 categories of vehicles: cars, trains and planes. The theme manifest contains a section for each of these categories, containing a list of vehicle types belonging to each category.
You can specify the following attributes for a vehicle type in each theme:

  • Model node name in the POD file
  • Model scale
  • Speed
  • Model node name and length of each carriage model: Engine, Middle and Tail (trains only)
  • Number of carriages (trains only)
  • Roads/railway category the vehicle is allowed on (cars and trains only)
  • Side of the road to drive on
  • Spawn chance
  • Minimum distance between spawns

Texture formats and naming

All texture names specified in the manfiest file are specified relative to a root URL and without file extension. The root URL which prefixes all texture names can be specified seperately for Android and Apple IOS platforms. This allows you to keep all the assets for a particular operating system in a common directory like this:

For iOS the platform expects PVR textures, and for Android we KTX textures are used. You can convert from PNG to these formats using the following PVRTexTool commands:

In order to minimize the size of texture data transferred across the network we recommend that textures are gzip compressed. This is entirely optional and consequently the manifest allows the file extension for textures to be specified as follows:

The URL that a texture is loaded from is formed by concatenting the root URL, texture name and file extension. By way of example, consider an Android app working from the following manifest:

In this case the full URL that would be loaded for “TerrainTexture0_LOD” would be:

Building Textures

Our building texture page, unsurprisingly textures the buildings. The platform default themes specify different versions for Day, Night and Snowy. The textures have the following layout:

building texture

The Texture Page has the following layout:

Building Atlas


  • Orange (SW0 – SW7): Short walls (used when all buildings in grouping are 3 floors or less)
  • Green (TW0 – TW11): Tall walls
  • Yellow / Blue (R0 – R13): Roofs
  • Purple (JW0 – JW7): Roof-junk walls
  • Pink (JR0 – JR7): Roof-junk roofs

Short walls

Top row (SW0-SW3) – can split into 2 parts; 2nd row (SW4-SW7) – can split into 3 parts

Roof mapping: columns map to similar column in yellow range R0-R3 (eg SW2 and SW6 both use R2)

Probability weighting:
1st column x4;
2nd column x2;
3rd and 4th columns x1
(eg SW0, which is in the 1st column, is 4 times more likely to be used than SW3, which is in the 4th column)

Roof junk mapping: SW[x] uses JW[x] for sides, JR[x] for tops (eg SW5 will use JW5 and JR5)

Tall walls

Horizontal splits: First 3 columns can be slit into 4; 4th column is never split

Vertical constraints: 1st row (TW0-TW3) can be used for any height of building, but the others (TW4-TW11) are only on building groups that have some part that is at least 8 floors high.

Roof mapping: TW[x] maps to R[x + 4] (blue area), except for bottom row where TW8+TW9 both use R12; TW10+TW11 both use R13

Probability weighting is similar to short walls:
1st column x4;
2nd column x2;
3rd and 4th columns x1
(eg TW0, which is in the 1st column, is 4 times more likely to be used than TW3, which is in the 4th column)

Roof junk mapping: TW[x] uses JW[x modulo 8] for sides, JR[x modulo 8] for tops


Each roof atlas entry has 4 associated detail sections immediately below it. These are used at more detailed lods, to give a bit of extra variation between the roofs of buildings that have been grouped together and assigned the same wall/roof atlas entry. It’s probably best to keep the main roof entry fairly plain, not too much high-frequency info, because these tend to get used at the lower lods when several adjacent buildings have been amalgamated into a single outline.

Night Time / Snow Variants

Examples of night time and snow texture pages are given below. Note the illuminated windows at night and the snow on roofs when the weather is snowy.

default building texture
night building texture
snow building texture

Transport Textures

Two transport texture types exist currently: Road and Rail. Rail includes a section for Tramlines.

Road texture
Rail texture

Terrain Textures

A range of terrain textures can be specified on a per-State basis, each one is associated with a different land use code:

These terrain textures are specified in the LcmDiffuse block of a State’s Textures block:

These textures take the form TerrainTextureN.png, where N is the land use code, an example of some of the default theme textures are:

Car park textureForest textureResidential texture

Additionally, LOD versions displayed at altitude exist, named TerrainTextureN_LOD.png, where N is the land use code. These are only displayed at high altitude so can remain very low detail. LOD textures are specified as follows:

These terrain textures are specified in the LcmLODDiffuse block of a State’s Textures block:

Water Textures

Land use codes 253, 254 and 255 are used for shallow, medium and deep water respectively. These diffuse textures are blended with normal and reflection maps as the water is rendered. The normal and relfection maps are shared across all depths of water. They are specified as follows:

Tree Textures

Trees can also be themed, two tree textures are available:

Car park texture

Rail texture

Tree textures are specified as follows:

Placeholder Textures

When the camera is moving very fast, or network conditions are poor, it is possible that map tiles can’t be loaded quickly enough to fill the view. In this case, the platform creates “placeholder” terrain tiles that are displayed until the correct data can be loaded. By default, the platform applies a “wireframe grid” texture to these placeholder tiles. It is possible to specify this texture on a per State basis with the AsyncPlaceholderDiffuse parameter.

Placeholder tiles are also created in areas where no map data exists. That is, for areas of the world that haven’t been built yet. This is specified with the PlaceholderNoDataDiffuse parameter. The platform’s default for this texture is a wireframe grid with a message explaining that no data is available.

Landmark Texture Pages

Landmarks are special buildings or locations in the world. These locations often have their own unique texture, for day and night. You can also create your own landmark textures to suit your style.

Access to the Landmark Texture Github Repository is Coming Soon

Load Efficiency

It is important to remember that when the Theme changes, all textures used in that Theme will be loaded. That is, every texture in every State in the Theme. In order to keep the load times associated with Theme changes as short as possible, its important that States within each Theme share as many textures as possible.

Animated Models

Sometimes you may want to add animated models to the environment to represent special animated landmarks. This can be achieved by defining them in the theme Manifest. We support PowerVR’s POD File format for 3D Animated Models. For more information on the POD File format, see the PowerVR SDK Documentation and for information on creating, loading and rendering these models yourself, see Loading and Rendering models.

Orientating an animated model

When modelling an animated model to be displayed in the world via the theme system, care has to be taken to get the correct orientation so the model is displayed correctly. eeGeo 3D Maps will automatically orientate the model anywhere in the world so the axes line up with facing North and East. This diagram represents what 3D Axes represent in the world.

Local space axes for animated models in the world

So if you were creating an animated model that faced North, you would orientate the model to face along the Y axis.

Adding animated models to a Theme

After exporting your POD file, you’ll need to place it relative to the custom theme manifest and define the animation in the JSON. For example, if we want to add two animated objects to our ‘London’ theme, we would place them and their textures here:

Example of where to put animated model files when using environment-themes

Then update the theme manifest to include the following JSON for our ‘London’ theme:

  • Name – Reference name.
  • Url – Case-sensitive path relative to the manifest of the POD file representing the animated object. The textures for the model must also be present, as these will also be downloaded.
  • LocationLatLong – The Latitude, Longitude and Altitude coordinates of the animated model. Latitude and Longitude are in degrees. Altitude is in meters.
  • FramerateScale – Modifies the rate of playback for the animation, affecting the speed.

Then deploy everything to your CDN and have the app load the deployed manifest.

When your application applies the theme, it will automatically download the model and its textures and animate it in the defined position.

Note: For textures, you will need to supply .pvr versions of the texture for loading on iOS, and .ktx versions for loading on Android devices. For example, if you exported a model called “/animations/boat_tours.pod” that used a texture called “boat_tour_texture.png”, you would need to ensure that “/animations/boat_tour_texture.pvr” and “/animations/boat_tour_texture.ktx” both existed.

Controlling Themes

By default, the theme in use will be the closest theme in decimal degrees based on the positions of the themes specified in the manifest. This behaviour can be turned off, and your application take full control over what theme is in use.

An example is provided to demonstrate how to achieve this

Transitions between States in the current Theme can be achieved as follows: