Merge pull request #939 from Turfjs/nearest-to-line

New module `@turf/nearest-point-to-line`

packages/turf-nearest-point-to-line/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-nearest-point-to-line/README.md

@@ -0,0 +1,51 @@
+# @turf/nearest-point-to-line
+
+# nearestPointToLine
+
+Returns the closest [point](http://geojson.org/geojson-spec.html#point), of a [collection](http://geojson.org/geojson-spec.html#feature-collection-objects) of points, to a [line](http://geojson.org/geojson-spec.html#linestring).
+The returned point has a `dist` property indicating its distance to the line.
+
+**Parameters**
+
+-   `points` **([FeatureCollection](http://geojson.org/geojson-spec.html#feature-collection-objects) \| [GeometryCollection](http://geojson.org/geojson-spec.html#geometrycollection)<[Point](http://geojson.org/geojson-spec.html#point)>)** Point Collection
+-   `line` **([Feature](http://geojson.org/geojson-spec.html#feature-objects) \| [Geometry](http://geojson.org/geojson-spec.html#geometry)<[LineString](http://geojson.org/geojson-spec.html#linestring)>)** Line Feature
+-   `units` **\[[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** unit of the output distance property, can be degrees, radians, miles, or kilometer (optional, default `kilometers`)
+
+**Examples**
+
+```javascript
+var points = featureCollection([point([0, 0]), point([0.5, 0.5])]);
+var line = lineString([[1,1], [-1,1]]);
+
+var nearest = turf.nearestPointToLine(points, line);
+
+//addToMap
+var addToMap = [nearest, line];
+```
+
+Returns **[Feature](http://geojson.org/geojson-spec.html#feature-objects)<[Point](http://geojson.org/geojson-spec.html#point)>** the closest point
+
+<!-- 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/nearest-point-to-line
+```
+
+Or install the Turf module that includes it as a function:
+
+```sh
+$ npm install @turf/turf
+```

packages/turf-nearest-point-to-line/bench.js

@@ -0,0 +1,36 @@
+const path = require('path');
+const glob = require('glob');
+const load = require('load-json-file');
+const Benchmark = require('benchmark');
+const nearestPointToLine = require('./');
+
+/**
+ * Benchmark Results
+ *
+ * fiji: 2.973ms
+ * on-line: 0.758ms
+ * one: 0.549ms
+ * resolute: 0.349ms
+ * two: 0.358ms
+ *
+ * fiji x 36,409 ops/sec ±4.14% (69 runs sampled)
+ * on-line x 14,044 ops/sec ±4.92% (69 runs sampled)
+ * one x 65,604 ops/sec ±11.55% (64 runs sampled)
+ * resolute x 44,962 ops/sec ±6.76% (67 runs sampled)
+ * two x 42,690 ops/sec ±2.34% (76 runs sampled)
+ */
+const suite = new Benchmark.Suite('turf-nearest-point-to-line');
+glob.sync(path.join(__dirname, 'test', 'in', '*.geojson')).forEach(filepath => {
+    const {name} = path.parse(filepath);
+    const geojson = load.sync(filepath);
+    const [points, line] = geojson.features;
+    console.time(name);
+    nearestPointToLine(points, line);
+    console.timeEnd(name);
+    suite.add(name, () => nearestPointToLine(points, line));
+});
+
+suite
+    .on('cycle', e => console.log(String(e.target)))
+    .on('complete', () => {})
+    .run();

packages/turf-nearest-point-to-line/index.d.ts

@@ -0,0 +1,19 @@
+/// <reference types="geojson" />
+
+import { Units, FeatureGeometryCollection } from '@turf/helpers'
+
+type Points = GeoJSON.FeatureCollection<GeoJSON.Point> | FeatureGeometryCollection;
+type LineString = GeoJSON.Feature<GeoJSON.LineString> | GeoJSON.LineString;
+interface Point extends GeoJSON.Feature<GeoJSON.Point> {
+  properties: {
+    dist: number
+    [key: string]: any
+  }
+}
+
+/**
+ * http://turfjs.org/docs/#nearestpointtoline
+ */
+declare function nearestPointToLine(points: Points, line: LineString, units?: Units): Point;
+declare namespace nearestPointToLine { }
+export = nearestPointToLine;

packages/turf-nearest-point-to-line/index.js

@@ -0,0 +1,72 @@
+var meta = require('@turf/meta');
+var pointToLineDistance = require('@turf/point-to-line-distance');
+var featureEach = meta.featureEach;
+var geomEach = meta.geomEach;
+
+/**
+ * Returns the closest {@link Point|point}, of a {@link FeatureCollection|collection} of points, to a {@link LineString|line}.
+ * The returned point has a `dist` property indicating its distance to the line.
+ *
+ * @name nearestPointToLine
+ * @param {FeatureCollection|GeometryCollection<Point>} points Point Collection
+ * @param {Feature|Geometry<LineString>} line Line Feature
+ * @param {string} [units=kilometers] unit of the output distance property, can be degrees, radians, miles, or kilometer
+ * @returns {Feature<Point>} the closest point
+ * @example
+ * var points = featureCollection([point([0, 0]), point([0.5, 0.5])]);
+ * var line = lineString([[1,1], [-1,1]]);
+ *
+ * var nearest = turf.nearestPointToLine(points, line);
+ *
+ * //addToMap
+ * var addToMap = [nearest, line];
+ */
+module.exports = function (points, line, units) {
+    // validation
+    if (!points) throw new Error('points is required');
+    points = handleCollection(points);
+    if (!points.features.length) throw new Error('points must contain features');
+
+    if (!line) throw new Error('line is required');
+    var type = line.geometry ? line.geometry.type : line.type;
+    if (type !== 'LineString') throw new Error('line must be a LineString');
+
+    var dist = Infinity;
+    var pt = null;
+
+    featureEach(points, function (point) {
+        var d = pointToLineDistance(point, line, units);
+        if (d < dist) {
+            dist = d;
+            pt = point;
+        }
+    });
+    pt.properties.dist = dist;
+    return pt;
+};
+
+/**
+ * Convert Collection to FeatureCollection
+ *
+ * @private
+ * @param {FeatureCollection|GeometryCollection<Point>} points Points
+ * @returns {FeatureCollection<Point>} points
+ */
+function handleCollection(points) {
+    var features = [];
+    var type = points.geometry ? points.geometry.type : points.type;
+    switch (type) {
+    case 'GeometryCollection':
+        geomEach(points, function (geom) {
+            if (geom.type === 'Point') features.push({type: 'Feature', properties: {}, geometry: geom});
+        });
+        return {type: 'FeatureCollection', features: features};
+    case 'FeatureCollection':
+        points.features = points.features.filter(function (feature) {
+            return feature.geometry.type === 'Point';
+        });
+        return points;
+    default:
+        throw new Error('points must be a Point Collection');
+    }
+}

packages/turf-nearest-point-to-line/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@turf/nearest-point-to-line",
+  "version": "4.0.0",
+  "description": "turf nearest-point-to-line 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",
+    "geojson",
+    "gis",
+    "near",
+    "nearest-point-to-line"
+  ],
+  "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/circle": "^4.7.3",
+    "@turf/helpers": "4.7.1",
+    "@turf/truncate": "^4.7.3",
+    "benchmark": "^2.1.4",
+    "load-json-file": "^2.0.0",
+    "tape": "^4.6.3",
+    "write-json-file": "^2.2.0"
+  },
+  "dependencies": {
+    "@turf/meta": "^4.7.3",
+    "@turf/point-to-line-distance": "^4.7.3"
+  }
+}

packages/turf-nearest-point-to-line/test.js

@@ -0,0 +1,76 @@
+const fs = require('fs');
+const test = require('tape');
+const path = require('path');
+const load = require('load-json-file');
+const write = require('write-json-file');
+const circle = require('@turf/circle');
+const truncate = require('@turf/truncate');
+const {geometryCollection, featureCollection, point, lineString, round} = require('@turf/helpers');
+const nearestPointToLine = require('./');
+
+const directories = {
+    in: path.join(__dirname, 'test', 'in') + path.sep,
+    out: path.join(__dirname, 'test', 'out') + path.sep
+};
+
+const fixtures = fs.readdirSync(directories.in).map(filename => {
+    return {
+        filename,
+        name: path.parse(filename).name,
+        geojson: load.sync(directories.in + filename)
+    };
+});
+
+test('turf-nearest-point-to-line', t => {
+    for (const {filename, name, geojson}  of fixtures) {
+        const [points, line] = geojson.features;
+        let {units} = geojson.properties || {};
+        const nearest = nearestPointToLine(points, line, units);
+        const distance = round(nearest.properties.dist, 13);
+        nearest.properties.dist = distance;
+        nearest.properties = Object.assign(nearest.properties, {
+            'marker-color': '#F00',
+            'marker-size': 'large',
+            'marker-symbol': 'star'
+        });
+        const distanceCircle = truncate(circle(nearest, distance || 1, null, units, {fill: '#F00'}));
+        const results = featureCollection([points, nearest, line, distanceCircle]);
+
+        if (process.env.REGEN) write.sync(directories.out + filename, results);
+        t.deepEqual(results, load.sync(directories.out + filename), name);
+    }
+    t.end();
+});
+
+
+test('turf-nearest-point-to-line -- throws', t => {
+    const points = featureCollection([point([0, 0]), point([0, 1])]);
+    const line = lineString([[1, 1], [-1, 1]]);
+
+    t.throws(() => nearestPointToLine(null, line), /points is required/, 'missing points');
+    t.throws(() => nearestPointToLine(points, null), /line is required/, 'missing line');
+
+    t.throws(() => nearestPointToLine(points, line, 'invalid'), /units is invalid/, 'invalid units');
+    t.throws(() => nearestPointToLine(points, points), /line must be a LineString/, 'invalid line');
+    t.throws(() => nearestPointToLine(line, line), /points must be a Point Collection/, 'invalid points');
+
+    t.end();
+});
+
+test('turf-nearest-point-to-line -- Geometry', t => {
+    const points = featureCollection([point([0, 0]), point([0, 1])]);
+    const geomPoints = geometryCollection([point([0, 0]).geometry, point([0, 1]).geometry]);
+    const line = lineString([[1, 1], [-1, 1]]);
+
+    t.assert(nearestPointToLine(points, line.geometry));
+    t.assert(nearestPointToLine(geomPoints, line.geometry));
+    t.end();
+});
+
+test('turf-nearest-point-to-line -- Empty FeatureCollection', t => {
+    const points = featureCollection([]);
+    const line = lineString([[1, 1], [-1, 1]]);
+
+    t.throws(() => nearestPointToLine(points, line), /points must contain features/, 'points must contain features');
+    t.end();
+});