Class: QgsLineString¶

Line string geometry type, with support for z-dimension and m-values.

Class Hierarchy¶

Base classes¶

`QgsCurve`	Abstract base class for curved geometry type.
`QgsAbstractGeometry`	Abstract base class for all geometries.

Abstract Methods

`curveToLine`	Returns a new line string geometry corresponding to a segmentized approximation of the curve.
`mAt`	Returns the m-coordinate of the specified node in the line string.
`sumUpArea`	Calculates the shoelace/triangle formula sum for the points in the linestring.
`xAt`	Returns the x-coordinate of the specified node in the line string.
`yAt`	Returns the y-coordinate of the specified node in the line string.
`zAt`	Returns the z-coordinate of the specified node in the line string.

Methods

`addVertex`	Adds a new vertex to the end of the line string.
`append`	Appends the contents of another line string to the end of this line string.
`calculateBoundingBox3d`	Calculates the minimal 3D bounding box for the geometry.
`close`	Closes the line string by appending the first point to the end of the line, if it is not already closed.
`collectDuplicateNodes`	Returns a list of any duplicate nodes contained in the geometry, within the specified tolerance.
`extend`	Extends the line geometry by extrapolating out the start or end of the line by a specified distance.
`interpolateM`	Returns a copy of this line with all missing (NaN) m values interpolated from m values of surrounding vertices.
`length3D`	Returns the length in 3D world of the line string.
`lineLocatePointByM`	Attempts to locate a point on the linestring by m value.
`measuredLine`	Re-write the measure ordinate (or add one, if it isn't already there) interpolating the measure between the supplied start and end values.
`pointN`	Returns the point at the specified index.
`setMAt`	Sets the m-coordinate of the specified node in the line string.
`setPoints`	Resets the line string to match the specified list of points.
`setXAt`	Sets the x-coordinate of the specified node in the line string.
`setYAt`	Sets the y-coordinate of the specified node in the line string.
`setZAt`	Sets the z-coordinate of the specified node in the line string.
`splitToDisjointXYParts`	Divides the linestring into parts that don't share any points or lines.

Virtual Methods

In PyQGIS, only methods marked as virtual can be safely overridden in a Python subclass of QgsLineString. See the FAQ for more details.

toCurveType

Returns the geometry converted to the more generic curve type QgsCompoundCurve

Static Methods

`fromBezierCurve`	Returns a new linestring created by segmentizing the bezier curve between start and end, with the specified control points.
`fromQPolygonF`	Returns a new linestring from a QPolygonF polygon input.

class qgis.core.QgsLineString[source]¶

Bases: QgsCurve

__init__(): Constructor for an empty linestring geometry.

__init__(points: Sequence[QgsPoint | QgsPointXY | Sequence[float]])

Construct a linestring from a sequence of points (QgsPoint objects, QgsPointXY objects, or sequences of float values).

The linestring Z and M type will be set based on the type of the first point in the sequence.

Added in version 3.20.

Parameters:: points (Sequence[Union[QgsPoint, QgsPointXY, Sequence[float]]])

__init__(segment: QgsLineSegment2D)

Construct a linestring from a single 2d line segment.

Added in version 3.2.

Parameters:: segment (QgsLineSegment2D)

__init__(x: Iterable[float], y: Iterable[float], z: Iterable[float] = [], m: Iterable[float] = [], is25DType: bool = False)

Construct a linestring from arrays of coordinates. If the z or m arrays are non-empty then the resultant linestring will have z and m types accordingly. This constructor is more efficient then calling setPoints() or repeatedly calling addVertex()

If the z vector is filled, then the geometry type will either be a LineStringZ(M) or LineString25D depending on the is25DType argument. If is25DType is True (and the m vector is unfilled) then the created Linestring will be a LineString25D type. Otherwise, the LineString will be LineStringZ (or LineStringZM) type.

If the sizes of x and y are non-equal then the resultant linestring will be created using the minimum size of these arrays.

Parameters:

x (Iterable[float])
y (Iterable[float])
z (Iterable[float] = [])
m (Iterable[float] = [])
is25DType (bool = False)

__init__(p1: QgsPoint, p2: QgsPoint)

Constructs a linestring with a single segment from p1 to p2.

Added in version 3.2.

Parameters:

p1 (QgsPoint)
p2 (QgsPoint)

__init__(a0: QgsLineString)

Parameters:: a0 (QgsLineString)

addVertex(self, pt: QgsPoint)[source]¶

Adds a new vertex to the end of the line string.

Parameters:: pt (QgsPoint) – vertex to add

append(self, line: QgsLineString | None)[source]¶

Appends the contents of another line string to the end of this line string.

Parameters:: line (Optional[QgsLineString]) – line to append. Ownership is not transferred.

calculateBoundingBox3d(self) → QgsBox3D[source]¶

Calculates the minimal 3D bounding box for the geometry.

See also

calculateBoundingBox()

Added in version 3.26.

Deprecated since version 3.34: Use calculateBoundingBox3D() instead.

Return type:: QgsBox3D

close(self)[source]¶: Closes the line string by appending the first point to the end of the line, if it is not already closed.

collectDuplicateNodes(self, epsilon: float = 4 * DBL_EPSILON, useZValues: bool = False) → List[QgsVertexId]¶

Returns a list of any duplicate nodes contained in the geometry, within the specified tolerance.

If useZValues is True then z values will also be considered when testing for duplicates.

Added in version 3.16.

Parameters:

epsilon (float = 4*DBL_EPSILON)
useZValues (bool = False)

Return type:

List[QgsVertexId]

abstract curveToLine(self, tolerance: float = M_PI_2 / 90, toleranceType: QgsAbstractGeometry.SegmentationToleranceType = QgsAbstractGeometry.MaximumAngle) → QgsLineString | None[source]¶

Returns a new line string geometry corresponding to a segmentized approximation of the curve.

Parameters:

tolerance (float = M_PI_2/90) – segmentation tolerance
toleranceType (QgsAbstractGeometry.SegmentationToleranceType = QgsAbstractGeometry.MaximumAngle) – maximum segmentation angle or maximum difference between approximation and curve

Return type:

Optional[QgsLineString]

extend(self, startDistance: float, endDistance: float)[source]¶

Extends the line geometry by extrapolating out the start or end of the line by a specified distance. Lines are extended using the bearing of the first or last segment in the line.

Parameters:

startDistance (float)
endDistance (float)

static fromBezierCurve(start: QgsPoint, controlPoint1: QgsPoint, controlPoint2: QgsPoint, end: QgsPoint, segments: int = 30) → QgsLineString | None¶

Returns a new linestring created by segmentizing the bezier curve between start and end, with the specified control points.

The segments parameter controls how many line segments will be present in the returned linestring.

Any z or m values present in the input coordinates will be interpolated along with the x and y values.

Added in version 3.10.

Parameters:

start (QgsPoint)
controlPoint1 (QgsPoint)
controlPoint2 (QgsPoint)
end (QgsPoint)
segments (int = 30)

Return type:

Optional[QgsLineString]

static fromQPolygonF(polygon: QPolygonF) → QgsLineString | None¶

Returns a new linestring from a QPolygonF polygon input.

Added in version 3.10.

Parameters:: polygon (QPolygonF)
Return type:: Optional[QgsLineString]

interpolateM(self, use3DDistance: bool = True) → QgsLineString | None¶

Returns a copy of this line with all missing (NaN) m values interpolated from m values of surrounding vertices.

If the line does not contain m values, None is returned.

The use3DDistance controls whether 2D or 3D distances between vertices should be used during interpolation. This option is only considered for lines with z values.

See also

lineLocatePointByM()

Added in version 3.38.

Parameters:: use3DDistance (bool = True)
Return type:: Optional[QgsLineString]

length3D(self) → float[source]¶

Returns the length in 3D world of the line string. If it is not a 3D line string, return its 2D length.

See also

length()

Added in version 3.10.

Return type:: float

lineLocatePointByM(self, m: float, use3DDistance: bool = True)[source]¶

Attempts to locate a point on the linestring by m value.

This method will linearly interpolate along line segments to find the point which corresponds to the specified m value.

If the linestring contains sections with constant m values matching m, then the interpolated point will be located at the center of these sections.

Any missing (NaN) values in the linestring will be linearly interpolated from the m values of surrounding vertices (see interpolateM()).

Parameters:

m (float) – target m value
use3DDistance (bool = True) -> (bool) – controls whether 2D or 3D distances between vertices should be used during interpolation. This option is only considered for lines with z values.

Returns:

True if a matching point was found, or False if it could not be found
x: interpolated x coordinate
y: interpolated y coordinate
z: interpolated z coordinate (for 3D lines only)
distanceFromStart: calculated distance from the start of the linestring to the located point

See also

interpolateM()

Added in version 3.40.

abstract mAt(self, index: int) → float[source]¶

Returns the m-coordinate of the specified node in the line string.

If the LineString does not have a m-dimension then NaN will be returned.

Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 corresponds to the last point in the line.

Raises:: IndexError – if no point with the specified index exists.
Parameters:: index (int)
Return type:: float

measuredLine(self, start: float, end: float) → QgsLineString | None¶

Re-write the measure ordinate (or add one, if it isn’t already there) interpolating the measure between the supplied start and end values.

Added in version 3.36.

Parameters:

start (float)
end (float)

Return type:

Optional[QgsLineString]

pointN(self, i: int) → QgsPoint[source]¶

Returns the point at the specified index.

Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 corresponds to the last point in the line.

Raises:: IndexError – if no point with the specified index exists.
Parameters:: i (int)
Return type:: QgsPoint

setMAt(self, index: int, m: float)[source]¶

Sets the m-coordinate of the specified node in the line string. The corresponding node must already exist in line string and the line string must have m-dimension.

Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 corresponds to the last point in the line.

Raises:: IndexError – if no point with the specified index exists.

See also

mAt()

Parameters:

index (int)
m (float)

setPoints(self, points: Iterable[QgsPoint])[source]¶

Resets the line string to match the specified list of points. The line string will inherit the dimensionality of the first point in the list.

Parameters:: points (Iterable[QgsPoint]) – new points for line string. If empty, line string will be cleared.

setXAt(self, index: int, x: float)[source]¶

Sets the x-coordinate of the specified node in the line string. The corresponding node must already exist in line string.

Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 corresponds to the last point in the line.

Raises:: IndexError – if no point with the specified index exists.

See also

xAt()

Parameters:

index (int)
x (float)

setYAt(self, index: int, y: float)[source]¶

Sets the y-coordinate of the specified node in the line string. The corresponding node must already exist in line string.

Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 corresponds to the last point in the line.

Raises:: IndexError – if no point with the specified index exists.

See also

yAt()

Parameters:

index (int)
y (float)

setZAt(self, index: int, z: float)[source]¶

Sets the z-coordinate of the specified node in the line string. The corresponding node must already exist in line string and the line string must have z-dimension.

Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 corresponds to the last point in the line.

Raises:: IndexError – if no point with the specified index exists.

See also

zAt()

Parameters:

index (int)
z (float)

splitToDisjointXYParts(self) → List[QgsLineString]¶

Divides the linestring into parts that don’t share any points or lines.

This method throws away Z and M coordinates.

The ownership of returned pointers is transferred to the caller.

Added in version 3.40.

Return type:: List[QgsLineString]

abstract sumUpArea(self) → float[source]¶

Calculates the shoelace/triangle formula sum for the points in the linestring. If the linestring is closed (i.e. a polygon) then the polygon area is equal to the absolute value of the sum. Please note that the sum will be negative if the points are defined in clockwise order. Therefore, if you want to use the sum as an area (as the method name indicates) then you probably should use the absolute value, since otherwise a bug can be introduced (such as the bug fixed for github issue 49578)

Return type:: float

virtual toCurveType(self) → QgsCompoundCurve | None[source]¶

Returns the geometry converted to the more generic curve type QgsCompoundCurve

Return type:: Optional[QgsCompoundCurve]
Returns:: the converted geometry. Caller takes ownership

abstract xAt(self, index: int) → float[source]¶

Returns the x-coordinate of the specified node in the line string.

Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 corresponds to the last point in the line.

Raises:: IndexError – if no point with the specified index exists.
Parameters:: index (int)
Return type:: float

abstract yAt(self, index: int) → float[source]¶

Returns the y-coordinate of the specified node in the line string.

Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 corresponds to the last point in the line.

Raises:: IndexError – if no point with the specified index exists.
Parameters:: index (int)
Return type:: float

abstract zAt(self, index: int) → float[source]¶

Returns the z-coordinate of the specified node in the line string.

If the LineString does not have a z-dimension then NaN will be returned.

Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 corresponds to the last point in the line.

Raises:: IndexError – if no point with the specified index exists.
Parameters:: index (int)
Return type:: float