viewport-mercator-project

What is viewport-mercator-project?

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.

What are viewport-mercator-project's main functionalities?

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]]

Other packages similar to viewport-mercator-project

mapbox-gl

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

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

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.

README

viewport-mercator-project | Docs

Projection and camera utilities supporting the Web Mercator Projection. At its core this is a utility for converting to and from map coordinates (i.e. latitude, longitude) to screen coordinates and back.

Installation

npm install viewport-mercator-project --save

Overview

The WebMercatorViewport class offers the equivalent of a 3D matrix "camera" class of the type you would find in any 3D/WebGL/OpenGL library.

import WebMercatorViewport from 'viewport-mercator-project';

// A viewport looking at San Francisco city area
const viewport = WebMercatorViewport({
  width: 800,
  height: 600,
  longitude: -122.45,
  latitude: 37.78,
  zoom: 12,
  pitch: 60,
  bearing: 30
});

viewport.project([-122.45, 37.78]);
// returns pixel coordinates [400, 300]
viewport.unproject([400, 300]);
// returns map coordinates [-122.45, 37.78]

Who is this for?

Specifically built for use with deck.gl and react-map-gl, but could be useful for any web mapping application that wants to support perspective enabled Web Mercator Projections with floating point zoom levels.