UI Classes
There are three primary UI classes, which connect the three kinds of geometry classes described below.
Map
Map is the core class of Modest Maps. Attaching an instance of this MovieClip subclass and calling its init() method will create a fully-functional interactive map.
The map knows about Points and Locations, and can convert between them:
- pointLocation() converts from an x, y point to a lat, lon location.
- locationPoint() converts from a lat, lon location to an x, y point.
Class: com.modestmaps.Map
Tile Grid
TileGrid is the geography-agnostic tile placement core of a map. It places, moves, and displays tiles within a map.
The grid knows about Points and Coordinates, and can convert between them:
- pointCoordinate() converts from an x, y point to a row, column, zoom coordinate.
- coordinatePoint() converts from a row, column, zoom coordinate to an x, y point.
Class: com.modestmaps.core.TileGrid
Map Provider
An implementation of the IMapProvider interface provides geographical info for the map, and paints tiles with the appropriate images for their coordinate.
The provider knows about Locations and Coordinates, and can convert between them:
- locationCoordinate() converts from an lat, long location to a row, column, zoom coordinate.
- coordinateLocation() converts from a row, column, zoom coordinate to an lat, long location.
The provider also provides boundaries for panning and zooming the rendering map. These are expressed as a pair of coordinates:
- top/left/outer-zoom places a boundary at the top left, and the furthest-out zoom (smallest map) possible. For the NASA Blue Marble provider, this is (0, -infinity, 0). The -infinity means that the map can be scrolled infinitely far to the left.
- bottom/right/inner-zoom places a boundary at the bottom right, and the furthest-in zoom (largest map) possible. For the NASA Blue Marble provider, this is (512, +infinity, 9). The +infinity means that the map can be scrolled infinitely far to the right.
Class: com.modestmaps.mapproviders.IMapProvider
Most of the map providers distributed with Modest Maps (Blue Marble, Google, Yahoo, Microsoft, etc.) all have the following definition in their constructors:
var t:Transformation = new Transformation(1.068070779e7, 0, 3.355443185e7, 0, -1.068070890e7, 3.355443057e7); __projection = new MercatorProjection(26, t);
Transformation
This is a linear transformation between two-dimensional points.
The one in the example above means: take a point, multiply its x by 1.068070779e7 and add 3.355443185e7, then multiply its y by -1.068070890e7 and add 3.355443057e7. These numbers were derived by examining the major commercial map providers, determining that they all used the same underlying projection and coordinate transformation (i.e. take a square Mercator world map, divide it into quarters until you run out of detail), and visually comparing known points on each map to their corresponding image tiles. Notes on this in TileCoordinateComparisons.
Class: com.modestmaps.geo.Transformation
Projection
A map provider contains a Projection, which does the actual work of converting between locations and coordinates. "Projecting" refers to the process of taking a three-dimensional globe with latitude and longitude locations on it, and flattening it out onto a two-dimensional map. Most of the big-name commercial tile providers use the Mercator projection. Just using projections (as defined in places like MathWorld) will yield small floating point values that are not immediately useful for drawing maps. The projection's transformation takes this raw output and converts it to usable coordinate values.
The 26 in the example above means the the two-dimensional transformation for that Mercator projection was calculated at zoom level 26, the highest zoom level for which reliable data could be found on the major map providers. Notes on this in TileCoordinateComparisons.
Class: com.modestmaps.geo.IProjection
Geometry Classes
The three geometry classes describe the three kinds of position information used in a map.
Location
Location is a geographical latitude and longitude, expressed as a simple pair of numbers. For example, San Francisco is near 37°N, 122°W or Location(37, -122).
Class: com.modestmaps.geo.Location
Point
Point is a pixel position in Flash, expressed as a simple pair of numbers. The methods of Map and TileGrid that convert points also accept a context clip parameter. This is used to locate the pixel within a particular movie clip, starting at 0, 0 in the upper-lefthand corner.
Class: flash.geom.Point
Coordinate
Coordinate is a three dimensional position that helps to convert between zoom levels. It is expressed as a row, column, and zoom. Zoom levels in Modest Maps start at zero, and grow as you zoom in. Tile providers typically express tile locations in such coordinates, which is why the map provider interface understands coordinates and not points. Whole-number coordinates in the tile grid correspond exactly to tile images requested from the provider server.
Class: com.modestmaps.core.Coordinate
