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

Utility for converting to and from latitude and longitude coordinates, given a map viewport projection. Initially built for use with react-map-gl but useful for most web mapping libraries that support floating point zoom levels.

Example usage

// Create a new viewport.
var ViewportMercator = require('viewport-mercator-project');
// NOTE: The `viewport` object returned from `ViewportMercator` are immutable by design.

var viewport = ViewportMercator({
  longitude: 0,
  latitude: 0,
  zoom: 0,
  width: 600,
  height: 500
});

// A longitude, latitude pair as an array.
var lnglat = [0, 0];
var pixels = viewport.project(lnglat); // returns [300, 400]

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

Installation

npm install viewport-mercator-project --save

To run the tests

npm run test

Notes on Projection

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

Change log

2.0.0

center property was broken up into longitude, latitude properties.

dimensions property was broken up into width, and height properties.

Here's what creating a viewport used to look like, prior to 2.0.

var viewport = ViewportMercator({
  center: [0, 0],
  zoom: 0,
  dimensions: [600, 800]
});

The change was made to support the typical viewport object from the new react-map-gl API changes.