union

Union of shapes in geographic or planar coordinates

Since R2025a

collapse all in page

    Syntax

    shapeout = union(shape1)
    shapeout = union(shape1,shape2)

    Description

    shapeout = union(shape1) calculates the geometric union of the specified point, line, or polygon shapes.

    • When you specify point shapes, the union is a point shape that contains all the points in shape1.

    • When you specify line shapes, the union is a line shape that contains all the line parts in shape1.

    • When you specify polygon shapes, the union is a polygon shape that combines the polygon regions in shape1.

    example

    shapeout = union(shape1,shape2) calculates element-wise unions of the shapes in shape1 and shape2.

    example

    Examples

    collapse all

    Open Live Script

    Read a shapefile of world rivers into the workspace as a geospatial table. The table represents the rivers using line shapes in geographic coordinates. Extract the line shapes. 

    rivers = readgeotable("worldrivers.shp");
shape1 = rivers.Shape
    shape1=128×1 geolineshape array with properties:
                NumParts: [128×1 double]
                Geometry: "line"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1×1 geocrs]
      ⋮

    Calculate the union of the line shapes. The result is a scalar line shape in geographic coordinates. 

    shapeout = union(shape1)
    shapeout = 
  geolineshape with properties:

                NumParts: 130
                Geometry: "line"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1×1 geocrs]
    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 a vector of polygon shapes by buffering the point shapes. 

    subGT = geocode(["BEACON HILL","COPPS HILL"],GT);
shape1 = buffer(subGT.Shape,1000)
    shape1=2×1 mappolyshape array with properties:
              NumRegions: [2×1 double]
                NumHoles: [2×1 double]
                Geometry: "polygon"
    CoordinateSystemType: "planar"
            ProjectedCRS: [1×1 projcrs]

    Display the polygon shapes on a map. 

    figure
geoplot(shape1)

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

    shapeout = union(shape1)
    shapeout = 
  mappolyshape with properties:

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

    Display the union on a new map. 

    figure
geoplot(shapeout)

    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 unions of the polygon shapes. The result is a two-element vector of polygon shapes.

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

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

    shapeout = union(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 unions on a new map. Note that the union function did not calculate the union of the polygon shapes for Melbourne and Sydney. 

    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

    If you specify both shape1 and shape2 as input to the union function, then 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

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

    When you specify only shape1, the shapeout argument is a scalar. When you specify both shape1 and shape2, 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 the input shape or shapes. For example, if shape1 and shape2 contain maplineshape objects, then shapeout also contains maplineshape objects.

    Version History

    Introduced in R2025a

    See Also

    Functions

    Objects