Point, Location, and Coordinate

Converting Point/Location/Coordinate

To convert from geographic Locations to on screen Points, use map.pointLocation and map.locationPoint:

// Dijbouti
var l1 = new MM.Location(11.7, 42.5);

// Dijbouti on screen:
var p1 = map.locationPoint(l1);

// some pixels in the map:
var p2 = new MM.Point(100, 100);

// the geographic location of p2:
var l2 = map.pointLocation(p2);

There are also equivalent internal functions for converting to/from coordinates: coordinatePoint(coord) and pointCoordinate(point).

Point

Points are places on your screen, within the map element. They are typically not geographic. Modest Maps also uses the point datatype to represent sizes: the third argument to the MM.Map constructor is a point in the form of new MM.Point(width, height).

Constructor

var point = new MM.Point(x, y)

Class Methods

// Get a point between two other points, biased by `t`.
var p3 = MM.Point.interpolate(p1, p2, t)

// Get the euclidean distance between two points
var d = MM.Point.distance(p1, p2);

Point is a simple data object with x and y properties. It's most often used to represent pixel positions on screen or within the map.

var p1 = new MM.Point(10, 20);
var p2 = new MM.Point(20, 20);

// d is 10
var d = MM.Point.distance(p1,p2);

// p3 is half way between p1 and p2: (15,20)
var amount = 0.5;
var p3 = MM.Point.interpolate(p1,p2,amount);

Location

Locations are places in the world: they are in latitude and longitude. If you were to store markers, you'd store their locations as locations, and only convert them into points in order to position them on the map element.

Constructor

var loc = new MM.Location(latitude, longitude);

Class Methods

// Get the distance between two points, in
// meters, with a sphere of radius r meters (default 6378000)
var d = MM.Location.distance(l1, l2, r)

// Get the interpolation of two points, biased by f,
// along the great circle
var l3 = MM.Location.interpolate(l1, l2, f)

Location is similar to Point, but for geographic coordinates. It has lat and lon properties (and expects them in that order, unlike Point which works the other way around). It represents locations on the surface of the earth in degrees latitude and longitude. You can use a site like getlatlon.com to find the latitude and longitude of places by name.

// Create a new location at 30 latitude, 114 longitude (Xinjiezhen)
var loc = new MM.Location(30, 114);

Coordinate

Coordinates are places in tiles. They're geographic but in a way more specific than Location and not based on conventional latitude and longitude - they represent tile coordinates and include a z - zoom - dimension.

Constructor

var coord = new MM.Coordinate(row, column, zoom);

Instance Methods

// Get a string key to refer to this coordinate
var key = coord.toKey();

// Get the whole-number coordinate that contains a potentially
// in-between coordinate
var container = coord.container();

// Get a copy of this coordinate
var copy = coord.copy();

// Navigation with coordinates
var zoomedTo = coord.zoomTo(5);
var zoomedIn = coord.zoomTo(1);
var pannedLeft = coord.left(1);

Coordinate is used internally to represent tiles, and the map state - so they have instance functions that let you do all of the navigation that you'd expect out of a map. It has row, column and zoom properties.

It also has several methods that help you navigate from one coordinate to another: up, right, down, left, zoomTo and zoomBy. All return a new Coordinate. Additionally, copy can be used to clone a Coordinate and container can be used to obtain a Coordinate with floored row, column and zoom for generating tile URLs.