polybool

Set operations on polygonal regions

The polybool function is not recommended. Use a shape object and the intersect, union, subtract, or xor function, instead. For more information, see Version History.

Syntax

[x,y] = polybool(flag,x1,y1,x2,y2)

Description

[x,y] = polybool(flag,x1,y1,x2,y2) performs the polygon set operation identified by flag. The result is output using the same format as the input. Geographic data that encompasses a pole cannot be used directly. Use flatearthpoly to convert polygons that contain a pole to Cartesian coordinates.

Most Mapping Toolbox™ functions adhere to the convention that individual contours with clockwise-ordered vertices are external contours and individual contours with counterclockwise-ordered vertices are internal contours. Although the polybool function ignores vertex order, follow this convention when creating contours to ensure consistency with other functions.

Examples

Set Operations on Two Overlapping Circular Regions

theta = linspace(0, 2*pi, 100);
x1 = cos(theta) - 0.5;
y1 = -sin(theta);    % -sin(theta) to make a clockwise contour
x2 = x1 + 1;
y2 = y1;
[xa, ya] = polybool('union', x1, y1, x2, y2);
[xb, yb] = polybool('intersection', x1, y1, x2, y2);
[xc, yc] = polybool('xor', x1, y1, x2, y2);
[xd, yd] = polybool('subtraction', x1, y1, x2, y2);

subplot(2, 2, 1)
patch(xa, ya, 1, 'FaceColor', 'r')
axis equal, axis off, hold on
plot(x1, y1, x2, y2, 'Color', 'k')
title('Union')

subplot(2, 2, 2)
patch(xb, yb, 1, 'FaceColor', 'r')
axis equal, axis off, hold on
plot(x1, y1, x2, y2, 'Color', 'k')
title('Intersection')

subplot(2, 2, 3)
% The output of the exclusive-or operation consists of disjoint
% regions.  It can be plotted as a single patch object using the
% face-vertex form.  Use poly2fv to convert a polygonal region
% to face-vertex form.
[f, v] = poly2fv(xc, yc);
patch('Faces', f, 'Vertices', v, 'FaceColor', 'r', ...
  'EdgeColor', 'none')
axis equal, axis off, hold on
plot(x1, y1, x2, y2, 'Color', 'k')
title('Exclusive Or')

subplot(2, 2, 4)
patch(xd, yd, 1, 'FaceColor', 'r')
axis equal, axis off, hold on
plot(x1, y1, x2, y2, 'Color', 'k')
title('Subtraction')

Set Operations on Regions with Holes

Ax = {[1 1 6 6 1], [2 5 5 2 2], [2 5 5 2 2]};
Ay = {[1 6 6 1 1], [2 2 3 3 2], [4 4 5 5 4]};
subplot(2, 3, 1)
[f, v] = poly2fv(Ax, Ay);
patch('Faces', f, 'Vertices', v, 'FaceColor', 'r', ...
  'EdgeColor', 'none')
axis equal, axis off, axis([0 7 0 7]), hold on
for k = 1:numel(Ax), plot(Ax{k}, Ay{k}, 'Color', 'k'), end
title('A')

Bx = {[0 0 7 7 0], [1 3 3 1 1], [4 6 6 4 4]};
By = {[0 7 7 0 0], [1 1 6 6 1], [1 1 6 6 1]};
subplot(2, 3, 4);
[f, v] = poly2fv(Bx, By);
patch('Faces', f, 'Vertices', v, 'FaceColor', 'r', ...
  'EdgeColor', 'none')
axis equal, axis off, axis([0 7 0 7]), hold on
for k = 1:numel(Bx), plot(Bx{k}, By{k}, 'Color', 'k'), end
title('B')

subplot(2, 3, 2)
[Cx, Cy] = polybool('union', Ax, Ay, Bx, By);
[f, v] = poly2fv(Cx, Cy);
patch('Faces', f, 'Vertices', v, 'FaceColor', 'r', ...
  'EdgeColor', 'none')
axis equal, axis off, axis([0 7 0 7]), hold on
for k = 1:numel(Cx), plot(Cx{k}, Cy{k}, 'Color', 'k'), end
title('A \cup B')

subplot(2, 3, 3)
[Dx, Dy] = polybool('intersection', Ax, Ay, Bx, By);
[f, v] = poly2fv(Dx, Dy);
patch('Faces', f, 'Vertices', v, 'FaceColor', 'r', ...
  'EdgeColor', 'none')
axis equal, axis off, axis([0 7 0 7]), hold on
for k = 1:numel(Dx), plot(Dx{k}, Dy{k}, 'Color', 'k'), end
title('A \cap B')

