@turf/difference

What is @turf/difference?

@turf/difference is a module in the Turf.js library that allows you to compute the geometric difference between two polygons. This is useful in geospatial analysis for determining the area that is unique to one polygon when compared to another.

What are @turf/difference's main functionalities?

Compute Difference Between Two Polygons

This feature allows you to compute the difference between two polygons. The resulting polygon represents the area that is unique to the first polygon when compared to the second polygon.

const turf = require('@turf/turf');

const polygon1 = turf.polygon([[
  [-82.574787, 35.594087],
  [-82.574787, 35.615581],
  [-82.545261, 35.615581],
  [-82.545261, 35.594087],
  [-82.574787, 35.594087]
]]);

const polygon2 = turf.polygon([[
  [-82.560024, 35.585153],
  [-82.560024, 35.602602],
  [-82.52964, 35.602602],
  [-82.52964, 35.585153],
  [-82.560024, 35.585153]
]]);

const difference = turf.difference(polygon1, polygon2);
console.log(difference);

Other packages similar to @turf/difference

jsts

JSTS is a JavaScript library of spatial predicates and functions for processing geometry. It is a port of the Java Topology Suite (JTS). JSTS provides a more comprehensive set of geometric operations compared to @turf/difference, including union, intersection, and buffer operations.

martinez-polygon-clipping

Martinez Polygon Clipping is a library for performing boolean operations on polygons, such as union, intersection, and difference. It is known for its performance and accuracy, making it a good alternative to @turf/difference for complex polygon operations.

README

@turf/difference

difference

Finds the difference between two polygons by clipping the second polygon from the first.

Parameters

• polygon1 Feature<(Polygon | MultiPolygon)> input Polygon feature
• polygon2 Feature<(Polygon | MultiPolygon)> Polygon feature to difference from polygon1

Examples

var polygon1 = turf.polygon([[
  [128, -26],
  [141, -26],
  [141, -21],
  [128, -21],
  [128, -26]
]], {
  "fill": "#F00",
  "fill-opacity": 0.1
});
var polygon2 = turf.polygon([[
  [126, -28],
  [140, -28],
  [140, -20],
  [126, -20],
  [126, -28]
]], {
  "fill": "#00F",
  "fill-opacity": 0.1
});

var difference = turf.difference(polygon1, polygon2);

//addToMap
var addToMap = [polygon1, polygon2, difference];

Returns (Feature<(Polygon | MultiPolygon)> | null) a Polygon or MultiPolygon feature showing the area of polygon1 excluding the area of polygon2 (if empty returns null)

---

This module is part of the Turfjs project, an open source module collection dedicated to geographic algorithms. It is maintained in the Turfjs/turf repository, where you can create PRs and issues.

Installation

Install this module individually:

$ npm install @turf/difference

Or install the Turf module that includes it as a function:

$ npm install @turf/turf

Changelog

5.0.0 🎉

⭐️ Major Updates

• TurfJS now supports ES Modules (Related PR's)
• Optional parameters are now defined as an Object.

🚀 New Modules

[@turf/voronoi][voronoi]

Takes a FeatureCollection of points, and a bounding box, and returns a FeatureCollection of Voronoi polygons. (PR https://github.com/Turfjs/turf/pull/1043 - Author @stevage)

[@turf/shortest-path][shortest-path]

Returns the shortest path from start to end without colliding with any feature in obstacles (PR https://github.com/Turfjs/turf/pull/956 - Author @stebogit)

[@turf/boolean-parallel][boolean-parallel]

Boolean-Parallel returns True if each segment of line1 is parallel to the correspondent segment of line2 (PR https://github.com/Turfjs/turf/pull/941 - Author @stebogit)

[@turf/nearest-point-on-line][nearest-point-on-line]

Takes a {@link Point} and a {@link LineString} and calculates the closest Point on the (Multi)LineString. (PR https://github.com/Turfjs/turf/pull/939 - Author @stebogit)

🏅 New Features/Enhancements

• Updates [@turf/unkink-polygon][unkink-polygon] testing & added flattenEach instead of using flatten. (PR https://github.com/Turfjs/turf/pull/889)

• Add multi-geomtry support to @turf/line-split (PR https://github.com/Turfjs/turf/pull/1078)

• Improve @turf/meta lineEach method to provide properties, id and bbox (PR https://github.com/Turfjs/turf/pull/1010)

🐛 Bug Fixes

• Fixes @turf/helpers earth radius variable (PR https://github.com/Turfjs/turf/pull/1012)

• Fixes @turf/polygon-tangents bug (PR https://github.com/Turfjs/turf/pull/1058)

• Fixes @turf/line-chunk bug when the number of segments is integer (PR https://github.com/Turfjs/turf/pull/1046)

• Fixes segmentEach and segmentReduce methods in @turf/meta to ensure something is returned (PR https://github.com/Turfjs/turf/pull/968)

⚠️ Breaking Change

• Optional parameters are now defined as an Object:

Before

var from = [-75.343, 39.984];
var to = [-75.534, 39.123];
var units = 'miles';
var distance = turf.distance(from, to, units);

After

var from = [-75.343, 39.984];
var to = [-75.534, 39.123];
var options = {units: 'miles'};
var distance = turf.distance(from, to, options);

• Reworked @turf/random PR https://github.com/Turfjs/turf/issues/994
• Deprecate @turf/idw Issue https://github.com/Turfjs/turf/issues/887
• Reworked Grid modules @turf/point-grid/hex/square/triangle PR https://github.com/Turfjs/turf/pull/1029
• Renamed Modules/Methods
  • [x] @turf/inside => @turf/boolean-point-in-polygon https://github.com/Turfjs/turf/issues/860#issuecomment-317216235
  • [x] @turf/within => @turf/points-within-polygon https://github.com/Turfjs/turf/issues/860#issuecomment-317216235
  • [x] @turf/bezier => @turf/bezier-spline Issue https://github.com/Turfjs/turf/issues/661
  • [x] @turf/nearest => @turf/nearest-point https://github.com/Turfjs/turf/pull/858#issuecomment-317197295
  • [x] @turf/point-on-line => @turf/nearest-point-on-line https://github.com/Turfjs/turf/pull/858#issuecomment-317197295
  • [x] @turf/lineDistance => @turf/length https://github.com/Turfjs/turf/issues/860#issuecomment-317229869
  • [x] @turf/helpers
    • [x] radians2degrees => radiansToDegrees
    • [x] degrees2radians => degreesToRadians
    • [x] distanceToDegrees => lengthToDegrees
    • [x] distanceToRadians => lengthToRadians
    • [x] radiansToDistance => radiansToLength
    • [x] bearingToAngle => bearingToAzimuth
    • [x] convertDistance => convertLength