Merge pull request #886 from mapbox/conversions-squash

fixes #476 & #853: pixel/meter/latlng conversion routines in core & iOS

android/cpp/jni.cpp

@@ -467,17 +467,16 @@ void JNICALL nativeSetLonLat(JNIEnv *env, jobject obj, jlong nativeMapViewPtr, j
         return;
     }
 
-    nativeMapView->getMap().setLonLat(lon, lat, std::chrono::milliseconds(duration));
+    nativeMapView->getMap().setLatLng(mbgl::LatLng(lat, lon), std::chrono::milliseconds(duration));
 }
 
 jobject JNICALL nativeGetLonLat(JNIEnv *env, jobject obj, jlong nativeMapViewPtr) {
     mbgl::Log::Debug(mbgl::Event::JNI, "nativeGetLonLat");
     assert(nativeMapViewPtr != 0);
     NativeMapView *nativeMapView = reinterpret_cast<NativeMapView *>(nativeMapViewPtr);
-    double lon = 0.0, lat = 0.0;
-    nativeMapView->getMap().getLonLat(lon, lat);
+    mbgl::LatLng latLng = nativeMapView->getMap().getLatLng();
 
-    jobject ret = env->NewObject(lonLatClass, lonLatConstructorId, lon, lat);
+    jobject ret = env->NewObject(lonLatClass, lonLatConstructorId, latLng.longitude, latLng.latitude);
     if (ret == nullptr) {
         env->ExceptionDescribe();
         return nullptr;
@@ -569,17 +568,17 @@ void JNICALL nativeSetLonLatZoom(JNIEnv *env, jobject obj, jlong nativeMapViewPt
         return;
     }
 
-    nativeMapView->getMap().setLonLatZoom(lon, lat, zoom, std::chrono::milliseconds(duration));
+    nativeMapView->getMap().setLatLngZoom(mbgl::LatLng(lat, lon), zoom, std::chrono::milliseconds(duration));
 }
 
 jobject JNICALL nativeGetLonLatZoom(JNIEnv *env, jobject obj, jlong nativeMapViewPtr) {
     mbgl::Log::Debug(mbgl::Event::JNI, "nativeGetLonLatZoom");
     assert(nativeMapViewPtr != 0);
     NativeMapView *nativeMapView = reinterpret_cast<NativeMapView *>(nativeMapViewPtr);
-    double lon = 0.0, lat = 0.0, zoom = 0.0;
-    nativeMapView->getMap().getLonLatZoom(lon, lat, zoom);
+    mbgl::LatLng latLng = nativeMapView->getMap().getLatLng();
+    double zoom = nativeMapView->getMap().getZoom();
 
-    jobject ret = env->NewObject(lonLatZoomClass, lonLatZoomConstructorId, lon, lat, zoom);
+    jobject ret = env->NewObject(lonLatZoomClass, lonLatZoomConstructorId, latLng.longitude, latLng.latitude, zoom);
     if (ret == nullptr) {
         env->ExceptionDescribe();
         return nullptr;

bin/render.cpp

@@ -100,7 +100,7 @@ int main(int argc, char *argv[]) {
 
     view.resize(width, height, pixelRatio);
     map.resize(width, height, pixelRatio);
-    map.setLonLatZoom(lon, lat, zoom);
+    map.setLatLonZoom(LatLng(lat, lon), zoom);
     map.setBearing(bearing);
 
     std::unique_ptr<uint32_t[]> pixels;

include/mbgl/ios/MGLMapView.h

@@ -131,6 +131,30 @@
 /** Resets the map rotation to a northern heading. */
 - (void)resetNorth;
 
+#pragma mark - Converting Map Coordinates
+
+/** @name Converting Map Coordinates */
+
+/** Converts a point in the specified view’s coordinate system to a map coordinate.
+*   @param point The point you want to convert.
+*   @param view The view that serves as the reference coordinate system for the `point` parameter.
+*   @return The map coordinate at the specified point. */
+- (CLLocationCoordinate2D)convertPoint:(CGPoint)point toCoordinateFromView:(UIView *)view;
+
+/** Converts a map coordinate to a point in the specified view.
+*   @param coordinate The map coordinate for which you want to find the corresponding point.
+*   @param view The view in whose coordinate system you want to locate the specified map coordinate. If this parameter is `nil`, the returned point is specified in the window’s coordinate system. If `view` is not `nil`, it must belong to the same window as the map view.
+*   @return The point (in the appropriate view or window coordinate system) corresponding to the specified latitude and longitude value. */
+- (CGPoint)convertCoordinate:(CLLocationCoordinate2D)coordinate toPointToView:(UIView *)view;
+
+/** Returns the distance spanned by one pixel at the specified latitude and current zoom level.
+*
+*   The distance between pixels decreases as the latitude approaches the poles. This relationship parallels the relationship between longitudinal coordinates at different latitudes.
+*
+*   @param latitude The latitude for which to return the value.
+*   @return The distance (in meters) spanned by a single pixel. */
+- (CLLocationDistance)metersPerPixelAtLatitude:(CLLocationDegrees)latitude;
+
 #pragma mark - Styling the Map
 
 /** @name Styling the Map */

include/mbgl/map/map.hpp

@@ -2,9 +2,12 @@
 #define MBGL_MAP_MAP
 
 #include <mbgl/map/transform.hpp>
+#include <mbgl/util/geo.hpp>
+#include <mbgl/util/projection.hpp>
 #include <mbgl/util/noncopyable.hpp>
 #include <mbgl/util/uv.hpp>
 #include <mbgl/util/ptr.hpp>
+#include <mbgl/util/vec.hpp>
 
 #include <cstdint>
 #include <atomic>
@@ -94,8 +97,8 @@ class Map : private util::noncopyable {
 
     // Position
     void moveBy(double dx, double dy, std::chrono::steady_clock::duration duration = std::chrono::steady_clock::duration::zero());
-    void setLonLat(double lon, double lat, std::chrono::steady_clock::duration duration = std::chrono::steady_clock::duration::zero());
-    void getLonLat(double &lon, double &lat) const;
+    void setLatLng(LatLng latLng, std::chrono::steady_clock::duration duration = std::chrono::steady_clock::duration::zero());
+    inline const LatLng getLatLng() const { return state.getLatLng(); }
     void startPanning();
     void stopPanning();
     void resetPosition();
@@ -106,8 +109,7 @@ class Map : private util::noncopyable {
     double getScale() const;
     void setZoom(double zoom, std::chrono::steady_clock::duration duration = std::chrono::steady_clock::duration::zero());
     double getZoom() const;
-    void setLonLatZoom(double lon, double lat, double zoom, std::chrono::steady_clock::duration duration = std::chrono::steady_clock::duration::zero());
-    void getLonLatZoom(double &lon, double &lat, double &zoom) const;
+    void setLatLngZoom(LatLng latLng, double zoom, std::chrono::steady_clock::duration duration = std::chrono::steady_clock::duration::zero());
     void resetZoom();
     void startScaling();
     void stopScaling();
@@ -127,6 +129,15 @@ class Map : private util::noncopyable {
     void setAccessToken(const std::string &token);
     const std::string &getAccessToken() const;
 
+    // Projection
+    inline void getWorldBoundsMeters(ProjectedMeters &sw, ProjectedMeters &ne) const { Projection::getWorldBoundsMeters(sw, ne); }
+    inline void getWorldBoundsLatLng(LatLng &sw, LatLng &ne) const { Projection::getWorldBoundsLatLng(sw, ne); }
+    inline double getMetersPerPixelAtLatitude(const double lat, const double zoom) const { return Projection::getMetersPerPixelAtLatitude(lat, zoom); }
+    inline const ProjectedMeters projectedMetersForLatLng(const LatLng latLng) const { return Projection::projectedMetersForLatLng(latLng); }
+    inline const LatLng latLngForProjectedMeters(const ProjectedMeters projectedMeters) const { return Projection::latLngForProjectedMeters(projectedMeters); }
+    inline const vec2<double> pixelForLatLng(const LatLng latLng) const { return state.pixelForLatLng(latLng); }
+    inline const LatLng latLngForPixel(const vec2<double> pixel) const { return state.latLngForPixel(pixel); }
+
     // Debug
     void setDebug(bool value);
     void toggleDebug();

include/mbgl/map/transform.hpp

@@ -2,7 +2,9 @@
 #define MBGL_MAP_TRANSFORM
 
 #include <mbgl/map/transform_state.hpp>
+#include <mbgl/util/geo.hpp>
 #include <mbgl/util/noncopyable.hpp>
+#include <mbgl/util/vec.hpp>
 
 #include <cstdint>
 #include <cmath>
@@ -26,10 +28,9 @@ class Transform : private util::noncopyable {
 
     // Position
     void moveBy(double dx, double dy, std::chrono::steady_clock::duration duration = std::chrono::steady_clock::duration::zero());
-    void setLonLat(double lon, double lat, std::chrono::steady_clock::duration duration = std::chrono::steady_clock::duration::zero());
-    void setLonLatZoom(double lon, double lat, double zoom, std::chrono::steady_clock::duration duration = std::chrono::steady_clock::duration::zero());
-    void getLonLat(double& lon, double& lat) const;
-    void getLonLatZoom(double& lon, double& lat, double& zoom) const;
+    void setLatLng(LatLng latLng, std::chrono::steady_clock::duration duration = std::chrono::steady_clock::duration::zero());
+    void setLatLngZoom(LatLng latLng, double zoom, std::chrono::steady_clock::duration duration = std::chrono::steady_clock::duration::zero());
+    inline const LatLng getLatLng() const { return current.getLatLng(); }
     void startPanning();
     void stopPanning();
 
@@ -91,9 +92,6 @@ class Transform : private util::noncopyable {
     const double min_scale = std::pow(2, 0);
     const double max_scale = std::pow(2, 18);
 
-    // cache values for spherical mercator math
-    double Bc, Cc;
-
     std::forward_list<util::ptr<util::transition>> transitions;
     util::ptr<util::transition> scale_timeout;
     util::ptr<util::transition> rotate_timeout;

include/mbgl/map/transform_state.hpp

@@ -4,6 +4,8 @@
 #include <mbgl/map/tile.hpp>
 
 #include <mbgl/util/mat4.hpp>
+#include <mbgl/util/geo.hpp>
+#include <mbgl/util/vec.hpp>
 
 #include <cstdint>
 #include <array>
@@ -34,6 +36,9 @@ class TransformState {
     std::array<float, 2> locationCoordinate(float lon, float lat) const;
     void getLonLat(double &lon, double &lat) const;
 
+    // Position
+    const LatLng getLatLng() const;
+
     // Zoom
     float getNormalizedZoom() const;
     double getZoom() const;
@@ -44,6 +49,10 @@ class TransformState {
     // Rotation
     float getAngle() const;
 
+    // Projection
+    const vec2<double> pixelForLatLng(const LatLng latLng) const;
+    const LatLng latLngForPixel(const vec2<double> pixel) const;
+
     // Changing
     bool isChanging() const;
 
@@ -61,6 +70,9 @@ class TransformState {
     // map scale factor
     float pixelRatio = 0;
 
+    // cache values for spherical mercator math
+    double Bc, Cc;
+
     // animation state
     bool rotating = false;
     bool scaling = false;

include/mbgl/util/constants.hpp

@@ -8,6 +8,13 @@ namespace mbgl {
 namespace util {
 
 extern const float tileSize;
+
+extern const double DEG2RAD;
+extern const double RAD2DEG;
+extern const double M2PI;
+extern const double EARTH_RADIUS_M;
+extern const double LATITUDE_MAX;
+
 }
 
 namespace debug {

include/mbgl/util/geo.hpp

@@ -0,0 +1,24 @@
+#ifndef MBGL_UTIL_GEO
+#define MBGL_UTIL_GEO
+
+namespace mbgl {
+
+struct LatLng {
+    double latitude = 0;
+    double longitude = 0;
+
+    inline LatLng(double lat = 0, double lon = 0)
+        : latitude(lat), longitude(lon) {}
+};
+
+struct ProjectedMeters {
+    double northing = 0;
+    double easting = 0;
+
+    inline ProjectedMeters(double n = 0, double e = 0)
+        : northing(n), easting(e) {}
+};
+
+}
+
+#endif

include/mbgl/util/projection.hpp

@@ -0,0 +1,65 @@
+#ifndef MBGL_UTIL_PROJECTION
+#define MBGL_UTIL_PROJECTION
+
+#include <mbgl/util/constants.hpp>
+#include <mbgl/util/geo.hpp>
+
+#include <cmath>
+
+namespace mbgl {
+
+class Projection {
+
+public:
+    static inline void getWorldBoundsMeters(ProjectedMeters &sw, ProjectedMeters &ne) {
+        const double d = util::EARTH_RADIUS_M * M_PI;
+
+        sw.easting  = -d;
+        sw.northing = -d;
+
+        ne.easting  =  d;
+        ne.northing =  d;
+    }
+
+    static inline void getWorldBoundsLatLng(LatLng &sw, LatLng &ne) {
+        ProjectedMeters projectedMetersSW = ProjectedMeters();
+        ProjectedMeters projectedMetersNE = ProjectedMeters();
+
+        getWorldBoundsMeters(projectedMetersSW, projectedMetersNE);
+
+        sw = latLngForProjectedMeters(projectedMetersSW);
+        ne = latLngForProjectedMeters(projectedMetersNE);
+    }
+
+    static inline double getMetersPerPixelAtLatitude(const double lat, const double zoom) {
+        const double mapPixelWidthAtZoom = std::pow(2.0, zoom) * util::tileSize;
+        const double constrainedLatitude = std::fmin(std::fmax(lat, -util::LATITUDE_MAX), util::LATITUDE_MAX);
+
+        return std::cos(constrainedLatitude * util::DEG2RAD) * util::M2PI * util::EARTH_RADIUS_M / mapPixelWidthAtZoom;
+    }
+
+    static inline const ProjectedMeters projectedMetersForLatLng(const LatLng latLng) {
+        const double constrainedLatitude = std::fmin(std::fmax(latLng.latitude, -util::LATITUDE_MAX), util::LATITUDE_MAX);
+
+        const double m = 1 - 1e-15;
+        const double f = std::fmin(std::fmax(std::sin(util::DEG2RAD * constrainedLatitude), -m), m);
+
+        const double easting  = util::EARTH_RADIUS_M * latLng.longitude * util::DEG2RAD;
+        const double northing = 0.5 * util::EARTH_RADIUS_M * std::log((1 + f) / (1 - f));
+
+        return ProjectedMeters(northing, easting);
+    }
+
+    static inline const LatLng latLngForProjectedMeters(const ProjectedMeters projectedMeters) {
+        double latitude = (2 * std::atan(std::exp(projectedMeters.northing / util::EARTH_RADIUS_M)) - (M_PI / 2)) * util::RAD2DEG;
+        double longitude = projectedMeters.easting * util::RAD2DEG / util::EARTH_RADIUS_M;
+
+        latitude = std::fmin(std::fmax(latitude, -util::LATITUDE_MAX), util::LATITUDE_MAX);
+
+        return LatLng(latitude, longitude);
+    }
+};
+
+}
+
+#endif

linux/main.cpp

@@ -72,7 +72,7 @@ int main(int argc, char *argv[]) {
 
     // Load settings
     mbgl::Settings_JSON settings;
-    map.setLonLatZoom(settings.longitude, settings.latitude, settings.zoom);
+    map.setLatLngZoom(mbgl::LatLng(settings.latitude, settings.longitude), settings.zoom);
     map.setBearing(settings.bearing);
     map.setDebug(settings.debug);
 
@@ -94,7 +94,10 @@ int main(int argc, char *argv[]) {
     int ret = view->run();
 
     // Save settings
-    map.getLonLatZoom(settings.longitude, settings.latitude, settings.zoom);
+    mbgl::LatLng latLng = map.getLatLng();
+    settings.latitude = latLng.latitude;
+    settings.longitude = latLng.longitude;
+    settings.zoom = map.getZoom();
     settings.bearing = map.getBearing();
     settings.debug = map.getDebug();
     settings.save();

macosx/main.mm

@@ -7,6 +7,8 @@
 #include <mbgl/storage/default/sqlite_cache.hpp>
 #include <mbgl/storage/network_status.hpp>
 
+#include <mbgl/util/geo.hpp>
+
 #import <Foundation/Foundation.h>
 
 @interface URLHandler : NSObject
@@ -31,15 +33,16 @@ - (void)handleGetURLEvent:(NSAppleEventDescriptor *)event
         [params setObject:[parts objectAtIndex:1] forKey:[parts objectAtIndex:0]];
     }
 
-    double latitude = 0, longitude = 0, zoom = 0, bearing = 0;
+    mbgl::LatLng latLng = mbgl::LatLng(0, 0);
+    double zoom = 0, bearing = 0;
     bool hasCenter = false, hasZoom = false, hasBearing = false;
 
     NSString *centerString = [params objectForKey:@"center"];
     if (centerString) {
-        NSArray *latlon = [centerString componentsSeparatedByString:@","];
-        if ([latlon count] == 2) {
-            latitude = [[latlon objectAtIndex:0] doubleValue];
-            longitude = [[latlon objectAtIndex:1] doubleValue];
+        NSArray *latLngValues = [centerString componentsSeparatedByString:@","];
+        if ([latLngValues count] == 2) {
+            latLng.latitude  = [latLngValues[0] doubleValue];
+            latLng.longitude = [latLngValues[1] doubleValue];
             hasCenter = true;
         }
     }
@@ -58,9 +61,9 @@ - (void)handleGetURLEvent:(NSAppleEventDescriptor *)event
 
     if ([self map]) {
         if (hasCenter && hasZoom) {
-            [self map]->setLonLatZoom(longitude, latitude, zoom);
+            [self map]->setLatLngZoom(latLng, zoom);
         } else if (hasCenter) {
-            [self map]->setLonLat(longitude, latitude);
+            [self map]->setLatLng(latLng);
         } else if (hasZoom) {
             [self map]->setZoom(zoom);
         }
@@ -120,7 +123,7 @@ int main() {
 
     // Load settings
     mbgl::Settings_NSUserDefaults settings;
-    map.setLonLatZoom(settings.longitude, settings.latitude, settings.zoom);
+    map.setLatLngZoom(mbgl::LatLng(settings.latitude, settings.longitude), settings.zoom);
     map.setBearing(settings.bearing);
     map.setDebug(settings.debug);
 
@@ -137,7 +140,10 @@ int main() {
     [reachability stopNotifier];
 
     // Save settings
-    map.getLonLatZoom(settings.longitude, settings.latitude, settings.zoom);
+    mbgl::LatLng latLng = map.getLatLng();
+    settings.latitude = latLng.latitude;
+    settings.longitude = latLng.longitude;
+    settings.zoom = map.getZoom();
     settings.bearing = map.getBearing();
     settings.debug = map.getDebug();
     settings.save();