buffer

Buffer shape in geographic or planar coordinates

Since R2024b

Syntax

buffered = buffer(shape,dist)

buffered = buffer(shape,dist,Direction=direction)

Description

buffered = buffer(shape,dist) creates a polygon shape that buffers the input point, line, or polygon shape by the specified distance. The function creates the polygon shape by calculating the union of circles that are centered on vertices of the input shape and that have radius dist. By default, the function outwardly buffers the shape.

buffered = buffer(shape,dist,Direction=direction) specifies the buffer direction. This syntax requires the input shapes to be polygons.

Examples

Buffer Shapes in Geographic Coordinates

Create a geospatial table containing a shape object for Australia. The table represents Australia using a polygon shape in geographic coordinates. Extract the polygon shape.

australia = geocode("australia");
shape = australia.Shape

shape = 
  geopolyshape with properties:

              NumRegions: 1
                NumHoles: 0
                Geometry: "polygon"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1x1 geocrs]

For shapes in geographic coordinates, the buffer distance units must match the angle unit of the geographic coordinate reference system (CRS) associated with the shape. Find the angle unit. The result indicates that the buffer distance must be in degrees.

shape.GeographicCRS.AngleUnit

ans = 
"degree"

Buffer the polygon shape by 2 degrees.

buffered = buffer(shape,2);

Create a map that displays the buffered shape and the outline of the original polygon.

figure
geobasemap none
geoplot(buffered)
hold on
geoplot(shape,LineWidth=2,FaceColor="none")

Buffer Shapes in Planar Coordinates

Read road data for an area in Concord, MA as a geospatial table. The table represents the roads using line shapes in planar coordinates. Create a subtable containing the line shapes for two named roads. Then, extract the line shapes.

roads = readgeotable("concord_roads.shp");

idx = ismember(roads.STREETNAME,["SOUTHFIELD CIRCLE","RIVERDALE ROAD"]);
subroads = roads(idx,:);

shape = subroads.Shape

shape=4×1 maplineshape array with properties:
                NumParts: [4×1 double]
                Geometry: "line"
    CoordinateSystemType: "planar"
            ProjectedCRS: [1×1 projcrs]

For shapes in planar coordinates, the buffer distance units must match the length unit of the projected CRS associated with the shape. Find the length unit. The result indicates that the buffer distance must be in meters.

shape.ProjectedCRS.LengthUnit

ans = 
"meter"

Buffer the line shapes by 15 meters.

buffered = buffer(shape,15);

Create a map that displays the buffered shapes and the original lines. The overlapping buffered shapes indicate that the road consists of multiple line shapes.

figure
geoplot(buffered)
hold on
geoplot(shape,LineWidth=2)

Specify Buffer Distance for Each Shape

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. Extract the point shapes.

places = readgeotable("boston_placenames.shp");
shape = places.Shape

shape = 
  13×1 mappointshape array with properties:

               NumPoints: [13×1 double]
                       X: [13×1 double]
                       Y: [13×1 double]
                Geometry: "point"
    CoordinateSystemType: "planar"
            ProjectedCRS: [1×1 projcrs]

Find the length unit to use for the buffer distances. The result indicates that the buffer distances must be in meters.

shape.ProjectedCRS.LengthUnit

ans = 
"meter"

For each shape, specify a random buffer distance between 100 meters and 400 meters. Then, buffer the point shapes.

sz = size(shape);
dist = 100 + (400-100)*rand(sz);
buffered = buffer(shape,dist);

Create a map that displays the buffered shapes and the original point shapes.

figure
geoplot(buffered)
hold on
geoplot(shape)

Inwardly Buffer Polygon Shapes

Read a shapefile containing hydrographic data for Concord, MA as a geospatial table. The table represents the data using polygon shapes in planar coordinates. Create a subtable containing the polygon shape for a pond. Then, extract the polygon shapes.

hydro = readgeotable("concord_hydro_area.shp");
pond = hydro(14,:);
shape = pond.Shape

shape = 
  mappolyshape with properties:

              NumRegions: 1
                NumHoles: 3
                Geometry: "polygon"
    CoordinateSystemType: "planar"
            ProjectedCRS: [1x1 projcrs]

Find the length unit to use for the buffer distance. The result indicates that the buffer distance must be in meters.

shape.ProjectedCRS.LengthUnit

ans = 
"meter"

Inwardly buffer the polygon shape by 20 meters by specifying the Direction name-value argument.

buffered = buffer(shape,20,Direction="in");

Create a map that uses the projected CRS associated with the shape. Then, display the buffered polygon and the outline of the original polygon.

figure
newmap(shape.ProjectedCRS)
geoplot(buffered)
hold on
geoplot(shape,LineWidth=2,FaceColor="none")

Input Arguments

shape — Shape

array of geopointshape, geolineshape, or geopolyshape objects | array of mappointshape, maplineshape, or mappolyshape objects

Shape, specified as one of these options:

• An array of geopointshape, geolineshape, or geopolyshape objects — Point, line, or polygon shapes in geographic coordinates.

• An array of mappointshape, maplineshape, or mappolyshape objects — Point, line, or polygon shapes in planar coordinates.

For each option, you can include a combination of point, line, and polygon shapes. You can also specify this argument as a scalar point, line, or polygon shape.

dist — Buffer distance

nonnegative scalar | array of nonnegative scalars

Buffer distance, specified as one of these options:

• A nonnegative scalar — Use the same buffer distance for all the shape objects.

• An array of nonnegative scalars — Use a different buffer distance for each shape object. The size of dist must match the size of shape.

The units you use to specify dist and the way the buffer function interprets dist depends on the type of shape.

Type of Shape Object	Units	Interpretation
geopointshape, geolineshape, and geopolyshape objects	Specify dist using degrees. The value you specify must be less than or equal to 90.	dist is a spherical distance along a great circle or geodesic path.
mappointshape, maplineshape, and mappolyshape objects	Specify dist using the length unit of the projected CRS for the shape. To find the length unit, get the projcrs object for the shape by querying the ProjectedCRS property of the shape object. Then, query the LengthUnit property of the projcrs object. For a shape, shp, the length unit is shp.ProjectedCRS.LengthUnit.	dist is a linear distance along the Cartesian plane.

direction — Buffer direction

"out" (default) | "in"

Buffer direction, specified as one of these options:

• "out" — Outwardly buffer the shape.

• "in" — Inwardly buffer the shape.

To use this argument, the shape argument must contain only geopolyshape or mappolyshape objects.

If you inwardly buffer a polygon shape using a buffer distance that shrinks the polygon to nothing, then the output polygon shape has no coordinate data and its NumPoints property is 0.

Output Arguments

buffered — Buffered shape

array of geopolyshape objects | array of mappolyshape objects

Buffered shape, returned as one of these options:

• An array of geopolyshape objects, when shape contains shapes in geographic coordinates.

• An array of mappolyshape objects, when shape contains shapes in planar coordinates.

The size of buffered matches the size of shape.

Version History

Introduced in R2024b