From 5a95ed9c9419c15352b8dc1d895c9adce30f99f5 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Sat, 6 Oct 2018 12:00:45 -0700 Subject: Add map-loading documentation Signed-off-by: Keith Packard --- doc/map-loading.txt | 221 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 221 insertions(+) create mode 100644 doc/map-loading.txt (limited to 'doc/map-loading.txt') diff --git a/doc/map-loading.txt b/doc/map-loading.txt new file mode 100644 index 00000000..3dffcd04 --- /dev/null +++ b/doc/map-loading.txt @@ -0,0 +1,221 @@ += Loading Map Tiles from Google Maps +:doctype: article + +== The Google Maps Problem + +Until recently, Google Maps could be used without fee to fetch map +tiles. Applications could load map tiles anonymously or using a key; +when used anonymously, the number of tiles that could be loaded per +day and the rate at which tiles could be loaded was throttled to make +the API practical only for development purpose. With an application +key, the number of tiles available per day was much higher, and there +was no rate limiting. This was usually sufficient for Altos Metrum +customer use. + +However, this has changed and now there is no way to load map tiles +anonymously, and any application key must be tied to a credit +card. The tile cap for free usage is now monthly instead of +daily. Because the key is tied to a credit card, we should not ship it +with the application any longer. And because the cap is monthly +instead of daily, we need some way to control usage by our +applications. + +=== The Proposed Solution — An Intermediate Service + +To give us some measure of control over tile loading, we will want to +interpose a server controlled by us between the application and Google +Maps. This will let us store the Google Maps key in a secure location, +and also control tile loading by each user. + +image::map-loading.svg[align="center"] + +== AltOS Map Service + +This service receives a URL request and replies with either a map tile +or an error. It is functionally equivalent to the Google Maps service, +except that it can control use of the Google Maps API. + +=== AltOS Map CGI Script + +The AltOS Map CGI Script is a straightforward script which connects to +the AltOS Map Cache Manager, transmits a URL describing the desired +map tile and receives back a filename (or error), then sends the +contents of that file back through Apache to the requesting +application. The name of the script is 'altos-map'. + +==== Inputs + +The AltOS Map CGI Script will parse the provided AltOS Map URI or +AltOS Version URI. + +==== Outputs + +For AltOS Map URLs, the CGI Script will return either the contents of +the associated Google Map tile or an error indicating what failed: + +_200 OK_: The map tile image data or version information + +_400 Bad Request_: The URL is malformed or not compatible with the +version supported by the service + +_403 Forbidden_: The map tile is outside the areas supported by the +current AltOS Map service area + +_408 Request Timeout_: Attempts to fetch the tile from Google Maps +timed out. + +_503 Service Unavailable_: The service is temporarily refusing to +satisfy this request due to resource limitations. + +=== AltOS Map Cache Manager + +This is a service running on the local machine and available over a +local network socket. It translates an AltOS Map URL into a local +filename containing the contents of the associated Google Maps +tile. The name of the cache manager is 'altos-mapd'. It will listen +for requests on port 16717. + +=== AltOS Map URI + +AltOS uses a limited subset of the Google Maps, and the AltOS Map URIs +only encode those elements which we currently use. This specification +describes AltOS Map URI format version 1.0.0. The application is +required to provide URIs compatible with the format supported by the +server. The elements of the elements are: + + * Latitude of center point + * Longitude of center point + * Zoom level (from bushes to planets) + +Encoding this in a URI is straightforward: + +\ altos-map?center=,&zoom= + +Latitude and longitude are both encoded using decimal degrees with 6 +digits following the decimal point. + +Zoom levels can range from 1 (world) to 20 (buildings). Higher zoom +levels show smaller areas at greater detail. + +The only Google Map type supported by version 1.0.0 of the service is +“hybrid”, which combines road graphics on top of satellite images. + +Version 1.0.0 always returns images which are 512x512 pixels. + +If we need additional elements in the URL, we can add them in the +future and bump the supported version number. + +=== AltOS Version URI + +To allow applications to discover what AltOS Map URI version is supported by the +AltOS Map service, the application may query the version of the API +supported using the Version URI. The application provides the version +that it supports and the AltOS Map service returns a version not +greater than the client version: + +\ altos-map?version=.. +\ → +\ .. + +=== AltOS Tile Request + +The AltOS Map CGI Script parses the Map URI and passes that +information to the AltOS Map Cache Manager using the AltOS Tile +Specifier syntax. This is a JSON representation of the same data +provided by the URI: + +\ { +\ "lat": , +\ "lon": , +\ "zoom": , +\ "remote_addr": "" +\ } + +Latitude and longitude are both encoded using decimal degrees with 6 +digits following the decimal point. + +=== AltOS Tile Reply + +Sent back from the Cache Manager to the CGI Script, this encodes the +status of the request and the filename of any tile data available. It +is encoded in JSON format: + +\ { +\ "status": , +\ "filename": "", +\ "content_type": "" +\ } + +The “filename” and “content-type” elements are only included when +the status is _200 OK_. + +=== AltOS Tile Filename + +While the current AltOS Map URI version only supports a limited subset +of the Google Maps functionality, we'll encode more of that data in +filenames to allow for easy expansion of functionality in the +future. The elements of an AltOS Tile filename consist of : + + * Latitude, with N/S indicator (instead of a sign) + * Longitude, with E/W indicator (instead of a sign) + * Map type. + * Zoom level + * Scale factor. Scale, and the preceding hyphen are omitted for a scale factor of 1. + * Image format suffix. '.jpg' for JPEG files and '.png' for PNG files. + +Latitude and longitude are both encoded using decimal degrees with 6 +digits following the decimal point. + +Map type is one of : + + _hybrid_: Road graphics over satellite images + _roadmap_: Symbolic road map + _satellite_: Un-annotated satellite images + _terrain_: Topographic map + +Here's what map filenames look like: + +\ map-{N,S},{E,W}--[-]. +\ +\ map-N36.508532,W107.823944-hybrid-18.jpg + +To transmit this name from the AltOS Map Cache Manager back to the +Altos Map CGI script, the filename will be wrapped in a JSON string + +== Implementation + +The AltOS Map CGI Script and AltOS Map Cache Manager will both be +implemented in Java as much of the required Google Maps infrastructure +is already available in that language. + +=== Access Control + +No access control to the service is planned at this point. If +necessary, we could implement username/password access control for each +user of the service. + +=== Location Restrictions + +To avoid unbounded usage, and confine the utility of this service to +AltOS users, the service will only offer map tiles whose center +location is within 10 miles of one of the sites registered in +our launch sites database. + +To allow testing of the registered launch site database, a database of +privileged clients will be supported. Privileged clients will have +unlimited access to the service. + +=== Per-Client Restrictions + +We should implement a per-day limit on the number of tiles provided to +a particular requesting client. We can also rate limit clients to a +certain number of tiles per minute to reduce the bandwidth consumed +out of our server. + +=== Cache Lifetime Restrictions. + +The Google Maps API allows for caching of map data for no more than 30 +days. To honor this, the Cache Manager will re-fetch any requested +tiles when the cached version is older than this. If the fetch fails, +the cache manager will continue to serve the data from the cached +version of the file. -- cgit v1.2.3 From ff5faf1cc710b7e9299dcaec719bc2421f4ca5b4 Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Sat, 6 Oct 2018 20:21:07 -0700 Subject: altoslib: Change map loading to lat=&lon= from center= This is easier to parse. Signed-off-by: Keith Packard --- altoslib/AltosMapStore.java | 2 +- doc/map-loading.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/map-loading.txt') diff --git a/altoslib/AltosMapStore.java b/altoslib/AltosMapStore.java index abd8c240..7e0f3fb8 100644 --- a/altoslib/AltosMapStore.java +++ b/altoslib/AltosMapStore.java @@ -57,7 +57,7 @@ public class AltosMapStore { } private static String altos_map_url(AltosLatLon center, int zoom, int maptype, int px_size, int scale, String format_string) { - return String.format("https://maps.altusmetrum.org/altos-map?center=%.6f,%.6f&zoom=%d", + return String.format("https://maps.altusmetrum.org/cgi-bin/altos-map?lat=%.6f&lon=%.6f&zoom=%d", center.lat, center.lon, zoom); } diff --git a/doc/map-loading.txt b/doc/map-loading.txt index 3dffcd04..1b39dd6b 100644 --- a/doc/map-loading.txt +++ b/doc/map-loading.txt @@ -89,7 +89,7 @@ server. The elements of the elements are: Encoding this in a URI is straightforward: -\ altos-map?center=,&zoom= +\ altos-map?lat=&lon=&zoom= Latitude and longitude are both encoded using decimal degrees with 6 digits following the decimal point. -- cgit v1.2.3