🗺️ Spherical Mercator math in Ruby
MIT License
Spherical Mercator gem is a port of Mapbox sphericalmercator JS lib that provides projection math for converting between mercator meters, screen pixels (of 256x256 or configurable-size tiles), and latitude/longitude.
Simple:
gem install spherical_mercator
For Gemfile:
gem 'spherical_mercator'
NOTE: API description copied from the original repo.
Some datatypes are assumed to be arrays: ll
is [lon, lat]
, xy
and px
are
[x, y]
.
# By default, precomputes up to z30
mercator = SphericalMercator.new(size: 256)
# Whether to round pixel values at integer zoom levels. Defaults to true.
mercator = SphericalMercator.new(round: false)
px(lon_lat, zoom)
Convert lon, lat to screen pixel x, y from 0, 0 origin, at a certain zoom level.
The inverse of ll
Screen pixel values are rounded, unless the zoom level is a floating point value. To disable rounding on integer zoom levels, specify round: false
when creating the SphericalMercator.
ll(px, zoom)
Convert screen pixel value to lon, lat, at a certain zoom level. The inverse
of px
bbox(x, y, zoom, tms_style, srs)
Convert tile xyz value to bbox of the form [west, south, east, north]
x
{Number} x (longitude) number.y
{Number} y (latitude) number.zoom
{Number} zoom.tms_style
{Boolean} whether to compute using tms-style. (optional, default false
)srs
{String} projection for resulting bbox ('WGS84'|'900913'). (optional, default 'WGS84')Returns bbox array of values in form [west, south, east, north]
.
xyz(bbox, zoom, tms_style, srs)
Convert bbox to xyz bounds
bbox
{Number} bbox in the form [west, south, east, north]
.zoom
{Number} zoom.tms_style
{Boolean} whether to compute using tms-style. (optional, default false
)srs
{String} projection of input bbox ('WGS84'|'900913'). (optional, default 'WGS84')Returns Hash
object ({...}
) for XYZ bounds containing :minX
, :maxX
, :minY
, :maxY
properties.
convert(bbox, to)
Convert bbox from 900913 to WGS84 or vice versa
bbox
{Number} bbox in the form [west, south, east, north]
.to
{String} projection of resulting bbox ('WGS84'|'900913'). (optional, default 'WGS84')Returns bbox array of values in form [west, south, east, north]
.
forward(lon_lat)
Convert lon, lat values (must be an array like [lon, lat]
) to mercator x, y
inverse(xy)
Convert mercator x, y values (xy
must be an array like [x, y]
) to lon, lat
You are very welcome to help improve spherical_mercator if you have suggestions for features that other people can use.
To contribute:
git checkout -b my-new-feature
).rake
to make sure all tests pass.git commit -am 'Add new feature'
).git push origin my-new-feature
).Thanks.
Spherical Mercator gem is released under the MIT License.
Copyright (c) 2017 Nikita Bulai ([email protected]) and original lib authors.