Revision as of 14:49, 8 October 2012

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

Viewer 1

Linden Lab viewer 1 and associated TPVs, and Linden Lab viewer 2 and 3 and associated TPVs have different ways of receiving map data.

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.

[Startup]
WorldMapModule = WorldMap
MapImageModule = MapImagemodule

You can also set

[Startup]
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 5 is the minimum. For instance

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

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. Instead of uploading them to the asset service and passing the asset UUID to the grid service, they upload a generated JPEG to the map image service. The map image service then stores them in a directory configured by

[MapImageService]
TilesStoragePath = "maptiles"

The default, as seen here, is bin/maptiles.

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. Currently in OpenSimulator there are two map image generation choices.

MapImageModule

This is the older map image module. Set

[Startup]
MapImageModule = MapImageModule

to use this.

Warp3DImageModule

This is a newer image module that produces higher quality map images but has been associated with memory leaks in the past (though efforts have and are being made to address this). For this module, set

[Startup]
MapImageModule = Warp3DImageModule

See Warp3DImageModule for some more information.