linelength

Length of line shape in geographic or planar coordinates

Since R2024a

collapse all in page

    Syntax

    len = linelength(shape)

    Description

    len = linelength(shape) calculates the length of a line shape, which is the sum of the lengths of the lines that comprise the shape.

    example

    Examples

    collapse all

    Open Live Script

    Read world rivers into the workspace as a geospatial table. Extract the line shapes. 

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

    Calculate the lengths of the line shapes.

    len = linelength(shape);

    The units depend on the geographic coordinate reference system (CRS) for the shape. Find the length unit for the geographic CRS. The result indicates that the line lengths are in meters. 

    shape.GeographicCRS.Spheroid.LengthUnit
    ans = 
'meter'

    Include the line lengths in the geospatial table by creating a new table variable. Sort the rows of the table in descending order by Length. Then, view the first eight rows of the table by using the head function. Note that, because the worldrivers.shp file stores information about some rivers using multiple line shapes, the line lengths reported in the first eight rows of the table might not reflect the total lengths of the named rivers. 

    rivers.Length = len;
rivers = sortrows(rivers,"Length","descend");
head(rivers)
           Shape               Name              Length  
    ____________    ___________________    __________

    geolineshape    "Nile - White Nile"    4.2573e+06
    geolineshape    "Mekong"               3.9981e+06
    geolineshape    "Yangtze"              3.3539e+06
    geolineshape    "Yellow"               3.1722e+06
    geolineshape    "Niger"                3.0812e+06
    geolineshape    "Missouri"             2.9331e+06
    geolineshape    "Indus"                2.5962e+06
    geolineshape    "Brahmaputra"          2.5607e+06
    Open Live Script

    Read hydrographic data for Concord, MA into the workspace as a geospatial table. Extract the line shapes. 

    hydro = readgeotable("concord_hydro_line.shp");
shape = hydro.Shape
    shape=237×1 maplineshape array with properties:
                NumParts: [237×1 double]
                Geometry: "line"
    CoordinateSystemType: "planar"
            ProjectedCRS: [1×1 projcrs]
      ⋮

    Calculate the lengths of the line shapes. 

    len = linelength(shape);

    The units depend on the projected coordinate reference system (CRS) for the shape. Find the length unit for the projected CRS. The result indicates that the line lengths are in meters. 

    shape.ProjectedCRS.LengthUnit
    ans = 
"meter"

    Create a new geospatial table from the shape objects and the line lengths. View the first eight rows of the table by using the head function. 

    hydro_length = table(shape,len,VariableNames=["Shape","Length"]);
head(hydro_length)
           Shape        Length
    ____________    ______

    maplineshape     86.53
    maplineshape    137.36
    maplineshape    151.86
    maplineshape    32.875
    maplineshape    70.196
    maplineshape    109.87
    maplineshape    117.55
    maplineshape    59.693

    Input Arguments

    collapse all

    Line shape, specified as a geolineshape object, a maplineshape object, an array of geolineshape objects, or an array of maplineshape objects.

    Output Arguments

    collapse all

    Line length, returned as an array. The size of len matches the size of shape.

    The units of len depend on the type of line shape.

    • When shape contains geolineshape objects, the length unit of the reference ellipsoid for the shape determines the units. To find the length unit, get the geocrs object for the shape by querying the GeographicCRS property of the shape object. Then, get the ellipsoid by querying the Spheroid property of the geocrs object. If the ellipsoid is a referenceEllipsoid or referenceSphere object, then query the LengthUnit property of the ellipsoid. For a shape shp, the length unit is shp.GeographicCRS.Spheroid.LengthUnit. If the GeographicCRS property of the object is empty, the function calculates the line length using the WGS84 reference ellipsoid and a length unit of meters.

    • When shape contains maplineshape objects, the length unit of the projected coordinate reference system for the shape determines the units. 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.

    When shape contains geolineshape objects, the linelength function calculates the line lengths using geodesics.

    Data Types: double

    Tips

    The accuracy of the linelength function depends on the resolution of the data used to create the lines. As a result, the function can return different results when you use line shapes from different data sets as inputs.

    Version History

    Introduced in R2024a

    See Also

    Functions

    Objects