diff --git a/packages/turf-helpers/README.md b/packages/turf-helpers/README.md index 41b72d46b..d5b43b397 100644 --- a/packages/turf-helpers/README.md +++ b/packages/turf-helpers/README.md @@ -249,6 +249,7 @@ Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refer # radiansToDistance Convert a distance measurement (assuming a spherical Earth) from radians to a more friendly unit. +Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet **Parameters** @@ -260,6 +261,7 @@ Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refer # distanceToRadians Convert a distance measurement (assuming a spherical Earth) from a real-world unit into radians +Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet **Parameters** @@ -271,6 +273,7 @@ Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refer # distanceToDegrees Convert a distance measurement (assuming a spherical Earth) from a real-world unit into degrees +Valid units: miles, nauticalmiles, inches, yards, meters, metres, centimeters, kilometres, feet **Parameters** @@ -310,6 +313,19 @@ Converts an angle in degrees to radians Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** angle in radians +# convertDistance + +Converts a distance to the requested unit. +Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet + +**Parameters** + +- `distance` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** to be converted +- `originalUnit` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** of the distance +- `finalUnit` **\[[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** returned unit (optional, default `kilometers`) + +Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** the converted distance + diff --git a/packages/turf-helpers/index.js b/packages/turf-helpers/index.js index db9b461ba..55c8a5895 100644 --- a/packages/turf-helpers/index.js +++ b/packages/turf-helpers/index.js @@ -264,6 +264,8 @@ var factors = { yards: 6969600, meters: 6373000, metres: 6373000, + centimeters: 6.373e+8, + centimetres: 6.373e+8, kilometers: 6373, kilometres: 6373, feet: 20908792.65 @@ -283,12 +285,15 @@ var factors = { * //=120.43 */ function round(num, precision) { + if (num === undefined || num === null || isNaN(num)) throw new Error('num is required'); + if (precision && !(precision >= 0)) throw new Error('precision must be a positive number'); var multiplier = Math.pow(10, precision || 0); return Math.round(num * multiplier) / multiplier; } /** * Convert a distance measurement (assuming a spherical Earth) from radians to a more friendly unit. + * Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet * * @name radiansToDistance * @param {number} radians in radians across the sphere @@ -305,6 +310,7 @@ function radiansToDistance(radians, units) { /** * Convert a distance measurement (assuming a spherical Earth) from a real-world unit into radians + * Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet * * @name distanceToRadians * @param {number} distance in real units @@ -321,6 +327,7 @@ function distanceToRadians(distance, units) { /** * Convert a distance measurement (assuming a spherical Earth) from a real-world unit into degrees + * Valid units: miles, nauticalmiles, inches, yards, meters, metres, centimeters, kilometres, feet * * @name distanceToDegrees * @param {number} distance in real units @@ -375,6 +382,25 @@ function degrees2radians(degrees) { return radians * Math.PI / 180; } + +/** + * Converts a distance to the requested unit. + * Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet + * + * @param {number} distance to be converted + * @param {string} originalUnit of the distance + * @param {string} [finalUnit=kilometers] returned unit + * @returns {number} the converted distance + */ +function convertDistance(distance, originalUnit, finalUnit) { + if (distance === null || distance === undefined) throw new Error('distance is required'); + if (!(distance >= 0)) throw new Error('distance must be a positive number'); + + var convertedDistance = radiansToDistance(distanceToRadians(distance, originalUnit), finalUnit || 'kilometers'); + return convertedDistance; +} + + module.exports = { feature: feature, featureCollection: featureCollection, @@ -391,5 +417,6 @@ module.exports = { radians2degrees: radians2degrees, degrees2radians: degrees2radians, bearingToAngle: bearingToAngle, + convertDistance: convertDistance, round: round }; diff --git a/packages/turf-helpers/package.json b/packages/turf-helpers/package.json index b4f9e3458..3b08b22d2 100644 --- a/packages/turf-helpers/package.json +++ b/packages/turf-helpers/package.json @@ -23,6 +23,11 @@ "geojson" ], "author": "Turf Authors", + "contributors": [ + "Tom MacWright <@tmcw>", + "Stefano Borghi <@stebogit>", + "Denis Carriere <@DenisCarriere>" + ], "license": "MIT", "bugs": { "url": "https://github.com/Turfjs/turf/issues" diff --git a/packages/turf-helpers/test.js b/packages/turf-helpers/test.js index 9197ae902..6b01fa96b 100644 --- a/packages/turf-helpers/test.js +++ b/packages/turf-helpers/test.js @@ -15,6 +15,7 @@ const { radians2degrees, degrees2radians, bearingToAngle, + convertDistance, round } = require('./'); @@ -317,11 +318,18 @@ test('distanceToRadians', t => { t.end(); }); +test('distanceToDegrees', t => { + t.equal(distanceToDegrees(1, 'radians'), 57.29577951308232); + t.equal(distanceToDegrees(100, 'kilometers'), 0.8990393772647469); + t.equal(distanceToDegrees(10, 'miles'), 0.14468631190172304); + t.throws(() => distanceToRadians(1, 'foo'), 'invalid units'); + t.end(); +}); + test('radians2degrees', t => { t.equal(round(radians2degrees(Math.PI / 3), 6), 60, 'radiance conversion PI/3'); t.equal(radians2degrees(3.5 * Math.PI), 270, 'radiance conversion 3.5PI'); t.equal(radians2degrees(-Math.PI), -180, 'radiance conversion -PI'); - t.end(); }); @@ -329,7 +337,6 @@ test('radians2degrees', t => { t.equal(degrees2radians(60), Math.PI / 3, 'degrees conversion 60'); t.equal(degrees2radians(270), 1.5 * Math.PI, 'degrees conversion 270'); t.equal(degrees2radians(-180), -Math.PI, 'degrees conversion -180'); - t.end(); }); @@ -339,7 +346,6 @@ test('bearingToAngle', t => { t.equal(bearingToAngle(410), 50); t.equal(bearingToAngle(-200), 160); t.equal(bearingToAngle(-395), 325); - t.end(); }); @@ -347,6 +353,17 @@ test('round', t => { t.equal(round(125.123), 125); t.equal(round(123.123, 1), 123.1); t.equal(round(123.5), 124); + t.throws(() => round(34.5, 'precision'), 'invalid precision'); + t.throws(() => round(34.5, -5), 'invalid precision'); + t.end(); +}); +test('convertDistance', t => { + t.equal(convertDistance(1000, 'meters'), 1); + t.equal(convertDistance(1, 'kilometers', 'miles'), 0.6213714106386318); + t.equal(convertDistance(1, 'miles', 'kilometers'), 1.6093434343434343); + t.equal(convertDistance(1, 'nauticalmiles'), 1.851999843075488); + t.equal(convertDistance(1, 'meters', 'centimeters'), 100); + t.throws(() => convertDistance(1, 'foo'), 'invalid units'); t.end(); });