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

From Second Life Wiki
Jump to navigation Jump to search
 
(94 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Help/Box|Update notice|<b>We've made improvements and changes to the webmap, effective January 15, 2009.<br>Some information here may be out of date as we update this wiki with the changes. Thanks for your patience.</b>}}
{{Supported API}}
{{:API Portal/navigation|map}}
Extend the reach of your Web site into Second Life using the ''Second Life Map API'', which enables you to embed interactive Second Life maps directly into your web pages. These maps look and act much like Google Maps, except that, instead of the Earth, they display the topography of the Second Life virtual world. See http://maps.secondlife.com/ for an example.


When you use the Map API to embed Second Life maps on your site, your visitors can:


{{:API Portal/navigation}}
* Click and drag the mouse pointer to pan the map view up, down, left, and right.
__TOC__
* Double-click to zoom in by one level (power of two) and display the teleport window.
 
* Click anywhere on the map to open a "teleport" window.
== Getting Started ==
* Use the mouse wheel or pan controls to zoom in and out.
 
=== What is the Webmap API? ===
 
The Second Life Webmap 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 webmap images. 
 
'''NOTE:'''
This API is still in beta.  URLs and API signatures may change.
 
=== Prerequisites ===
 
To use the Second Life Webmap API, you must first:
* [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.
* Download [http://www.prototypejs.org/assets/2007/1/18/prototype.js prototype.js] version 1.5.0. 
* Download [http://script.aculo.us/ scriptaculous.js] version 1.7.0.
* Download [http://slurl.com/_scripts/slmapapi.js slmapapi.js].  Alternatively, you can reference the online version in your pages; for example:
: <code> <script src="http://slurl.com/_scripts/slmapapi.js"><script> </code>
 
<span style="background: yellow">I think prototype.js and scriptaculous.js are no longer needed, but need to confirm.
--[[User:Rand Linden|Rand Linden]] 08:17, 26 January 2009 (UTC)
</span>
 
===About coordinates===
 
Map coordinates are based on the Second Life grid system for positioning regions.
 
The Second Life world is mapped to the upper right quadrant of the
world map as used by Google lat/long coordinates.  A large scaling value
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.
 
''Diagram TBD.''
 
The little xxx's in the diagram shows where the populated sims are in SL
today.
 
=== Zoom levels ===
There are six zoom levels: one through six, one being the closest and six 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.
 
=== Browser compatibility ===
The Webmap API has been tested to work with the following browsers:
* Internet Explorer 6.0
* Internet Explorer 7.0
* Firefox 1.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.
 
== Basic concepts ==
 
The Webmap 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.
 
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.
* [[Webmap_API_Reference#MapWindow|Window]] - represents a captioned balloon pointing to a specified map location.
* [[Webmap_API_Reference#Img|Img]] and [[Webmap_API_Reference#Icon|Icon]] - represent an image to use for markers, controls, or in windows.
 
== Basic Examples ==
 
=== Required image files ===
 
Some of the following examples use image files for markers.  To run the examples with the code as shown, download the image files and save them in the same directory as the example HTML files.  Alternatively, create the Img objects using the URLs listed in the table below that refer to the images stored on this wiki.
 
The following table lists the images used in the examples:
 
{| {{Prettytable}}
|-{{Hl2}}
! Image
! File name
! URL
 
|-
| [[Image:Yellow marker.gif]]
| Yellow marker.gif
| https://wiki.secondlife.com/w/images/2/23/Yellow_marker.gif
 
 
|-
| [[Image:Fountain.gif]]
|Fountain.gif
| https://wiki.secondlife.com/w/images/6/60/Fountain.gif
 
|-
| [[Image:Forsale.png]]
| Forsale.png
| https://wiki.secondlife.com/wiki/Image:Forsale.png
 
|-
|[[Image:Forsale-shadow.png]]
|Forsale-shadow.png
|https://wiki.secondlife.com/w/images/d/d9/Forsale-shadow.png
|}
 
=== Common HTML fragments ===
 
All the examples require the following "header" at the beginning of the HTML <head> element:
 
<pre>
<html>
<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=[YOUR GOOGLE MAP API KEY HERE]"
  type="text/javascript"></script>
<script src="http://slurl.com/_scripts/slmapapi.js" type="text/javascript"></script>
 
<style>
div#map-container {
      width: 500px;
      height: 500px;
}
</style>
...
</pre>
 
Most examples require additional scripts in the HTML heading.
 
All the examples require the following in the HTML <body> element:
 
<pre>
<body onload="loadmap()">
<div id="map-container"></div>
</body>
</pre>
 
Some examples require additional elements in the document body.
 
=== Simple map ===
 
The first example is a map with basic panning and zooming capabilities.  When you are done, it will look as shown here.
 
[[Image:MapAPI ex1.png|thumb|right|Simple map]]
 
You can pan the map and zoom in and out.
 
To create this example, follow these steps:
# Include required Javascript libraries.
# Include or reference the SLMAPAPI library.
# Add HTML body and div elements.
# Add Javascript onload event handler function.
# Save and test.
 
'''Include required Javascript libraries'''
 
<span style="background: yellow">I think these JS files are no longer needed, but need to confirm.
--[[User:Rand Linden|Rand Linden]] 08:17, 26 January 2009 (UTC)
</span>
 
Include the references to <code>protoype.js</code> and <code>scriptaculous.js</code>:
<script src="prototype.js" type="text/javascript"></script>
<script src="scriptaculous/scriptaculous.js" type="text/javascript"></script>
 
Make sure both files are where you specify.  Here, <code>protoype.js</code> is in the same directory as the example HTML file and <code>scriptaculous.js</code> is in a <code>/scriptaculous</code> subdirectory.
 
Next include the reference for the Google Maps API:
 
<script src=<nowiki>"http://maps.google.com/maps?file=api&amp;v=2&amp;key={YOUR GOOGLE MAPS KEY GOES HERE}"</nowiki> type="text/javascript"></script>
 
Replace {YOUR GOOGLE MAPS KEY GOES HERE} with your Google Map key.
 
'''Include or reference the Webmap API library'''
 
Include the reference to the Second Life Map API Javascript file:
 
<script src="<nowiki>http://slurl.com/_scripts/slmapapi.js</nowiki>" type="text/javascript"></script>
 
If you prefer, download the file locally, and refer to it using a relative path.
 
'''Add HTML body and div elements'''
 
Next, add the HTML body containing div element to contain your map. The body contains a Javascript onload event handler that calls the <code>loadmap()</code> function you will define in the next step.
 
<body onload="loadmap()">
  &tl;div id="map-container"&gt;&lt;/div&gt;
</body>
 
After the div element is passed to the map constructor, all that is left to do is to center the map and set the zoom.
 
NOTE: If you want the position attribute of the div element to be absolute, either set it programmatically via Javascript or using the style attribute tag. Setting the position attribute of this element in the CSS stylesheet will not work.
 
'''Add Javascript onload event handler function'''
 
Add the following Javascript function in the head of your page to instantiate the map and center it.
 
<script>
function loadmap() {
  mapInstance = new SLMap(document.getElementById('map-container'));
  mapInstance.centerAndZoomAtSLCoord(new XYPoint(1000,1000),3);
}
</script>
 
'''Save and test'''
 
When you are done, save the file, and then load it into your web browser.  Try panning the map by clicking and dragging the mouse cursor; you can also pan by clicking on the arrow icons on the four sides.  Also try zooming the view in and out by clicking the "+" and "-" icons.
 
'''Complete source code'''
 
<pre>
<!-- Insert common HTML header -->   
<script>
function loadmap() {
  // creates the map
  mapInstance = new SLMap(document.getElementById('map-container'), {disableVoiceInfo: true});
  mapInstance.centerAndZoomAtSLCoord(new XYPoint(997,1002),2);
}
</script>
</head>
<body onload="loadmap()">
<div id="map-container"></div>
</body>
</pre>
 
=== Map with a marker ===
 
[[Image:Map with Marker.png|thumb|right|Map with a marker]]
 
This example shows how to make a map with a marker. The code is the same as the first example, with with addition of some Javascript after the initialization of the map in the page's onload handler.
 
To use the code below verbatim, you must download the marker image as described in [[#Required_image_files|Required image files]]; you can also use the URL of the wiki image if you prefer. 
 
The code first creates the icon for the marker, then places it on the map at (997, 1002) at the welcome area fountain.  Because the same icon is specified for every zoom level, it appears the same size regardless of zoom level.


For more information, see [[Map API Introduction]].
<br clear="all"/>
<br clear="all"/>
<pre>
// creates the icons
var yellow_dot_image = new Img("Yellow_marker.gif",9,9);
var yellow_icon = new Icon(yellow_dot_image);
var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];
// creates the marker
var marker = new Marker(all_images, new XYPoint(997,1002));
mapInstance.addMarker(marker);
</pre>
In this example, clicking on the marker does nothing.  Subsequent examples illustrate adding some onClick behavior.
'''Source code'''
<pre>
<!-- Insert common HTML header -->
<script>
function loadmap() {
  // creates the map
  var mapInstance = new SLMap(document.getElementById('map-container'), {disableVoiceInfo: true});
  mapInstance.centerAndZoomAtSLCoord(new XYPoint(997,1002),2);
 
  // creates the icons
  var yellow_dot_image = new Img("b_map_yellow.gif",9,9);
  var yellow_icon = new Icon(yellow_dot_image);
  var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];
 
  // creates the marker
  var marker = new Marker(all_images, new XYPoint(997,1002));
  mapInstance.addMarker(marker);
}
</script>
</head>
<body onload="loadmap()">
<p>There should be a yellow marker in the center of this map:
<div id="map-container"></div>
</body>
</pre>
=== Map with an initial open window ===
[[Image:Map_with_window.png|thumb|right|Map with a window]]
A Webmap ''window'' is a caption pointing to a specific point on the map, as shown in the screenshot at right.  It looks something like a comic book dialog bubble. 
Use the [[Webmap_API_Reference#MapWindow|MapWindow]] object to create a window.
For example, to create a window that opens initially when the page loads:
# Instantiate a [[Webmap_API_Reference#MapWindow|MapWindow]] object with the desired caption.
# Call the addMapWindow() method on the [[Webmap_API_Reference#SLMap|SLMap]] object to add the window to the map.
<br clear="all"/>
For example:
<pre>
// creates a window
var mapWindow = new MapWindow("This is where the welcome area fountain is!!");
mapInstance.addMapWindow(mapWindow, new XYPoint(997,1002));
</pre>
The code adds an open window to the map positioned again at (997,1002), right above the welcome area fountain. NOTE: after the user closes the window there is no way to bring it back.  A subsequent example will show how to enable the user to reopen the window, by using markers with windows.
<br clear="all"/>
To make the map initially centered on the fountain, change the call to <code>centerAndZoomAtSLCoord()</code> as follows:
  mapInstance.centerAndZoomAtSLCoord(new XYPoint(997,1002),3);
'''Source code'''
This example shows how to create a map with a window. The code is the same as the first example, with the addition of some lines of Javascript after the initialization of the map, in the <code>loadmap()</code> function. In addition, the map is centered in a different location in order to make the window fully visible.
<pre>
<!-- Insert common HTML header -->
<script>
function loadmap() {
  mapInstance = new SLMap(document.getElementById('map-container'));
  mapInstance.centerAndZoomAtSLCoord(new XYPoint(997,1002),3);
 
  // creates a window
var mapWindow = new MapWindow("This is where the welcome area fountain is!!");
mapInstance.addMapWindow(mapWindow, new XYPoint(997,1002));
}
</script>
</head>
<body onload="loadmap()">
    <h1>Simple Map Example</h1>
<div id="map-container"></div>
</body>
</pre>
=== Map with a marker that opens a windows ===
[[Image:Map with marker and window.png|thumb|right|Map with marker that opens a window]]
This example shows how to create a map with a marker which opens a window when clicked.  It is a combination of the previous two examples, because the code first creates a marker and a window.  The difference comes in adding the marker to the map--this time you provide the window object as well as the marker object in the call to addMarker():
mapInstance.addMarker(marker, mapWindow);
Doing this adds the marker and causes it to open the specified window when the user clicks it.  If the user subsequently closes the window, he can open it again by clicking on the marker.
<br clear="all" />
'''Source code'''
<pre>
<!--- Insert HTML header --->
<script>
function loadmap() {
  // creates the map
  var mapInstance = new SLMap(document.getElementById('map-container'));
  mapInstance.centerAndZoomAtSLCoord(new XYPoint(997.5,1001.5),2);
 
  // creates the icons
  var yellow_dot_image = new Img("Yellow_marker.gif",9,9);
  var yellow_icon = new Icon(yellow_dot_image);
  var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];
 
  // creates the marker
  var marker = new Marker(all_images, new XYPoint(997,1002));
 
  // creates a window
  var mapWindow = new MapWindow("This is where the welcome area fountain is!! <br><img src='fountain.gif'>");
 
  // adds the marker to the map
  mapInstance.addMarker(marker, mapWindow);
}
</script>
</head>
<body onload="loadmap()">
<p>This map shows a yellow marker on the welcome fountain.  When you click the marker, a window appears with a screenshot of the fountain.
<div id="map-container"></div>
</body>
</pre>
== Accessing map images directly ==
You can also access the map images directly by reading them from the Amazon S3 servers. 
The file format:
<nowiki>http://map.secondlife.com.s3.amazonaws.com/Z/XXXXX/YYYYY/map-Z-X-Y-objects.jpg</nowiki>
Where:
* Z = Zoom level desired. One is the most zoomed-in view, showing individual region tiles. The current max/world zoom is eight.  <span style="background: yellow">In the previous section, it says six is max.  Which is it?</span>
* X,Y = The X and Y coordinates on the SL Grid of the region, for example, region Ahern is (997,1002).  Directory names are padded to five characters with leading zeros.
Tiles with zoom greater than 1 are stored at the lower left corner coordinate of the tiles that are included in the image.
In other words, you can find the zoom tile containing region /1/X/Y for zoom level Z at /Z/X - (X % Z)/Y - (Y % Z)
http://map.secondlife.com.s3.amazonaws.com/2/00498/00804/map-2-498-804-objects.jpg
For example: if Z = 2, the following four region tiles:
* http://map.secondlife.com.s3.amazonaws.com/1/01000/01000/map-1-1000-1000-objects.jpg
* http://map.secondlife.com.s3.amazonaws.com/1/01001/01000/map-1-1001-1000-objects.jpg
* http://map.secondlife.com.s3.amazonaws.com/1/01000/01001/map-1-1000-1001-objects.jpg
* http://map.secondlife.com.s3.amazonaws.com/1/01001/01001/map-1-1001-1001-objects.jpg
are compressed into the single tile:
http://map.secondlife.com.s3.amazonaws.com/2/01000/01000/map-2-1000-1000-objects.jpg
=== Other examples ===
The following shows the map zoomed all the way out, showing the entire Second Life world view:
http://map.secondlife.com.s3.amazonaws.com/8/01024/00896/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.s3.amazonaws.com/1/01027/01019/map-1-1027-1019-objects.jpg
=== Getting the URL of a sim map from LSL ===
<lsl>
ShowMap(key avatar) {
    string url = "http://map.secondlife.com.s3.amazonaws.com/1/";
    vector sim_coord = llGetRegionCorner();
    string x = (string)((integer)(sim_coord.x / 256.0));
    string y = (string)((integer)(sim_coord.y / 256.0));
    string x0 = llStringTrim(llGetSubString(" 00000", 0, 5 - llStringLength(x)), STRING_TRIM_HEAD) + x;
    string y0 = llStringTrim(llGetSubString(" 00000", 0, 5 - llStringLength(y)), STRING_TRIM_HEAD) + y;
    url += x0 + "/" + y0 + "/" + "map-1-" + x + "-" + y + "-objects.jpg";
    llLoadURL(avatar, "View the sim map", url);
}
</lsl>
Contributed under GPL v3 license by [[User:Henri Beauchamp|Henri Beauchamp]] 09:00, 24 January 2009 (UTC)
== Comments and feedback ==
We've developed this API around features we think will be most useful, but there is always room for improvement. So, if you encounter problems or bugs, have API feature requests, please email '''webmap@secondlife.com'''.
Happy coding from the Second Life Web team!

Latest revision as of 14:27, 4 May 2011

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

Extend the reach of your Web site into Second Life using the Second Life Map API, which enables you to embed interactive Second Life maps directly into your web pages. These maps look and act much like Google Maps, except that, instead of the Earth, they display the topography of the Second Life virtual world. See http://maps.secondlife.com/ for an example.

When you use the Map API to embed Second Life maps on your site, your visitors can:

  • Click and drag the mouse pointer to pan the map view up, down, left, and right.
  • Double-click to zoom in by one level (power of two) and display the teleport window.
  • Click anywhere on the map to open a "teleport" window.
  • Use the mouse wheel or pan controls to zoom in and out.

For more information, see Map API Introduction.

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