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:/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:/Turfjs/turf.git"
+ },
+ "keywords": [
+ "turf",
+ "geojson",
+ "gis",
+ "near",
+ "nearest-point-to-line"
+ ],
+ "author": "Turf Authors",
+ "contributors": [
+ "Stefano Borghi <@stebogit>"
+ ],
+ "license": "MIT",
+ "bugs": {
+ "url": "https:/Turfjs/turf/issues"
+ },
+ "homepage": "https:/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();
+});