Main Content

mapclip

Clip shape to xy-limits in planar coordinates

    Description

    example

    clipped = mapclip(shape,xlimits,ylimits) clips the planar point, line, or polygon shapes in shape to the xy-limits in xlimits and ylimits.

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

    Examples

    collapse all

    Read hydrography data as a geospatial table. Extract the polygon shape for a pond.

    hydro = readgeotable("concord_hydro_area.shp");
    shape = hydro.Shape(14)
    shape = 
      mappolyshape with properties:
    
                  NumRegions: 1
                    NumHoles: 3
                    Geometry: "polygon"
        CoordinateSystemType: "planar"
                ProjectedCRS: [1×1 projcrs]
    
    

    Specify the xy-limits and clip the shape.

    xlimits = [207736  208212];
    ylimits = [912283  912636];
    clipped = mapclip(shape,xlimits,ylimits);

    Display the shape and the clipped shape on a map.

    figure
    geoplot(shape)
    hold on
    geoplot(clipped)

    Read the names and locations of places in Boston as a geospatial table. Extract the point shapes.

    places = readgeotable("boston_placenames.shp");
    shape = places.Shape
    shape = 
      13x1 mappointshape array with properties:
    
                   NumPoints: [13x1 double]
                           X: [13x1 double]
                           Y: [13x1 double]
                    Geometry: "point"
        CoordinateSystemType: "planar"
                ProjectedCRS: [1x1 projcrs]
    
    

    Specify the xy-limits and clip the shapes.

    xlimits = [235226 237174];
    ylimits = [900179 901059];
    clipped = mapclip(shape,xlimits,ylimits);

    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 = 
      5x1 mappointshape array with properties:
    
                   NumPoints: [5x1 double]
                           X: [5x1 double]
                           Y: [5x1 double]
                    Geometry: "point"
        CoordinateSystemType: "planar"
                ProjectedCRS: [1x1 projcrs]
    
    

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

    If your shape is in projected coordinates and your limits are in geographic coordinates, then you must project the geographic coordinates before clipping the shape. To use this approach:

    • You must know the projected coordinate reference system (CRS) for the shape. You can determine whether a shape object is associated with a projected CRS by querying the ProjectedCRS property.

    • The projection method for the CRS must result in x-coordinates and y-coordinates that run approximately west-to-east and south-to-north, respectively, such as transverse Mercator or Lambert Conic Conformal. This approach is not valid for projection methods such as polar stereographic. You can find the projection method for a projected CRS object by querying the ProjectionMethod property.

    Read road data for an area in Boston as a geospatial table. Extract the line shapes.

    roads = readgeotable("boston_roads.shp");
    shape = roads.Shape
    shape=2795×1 object
      16×1 maplineshape array with properties:
    
                    NumParts: [16×1 double]
                    Geometry: "line"
        CoordinateSystemType: "planar"
                ProjectedCRS: [1×1 projcrs]
          ⋮
    
    

    Verify that the shape has a projected CRS with an appropriate projection method.

    crs = shape.ProjectedCRS
    crs = 
      projcrs with properties:
    
                        Name: "NAD83 / Massachusetts Mainland"
               GeographicCRS: [1×1 geocrs]
            ProjectionMethod: "Lambert Conic Conformal (2SP)"
                  LengthUnit: "meter"
        ProjectionParameters: [1×1 map.crs.ProjectionParameters]
    
    

    Specify the latitude and longitude limits using geographic coordinates. Project the latitude and longitude limits to xy-limits by using the projected CRS and the projfwd function.

    latlim = [42.3494 42.3614];
    lonlim = [-71.0766 -71.0571];
    [xlimits,ylimits] = projfwd(crs,latlim,lonlim);

    Clip the shapes.

    clipped = mapclip(shape,xlimits,ylimits);

    Display the clipped shapes on a map. Compare the limits you specified with the limits of the plot by setting the tick format to decimal degrees.

    figure
    geoplot(clipped)
    geotickformat("dd")

    Input Arguments

    collapse all

    Shape, specified as a mappointshape, maplineshape, or mappolyshape object or as an array of mappointshape, maplineshape, or mappolyshape objects. When you specify an array, you can include a combination of point, line, and polygon shape objects.

    x-limits, specified as a two-element vector of the form [xmin xmax], where xmax is greater than xmin.

    The units of xlimits must match the units of shape. If the ProjectedCRS property of shape contains a projcrs object, you can find the units by querying the LengthUnit property of the projcrs object, for example shape.ProjectedCRS.LengthUnit.

    y-limits, specified as a two-element vector of the form [ymin ymax], where ymax is greater than ymin.

    The units of ylimits must match the units of shape. If the ProjectedCRS property of shape contains a projcrs object, you can find the units by querying the LengthUnit property of the projcrs object, for example shape.ProjectedCRS.LengthUnit.

    Output Arguments

    collapse all

    Clipped shape, returned as a mappointshape, maplineshape, or mappolyshape object or as an array of mappointshape, maplineshape, or mappolyshape 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.

    Version History

    Introduced in R2022a

    See Also

    Functions

    Objects