subtract

R2026b

Boolean subtraction of geometries

Since R2025a

Syntax

g3 = subtract(g1,g2)

Description

g3 = subtract(g1,g2) subtracts the geometry g2 from the geometry g1 and returns the combined geometry g3. If g2 is a vector of geometries, the function subtracts all geometries specified by g2 from the geometry g1.

All geometries must be either 2-D or 3-D. The function does not support a mix of 2-D and 3-D geometries.

Examples

Create Sphere with Cutout Piece

Cut out a quarter of a sphere by subtracting a cube from the sphere.

Create and plot a geometry of a sphere.

gsphere = multisphere(5);
pdegplot(gsphere)

Create and plot a geometry of a cuboid.

gcube = multicuboid(5,5,10);
gcube = translate(gcube,[2.5 -2.5 -5]);
figure
pdegplot(gcube)

Convert both geometries to fegeometry objects.

gsphere = fegeometry(gsphere);
gcube = fegeometry(gcube);

Subtract the cuboid from the sphere by using the Boolean subtraction operation.

g = subtract(gsphere,gcube);

Plot the resulting geometry with cell labels.

figure
pdegplot(g,CellLabels="on",FaceAlpha=0.3)

Subtract Cube from Sphere

Subtract a cube from a larger sphere by using the Boolean subtraction operation.

Create and plot a geometry of a sphere.

gsphere = multisphere(5);
pdegplot(gsphere)

Create and plot a geometry of a cube.

gcube = multicuboid(6,6,6,Zoffset=-3);
figure
pdegplot(gcube)

Convert both geometries to fegeometry objects.

gsphere = fegeometry(gsphere);
gcube = fegeometry(gcube);

Subtract the cube from the sphere by using the Boolean subtraction operation.

g = subtract(gsphere,gcube);

Plot the resulting geometry with cell labels.

figure
pdegplot(g,CellLabels="on",FaceAlpha=0.3)

Subtract Multiple Geometries

Since R2026a

Cut out multiple cubes from a cylinder.

Create geometries representing a cylinder and a unit cube.

gmcyl = fegeometry(multicylinder(1,1));
gmcube = fegeometry(multicuboid(1,1,1));

Create a vector of geometries by rotating the cube by 30 and 60 degrees.

angle = [0 30 60];
for k = 1:numel(angle)
    gv(k) = rotate(gmcube,angle(k));
end

Subtract the resulting vector of geometries from the cylinder.

gm = subtract(gmcyl,gv);

Plot the result.

pdegplot(gm)

Subtract Circle from Cardioid

Since R2026b

Subtract a circle from a larger cardioid by using the Boolean subtraction operation.

Create and plot a geometry of a cardioid.

gcard = fegeometry(@cardg);
pdegplot(gcard)

Create and plot a geometry of a circle.

gcircle = fegeometry(@circleg);
pdegplot(gcircle)

Subtract the circle from the cardioid by using the Boolean subtraction operation.

g = subtract(gcard,gcircle);

Plot the resulting geometry with face labels.

pdegplot(g,FaceLabels="on")

Input Arguments

g1 — Geometry

fegeometry object | DiscreteGeometry object | AnalyticGeometry object

Geometry, specified as an fegeometry object, DiscreteGeometry object, or AnalyticGeometry object.

g2 — Geometries to subtract

fegeometry object | DiscreteGeometry object | AnalyticGeometry object | vector of fegeometry objects | vector of DiscreteGeometry objects | vector of AnalyticGeometry objects

Geometry, specified as an fegeometry object, DiscreteGeometry object, AnalyticGeometry object, or a vector of fegeometry, DiscreteGeometry, or AnalyticGeometry objects.

Output Arguments

g3 — Combined geometry

fegeometry object

Combined geometry, returned as an fegeometry object. Note that subtract returns an fegeometry object when input arguments are AnalyticGeometry or DiscreteGeometry objects.

Tips

• When creating a 3-D geometry, subtract uses the default threshold of 44 degrees for the dihedral angle between adjacent triangles. If the angle between the triangles exceeds the threshold, the edge becomes a topological (feature) edge separating two faces. If the angle does not exceed the threshold, subtract does not create a topological edge with two separate faces, unless the function can create the edge based on other criteria. Instead, subtract creates one face.

  To use a different feature angle value, create a triangulation object from the resulting geometry g3, and then convert the object back to an fegeometry object. Set the value of the FeatureAngle argument as a number between 10 and 90. The specified FeatureAngle value represents degrees.

  tr = triangulation(g3);
  g3 = fegeometry(tr,FeatureAngle=15)

  The triangulation function accepts only single-domain geometries, so g3 must have one cell.

• Boolean operations on AnalyticGeometry or DiscreteGeometry objects return an fegeometry object.

Version History

Introduced in R2025a

R2026b: Subtract 2-D geometries

The subtract function accepts 2-D geometries. All geometries must be either 2-D or 3-D. The function does not support a mix of 2-D and 3-D geometries.

R2026a: Subtract several geometries

The subtract function subtracts a vector of 3-D geometries from a 3-D geometry.