viewport-mercator-project
Advanced tools
Convert to and from lat/lng and pixels in web mercator at arbitrary floating point zoom levels.
The viewport-mercator-project npm package is a utility library for performing viewport-related calculations in web mapping applications. It is particularly useful for converting between geographic coordinates and screen coordinates, handling zoom levels, and managing map projections.
Project geographic coordinates to screen coordinates
This feature allows you to project geographic coordinates (longitude, latitude) to screen coordinates (x, y) based on the current viewport settings.
const { WebMercatorViewport } = require('viewport-mercator-project');
const viewport = new WebMercatorViewport({
width: 800,
height: 600,
longitude: -122.45,
latitude: 37.78,
zoom: 12
});
const screenCoords = viewport.project([-122.45, 37.78]);
console.log(screenCoords); // [400, 300]Unproject screen coordinates to geographic coordinates
This feature allows you to convert screen coordinates (x, y) back to geographic coordinates (longitude, latitude) based on the current viewport settings.
const { WebMercatorViewport } = require('viewport-mercator-project');
const viewport = new WebMercatorViewport({
width: 800,
height: 600,
longitude: -122.45,
latitude: 37.78,
zoom: 12
});
const geoCoords = viewport.unproject([400, 300]);
console.log(geoCoords); // [-122.45, 37.78]Get bounding box of the viewport
This feature allows you to get the geographic bounding box of the current viewport, which can be useful for determining the area currently visible on the map.
const { WebMercatorViewport } = require('viewport-mercator-project');
const viewport = new WebMercatorViewport({
width: 800,
height: 600,
longitude: -122.45,
latitude: 37.78,
zoom: 12
});
const bounds = viewport.getBounds();
console.log(bounds); // [[-122.519, 37.704], [-122.381, 37.856]]Mapbox GL JS is a powerful library for interactive, customizable vector maps on the web. It provides similar functionalities for projecting and unprojecting coordinates, but also includes a full-featured map rendering engine and extensive styling options.
Leaflet is a popular open-source JavaScript library for mobile-friendly interactive maps. It offers similar coordinate transformation functionalities, but is more focused on ease of use and simplicity, making it a good choice for basic mapping applications.
Proj4 is a library for performing cartographic transformations, including coordinate projections. It is more specialized in handling various map projections and transformations, making it a good complement to viewport-mercator-project for advanced geospatial applications.
npm install viewport-mercator-project --save
Provides two options:
FlatViewport for flat Web Mercator projection and unprojectionPerspectiveViewport class.Specifically built for use with deck.gl and react-map-gl, but could be useful for any web mapping application that wants to support Web Mercator Projection with floating point zoom levels.
const ViewportMercator = require('viewport-mercator-project');
// NOTE: The `viewport` object returned from `ViewportMercator` is immutable.
const viewport = ViewportMercator({
longitude: 0,
latitude: 0,
zoom: 0,
width: 600,
height: 500
});
// A longitude, latitude pair as an array.
const lnglat = [0, 0];
const pixels = viewport.project(lnglat); // returns [300, 250]
// A width, height pair as an array.
viewport.unproject(pixels); // returns [0, 0]
// Test if a lnglat is within the viewport
viewport.contains(lnglat); // true
The default coordinate system of the viewport is defined as a cartesian
plane with the origin in the top left, where the positive x-axis goes
right, and the positive y-axis goes down. That is, the top left corner
is [0, 0] and the bottom right corner is [width, height].
Coordinates are specified in an lng-lat format [lng, lat, z] format which
most closely corresponds to [x, y, z] coords, with lng and lat specified
in degrees and z specified in meters above sea level.
Unless otherwise noted, per cartographic tradition, all angles including latitude and longitude are specified in degrees, not radians
A PerspectiveViewport can be configured to work with positions specified in different units.
LNGLAT) -
positions are interpreted as Web Mercator coordinates:
[longitude, latitude, altitude].METERS) -
positions are given in meter offsets from a reference point
that is specified separately.Longitude and latitude are specified in degrees from Greenwich meridian / equator respectively, and altitude is specified in meters above sea level.
Note that that distance scales are latitude dependent under web mercator projection (see), so scaling will depend on the viewport center and any linear scale factor should only be expected to be locally correct.
TBA
In this mode, which does not offer any synchronization with maps, the application specifies its world size (the number of pixels that the world occupies).
| Parameter | Type | Default | Description |
|---|---|---|---|
| mercator | Boolean | true | Whether to use mercator projection |
| opt.width | Number | 1 | Width of "viewport" or window |
| opt.height | Number | 1 | Height of "viewport" or window |
| opt.center | Array | [0, 0] | Center of viewport [longitude, latitude] or [x, y] |
| opt.scale | Number | 1 | Either use scale or zoom |
| opt.pitch | Number | 0 | Camera angle in degrees (0 is straight down) |
| opt.bearing | Number | 0 | Map rotation in degrees (0 means north is up) |
| opt.altitude | Number | 1.5 | Altitude of camera in screen units |
Web mercator projection short-hand parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| opt.latitude | Number | 37 | Center of viewport on map (alternative to opt.center) |
| opt.longitude | Number | -122 | Center of viewport on map (alternative to opt.center) |
| opt.zoom | Number | 11 | Scale = Math.pow(2,zoom) on map (alternative to opt.scale) |
Remarks:
center or [latitude, longitude] can be specified.[latitude, longitude] can only be specified when mercator is truewidth and height are forced to 1 if supplied as 0, to avoid
division by zero. This is intended to reduce the burden of apps to
to check values before instantiating a Viewport.PerspectiveViewport.projectProjects latitude, longitude (and altitude) to pixel coordinates in window using viewport projection parameters.
Parameters:
coordinates {Array} - [lng, lat, altitude] Passing an altitude is optional.opts {Object}
topLeft {Boolean} - Whether projected coords are top left.Returns:
[x, y] or [x, y, z] if an altitude was given.Note: By default, returns top-left coordinates for canvas/SVG type render
PerspectiveViewport.unprojectUnproject pixel coordinates on screen onto [lng, lat, altitude] on map.
Parameters:
pixels {Array} - [x, y, z] Passing a z is optional.Returns:
[lng, lat] or [lng, lat, altitude] if a z was given.PerspectiveViewport.projectFlatProject [lng, lat] on sphere onto "screen pixel" coordinates [x, y] without
considering any perspective (effectively ignoring pitch, bearing and altitude).
Parameters:
coordinates {Array} - [lng, lat] or [xmap, ymap] coordinates.Returns:
[x, y], representing map or world coordinates.PerspectiveViewport.unprojectFlatUnprojects a screen point [x, y] on the map or world [lng, lat] on sphere.
Parameters:
pixels {Array} - [x, y]Returns:
[lng, lat]FAQs
Utilities for perspective-enabled Web Mercator projections
The npm package viewport-mercator-project receives a total of 162,918 weekly downloads. As such, viewport-mercator-project popularity was classified as popular.
We found that viewport-mercator-project demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 8 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.