Merge pull request #927 from Turfjs/projection

New module `@turf/projection`

packages/turf-clone/index.js

@@ -60,6 +60,7 @@ function cloneFeature(geojson) {
 /**
  * Clone Properties
  *
+ * @private
  * @param {Object} properties GeoJSON Properties
  * @returns {Object} cloned Properties
  */

packages/turf-projection/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 TurfJS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

packages/turf-projection/README.md

@@ -0,0 +1,68 @@
+# @turf/projection
+
+# toMercator
+
+Converts a WGS84 GeoJSON object into Mercator (EPSG:900913) projection
+
+**Parameters**
+
+-   `geojson` **[GeoJSON](http://geojson.org/geojson-spec.html#geojson-objects)** WGS84 GeoJSON object
+-   `mutate` **\[[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)]** allows GeoJSON input to be mutated (significant performance increase if true) (optional, default `false`)
+
+**Examples**
+
+```javascript
+var pt = turf.point([-71,41]);
+var converted = turf.toMercator(pt);
+
+//addToMap
+var addToMap = [pt, converted];
+```
+
+Returns **[GeoJSON](http://geojson.org/geojson-spec.html#geojson-objects)** true/false
+
+# toWgs84
+
+Converts a Mercator (EPSG:900913) GeoJSON object into WGS84 projection
+
+**Parameters**
+
+-   `geojson` **[GeoJSON](http://geojson.org/geojson-spec.html#geojson-objects)** Mercator GeoJSON object
+-   `mutate` **\[[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)]** allows GeoJSON input to be mutated (significant performance increase if true) (optional, default `false`)
+
+**Examples**
+
+```javascript
+var pt = turf.point([-7903683.846322424, 5012341.663847514]);
+var converted = turf.toWgs84(pt);
+
+//addToMap
+var addToMap = [pt, converted];
+```
+
+Returns **[GeoJSON](http://geojson.org/geojson-spec.html#geojson-objects)** true/false
+
+<!-- This file is automatically generated. Please don't edit it directly:
+if you find an error, edit the source file (likely index.js), and re-run
+./scripts/generate-readmes in the turf project. -->
+
+---
+
+This module is part of the [Turfjs project](http://turfjs.org/), an open source
+module collection dedicated to geographic algorithms. It is maintained in the
+[Turfjs/turf](https://github.com/Turfjs/turf) repository, where you can create
+PRs and issues.
+
+### Installation
+
+Install this module individually:
+
+```sh
+$ npm install @turf/projection
+```
+
+Or install the Turf module that includes it as a function:
+
+```sh
+$ npm install @turf/turf
+```

packages/turf-projection/bench.js

@@ -0,0 +1,78 @@
+const path = require('path');
+const glob = require('glob');
+const load = require('load-json-file');
+const Benchmark = require('benchmark');
+const {toMercator, toWgs84} = require('./');
+
+const suite = new Benchmark.Suite('turf-projection');
+
+/**
+ * Benchmark Results toMercator
+ *
+ * featureCollection: 3.501ms
+ * fiji: 0.118ms
+ * geometry: 0.081ms
+ * line: 0.077ms
+ * multiLine: 0.083ms
+ * multiPolygon: 0.123ms
+ * passed-180th-meridian: 0.044ms
+ * passed-180th-meridian2: 0.151ms
+ * point: 0.065ms
+ * polygon: 0.060ms
+ *
+ *
+ *
+ *
+ * 180th-meridian x 115,084 ops/sec ±2.82% (78 runs sampled)
+ * featureCollection x 133,945 ops/sec ±7.66% (73 runs sampled)
+ * line x 349,467 ops/sec ±3.93% (74 runs sampled)
+ * multiLine x 139,763 ops/sec ±5.19% (71 runs sampled)
+ * multiPolygon x 118,105 ops/sec ±4.80% (75 runs sampled)
+ * point x 1,539,797 ops/sec ±3.72% (77 runs sampled)
+ * polygon x 203,059 ops/sec ±16.43% (58 runs sampled)
+ */
+glob.sync(path.join(__dirname, 'test', 'mercator', '*.geojson')).forEach(filepath => {
+    const {name} = path.parse(filepath);
+    const geojson = load.sync(filepath);
+    console.time(name);
+    toMercator(geojson);
+    console.timeEnd(name);
+    suite.add(name, () => toMercator(geojson));
+});
+
+/**
+ * Benchmark Results toWgs84
+ *
+ * featureCollection: 2.290ms
+ * fiji: 0.062ms
+ * geometry: 0.109ms
+ * multiLine: 0.060ms
+ * multiPolygon: 0.075ms
+ * passed-180th-meridian: 0.084ms
+ * passed-180th-meridian2: 0.099ms
+ * point: 0.037ms
+ * polygon: 0.054ms
+ *
+ * featureCollection x 153,988 ops/sec ±3.13% (77 runs sampled)
+ * fiji x 266,735 ops/sec ±1.90% (79 runs sampled)
+ * geometry x 406,995 ops/sec ±1.91% (79 runs sampled)
+ * multiLine x 175,761 ops/sec ±2.32% (77 runs sampled)
+ * multiPolygon x 135,507 ops/sec ±1.95% (79 runs sampled)
+ * passed-180th-meridian x 131,944 ops/sec ±2.04% (79 runs sampled)
+ * passed-180th-meridian2 x 106,320 ops/sec ±1.91% (80 runs sampled)
+ * point x 1,784,702 ops/sec ±2.29% (76 runs sampled)
+ * polygon x 307,268 ops/sec ±1.95% (79 runs sampled)
+ */
+glob.sync(path.join(__dirname, 'test', 'wgs84', '*.geojson')).forEach(filepath => {
+    const {name} = path.parse(filepath);
+    const geojson = load.sync(filepath);
+    console.time(name);
+    toWgs84(geojson);
+    console.timeEnd(name);
+    suite.add(name, () => toWgs84(geojson));
+});
+
+suite
+    .on('cycle', e => console.log(String(e.target)))
+    .on('complete', () => {})
+    .run();

packages/turf-projection/index.d.ts

@@ -0,0 +1,13 @@
+/// <reference types="geojson" />
+
+type Types = GeoJSON.FeatureCollection<any> | GeoJSON.Feature<any> | GeoJSON.GeometryObject | GeoJSON.GeometryCollection;
+
+/**
+ * http://turfjs.org/docs/#toMercator
+ */
+export function toMercator<T extends Types>(geojson: T, mutate?: boolean): T;
+
+/**
+ * http://turfjs.org/docs/#toWgs84
+ */
+export function toWgs84<T extends Types>(geojson: T, mutate?: boolean): T;

packages/turf-projection/index.js

@@ -0,0 +1,128 @@
+var coordEach = require('@turf/meta').coordEach;
+var clone = require('@turf/clone');
+
+module.exports = {
+    toMercator: toMercator,
+    toWgs84: toWgs84
+};
+
+/**
+ * Converts a WGS84 GeoJSON object into Mercator (EPSG:900913) projection
+ *
+ * @name toMercator
+ * @param {GeoJSON} geojson WGS84 GeoJSON object
+ * @param {boolean} [mutate=false] allows GeoJSON input to be mutated (significant performance increase if true)
+ * @returns {GeoJSON} true/false
+ * @example
+ * var pt = turf.point([-71,41]);
+ * var converted = turf.toMercator(pt);
+ *
+ * //addToMap
+ * var addToMap = [pt, converted];
+ */
+function toMercator(geojson, mutate) {
+    return convert(geojson, mutate, 'mercator');
+}
+
+/**
+ * Converts a Mercator (EPSG:900913) GeoJSON object into WGS84 projection
+ *
+ * @name toWgs84
+ * @param {GeoJSON} geojson Mercator GeoJSON object
+ * @param {boolean} [mutate=false] allows GeoJSON input to be mutated (significant performance increase if true)
+ * @returns {GeoJSON} true/false
+ * @example
+ * var pt = turf.point([-7903683.846322424, 5012341.663847514]);
+ * var converted = turf.toWgs84(pt);
+ *
+ * //addToMap
+ * var addToMap = [pt, converted];
+ */
+function toWgs84(geojson, mutate) {
+    return convert(geojson, mutate, 'wgs84');
+}
+
+
+/**
+ * Converts a GeoJSON coordinates to the defined `projection`
+ *
+ * @private
+ * @param {GeoJSON} geojson GeoJSON Feature or Geometry
+ * @param {boolean} [mutate=false] allows GeoJSON input to be mutated (significant performance increase if true)
+ * @param {string} projection defines the projection system to convert the coordinates to
+ * @returns {GeoJSON} true/false
+ */
+function convert(geojson, mutate, projection) {
+    if (!geojson) throw new Error('geojson is required');
+
+    if (mutate !== true) geojson = clone(geojson);
+
+    coordEach(geojson, function (coord) {
+        var newCoord = (projection === 'mercator') ? convertToMercator(coord) : convertToWgs84(coord);
+        coord[0] = newCoord[0];
+        coord[1] = newCoord[1];
+    });
+
+    return geojson;
+}
+
+/**
+ * Convert lon/lat values to 900913 x/y.
+ * (from https://github.com/mapbox/sphericalmercator)
+ *
+ * @private
+ * @param {Array<number>} lonLat WGS84 point
+ * @returns {Array<number>} Mercator [x, y] point
+ */
+function convertToMercator(lonLat) {
+    var D2R = Math.PI / 180,
+        // 900913 properties
+        A = 6378137.0,
+        MAXEXTENT = 20037508.342789244;
+
+    // compensate longitudes passing the 180th meridian
+    // from https://github.com/proj4js/proj4js/blob/master/lib/common/adjust_lon.js
+    var adjusted = (Math.abs(lonLat[0]) <= 180) ? lonLat[0] : (lonLat[0] - (sign(lonLat[0]) * 360));
+    var xy = [
+        A * adjusted * D2R,
+        A * Math.log(Math.tan((Math.PI * 0.25) + (0.5 * lonLat[1] * D2R)))
+    ];
+
+    // if xy value is beyond maxextent (e.g. poles), return maxextent
+    if (xy[0] > MAXEXTENT) xy[0] = MAXEXTENT;
+    if (xy[0] < -MAXEXTENT) xy[0] = -MAXEXTENT;
+    if (xy[1] > MAXEXTENT) xy[1] = MAXEXTENT;
+    if (xy[1] < -MAXEXTENT) xy[1] = -MAXEXTENT;
+
+    return xy;
+}
+
+/**
+ * Convert 900913 x/y values to lon/lat.
+ * (from https://github.com/mapbox/sphericalmercator)
+ *
+ * @private
+ * @param {Array<number>} xy Mercator [x, y] point
+ * @returns {Array<number>} WGS84 [lon, lat] point
+ */
+function convertToWgs84(xy) {
+    // 900913 properties.
+    var R2D = 180 / Math.PI,
+        A = 6378137.0;
+
+    return [
+        (xy[0] * R2D / A),
+        ((Math.PI * 0.5) - 2.0 * Math.atan(Math.exp(-xy[1] / A))) * R2D
+    ];
+}
+
+/**
+ * Returns the sign of the input, or zero
+ *
+ * @private
+ * @param {number} x input
+ * @returns {number} -1|0|1 output
+ */
+function sign(x) {
+    return (x < 0) ? -1 : (x > 0) ? 1 : 0;
+}

packages/turf-projection/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@turf/projection",
+  "version": "4.0.0",
+  "description": "turf projection module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts"
+  ],
+  "scripts": {
+    "test": "node test.js",
+    "bench": "node bench.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/Turfjs/turf.git"
+  },
+  "keywords": [
+    "turf",
+    "projection",
+    "to-mercator",
+    "to-wgs84",
+    "EPSG:4326",
+    "WGS84",
+    "mercator",
+    "web-mercator",
+    "EPSG:3857",
+    "EPSG:3785",
+    "900913",
+    "EPSG:900913",
+    "EPSG:102113"
+  ],
+  "author": "Turf Authors",
+  "contributors": [
+    "Stefano Borghi <@stebogit>"
+  ],
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Turfjs/turf/issues"
+  },
+  "homepage": "https://github.com/Turfjs/turf",
+  "devDependencies": {
+    "@turf/helpers": "^4.6.0",
+    "@turf/truncate": "^4.6.0",
+    "benchmark": "^2.1.4",
+    "write-json-file": "^2.2.0",
+    "load-json-file": "^2.0.0",
+    "proj4": "2.4.4",
+    "tape": "^4.6.3"
+  },
+  "dependencies": {
+    "@turf/clone": "^4.6.1",
+    "@turf/meta": "^4.6.0"
+  }
+}