| 1 | [](http://travis-ci.com/mapbox/sphericalmercator)
|
| 2 |
|
| 3 | `sphericalmercator` provides projection math for converting between
|
| 4 | mercator meters, screen pixels (of 256x256 or configurable-size tiles), and
|
| 5 | latitude/longitude.
|
| 6 |
|
| 7 | Compatible with nodejs packages and in-browser.
|
| 8 |
|
| 9 | ## Installation
|
| 10 |
|
| 11 | `npm install @mapbox/sphericalmercator`
|
| 12 |
|
| 13 | ## API
|
| 14 |
|
| 15 | Some datatypes are assumed to be arrays: `ll` is `[lon, lat]`, `xy` and `px` are
|
| 16 | `[x, y]`.
|
| 17 |
|
| 18 | ```javascript
|
| 19 | // By default, precomputes up to z30
|
| 20 | var merc = new SphericalMercator({
|
| 21 | size: 256,
|
| 22 | antimeridian: true
|
| 23 | });
|
| 24 | ```
|
| 25 |
|
| 26 | ### `px(ll, zoom)`
|
| 27 |
|
| 28 | Convert lon, lat to screen pixel x, y from 0, 0 origin, at a certain zoom level.
|
| 29 | The inverse of `ll`
|
| 30 |
|
| 31 | If `antimeridian: true` is passed on initialization of the `SphericalMercator` object, this method will support converting longitude values up to 360°.
|
| 32 |
|
| 33 | ### `ll(px, zoom)`
|
| 34 |
|
| 35 | Convert screen pixel value to lon, lat, at a certain zoom level. The inverse
|
| 36 | of `px`
|
| 37 |
|
| 38 | ### `bbox(x, y, zoom, tms_style, srs)`
|
| 39 |
|
| 40 | Convert tile xyz value to bbox of the form `[w, s, e, n]`
|
| 41 |
|
| 42 | * `x` {Number} x (longitude) number.
|
| 43 | * `y` {Number} y (latitude) number.
|
| 44 | * `zoom` {Number} zoom.
|
| 45 | * `tms_style` {Boolean} whether to compute using tms-style. (optional, default false)
|
| 46 | * `srs` {String} projection for resulting bbox (WGS84|900913). (optional, default WGS84)
|
| 47 |
|
| 48 | Returns bbox array of values in form `[w, s, e, n]`.
|
| 49 |
|
| 50 | ### `xyz(bbox, zoom, tms_style, srs)`
|
| 51 |
|
| 52 | Convert bbox to xyz bounds
|
| 53 |
|
| 54 | * `bbox` {Number} bbox in the form `[w, s, e, n]`.
|
| 55 | * `zoom` {Number} zoom.
|
| 56 | * `tms_style` {Boolean} whether to compute using tms-style. (optional, default false)
|
| 57 | * `srs` {String} projection of input bbox (WGS84|900913). (optional, default WGS84)
|
| 58 |
|
| 59 | Returns {Object} XYZ bounds containing minX, maxX, minY, maxY properties.
|
| 60 |
|
| 61 | ### `convert(bbox, to)`
|
| 62 |
|
| 63 | Convert bbox from 900913 to WGS84 or vice versa
|
| 64 |
|
| 65 | * `bbox` {Number} bbox in the form `[w, s, e, n]`.
|
| 66 | * `to` {String} projection of resulting bbox (WGS84|900913). (optional, default WGS84)
|
| 67 |
|
| 68 | Returns bbox array of values in form `[w, s, e, n]`.
|
| 69 |
|
| 70 | ### `forward(ll)`
|
| 71 |
|
| 72 | Convert lon, lat values to mercator x, y
|
| 73 |
|
| 74 | ### `inverse(xy)`
|
| 75 |
|
| 76 | Convert mercator x, y values to lon, lat
|
| 77 |
|
| 78 | ## See Also
|
| 79 |
|
| 80 | * [mercantile](https://github.com/sgillies/mercantile) provides similar utilities for projection and tile math in Python
|