subtract

Difference of shapes in geographic or planar coordinates

Since R2025a

collapse all in page

    Syntax

    shapeout = subtract(shape1,shape2)

    Description

    shapeout = subtract(shape1,shape2) calculates the geometric difference of the specified point, line, or polygon shapes by comparing the shapes in shape1 to the shapes in shape2. The function calculates element-wise differences.

    • When you specify point shapes, the difference is a point shape that contains the points in shape1 that are not in shape2.

    • When you specify line shapes, the difference is a line shape that contains the line parts in shape1 that are not in shape2.

    • When you specify polygon shapes, the difference is a polygon shape that contains the polygon regions in shape1 that are not in shape2.

    example

    Examples

    collapse all

    Open Live Script

    Read a shapefile containing the coordinates of locations in Boston as a geospatial table. The table represents the locations using point shapes in planar coordinates. 

    GT = readgeotable("boston_placenames.shp");

    Create a subtable that contains two table rows. Then, create two polygon shapes by buffering the point shapes. 

    subGT = geocode(["BEACON HILL","COPPS HILL"],GT);
buffered = buffer(subGT.Shape,1000);

shape1 = buffered(1);
shape2 = buffered(2);

    Display the polygon shapes on a map. 

    figure
geoplot([shape1 shape2])

    Figure contains an axes object with type geoaxes. The geoaxes object contains an object of type polygon.

    Prepare to display the difference of the polygon shapes on a similar map by getting the limits of the current map. 

    [latlim,lonlim] = geolimits;

    Calculate the difference of the polygon shapes. The result is a scalar polygon shape in planar coordinates. 

    shapeout = subtract(shape1,shape2)
    shapeout = 
  mappolyshape with properties:

              NumRegions: 1
                NumHoles: 0
                Geometry: "polygon"
    CoordinateSystemType: "planar"
            ProjectedCRS: [1×1 projcrs]

    Display the difference on a new map.

    figure
geoplot(shapeout)
geolimits(latlim,lonlim)

    Figure contains an axes object with type geoaxes. The geoaxes object contains an object of type polygon.

    Open Live Script

    Create two vectors of polygon shapes in geographic coordinates.

    • The first vector contains polygon shapes that buffer the cities of Adelaide and Brisbane.

    • The second vector contains polygon shapes that buffer the cities of Melbourne and Sydney. 

    GT1 = geocode(["Adelaide","Brisbane"]);
shape1 = buffer(GT1.Shape,6);

GT2 = geocode(["Melbourne","Sydney"]);
shape2 = buffer(GT2.Shape,3.5);

    Display the polygon shapes on a map. 

    figure
geoplot([shape1; shape2])

    Calculate the element-wise differences of the polygon shapes. The result is a two-element vector of polygon shapes.

    • The first polygon shape is the difference of the polygon shapes for Adelaide and Melbourne.

    • The second polygon shape is the difference of the polygon shapes for Brisbane and Sydney. 

    shapeout = subtract(shape1,shape2)
    shapeout=2×1 geopolyshape array with properties:
              NumRegions: [2×1 double]
                NumHoles: [2×1 double]
                Geometry: "polygon"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1×1 geocrs]

    Display the differences on a new map.

    figure
geoplot(shapeout)

    Input Arguments

    collapse all

    Input shapes, specified as one of these options:

    • Array of geopointshape objects — Point shapes in geographic coordinates

    • Array of geolineshape objects — Line shapes in geographic coordinates

    • Array of geopolyshape objects — Polygon shapes in geographic coordinates

    • Array of mappointshape objects — Point shapes in planar coordinates

    • Array of maplineshape objects — Line shapes in planar coordinates

    • Array of mappolyshape objects — Polygon shapes in planar coordinates

    shape1 and shape2 must share these characteristics:

    • The geometric types of shape1 and shape2 must match. For example, if shape1 is a polygon, then shape2 must also be a polygon. You can find the geometric type of a shape object by querying the Geometry property.

    • The coordinate system types of shape1 and shape2 must match. For example, if shape1 is in geographic coordinates, then shape2 must also be in geographic coordinates. You can find the coordinate system type of a shape object by querying the CoordinateSystemType property.

    • The coordinate reference systems (CRSs) of shape1 and shape2 must match, unless one of shape1 or shape2 is not associated with a CRS. For a shape object in geographic coordinates, you can find the CRS by querying the GeographicCRS property. For a shape object in planar coordinates, you can find the CRS by querying the ProjectedCRS property.

    • The sizes of shape1 and shape2 must be compatible. For more information about compatible array sizes, see Compatible Array Sizes for Basic Operations.

    Output Arguments

    collapse all

    Difference of the shapes, returned as an array of geopointshape, geolineshape, geopolyshape, mappointshape, maplineshape, or mappolyshape objects.

    The size of shapeout depends on the sizes of shape1 and shape2. For more information about array sizes, see Compatible Array Sizes for Basic Operations.

    The geometric type and coordinate system of shapeout matches the geometric type and coordinate system of shape1 and shape2. For example, if shape1 and shape2 contain maplineshape objects, then shapeout also contains maplineshape objects.

    Version History

    Introduced in R2025a

    See Also

    Functions

    Objects