@turf/helpers
Version:
turf geometries
325 lines (307 loc) • 9.58 kB
JavaScript
/**
* Wraps a GeoJSON {@link Geometry} in a GeoJSON {@link Feature}.
*
* @name feature
* @param {Geometry} geometry input geometry
* @param {Object} properties properties
* @returns {FeatureCollection} a FeatureCollection of input features
* @example
* var geometry = {
* "type": "Point",
* "coordinates": [
* 67.5,
* 32.84267363195431
* ]
* }
*
* var feature = turf.feature(geometry);
*
* //=feature
*/
function feature(geometry, properties) {
return {
type: 'Feature',
properties: properties || {},
geometry: geometry
};
}
module.exports.feature = feature;
/**
* Takes coordinates and properties (optional) and returns a new {@link Point} feature.
*
* @name point
* @param {Array<number>} coordinates longitude, latitude position (each in decimal degrees)
* @param {Object=} properties an Object that is used as the {@link Feature}'s
* properties
* @returns {Feature<Point>} a Point feature
* @example
* var pt1 = turf.point([-75.343, 39.984]);
*
* //=pt1
*/
module.exports.point = function (coordinates, properties) {
if (!Array.isArray(coordinates)) throw new Error('Coordinates must be an array');
if (coordinates.length < 2) throw new Error('Coordinates must be at least 2 numbers long');
return feature({
type: 'Point',
coordinates: coordinates.slice()
}, properties);
};
/**
* Takes an array of LinearRings and optionally an {@link Object} with properties and returns a {@link Polygon} feature.
*
* @name polygon
* @param {Array<Array<Array<number>>>} coordinates an array of LinearRings
* @param {Object=} properties a properties object
* @returns {Feature<Polygon>} a Polygon feature
* @throws {Error} throw an error if a LinearRing of the polygon has too few positions
* or if a LinearRing of the Polygon does not have matching Positions at the
* beginning & end.
* @example
* var polygon = turf.polygon([[
* [-2.275543, 53.464547],
* [-2.275543, 53.489271],
* [-2.215118, 53.489271],
* [-2.215118, 53.464547],
* [-2.275543, 53.464547]
* ]], { name: 'poly1', population: 400});
*
* //=polygon
*/
module.exports.polygon = function (coordinates, properties) {
if (!coordinates) throw new Error('No coordinates passed');
for (var i = 0; i < coordinates.length; i++) {
var ring = coordinates[i];
if (ring.length < 4) {
throw new Error('Each LinearRing of a Polygon must have 4 or more Positions.');
}
for (var j = 0; j < ring[ring.length - 1].length; j++) {
if (ring[ring.length - 1][j] !== ring[0][j]) {
throw new Error('First and last Position are not equivalent.');
}
}
}
return feature({
type: 'Polygon',
coordinates: coordinates
}, properties);
};
/**
* Creates a {@link LineString} based on a
* coordinate array. Properties can be added optionally.
*
* @name lineString
* @param {Array<Array<number>>} coordinates an array of Positions
* @param {Object=} properties an Object of key-value pairs to add as properties
* @returns {Feature<LineString>} a LineString feature
* @throws {Error} if no coordinates are passed
* @example
* var linestring1 = turf.lineString([
* [-21.964416, 64.148203],
* [-21.956176, 64.141316],
* [-21.93901, 64.135924],
* [-21.927337, 64.136673]
* ]);
* var linestring2 = turf.lineString([
* [-21.929054, 64.127985],
* [-21.912918, 64.134726],
* [-21.916007, 64.141016],
* [-21.930084, 64.14446]
* ], {name: 'line 1', distance: 145});
*
* //=linestring1
*
* //=linestring2
*/
module.exports.lineString = function (coordinates, properties) {
if (!coordinates) {
throw new Error('No coordinates passed');
}
return feature({
type: 'LineString',
coordinates: coordinates
}, properties);
};
/**
* Takes one or more {@link Feature|Features} and creates a {@link FeatureCollection}.
*
* @name featureCollection
* @param {Feature[]} features input features
* @returns {FeatureCollection} a FeatureCollection of input features
* @example
* var features = [
* turf.point([-75.343, 39.984], {name: 'Location A'}),
* turf.point([-75.833, 39.284], {name: 'Location B'}),
* turf.point([-75.534, 39.123], {name: 'Location C'})
* ];
*
* var fc = turf.featureCollection(features);
*
* //=fc
*/
module.exports.featureCollection = function (features) {
return {
type: 'FeatureCollection',
features: features
};
};
/**
* Creates a {@link Feature<MultiLineString>} based on a
* coordinate array. Properties can be added optionally.
*
* @name multiLineString
* @param {Array<Array<Array<number>>>} coordinates an array of LineStrings
* @param {Object=} properties an Object of key-value pairs to add as properties
* @returns {Feature<MultiLineString>} a MultiLineString feature
* @throws {Error} if no coordinates are passed
* @example
* var multiLine = turf.multiLineString([[[0,0],[10,10]]]);
*
* //=multiLine
*
*/
module.exports.multiLineString = function (coordinates, properties) {
if (!coordinates) {
throw new Error('No coordinates passed');
}
return feature({
type: 'MultiLineString',
coordinates: coordinates
}, properties);
};
/**
* Creates a {@link Feature<MultiPoint>} based on a
* coordinate array. Properties can be added optionally.
*
* @name multiPoint
* @param {Array<Array<number>>} coordinates an array of Positions
* @param {Object=} properties an Object of key-value pairs to add as properties
* @returns {Feature<MultiPoint>} a MultiPoint feature
* @throws {Error} if no coordinates are passed
* @example
* var multiPt = turf.multiPoint([[0,0],[10,10]]);
*
* //=multiPt
*
*/
module.exports.multiPoint = function (coordinates, properties) {
if (!coordinates) {
throw new Error('No coordinates passed');
}
return feature({
type: 'MultiPoint',
coordinates: coordinates
}, properties);
};
/**
* Creates a {@link Feature<MultiPolygon>} based on a
* coordinate array. Properties can be added optionally.
*
* @name multiPolygon
* @param {Array<Array<Array<Array<number>>>>} coordinates an array of Polygons
* @param {Object=} properties an Object of key-value pairs to add as properties
* @returns {Feature<MultiPolygon>} a multipolygon feature
* @throws {Error} if no coordinates are passed
* @example
* var multiPoly = turf.multiPolygon([[[[0,0],[0,10],[10,10],[10,0],[0,0]]]]);
*
* //=multiPoly
*
*/
module.exports.multiPolygon = function (coordinates, properties) {
if (!coordinates) {
throw new Error('No coordinates passed');
}
return feature({
type: 'MultiPolygon',
coordinates: coordinates
}, properties);
};
/**
* Creates a {@link Feature<GeometryCollection>} based on a
* coordinate array. Properties can be added optionally.
*
* @name geometryCollection
* @param {Array<{Geometry}>} geometries an array of GeoJSON Geometries
* @param {Object=} properties an Object of key-value pairs to add as properties
* @returns {Feature<GeometryCollection>} a GeoJSON GeometryCollection Feature
* @example
* var pt = {
* "type": "Point",
* "coordinates": [100, 0]
* };
* var line = {
* "type": "LineString",
* "coordinates": [ [101, 0], [102, 1] ]
* };
* var collection = turf.geometryCollection([pt, line]);
*
* //=collection
*/
module.exports.geometryCollection = function (geometries, properties) {
return feature({
type: 'GeometryCollection',
geometries: geometries
}, properties);
};
var factors = {
miles: 3960,
nauticalmiles: 3441.145,
degrees: 57.2957795,
radians: 1,
inches: 250905600,
yards: 6969600,
meters: 6373000,
metres: 6373000,
kilometers: 6373,
kilometres: 6373,
feet: 20908792.65
};
/*
* Convert a distance measurement from radians to a more friendly unit.
*
* @name radiansToDistance
* @param {number} distance in radians across the sphere
* @param {string} [units=kilometers] can be degrees, radians, miles, or kilometers
* inches, yards, metres, meters, kilometres, kilometers.
* @returns {number} distance
*/
module.exports.radiansToDistance = function (radians, units) {
var factor = factors[units || 'kilometers'];
if (factor === undefined) {
throw new Error('Invalid unit');
}
return radians * factor;
};
/*
* Convert a distance measurement from a real-world unit into radians
*
* @name distanceToRadians
* @param {number} distance in real units
* @param {string} [units=kilometers] can be degrees, radians, miles, or kilometers
* inches, yards, metres, meters, kilometres, kilometers.
* @returns {number} radians
*/
module.exports.distanceToRadians = function (distance, units) {
var factor = factors[units || 'kilometers'];
if (factor === undefined) {
throw new Error('Invalid unit');
}
return distance / factor;
};
/*
* Convert a distance measurement from a real-world unit into degrees
*
* @name distanceToRadians
* @param {number} distance in real units
* @param {string} [units=kilometers] can be degrees, radians, miles, or kilometers
* inches, yards, metres, meters, kilometres, kilometers.
* @returns {number} degrees
*/
module.exports.distanceToDegrees = function (distance, units) {
var factor = factors[units || 'kilometers'];
if (factor === undefined) {
throw new Error('Invalid unit');
}
return (distance / factor) * 57.2958;
};