# @mapbox/geo-viewport

> convert between viewports and extents

Latest version **0.5.0** (published 2021-09-21) · BSD-2-Clause license · 0 weekly downloads

## Install

```sh
npm install @mapbox/geo-viewport
pnpm add @mapbox/geo-viewport
yarn add @mapbox/geo-viewport
bun add @mapbox/geo-viewport
```

## Health

**Score 33/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 0.5.0 |
| Published | 2021-09-21 |
| First published | 2017-04-20 |
| Weekly downloads | 0 |
| License | BSD-2-Clause |
| TypeScript types | separate (@types/mapbox__geo-viewport) |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 22.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 197 |
| Author | Tom MacWright |
| Maintainers | mapbox-npm-01, mapbox-npm-02, mapbox-npm-07, mapbox-npm-03, mapbox-npm-04, mapbox-npm-09, mapbox-npm-05, mapbox-npm-06, mapbox-npm-08, mapbox-npm-advanced-actions, mapbox-npm-ci, mapbox-npm, mapbox-admin, mapbox-machine-user |
| Keywords | geographic, viewport, zoom, scale |

## Links

- npm: https://www.npmjs.com/package/@mapbox/geo-viewport
- Repository: https://github.com/mapbox/geo-viewport
- Issues: https://github.com/mapbox/geo-viewport/issues
- npm.io page: https://npm.io/package/@mapbox/geo-viewport

## Dependencies (1)

- [@mapbox/sphericalmercator](https://npm.io/package/@mapbox/sphericalmercator.md) ^1.2.0

## Alternatives

- [d3-force-3d](https://npm.io/package/d3-force-3d.md) — 1.0M weekly downloads
- [ng2-charts](https://npm.io/package/ng2-charts.md) — 486.8K weekly downloads
- [@arcgis/core](https://npm.io/package/@arcgis/core.md) — 257.8K weekly downloads
- [react-sparklines](https://npm.io/package/react-sparklines.md) — 249.3K weekly downloads
- [react-native-gifted-charts](https://npm.io/package/react-native-gifted-charts.md) — 182.3K weekly downloads

## Recent versions

- 0.5.0 (latest) — 2021-09-21
- 0.5.0-dev (dev) — 2021-09-20
- 0.4.1 — 2020-09-24
- 0.4.0 — 2018-07-26
- 0.3.0 — 2018-05-29
- 0.2.2 — 2017-04-20

## README

[![Build Status](https://travis-ci.com/mapbox/geo-viewport.svg)](https://travis-ci.com/mapbox/geo-viewport) [![codecov](https://codecov.io/gh/mapbox/geo-viewport/branch/master/graph/badge.svg)](https://codecov.io/gh/mapbox/geo-viewport)

# geo-viewport

Turns bounding boxes / extents into centerpoint & zoom
combos for static maps.

Works in node.js and browsers, via [browserify](http://browserify.org/)
or a script tag.

## Install

    npm install --save @mapbox/geo-viewport

Or use a plugin:

```html
<script src='//api.tiles.mapbox.com/mapbox.js/plugins/geo-viewport/v0.2.1/geo-viewport.js'></script>
```

The script-tag include exports an object called `geoViewport`,
with methods `bounds` and `viewport` documented below.

## Example

[Live example with Mapbox Static Map API](https://www.mapbox.com/mapbox.js/example/v1.0.0/static-map-from-bounds-with-geo-viewport/)

### With Node

```js
var geoViewport = require('@mapbox/geo-viewport');

geoViewport.viewport([
    5.668343999999995,
    45.111511000000014,
    5.852471999999996,
    45.26800200000002
], [640, 480])

// yields
// {
//     center: [
//         5.7604079999999955,
//         45.189756500000016
//     ],
//     zoom: 11
// }
```

In a browser:

```html
<script src='//api.tiles.mapbox.com/mapbox.js/plugins/geo-viewport/v0.1.1/geo-viewport.js'></script>
<script>
var bounds = geoViewport.viewport([
    5.668343999999995,
    45.111511000000014,
    5.852471999999996,
    45.26800200000002
], [640, 480]);

var center = geoViewport.bounds(
  [-75.03,
  35.25],
  14,
  [600, 400]);

console.log(bounds);
console.log(center);
</script>
```

## api

### `viewport(bounds, dimensions, minzoom, maxzoom, tileSize, allowFloat, allowAntiMeridian)`

Given a `WSEN` array of bounds and a `[x, y]` array of pixel dimensions, return a `{ center: [lon, lat], zoom: zoom }` viewport. Use `allowFloat` to retain float values in the output.

Example:

```js
// first argument is the bounds, and the image is 640x480
geoViewport.viewport([
    5.6683, 45.111, 5.8524, 45.268
], [640, 480])
```

### `bounds(viewport, zoom, dimensions, tileSize)`

Given a centerpoint as `[lon, lat]` or `{ lon, lat }`, a zoom,
and dimensions as `[x, y]`, return a bounding box.

Example:

```js
geoViewport.bounds([-75.03, 35.25], 14, [600, 400])
```

## tile sizes

Be aware that these calculations are sensitive to tile size. The default size assumed by this library is 256x256px; however, Mapbox Vector Tiles are 512x512px.

For example, to calculating a bounding box for a classic raster-based 256x256 tile:

```js
geoViewport.bounds([-75.03, 35.25], 14, [600, 400], 256)

// since 256 is default, you can omit the tileSize param
geoViewport.bounds([-75.03, 35.25], 14, [600, 400])
```

To calculate a bounding box for a Mapbox vector tile source, such as an image from the [Mapbox Static Image API](https://www.mapbox.com/api-documentation/#static):

```js
geoViewport.bounds([-75.03, 35.25], 14, [600, 400], 512)
```

There's a [handy blog post discussing the issue here](https://www.mapbox.com/blog/512px-map-tile).

---
_Source: https://npm.io/package/@mapbox/geo-viewport · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._