geoclip

Clip geographic shape to latitude-longitude limits or polygon

Since R2022a

Syntax

clipped = geoclip(shape,latlim,lonlim)

clipped = geoclip(shape,clipperPolygon)

Description

clipped = geoclip(shape,latlim,lonlim) clips the specified geographic point, line, or polygon shapes to the specified latitude and longitude limits. Specify the shapes using shape, the latitude limits using latlim, and the longitude limits using lonlim.

To crop raster data that is represented by an array and a geographic raster reference object, use the geocrop function instead.

clipped = geoclip(shape,clipperPolygon) clips the shapes to the specified clipper polygon. (since R2024b)

Examples

Clip Geographic Shapes to Latitude-Longitude Limits

Read worldwide land areas as a geospatial table. Extract the polygon shapes.

land = readgeotable("landareas.shp");
shape = land.Shape

shape=537×1 geopolyshape array with properties:
              NumRegions: [537x1 double]
                NumHoles: [537x1 double]
                Geometry: "polygon"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1x1 geocrs]
      ⋮

Specify the latitude and longitude limits for an area containing part of Asia. Then, clip the shapes.

latlim = [4 42];
lonlim = [65 130];
clipped = geoclip(shape,latlim,lonlim);

Display the clipped shapes on a map with no basemap. Display the bounding box as a rectangle.

figure
geobasemap none
hold on
geoplot(clipped)
geoplot(latlim([1 2 2 1 1]),lonlim([1 1 2 2 1]),"k")

Clip Geographic Shape to Polygon

Since R2024b

Read the locations of world cities as a geospatial table. The table represents the cities using point shapes in geographic coordinates. Extract the point shapes.

cities = readgeotable("worldcities.shp");
shape = cities.Shape

shape = 
  318×1 geopointshape array with properties:

               NumPoints: [318×1 double]
                Latitude: [318×1 double]
               Longitude: [318×1 double]
                Geometry: "point"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1×1 geocrs]

Specify the clipper polygon. Create a geospatial table that contains a point shape object for Detroit. Then, define an area of interest (AOI) by creating a circle with a radius of 8 degrees that is centered on the point shape.

detroit = geocode("Detroit","city");
clipperPolygon = aoicircle(detroit,8);

Verify that the city locations and the clipper polygon use the same geographic coordinate reference system (CRS).

isequal(shape.GeographicCRS,clipperPolygon.GeographicCRS)

ans = logical
   1

Clip the city locations to the AOI.

clipped = geoclip(shape,clipperPolygon);

Create a map that displays the clipped city locations and the AOI.

figure
geoplot(clipped,MarkerSize=15)
hold on
geoplot(clipperPolygon,FaceColor="none")

Remove Shapes with No Coordinate Data from Output

Read the names and locations of world cities as a geospatial table. Extract the point shapes.

cities = readgeotable("worldcities.shp");
shape = cities.Shape

shape = 
  318x1 geopointshape array with properties:

               NumPoints: [318x1 double]
                Latitude: [318x1 double]
               Longitude: [318x1 double]
                Geometry: "point"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1x1 geocrs]

Specify the latitude and longitude limits for an area containing part of Asia. Then, clip the shapes.

latlim = [4 42];
lonlim = [65 130];
clipped = geoclip(shape,latlim,lonlim);

When a point shape lies outside the specified limits, the clipped shape has no coordinate data and the NumPoints property is 0. Remove shapes with no coordinate data from the clipped shapes.

idx = clipped.NumPoints ~= 0;
clipped = clipped(idx)

clipped = 
  57x1 geopointshape array with properties:

               NumPoints: [57x1 double]
                Latitude: [57x1 double]
               Longitude: [57x1 double]
                Geometry: "point"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1x1 geocrs]

When a line or polygon shape has no coordinate data, its respective NumParts or NumRegions property is 0.

Shift Longitude Limits

Create a line shape in geographic coordinates from global coastline data. The longitude coordinates are in the range of –180 to 180 degrees.

load coastlines
coast = geolineshape(coastlat,coastlon)

coast = 
  geolineshape with properties:

                NumParts: 241
                Geometry: "line"
    CoordinateSystemType: "geographic"
           GeographicCRS: []

Shift the longitude coordinates so they are in the range of 0 to 360 degrees.

coastShift = geoclip(coast,[-90 90],[0 360]);

Display the shifted line shape on a map.

figure
geobasemap none
hold on
geoplot(coastShift)

Input Arguments

shape — Shape

geopointshape, geolineshape, or geopolyshape object | array of geopointshape, geolineshape, or geopolyshape objects

Shape, specified as a geopointshape, geolineshape, or geopolyshape object or as an array of geopointshape, geolineshape, or geopolyshape objects. When you specify an array, you can include a combination of point, line, and polygon shape objects.

latlim — Latitude limits

two-element vector

Latitude limits, specified as a two-element vector of the form [slat nlat], where slat is the southern limit in degrees and nlat is the northern limit in degrees.

lonlim — Longitude limits

two-element vector

Longitude limits, specified as a two-element vector of the form [wlon elon], where wlon is the western limit in degrees and elon is the eastern limit in degrees.

clipperPolygon — Clipper polygon

geopolyshape object

Since R2024b

Clipper polygon, specified as a geopolyshape object.

The GeographicCRS properties of clipperPolygon and shape must be equal, unless one of the GeographicCRS properties is empty.

The geoclip function assumes that the boundaries of the clipper polygon follow linear paths. When you create the clipper polygon by using the geopolyshape function, you can interpolate the input vertices so that the boundaries follow great circle paths by using the interpm function.

Output Arguments

clipped — Clipped shape

geopointshape, geolineshape, or geopolyshape object | array of geopointshape, geolineshape, or geopolyshape objects

Clipped shape, returned as a geopointshape, geolineshape, or geopolyshape object or as an array of geopointshape, geolineshape, or geopolyshape objects.

clipped has the same type and size as shape.

If an element of shape lies completely outside the specified limits, then the corresponding element of clipped does not contain coordinate data. When a point, line, or polygon shape does not contain coordinate data, its respective NumPoints, NumParts, or NumRegions property is 0.

Tips

• If you clip a shape within a geospatial table, the function does not modify any attributes of the table.

• If you do not know the latitude and longitude limits you want, you can open and explore a geographic axes by using the geoaxes function. Return the limits of the axes by using the geolimits function or interactively select the southwest and northeast corners of a bounding box by using the ginput function.

Version History

Introduced in R2022a

R2024b: Clip shape objects to polygon

Clip point, line, and polygon shape objects to a polygon shape.