Difference between revisions of "Linden Lab Official:Map API Introduction"

From Second Life Wiki
Jump to navigation Jump to search
(Removing very old "new features" section....they are no longer 'new')
(Updated for version 2 of the API)
 
Line 5: Line 5:
== Getting Started ==
== Getting Started ==


The Second Life Map API is a set of Javascript objects and functions that enable you to embed Second Life maps onto your web pages.  It is a purely client-side Javascript API.  If needed, you can also [[#Accessing_map_images_directly|directly access]] the map images.
The Second Life Map API is a JavaScript library to embed Second Life maps onto your web pages.  It's a purely client-side JavaScript API.  If needed, you can also [[#Accessing_map_images_directly|directly access]] the map images.


'''NOTE:'''
'''NOTE:'''
Line 12: Line 12:
=== Map UI features ===
=== Map UI features ===


The Map API enables you to create web pages that have Google Maps functionality, using maps of Second Life, rather than Earth.  In general, the default map interface looks as shown here.
The Map API enables you to create web pages that have web map functionality, using maps of Second Life, rather than Earth.  In general, the default map interface looks as shown here.


[[Image:Map ui cropped.png|right]]
[[Image:Map ui cropped.png|right]]
Line 18: Line 18:
The main map display area shows the current map area.  By default, the map provides the following features:
The main map display area shows the current map area.  By default, the map provides the following features:


* Click and drag the mouse pointer to pan the map view up, down, left, and right. If desired, you can [[Map_API_Advanced_Examples#Disabling_and_enabling_dragging|disable this behavior]]. 
* Click and drag the mouse pointer to pan the map around.
* Double-click to zoom in by one level (power of two) and display the teleport window.
* Double-click to zoom in by one level (power of two).
* Click anywhere on the map to open a "teleport" window; see '''Teleport window''' below.
* Click anywhere on the map to open a "teleport" popup (see '''Teleport popup''' below).
* Use the mouse wheel to zoom in and out.  See [[#Zoom_levels|Zoom levels]] for more information about zoom levels.
* Use the mouse wheel to zoom in and out.  See [[#Zoom_levels|Zoom levels]] for more information about zoom levels.
* Use the zoom and pan controls at upper left to zoom the view in and out and to pan the view up, down, left, and right.  If desired, you can easily [[Map_API_Advanced_Examples#Customizing_zoom_and_pan_controls|create your own custom zoom and pan controls]].
* Use the zoom controls at upper left to zoom the view in and out.
* Use the overview control to move the view around by clicking and dragging, or double-clicking.  Close the overview control by clicking on the diagonal arrow at the very bottom right of the map.  You can specify whether the map provides an overview control when you [[Map_API_Reference#MarkerOptions|create the map object]].


<br clear="all" />
<br clear="all" />


'''Teleport window'''
'''Teleport popup'''
[[Image:Teleport window.png|left]]
[[Image:Teleport window.png|left]]
Clicking anywhere on the map opens a window,  such as the one shown at left, indicating the point on which you clicked.  Clicking on the teleport button in the window then starts the Second Life Viewer, automatically teleporting you to the window's location.  This feature is implemented with the [[Map_API_Reference#Global_functions|gotoSLURL()]] global function.
Clicking anywhere on the map opens a popup (left) where you click.  Click "Visit this location" to start the Second Life Viewer & teleport you where you clicked.  This feature is implemented with the [[Map_API_Reference#Global_functions|gotoSLURL()]] global function.


<br clear="all" />
<br clear="all" />
Line 35: Line 34:
=== Working examples ===
=== Working examples ===


See [[Map API Basic Examples]] for a detailed explanation of the working examples at http://slurl.com/examples/.
See [[Map API Basic Examples]] for a detailed explanation of the working examples at http://maps.secondlife.com/examples/.


=== Using slurl.com and DirectSLurl ===
<span id="Using slurl.com and DirectSLurl"></span>
=== Using web links ===


The website http://slurl.com uses the Map API to provide a mechanism to teleport directly to locations in Second Life from web pages.
The [http://maps.secondlife.com/ web site] uses the Map API to provide a mechanism to teleport directly to locations in Second Life from web pages.


For more information, see [[Using Second Life URLs (SLurls)]].
For more information, see [[Using Second Life URLs (SLurls)]].


=== Prerequisites ===
=== Include the API files ===


To use the Second Life Map API in a web page, you must first:
To use the Map API, put the following lines at the beginning of each HTML page.  This includes the JavaScript & CSS so that you can create the map & display it correctly.
* [http://www.google.com/apis/maps/signup.html Sign up for a Google Maps API key].  This enables you to use the Google Maps API, which is required to use SLMAPI.  See the [http://code.google.com/apis/maps/documentation/ Google Maps API documentation] for more information.
* Add the [[#Common_HTML_header|common header code]] at the beginning of each HTML file.  This code loads the Google Maps and Webmap Javascript libraries, the Webmap cascading stylesheet (CSS), and some other basic code.


NOTE: In general, it is best to reference the Map API Javascript library and CSS files that are on http://slurl.com.  Although you can download these files locally and modify them for your own use, if Linden Lab updates or changes these files, your applications will not get the benefit and may even stop working properly. 
<pre>
 
<!DOCTYPE html>
=== Common HTML header ===
<html><head>
 
    <meta charset="utf-8">
To use the Map API, put the following lines at the beginning of each HTML page.  This includes:
* Statements to load the required Second Life Map API and Google Maps Javascript libraries.
* Link to the Webmap cascading style sheet.
* Style declaration for the map div element.  This defines the size and other layout attributes of the map display.


<pre>
    <script src="http://maps.secondlife.com/_scripts/sl.mapapi2.js"></script>
<html>
    <link rel="stylesheet" type="text/css" href="http://maps.secondlife.com/_styles/sl.mapapi2.css">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script src="http://maps.google.com/maps?file=api&v=2&key={GOOGLE MAPS KEY}"
  type="text/javascript"></script>
<script src="http://slurl.com/_scripts/slmapapi.js" type="text/javascript"></script>


<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
    ...
<style>
div#map-container {
      width: 500px;
      height: 500px;
}
</style>
...
</pre>
</pre>
Replace {GOOGLE MAPS KEY} with you Google Maps Key.


All the examples also require additional script statements in the HTML header.
All the examples also require additional script statements in the HTML header.
Line 83: Line 62:
'''Stylesheet'''
'''Stylesheet'''


To use your own stylesheet, just include it AFTER the Webmap CSS, for example:
You can also include your own stylesheet to style the other elements of your page. For example:


<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" />
<pre>
<link rel="stylesheet" type="text/css" href="myStyleSheet.css" />
    <link rel="stylesheet" type="text/css" href="http://maps.secondlife.com/_styles/sl.mapapi2.css">
 
    <link rel="stylesheet" type="text/css" href="myStyleSheet.css">
'''Body element'''
</pre>
 
Use the following body element in your HTML document:
 
<body onload="loadmap()" onunload="GUnload();">
...
 
The '''GUnload()''' function is a Google Maps API  function that reduces memory leaks, particularly with Internet Explorer.  For more information, see the [http://code.google.com/apis/maps/documentation/#Memory_Leaks Google Maps API documentation].


=== Browser compatibility ===
=== Browser compatibility ===
Line 114: Line 86:
== Basic concepts ==
== Basic concepts ==


The Map API's fundamental class is [[Webmap_API_Reference#SLMap|SLMap]]. It is a Javascript object representing the map with a large number of methods, enabling you to zoom, pan the view, and so on.
The Map API is built around [http://leafletjs.com the Leaflet web map library]. Leaflet provides many options, methods & events for customizing the presentation of your Second Life map.
 
Additionally, the API includes the following key classes:
* [[Webmap_API_Reference#Marker|Marker]] - represents an image to display at a specify (x,y) point on the map.  You provide a set of images to display at each zoom level.  Contains several event handlers and other properties.  See [[#Map_with_a_marker|Map with a marker]] for a basic example.
* [[Webmap_API_Reference#MapWindow|Window]] - represents a captioned balloon pointing to a specified map location.  See [[Webmap_API#Map_with_an_initial_open_window|Map with an initial open window]] for a basic example.
* [[Webmap_API_Reference#Img|Img]] and [[Webmap_API_Reference#Icon|Icon]] - represent an image to use for markers, controls, or in windows.


===About coordinates===
===About coordinates===


Map coordinates are based on the Second Life grid system for positioning regions.  
Map coordinates are based on the Second Life grid system for positioning regions.


[[Image:Webmap coords.jpg]]
[[Image:Webmap coords.jpg]]


As illustrated in the diagram above, the Map API maps the Second Life world to the upper right quadrant of the Google world map.  A large scaling value
As illustrated in the diagram above, the Map API maps the Second Life world to the upper right quadrant of an earth map.  A large scaling value equal to 2<sup>20</sup> or 1,048,576 defines the largest region coordinate at the top and far right edge of the displayed area.  This value creates a map area with room for one trillion sims.
called slGridEdgeSizeInRegions (equal to 2<sup>20</sup> or 1,048,576) defines the largest region coordinate at the top and far right edge of the displayed area.  This value creates a map area with room for one trillion sims.


The little blue square illustrates where the populated sims are in Second Life.
The little blue square illustrates where the populated sims are in Second Life.


=== Zoom levels ===
=== Zoom levels ===
There are eight zoom levels: one through eight, one being the closest and eight being the farthest. Each level zooms by a power of two. In other words, at zoom level five, each region is twice the width as it was at zoom level six.
There are eight zoom levels: one through eight. Zoom level 8 is most zoomed in, and zoom level 1 is most zoomed out. Each level zooms by a power of two. In other words, at zoom level six, each region is twice the width it was at zoom level five.


== Accessing map images directly ==
== Accessing map images directly ==


The Second Life map images are stored on [http://aws.amazon.com/s3/ Amazon Simple Storage Service (Amazon S3)].  You can access the map images directly on the Amazon S3 servers using the following URL format (new as of February 10, 2009):
The Second Life map images are stored on [http://aws.amazon.com/s3/ Amazon Simple Storage Service (Amazon S3)].  You can access the map images directly on the Amazon S3 servers using the following URL format:


  <nowiki>http://map.secondlife.com/map-Z-X-Y-objects.jpg</nowiki>
  <nowiki>http://map.secondlife.com/map-{z}-{x}-{y}-objects.jpg</nowiki>


Where:
Where:
* Z - Zoom level desired:
* <tt>z</tt> - zoom level from 1 (most zoomed-in, where each tile is one region) to 8 (most zoomed out). Note this is ''backward'' from how are addressed when making Leaflet API calls in your JavaScript.
** One (1) is the most zoomed-in view, showing individual region tiles.
* <tt>x</tt> & <tt>y</tt> - the X and Y coordinates on the Second Life Grid of the region. For example, region Ahern is (997, 1002).
** Eight (8) is the maximum zoom level, showing the entire world.  
* X,Y - X and Y coordinates on the Second Life Grid of the region, for example, region Ahern is (997,1002).


Tiles with zoom greater than one are stored at the lower left corner coordinate of the tiles that are included in the image.
Even zoomed-in tiles are addressed by their region coordinates. That is, tiles with zoom greater than 1 are stored by the <tt>x</tt> & <tt>y</tt> of the regions at their lower left corners. You can find the zoom tile containing region (X,Y) for zoom level Z with the filename map-Z-X'-Y'-objects.jpg where:
In other words, you can find the zoom tile containing region (X,Y) for zoom level Z with the filename map-Z-X'-Y'-objects.jpg where:


X' = X - (X % (2<sup>Z - 1</sup>) )
X' = X - (X % (2<sup>Z - 1</sup>) )
Line 160: Line 123:
=== Examples ===
=== Examples ===


For example: if Z = 1, the four region tiles are:
For example, at Z = 1, four region tiles are:


* http://map.secondlife.com/map-1-1000-1000-objects.jpg
* http://map.secondlife.com/map-1-1000-1000-objects.jpg
Line 171: Line 134:
http://map.secondlife.com/map-2-1000-1000-objects.jpg
http://map.secondlife.com/map-2-1000-1000-objects.jpg


The following shows the map zoomed all the way out, showing the entire Second Life world view:
The following shows the map zoomed all the way out, showing the once-entire Second Life world view:
http://map.secondlife.com/map-8-1024-896-objects.jpg  
http://map.secondlife.com/map-8-1024-896-objects.jpg


The following displays a single tile contained in the view above, zoomed all the way in:
The following displays a single tile contained in the view above, zoomed all the way in:
http://map.secondlife.com/map-1-1027-1019-objects.jpg
http://map.secondlife.com/map-1-1027-1019-objects.jpg


===Implementation notes===
=== Implementation notes ===


The map generation process is more scalable than the previous release, and is able to image the entire Second Life grid of about 30,000 regions in less than two days.   
The map generation process is more scalable than the previous release, and is able to image the entire Second Life grid of about 30,000 regions in less than two days.   
Line 187: Line 150:
The following LSL script illustrates how to display a map of the current region to an avatar:
The following LSL script illustrates how to display a map of the current region to an avatar:


<lsl>
<source lang="lsl2">
ShowMap(key avatar) {
ShowMap(key avatar) {
     string url = "http://map.secondlife.com/";
     string url = "http://map.secondlife.com/";
Line 196: Line 159:
     llLoadURL(avatar, "View the sim map", url);
     llLoadURL(avatar, "View the sim map", url);
}
}
</lsl>
</source>


== Release notes ==
== Release notes ==


This section describes new features and known issues with the current release of the Map API. See also [http://blog.secondlife.com/2009/01/22/improvements-to-mapping-and-upgrade-to-slurlcom/ Philip Linden's blog post announcement].
This section describes new features and known issues with the current release of the Map API.
 
Version 2 of the Map API was released on Dec 12, 2016.


The current version of the Map API was released on Jan 15, 2009.
* Converted the Map API to Leaflet.


=== Known issues ===
Version 1 of the Map API was released on Jan 15, 2009.


* Map object click and doubleclick handlers do not work. They always have the default behavior.
* See also [http://blog.secondlife.com/2009/01/22/improvements-to-mapping-and-upgrade-to-slurlcom/ Philip Linden's blog post announcement].
* Method '''SLMap.clickMarker(marker)''' doesn't work.
* Marker options do not work:
** '''centerOnClick: true''' - This works, but does NOT work if you open a window onclicking the marker.
** '''autopanOnClick: false''' - Always autopans
** '''autopanPadding: n''' - No effect
* Setting a different marker image/icon for each zoom level doesn't work - always uses first icon.
* Window width option doesn't work.

Latest revision as of 11:14, 13 December 2016

NOTE: This is an official Second Life API provided and documented by Linden Lab. Its use is subject to the API Terms of Use.

Getting Started

The Second Life Map API is a JavaScript library to embed Second Life maps onto your web pages. It's a purely client-side JavaScript API. If needed, you can also directly access the map images.

NOTE: This API is still in beta. URLs and API signatures may change. See the Release Notes for information on new features and known issues.

Map UI features

The Map API enables you to create web pages that have web map functionality, using maps of Second Life, rather than Earth. In general, the default map interface looks as shown here.

Map ui cropped.png

The main map display area shows the current map area. By default, the map provides the following features:

  • Click and drag the mouse pointer to pan the map around.
  • Double-click to zoom in by one level (power of two).
  • Click anywhere on the map to open a "teleport" popup (see Teleport popup below).
  • Use the mouse wheel to zoom in and out. See Zoom levels for more information about zoom levels.
  • Use the zoom controls at upper left to zoom the view in and out.


Teleport popup

Teleport window.png

Clicking anywhere on the map opens a popup (left) where you click. Click "Visit this location" to start the Second Life Viewer & teleport you where you clicked. This feature is implemented with the gotoSLURL() global function.


Working examples

See Map API Basic Examples for a detailed explanation of the working examples at http://maps.secondlife.com/examples/.

Using web links

The web site uses the Map API to provide a mechanism to teleport directly to locations in Second Life from web pages.

For more information, see Using Second Life URLs (SLurls).

Include the API files

To use the Map API, put the following lines at the beginning of each HTML page. This includes the JavaScript & CSS so that you can create the map & display it correctly. 

<!DOCTYPE html>
<html><head>
    <meta charset="utf-8">

    <script src="http://maps.secondlife.com/_scripts/sl.mapapi2.js"></script>
    <link rel="stylesheet" type="text/css" href="http://maps.secondlife.com/_styles/sl.mapapi2.css">

    ...

All the examples also require additional script statements in the HTML header.

Stylesheet

You can also include your own stylesheet to style the other elements of your page. For example: 

    <link rel="stylesheet" type="text/css" href="http://maps.secondlife.com/_styles/sl.mapapi2.css">
    <link rel="stylesheet" type="text/css" href="myStyleSheet.css">

Browser compatibility

The Map API has been tested to work with the following browsers:

  • Internet Explorer 6.0
  • Internet Explorer 7.0
  • Firefox 2.0 or greater
  • Safari 2.0

Other browsers may work but little issues may appear. Unless otherwise noted, all features work in all supported browsers.

Comments and feedback

If you encounter problems or bugs or have feature requests, please email webmap@secondlife.com.

Happy coding from the Second Life Web team!

Basic concepts

The Map API is built around the Leaflet web map library. Leaflet provides many options, methods & events for customizing the presentation of your Second Life map.

About coordinates

Map coordinates are based on the Second Life grid system for positioning regions.

Webmap coords.jpg

As illustrated in the diagram above, the Map API maps the Second Life world to the upper right quadrant of an earth map. A large scaling value equal to 220 or 1,048,576 defines the largest region coordinate at the top and far right edge of the displayed area. This value creates a map area with room for one trillion sims.

The little blue square illustrates where the populated sims are in Second Life.

Zoom levels

There are eight zoom levels: one through eight. Zoom level 8 is most zoomed in, and zoom level 1 is most zoomed out. Each level zooms by a power of two. In other words, at zoom level six, each region is twice the width it was at zoom level five.

Accessing map images directly

The Second Life map images are stored on Amazon Simple Storage Service (Amazon S3). You can access the map images directly on the Amazon S3 servers using the following URL format: 

http://map.secondlife.com/map-{z}-{x}-{y}-objects.jpg

Where:

  • z - zoom level from 1 (most zoomed-in, where each tile is one region) to 8 (most zoomed out). Note this is backward from how are addressed when making Leaflet API calls in your JavaScript.
  • x & y - the X and Y coordinates on the Second Life Grid of the region. For example, region Ahern is (997, 1002).

Even zoomed-in tiles are addressed by their region coordinates. That is, tiles with zoom greater than 1 are stored by the x & y of the regions at their lower left corners. You can find the zoom tile containing region (X,Y) for zoom level Z with the filename map-Z-X'-Y'-objects.jpg where:

X' = X - (X % (2Z - 1) )

and

Y' = Y - (Y % (2Z - 1) )

Note that 2Z - 1 is the number of regions encompassed by the width of a tile at resolution Z.

Examples

For example, at Z = 1, four region tiles are:

These four region tiles are compressed into the single tile:

http://map.secondlife.com/map-2-1000-1000-objects.jpg

The following shows the map zoomed all the way out, showing the once-entire Second Life world view: http://map.secondlife.com/map-8-1024-896-objects.jpg

The following displays a single tile contained in the view above, zoomed all the way in: http://map.secondlife.com/map-1-1027-1019-objects.jpg

Implementation notes

The map generation process is more scalable than the previous release, and is able to image the entire Second Life grid of about 30,000 regions in less than two days.

There is a "decay period" for offline regions. If a region is disabled, the tile will stay up for several days (in case it comes back or something else has gone wrong) before the tile disappears. That several-day period will be longer than the time it takes to update existing regions or put new regions on the map.

Getting a map URL from LSL

The following LSL script illustrates how to display a map of the current region to an avatar: 

ShowMap(key avatar) {
    string url = "http://map.secondlife.com/";
    vector sim_coord = llGetRegionCorner();
    string x = (string)((integer)(sim_coord.x / 256.0));
    string y = (string)((integer)(sim_coord.y / 256.0));
    url += "map-1-" + x + "-" + y + "-objects.jpg";
    llLoadURL(avatar, "View the sim map", url);
}

Release notes

This section describes new features and known issues with the current release of the Map API.

Version 2 of the Map API was released on Dec 12, 2016.

  • Converted the Map API to Leaflet.

Version 1 of the Map API was released on Jan 15, 2009.

Retrieved from "https://wiki.secondlife.com/w/index.php?title=Linden_Lab_Official:Map_API_Introduction&oldid=1205048"