Languages:

English    Français

Introduction

The concept of 'map' in OpenSimulator can refer to one of two things.

1. The minimap - this is the small map you see of the current and surrounding regions in the viewer.
2. The main map - This is the map you see when opening the main map window.

The minimap is generated purely by the viewer, and is decorated with an image of the terrain, the positions of other avatars on that region, objects colour coded by whether you own them, etc.

The main map is generated purely by OpenSimulator.

For the rest of this document we will talk about the main map, though more information can be inserted in the future about the minimap.

The main map

Overview

Linden Lab viewer 1 and associated TPVs, and Linden Lab viewer 2 and 3 and associated TPVs have different ways of receiving map data. Unfortunately, this means that some config operations (e.g. disabling map generation entirely) have to be done in two separate places.

Viewer 1

For viewer 1, maptiles were generated and stored in the asset service, with the asset UUID recorded in the regionMapTexture column in the regions table by the grid service. On opening the main map, the viewer would send a MapBlockRequest UDP message requesting the map blocks for a certain range. The simulator would interpret this message, fetch the appropriate map texture UUIDs by requesting the region information from the grid service (and parcel image if available, though we won't get into that here) and return them to the viewer. The viewer would then request the textures identified by the UUIDs as required.

The world map is activated by default for viewer 1 and associated TPVs with the following settings in OpenSimDefaults.ini and which can be overridden in your own OpenSim.ini.

[Map]
WorldMapModule = WorldMap
MapImageModule = MapImagemodule

You can also set

[Map]
GenerateMapTiles = true|false
MaptileRefresh = <seconds>
DrawPrimOnMapTile = true|false
TextureOnMapTile = true|false

• GenerateMapTiles will control whether map tiles are generated at all.
• MaptileRefresh will control whether map tiles are periodically regenerated.
• DrawPrimOnMapTile will control whether prims are drawn on map tiles (default true)
• TextureOnMapTile will control whether terrain textures are used on maptiles or whether everything is simply shaded green.

There is an alternative higher quality but more resource intensive MapImageModule called Warp3DImageModule which we shall discuss more below.

Viewer 2 and later

Viewers 2 and 3 would instead fetch ordinary JPEG images from an address given to them during login. In OpenSimulator, this address is set using

[LoginService]
MapTileURL = "http://<robust-or-standalone-ip>:<public-port>/"

in the [LoginService] section of Robust.ini (when in grid mode) or StandaloneCommon.ini (which in standalone mode). Requests are handled by the MapGetServiceConnector which listens on the public services port (typically 8002 on grid, 9000 on standalone).

e.g.

[LoginService]
MapTileURL = "http://192.0.43.10:9000"

Requests from the viewer follow the format

/map-<zoom-level>-<x-coord>-<y-coord>-objects.jpg

where 1 is the maximum zoom level and 8 is the minimum. For instance

GET /map-1-1000-1000-objects.jpg

At zoom levels higher than 1, the image displays multiple map blocks with the block named in the filename being in the SW corner (e.g. map-2-1000-1000-objects.jpg is an image of 4 regions).

The files served are ordinary JPEGs rather than JPEG2000, as used by the asset texture system.

As with viewer 1, simulators are responsible for generating the maptiles. This is controlled by the [MapImageService] section in StandaloneCommon.ini or GridCommon.ini. For StandaloneCommon.ini, the configurable parameter is

[MapImageService]
RefreshTime = 60

This controls the maptile refresh time in minutes where the default is 60 (confusingly this is not done in seconds as with the viewer 1 setting).

To disable viewer 2/3 maptile generation entirely, one would need to override the

[Modules]
MapImageService = MapImageServiceModule 

configuration parameter in Standalone.ini. One can do this by blanking it with

[Modules]
MapImageService =

in StandaloneCommon.ini.

In GridCommon.ini, RefreshTime can also be adjusted but there is another parameter which tells the simulator where to upload the generated image.

[MapImageService]
MapImageServerURI = <ROBUST-map-image-service>:<private-port>

e.g.

MapImageServerURI = http://192.168.1.4:8003

Unlike MapTileURL, the port this time is private (default 8003) since we do not want viewers to be able to add their own map tiles! This also means that the IP need only be one that can be reached by the simulator. If simulator and services are running on the same LAN then this can be a local LAN IP address.

The viewer 2/3 map image service module, instead of generating map tiles and uploading them to the asset service before passing the asset UUIDs on to the grid service, instead upload a generated JPEG directly to the map image service (either in process for standalone or using the MapImageServerURI in grid mode). The map image service then stores them in a directory configured by

[MapImageService]
TilesStoragePath = "maptiles"

in Robust.ini or StandaloneCommon.ini. The default, as seen here, is bin/maptiles. If you look in this directory, you will see all the generated and uploaded jpg files.

Maptile generation

Even though viewer 1 and viewer 2 and later consume and request maptiles rather differently, the maptile images are still created by common image generation code.

Generators

Currently in OpenSimulator there are two map image generation choices.

MapImageModule

This is the older map image module. Set

[Map]
MapImageModule = MapImageModule

to use this.

Warp3DImageModule

This is a newer image module that produces higher quality map images but leaks memory like it's going out of fashion. This will be addressed in a future OpenSimulator release (after 0.8). In the mean time, please use this to generate map tiles once a session, at most (e.g. at startup). For this module, set

[Map]
MapImageModule = Warp3DImageModule

See Warp3DImageModule for some more information.

General configuration

Apart from some specific Warp3DImageModule parameters, the parameters for controlling the specifics of maptile generation are in the [Map] section of OpenSim.ini. The parameters need to be documented here, but in the meantime, please see the OpenSim.ini.example file for more details.

Manual regeneration

Normally, one would generate maptiles at startup and/or at regular intervals. From OpenSimulator 0.8 onwards, one can also manually force maptile regeneration with the console command

# generate map

Code

This is an extremely rough code overview which may be elaborated later