Package org.oscim.core

Class MercatorProjection

java.lang.Object
org.oscim.core.MercatorProjection
public final class MercatorProjection extends Object
An implementation of the spherical Mercator projection.

There are generally two methods for each operation: one taking a byte zoom level and a parallel one taking a double scale. The scale is Math.pow(2, zoomLevel) for a given zoom level, but the operations take intermediate values as well. The zoom level operation is a little faster as it can make use of shift operations, the scale operation offers greater flexibility in computing the values for intermediate zoom levels.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final double
    EARTH_CIRCUMFERENCE
    The circumference of the earth at the equator in meters.
    static final double
    LATITUDE_MAX
    Maximum possible latitude coordinate of the map.
    static final double
    LATITUDE_MIN
    Minimum possible latitude coordinate of the map.
    static final double
    LONGITUDE_MAX
    Maximum possible longitude coordinate of the map.
    static final double
    LONGITUDE_MIN
    Minimum possible longitude coordinate of the map.

  • Method Summary

    Modifier and Type
    Method
    Description
    static GeoPoint
    fromPixels(double pixelX, double pixelY, long mapSize)
    Get GeoPoint from Pixels.
    static GeoPoint
    fromPixelsWithScale(double pixelX, double pixelY, double scale)
    Get GeoPoint from Pixels.
    static long
    getMapSize(byte zoomLevel)
     
    static long
    getMapSizeWithScale(double scale)
     
    static Point
    getPixel(GeoPoint geoPoint, long mapSize)
     
    static Point
    getPixelAbsolute(GeoPoint geoPoint, long mapSize)
    Calculates the absolute pixel position for a map size and tile size
    static Point
    getPixelRelative(GeoPoint geoPoint, long mapSize, double x, double y)
    Calculates the absolute pixel position for a map size and tile size relative to origin
    static Point
    getPixelRelative(GeoPoint geoPoint, long mapSize, Point origin)
    Calculates the absolute pixel position for a map size and tile size relative to origin
    static Point
    getPixelRelativeToTile(GeoPoint geoPoint, Tile tile)
    Calculates the absolute pixel position for a tile and tile size relative to origin
    static Point
    getPixelWithScale(GeoPoint geoPoint, double scale)
     
    static double
    groundResolution(double latitude, long mapSize)
    Calculates the distance on the ground that is represented by a single pixel on the map.
    static double
    groundResolution(MapPosition pos)
     
    static double
    groundResolutionWithScale(double latitude, double scale)
    Calculates the distance on the ground that is represented by a single pixel on the map.
    static double
    latitudeToPixelY(double latitude, byte zoomLevel)
    Converts a latitude coordinate (in degrees) to a pixel Y coordinate at a certain zoom level.
    static double
    latitudeToPixelY(double latitude, long mapSize)
    Converts a latitude coordinate (in degrees) to a pixel Y coordinate at a certain map size.
    static double
    latitudeToPixelYWithScale(double latitude, double scale)
    Converts a latitude coordinate (in degrees) to a pixel Y coordinate at a certain scale.
    static int
    latitudeToTileY(double latitude, byte zoomLevel)
    Converts a latitude coordinate (in degrees) to a tile Y number at a certain zoom level.
    static int
    latitudeToTileYWithScale(double latitude, double scale)
    Converts a latitude coordinate (in degrees) to a tile Y number at a certain scale.
    static double
    latitudeToY(double latitude)
    Projects a latitude coordinate (in degrees) to the range [0.0,1.0]
    static double
    limitLatitude(double latitude)
     
    static double
    limitLongitude(double longitude)
     
    static double
    longitudeToPixelX(double longitude, byte zoomLevel)
    Converts a longitude coordinate (in degrees) to a pixel X coordinate at a certain zoom level.
    static double
    longitudeToPixelX(double longitude, long mapSize)
    Converts a longitude coordinate (in degrees) to a pixel X coordinate at a certain map size.
    static double
    longitudeToPixelXWithScale(double longitude, double scale)
    Converts a longitude coordinate (in degrees) to a pixel X coordinate at a certain scale factor.
    static int
    longitudeToTileX(double longitude, byte zoomLevel)
    Converts a longitude coordinate (in degrees) to the tile X number at a certain zoom level.
    static int
    longitudeToTileXWithScale(double longitude, double scale)
    Converts a longitude coordinate (in degrees) to the tile X number at a certain scale factor.
    static double
    longitudeToX(double longitude)
    Projects a longitude coordinate (in degrees) to the range [0.0,1.0]
    static double
    metersToPixels(float meters, double latitude, long mapSize)
    Converts meters to pixels at latitude for zoom-level.
    static double
    metersToPixelsWithScale(float meters, double latitude, double scale)
    Converts meters to pixels at latitude for zoom-level.
    static double
    pixelXToLongitude(double pixelX, long mapSize)
    Converts a pixel X coordinate at a certain map size to a longitude coordinate.
    static double
    pixelXToLongitudeWithScale(double pixelX, double scale)
    Converts a pixel X coordinate at a certain scale to a longitude coordinate.
    static int
    pixelXToTileX(double pixelX, byte zoomLevel)
    Converts a pixel X coordinate to the tile X number.
    static int
    pixelXToTileXWithScale(double pixelX, double scale)
    Converts a pixel X coordinate to the tile X number.
    static double
    pixelYToLatitude(double pixelY, long mapSize)
    Converts a pixel Y coordinate at a certain map size to a latitude coordinate.
    static double
    pixelYToLatitudeWithScale(double pixelY, double scale)
    Converts a pixel Y coordinate at a certain scale to a latitude coordinate.
    static int
    pixelYToTileY(double pixelY, byte zoomLevel)
    Converts a pixel Y coordinate to the tile Y number.
    static int
    pixelYToTileYWithScale(double pixelY, double scale)
    Converts a pixel Y coordinate to the tile Y number.
    static void
    project(double latitude, double longitude, double[] out, int pos)
     
    static void
    project(GeoPoint p, double[] out, int pos)
     
    static Point
    project(GeoPoint p, Point reuse)
     
    static double
    scaleToZoomLevel(double scale)
    Converts a scale factor to a zoomLevel.
    static long
    tileToPixel(long tileNumber)
     
    static double
    tileXToLongitude(long tileX, byte zoomLevel)
    Converts a tile X number at a certain zoom level to a longitude coordinate.
    static double
    tileXToLongitudeWithScale(long tileX, double scale)
    Converts a tile X number at a certain scale to a longitude coordinate.
    static double
    tileYToLatitude(long tileY, byte zoomLevel)
    Converts a tile Y number at a certain zoom level to a latitude coordinate.
    static double
    tileYToLatitudeWithScale(long tileY, double scale)
    Converts a tile Y number at a certain scale to a latitude coordinate.
    static long
    tileYToTMS(long tileY, byte zoomLevel)
    Converts a tile Y number at a certain zoom level to TMS notation.
    static double
    toLatitude(double y)
    Converts y map position to latitude in degrees.
    static double
    toLongitude(double x)
    Converts x map position to longitude in degrees.
    static double
    wrapLongitude(double longitude)
     
    static double
    zoomLevelToScale(byte zoomLevel)
    Converts a zoom level to a scale factor.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • EARTH_CIRCUMFERENCE

      public static final double EARTH_CIRCUMFERENCE
      The circumference of the earth at the equator in meters.
      See Also:

    • LATITUDE_MAX

      public static final double LATITUDE_MAX
      Maximum possible latitude coordinate of the map.
      See Also:

    • LATITUDE_MIN

      public static final double LATITUDE_MIN
      Minimum possible latitude coordinate of the map.
      See Also:

    • LONGITUDE_MAX

      public static final double LONGITUDE_MAX
      Maximum possible longitude coordinate of the map.
      See Also:

    • LONGITUDE_MIN

      public static final double LONGITUDE_MIN
      Minimum possible longitude coordinate of the map.
      See Also:

  • Method Details

    • fromPixelsWithScale

      public static GeoPoint fromPixelsWithScale(double pixelX, double pixelY, double scale)
      Get GeoPoint from Pixels.

    • fromPixels

      public static GeoPoint fromPixels(double pixelX, double pixelY, long mapSize)
      Get GeoPoint from Pixels.

    • getMapSizeWithScale

      public static long getMapSizeWithScale(double scale)
      Parameters:
      scale - the scale factor for which the size of the world map should be returned.
      Returns:
      the horizontal and vertical size of the map in pixel at the given scale.
      Throws:
      IllegalArgumentException - if the given scale factor is < 1

    • getMapSize

      public static long getMapSize(byte zoomLevel)
      Parameters:
      zoomLevel - the zoom level for which the size of the world map should be returned.
      Returns:
      the horizontal and vertical size of the map in pixel at the given zoom level.
      Throws:
      IllegalArgumentException - if the given zoom level is negative.

    • getPixelWithScale

      public static Point getPixelWithScale(GeoPoint geoPoint, double scale)

    • getPixel

      public static Point getPixel(GeoPoint geoPoint, long mapSize)

    • getPixelAbsolute

      public static Point getPixelAbsolute(GeoPoint geoPoint, long mapSize)
      Calculates the absolute pixel position for a map size and tile size
      Parameters:
      geoPoint - the geographic position.
      mapSize - precomputed size of map.
      Returns:
      the absolute pixel coordinates (for world)

    • getPixelRelative

      public static Point getPixelRelative(GeoPoint geoPoint, long mapSize, double x, double y)
      Calculates the absolute pixel position for a map size and tile size relative to origin
      Parameters:
      geoPoint - the geographic position.
      mapSize - precomputed size of map.
      Returns:
      the relative pixel position to the origin values (e.g. for a tile)

    • getPixelRelative

      public static Point getPixelRelative(GeoPoint geoPoint, long mapSize, Point origin)
      Calculates the absolute pixel position for a map size and tile size relative to origin
      Parameters:
      geoPoint - the geographic position.
      mapSize - precomputed size of map.
      Returns:
      the relative pixel position to the origin values (e.g. for a tile)

    • getPixelRelativeToTile

      public static Point getPixelRelativeToTile(GeoPoint geoPoint, Tile tile)
      Calculates the absolute pixel position for a tile and tile size relative to origin
      Parameters:
      geoPoint - the geographic position.
      tile - tile
      Returns:
      the relative pixel position to the origin values (e.g. for a tile)

    • groundResolutionWithScale

      public static double groundResolutionWithScale(double latitude, double scale)
      Calculates the distance on the ground that is represented by a single pixel on the map.
      Parameters:
      latitude - the latitude coordinate at which the resolution should be calculated.
      scale - the map scale at which the resolution should be calculated.
      Returns:
      the ground resolution at the given latitude and scale.

    • groundResolution

      public static double groundResolution(MapPosition pos)

    • groundResolution

      public static double groundResolution(double latitude, long mapSize)
      Calculates the distance on the ground that is represented by a single pixel on the map.
      Parameters:
      latitude - the latitude coordinate at which the resolution should be calculated.
      mapSize - precomputed size of map.
      Returns:
      the ground resolution at the given latitude and map size.

    • latitudeToPixelYWithScale

      public static double latitudeToPixelYWithScale(double latitude, double scale)
      Converts a latitude coordinate (in degrees) to a pixel Y coordinate at a certain scale.
      Parameters:
      latitude - the latitude coordinate that should be converted.
      scale - the scale factor at which the coordinate should be converted.
      Returns:
      the pixel Y coordinate of the latitude value.

    • latitudeToPixelY

      public static double latitudeToPixelY(double latitude, byte zoomLevel)
      Converts a latitude coordinate (in degrees) to a pixel Y coordinate at a certain zoom level.
      Parameters:
      latitude - the latitude coordinate that should be converted.
      zoomLevel - the zoom level at which the coordinate should be converted.
      Returns:
      the pixel Y coordinate of the latitude value.

    • latitudeToPixelY

      public static double latitudeToPixelY(double latitude, long mapSize)
      Converts a latitude coordinate (in degrees) to a pixel Y coordinate at a certain map size.
      Parameters:
      latitude - the latitude coordinate that should be converted.
      mapSize - precomputed size of map.
      Returns:
      the pixel Y coordinate of the latitude value.

    • latitudeToTileYWithScale

      public static int latitudeToTileYWithScale(double latitude, double scale)
      Converts a latitude coordinate (in degrees) to a tile Y number at a certain scale.
      Parameters:
      latitude - the latitude coordinate that should be converted.
      scale - the scale factor at which the coordinate should be converted.
      Returns:
      the tile Y number of the latitude value.

    • latitudeToTileY

      public static int latitudeToTileY(double latitude, byte zoomLevel)
      Converts a latitude coordinate (in degrees) to a tile Y number at a certain zoom level.
      Parameters:
      latitude - the latitude coordinate that should be converted.
      zoomLevel - the zoom level at which the coordinate should be converted.
      Returns:
      the tile Y number of the latitude value.

    • latitudeToY

      public static double latitudeToY(double latitude)
      Projects a latitude coordinate (in degrees) to the range [0.0,1.0]
      Parameters:
      latitude - the latitude coordinate that should be converted.
      Returns:
      the position.

    • limitLatitude

      public static double limitLatitude(double latitude)
      Parameters:
      latitude - the latitude value which should be checked.
      Returns:
      the given latitude value, limited to the possible latitude range.

    • limitLongitude

      public static double limitLongitude(double longitude)
      Parameters:
      longitude - the longitude value which should be checked.
      Returns:
      the given longitude value, limited to the possible longitude range.

    • longitudeToPixelXWithScale

      public static double longitudeToPixelXWithScale(double longitude, double scale)
      Converts a longitude coordinate (in degrees) to a pixel X coordinate at a certain scale factor.
      Parameters:
      longitude - the longitude coordinate that should be converted.
      scale - the scale factor at which the coordinate should be converted.
      Returns:
      the pixel X coordinate of the longitude value.

    • longitudeToPixelX

      public static double longitudeToPixelX(double longitude, byte zoomLevel)
      Converts a longitude coordinate (in degrees) to a pixel X coordinate at a certain zoom level.
      Parameters:
      longitude - the longitude coordinate that should be converted.
      zoomLevel - the zoom level at which the coordinate should be converted.
      Returns:
      the pixel X coordinate of the longitude value.

    • longitudeToPixelX

      public static double longitudeToPixelX(double longitude, long mapSize)
      Converts a longitude coordinate (in degrees) to a pixel X coordinate at a certain map size.
      Parameters:
      longitude - the longitude coordinate that should be converted.
      mapSize - precomputed size of map.
      Returns:
      the pixel X coordinate of the longitude value.

    • longitudeToTileXWithScale

      public static int longitudeToTileXWithScale(double longitude, double scale)
      Converts a longitude coordinate (in degrees) to the tile X number at a certain scale factor.
      Parameters:
      longitude - the longitude coordinate that should be converted.
      scale - the scale factor at which the coordinate should be converted.
      Returns:
      the tile X number of the longitude value.

    • longitudeToTileX

      public static int longitudeToTileX(double longitude, byte zoomLevel)
      Converts a longitude coordinate (in degrees) to the tile X number at a certain zoom level.
      Parameters:
      longitude - the longitude coordinate that should be converted.
      zoomLevel - the zoom level at which the coordinate should be converted.
      Returns:
      the tile X number of the longitude value.

    • longitudeToX

      public static double longitudeToX(double longitude)
      Projects a longitude coordinate (in degrees) to the range [0.0,1.0]
      Parameters:
      longitude - the longitude coordinate that should be converted.
      Returns:
      the position.

    • metersToPixelsWithScale

      public static double metersToPixelsWithScale(float meters, double latitude, double scale)
      Converts meters to pixels at latitude for zoom-level.
      Parameters:
      meters - the meters to convert
      latitude - the latitude for the conversion.
      scale - the scale factor for the conversion.
      Returns:
      pixels that represent the meters at the given zoom-level and latitude.

    • metersToPixels

      public static double metersToPixels(float meters, double latitude, long mapSize)
      Converts meters to pixels at latitude for zoom-level.
      Parameters:
      meters - the meters to convert
      latitude - the latitude for the conversion.
      mapSize - precomputed size of map.
      Returns:
      pixels that represent the meters at the given zoom-level and latitude.

    • pixelXToLongitudeWithScale

      public static double pixelXToLongitudeWithScale(double pixelX, double scale)
      Converts a pixel X coordinate at a certain scale to a longitude coordinate.
      Parameters:
      pixelX - the pixel X coordinate that should be converted.
      scale - the scale factor at which the coordinate should be converted.
      Returns:
      the longitude value of the pixel X coordinate.
      Throws:
      IllegalArgumentException - if the given pixelX coordinate is invalid.

    • pixelXToLongitude

      public static double pixelXToLongitude(double pixelX, long mapSize)
      Converts a pixel X coordinate at a certain map size to a longitude coordinate.
      Parameters:
      pixelX - the pixel X coordinate that should be converted.
      mapSize - precomputed size of map.
      Returns:
      the longitude value of the pixel X coordinate.
      Throws:
      IllegalArgumentException - if the given pixelX coordinate is invalid.

    • pixelXToTileXWithScale

      public static int pixelXToTileXWithScale(double pixelX, double scale)
      Converts a pixel X coordinate to the tile X number.
      Parameters:
      pixelX - the pixel X coordinate that should be converted.
      scale - the scale factor at which the coordinate should be converted.
      Returns:
      the tile X number.

    • pixelXToTileX

      public static int pixelXToTileX(double pixelX, byte zoomLevel)
      Converts a pixel X coordinate to the tile X number.
      Parameters:
      pixelX - the pixel X coordinate that should be converted.
      zoomLevel - the zoom level at which the coordinate should be converted.
      Returns:
      the tile X number.

    • pixelYToLatitudeWithScale

      public static double pixelYToLatitudeWithScale(double pixelY, double scale)
      Converts a pixel Y coordinate at a certain scale to a latitude coordinate.
      Parameters:
      pixelY - the pixel Y coordinate that should be converted.
      scale - the scale factor at which the coordinate should be converted.
      Returns:
      the latitude value of the pixel Y coordinate.
      Throws:
      IllegalArgumentException - if the given pixelY coordinate is invalid.

    • pixelYToLatitude

      public static double pixelYToLatitude(double pixelY, long mapSize)
      Converts a pixel Y coordinate at a certain map size to a latitude coordinate.
      Parameters:
      pixelY - the pixel Y coordinate that should be converted.
      mapSize - precomputed size of map.
      Returns:
      the latitude value of the pixel Y coordinate.
      Throws:
      IllegalArgumentException - if the given pixelY coordinate is invalid.

    • pixelYToTileYWithScale

      public static int pixelYToTileYWithScale(double pixelY, double scale)
      Converts a pixel Y coordinate to the tile Y number.
      Parameters:
      pixelY - the pixel Y coordinate that should be converted.
      scale - the scale factor at which the coordinate should be converted.
      Returns:
      the tile Y number.

    • pixelYToTileY

      public static int pixelYToTileY(double pixelY, byte zoomLevel)
      Converts a pixel Y coordinate to the tile Y number.
      Parameters:
      pixelY - the pixel Y coordinate that should be converted.
      zoomLevel - the zoom level at which the coordinate should be converted.
      Returns:
      the tile Y number.

    • project

      public static Point project(GeoPoint p, Point reuse)

    • project

      public static void project(GeoPoint p, double[] out, int pos)

    • project

      public static void project(double latitude, double longitude, double[] out, int pos)

    • scaleToZoomLevel

      public static double scaleToZoomLevel(double scale)
      Converts a scale factor to a zoomLevel. Note that this will return a double, as the scale factors cover the intermediate zoom levels as well.
      Parameters:
      scale - the scale factor to convert to a zoom level.
      Returns:
      the zoom level.

    • tileToPixel

      public static long tileToPixel(long tileNumber)
      Parameters:
      tileNumber - the tile number that should be converted.
      Returns:
      the pixel coordinate for the given tile number.

    • tileXToLongitudeWithScale

      public static double tileXToLongitudeWithScale(long tileX, double scale)
      Converts a tile X number at a certain scale to a longitude coordinate.
      Parameters:
      tileX - the tile X number that should be converted.
      scale - the scale factor at which the number should be converted.
      Returns:
      the longitude value of the tile X number.

    • tileXToLongitude

      public static double tileXToLongitude(long tileX, byte zoomLevel)
      Converts a tile X number at a certain zoom level to a longitude coordinate.
      Parameters:
      tileX - the tile X number that should be converted.
      zoomLevel - the zoom level at which the number should be converted.
      Returns:
      the longitude value of the tile X number.

    • tileYToLatitudeWithScale

      public static double tileYToLatitudeWithScale(long tileY, double scale)
      Converts a tile Y number at a certain scale to a latitude coordinate.
      Parameters:
      tileY - the tile Y number that should be converted.
      scale - the scale factor at which the number should be converted.
      Returns:
      the latitude value of the tile Y number.

    • tileYToLatitude

      public static double tileYToLatitude(long tileY, byte zoomLevel)
      Converts a tile Y number at a certain zoom level to a latitude coordinate.
      Parameters:
      tileY - the tile Y number that should be converted.
      zoomLevel - the zoom level at which the number should be converted.
      Returns:
      the latitude value of the tile Y number.

    • tileYToTMS

      public static long tileYToTMS(long tileY, byte zoomLevel)
      Converts a tile Y number at a certain zoom level to TMS notation.
      Parameters:
      tileY - the tile Y number that should be converted.
      zoomLevel - the zoom level at which the number should be converted.
      Returns:
      the TMS value of the tile Y number.

    • toLatitude

      public static double toLatitude(double y)
      Converts y map position to latitude in degrees.
      Parameters:
      y - the map position y.
      Returns:
      the latitude in degrees.

    • toLongitude

      public static double toLongitude(double x)
      Converts x map position to longitude in degrees.
      Parameters:
      x - the map position x.
      Returns:
      the longitude in degrees.

    • wrapLongitude

      public static double wrapLongitude(double longitude)

    • zoomLevelToScale

      public static double zoomLevelToScale(byte zoomLevel)
      Converts a zoom level to a scale factor.
      Parameters:
      zoomLevel - the zoom level to convert.
      Returns:
      the corresponding scale factor.