subplot(2, 3, 5)
[Ex, Ey] = polybool('subtraction', Ax, Ay, Bx, By);
[f, v] = poly2fv(Ex, Ey);
patch('Faces', f, 'Vertices', v, 'FaceColor', 'r', ...
  'EdgeColor', 'none')
axis equal, axis off, axis([0 7 0 7]), hold on
for k = 1:numel(Ex), plot(Ex{k}, Ey{k}, 'Color', 'k'), end
title('A - B')

subplot(2, 3, 6)
[Fx, Fy] = polybool('xor', Ax, Ay, Bx, By);
[f, v] = poly2fv(Fx, Fy);
patch('Faces', f, 'Vertices', v, 'FaceColor', 'r', ...
  'EdgeColor', 'none')
axis equal, axis off, axis([0 7 0 7]), hold on
for k = 1:numel(Fx), plot(Fx{k}, Fy{k}, 'Color', 'k'), end
title('XOR(A, B)')

Input Arguments

flag — Polygon set operation

'intersection' | 'and' | '&' | 'union' | 'or' | '|' | '+' | 'plus' | 'subtraction' | 'minus' | '-' | 'exclusiveor' | 'xor'

Polygon set operation, specified as one of the following values.

Operation
Region intersection	'intersection'	'and'	'&'
Region union	'union'	'or'	'|'	'+'	'plus'
Region subtraction	'subtraction'	'minus'	'-'
Region exclusive or	'exclusiveor'	'xor'

Data Types: char | string

x1 — Polygon contours

NaN-delimited vector | cell array

Polygon contours, specified as a NaN-delimited vector or cell array.

Data Types: double

x2 — Polygon contours

NaN-delimited vector | cell array

Polygon contours, specified as a NaN-delimited vector or cell array.

Data Types: double

y1 — Polygon contours

NaN-delimited vector | cell array

Polygon contours, specified as a NaN-delimited vector or cell array.

Data Types: double

y2 — Polygon contours

NaN-delimited vector | cell array

Polygon contours, specified as a NaN-delimited vector or cell array.

Data Types: double

Output Arguments

x — Polygon contour after set operation

NaN-delimited vector | cell array

Polygon contour after set operation, returned as a NaN-delimited vector or cell array. The output returns in the same format as the input.

y — Polygon contour after set operation

NaN-delimited vector | cell array

Polygon contour after set operation, returned as a NaN-delimited vector or cell array. The output returns in the same format as the input.

Tips

• Numerical problems can occur when the polygons have a large offset from the origin. To avoid this issue, translate the coordinates to a location closer to the origin before performing the operation. Then, undo the translation after completing the operation. For example:

  [x,y] = polybool(flag,x1-xt,y1-yt,x2-xt,y2-yt);

  x = x+xt;

  y = y+yt;

Version History

Introduced before R2006a

R2018a: polybool is not recommended

The polybool function is not recommended.

Starting in R2025a, use a shape object and the intersect, union, subtract, or xor function, instead.

To update your code, first create polygon shape objects from the input coordinates. Create polygon shape objects in planar map coordinates by using the mappolyshape function, and create polygon shape objects in geographic coordinates by using the geopolyshape function. Then, replace uses of the polybool function with the intersect, union, subtract, or xor function.

This table shows replacement patterns for polygon shape objects in planar map coordinates.

Not Recommended	Recommended
[x,y] = polybool("intersection",x1,y1,x2,y2)	shape1 = mappolyshape(x1,y1); shape2 = mappolyshape(x2,y2); shapeout = intersect(shape1,shape2);
[x,y] = polybool("union",x1,y1,x2,y2)	shape1 = mappolyshape(x1,y1); shape2 = mappolyshape(x2,y2); shapeout = union(shape1,shape2);
[x,y] = polybool("subtraction",x1,y1,x2,y2)	shape1 = mappolyshape(x1,y1); shape2 = mappolyshape(x2,y2); shapeout = subtract(shape1,shape2);
[x,y] = polybool("xor",x1,y1,x2,y2)	shape1 = mappolyshape(x1,y1); shape2 = mappolyshape(x2,y2); shapeout = xor(shape1,shape2);

Unlike the polybool function, which represents the output using numeric coordinates, the intersect, union, subtract, and xor functions represent the output using polygon shape objects. Shape objects enable you to:

• Query properties that store the number of polygon regions, the number of polygon holes, and the coordinate reference system associated with the polygon.

• Examine and modify the shapes by using functions such as area, perimeter, geoclip, and mapclip.

• Plot data on geographic or map axes by using the geoplot function.

Before R2025a, use a polyshape object and the intersect, union, subtract, or xor function, instead. You can get the vertex coordinates of a polyshape boundary by using the boundary function. Note that the boundary function might return polygon vertices in a different order than the polybool function.