Class: QgsLineString

class qgis.core.QgsLineString

Bases: QgsCurve

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

New in version 2.10.

QgsLineString() Constructor for an empty linestring geometry.

QgsLineString(points: Sequence[Union[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.

New in version 3.20.

QgsLineString(segment: QgsLineSegment2D) Construct a linestring from a single 2d line segment.

New in version 3.2.

QgsLineString(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.

New in version 3.0.

QgsLineString(p1: QgsPoint, p2: QgsPoint) Constructs a linestring with a single segment from p1 to p2.

New in version 3.2.

QgsLineString(QgsLineString)

Methods

addMValue

param mValue:

addToPainterPath

param path:

addVertex

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

addZValue

param zValue:

append

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

asGml2

param doc:

asGml3

param doc:

asKml

param precision:

asQPolygonF

rtype:

QPolygonF

asWkb

param flags:

asWkt

param precision:

boundingBoxIntersects

param rectangle:

calculateBoundingBox

rtype:

QgsRectangle

calculateBoundingBox3d

Calculates the minimal 3D bounding box for the geometry.

centroid

rtype:

QgsPoint

childCount

Returns number of child geometries (for geometries with child geometries) or child points (for geometries without child geometries - i.e. curve / point).

childGeometry

Returns pointer to child geometry (for geometries with child geometries - i.e. geom.

childPoint

Returns point at index (for geometries without child geometries - i.e. curve / point).

clear

clearCache

Clears any cached parameters associated with the geometry, e.g., bounding boxes

clone

rtype:

QgsLineString

close

Closes the line string by appending the first point to the end of the line, if it is not already closed.

closestSegment

param pt:

collectDuplicateNodes

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

compareToSameClass

param other:

convertTo

param type:

createEmptyWithSameType

rtype:

QgsLineString

curveSubstring

param startDistance:

curveToLine

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

deleteVertex

param position:

dimension

rtype:

int

draw

param p:

drawAsPolygon

param p:

dropMValue

rtype:

bool

dropZValue

rtype:

bool

endPoint

rtype:

QgsPoint

equals

param other:

extend

Extends the line geometry by extrapolating out the start or end of the line by a specified distance.

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.

fromWkb

param wkb:

fromWkt

param wkt:

geometryType

rtype:

str

hasChildGeometries

Returns whether the geometry has any child geometries (False for point / curve, True otherwise)

indexOf

param point:

insertVertex

param position:

interpolatePoint

param distance:

isClosed

rtype:

bool

isClosed2D

rtype:

bool

isEmpty

rtype:

bool

isValid

param flags:

length

rtype:

float

length3D

Returns the length in 3D world of the line string.

mAt

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

moveVertex

param position:

nCoordinates

rtype:

int

numPoints

rtype:

int

pointAt

param node:

pointN

Returns the point at the specified index.

points

rtype:

List[QgsPoint]

removeDuplicateNodes

param epsilon:

reversed

rtype:

QgsLineString

scroll

param firstVertexIndex:

segmentLength

param startVertex:

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.

setZMTypeFromSubGeometry

Updates the geometry type based on whether sub geometries contain z or m values.

snappedToGrid

param hSpacing:

sortIndex

Returns the sort index for the geometry, used in the compareTo() method to compare geometries of different types.

startPoint

rtype:

QgsPoint

sumUpArea

Calculates the shoelace/triangle formula sum for the points in the linestring.

swapXy

toCurveType

Returns the geometry converted to the more generic curve type QgsCompoundCurve

transform

param ct:

vertexAngle

param vertex:

wkbSize

param flags:

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.

addMValue(self, mValue: float = 0) bool
Parameters:

mValue (float = 0) –

Return type:

bool

addToPainterPath(self, path: QPainterPath)
Parameters:

path (QPainterPath) –

addVertex(self, pt: QgsPoint)

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

Parameters:

pt (QgsPoint) – vertex to add

addZValue(self, zValue: float = 0) bool
Parameters:

zValue (float = 0) –

Return type:

bool

append(self, line: QgsLineString)

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

Parameters:

line (QgsLineString) – line to append. Ownership is not transferred.

asGml2(self, doc: QDomDocument, precision: int = 17, ns: str = '', axisOrder: QgsAbstractGeometry.AxisOrder = QgsAbstractGeometry.AxisOrder.XY) QDomElement
Parameters:
  • doc (QDomDocument) –

  • precision (int = 17) –

  • ns (str = '') –

  • axisOrder (QgsAbstractGeometry.AxisOrder = QgsAbstractGeometry.AxisOrder.XY) –

Return type:

QDomElement

asGml3(self, doc: QDomDocument, precision: int = 17, ns: str = '', axisOrder: QgsAbstractGeometry.AxisOrder = QgsAbstractGeometry.AxisOrder.XY) QDomElement
Parameters:
  • doc (QDomDocument) –

  • precision (int = 17) –

  • ns (str = '') –

  • axisOrder (QgsAbstractGeometry.AxisOrder = QgsAbstractGeometry.AxisOrder.XY) –

Return type:

QDomElement

asKml(self, precision: int = 17) str
Parameters:

precision (int = 17) –

Return type:

str

asQPolygonF(self) QPolygonF
Return type:

QPolygonF

asWkb(self, flags: QgsAbstractGeometry.WkbFlags | QgsAbstractGeometry.WkbFlag = QgsAbstractGeometry.WkbFlags()) QByteArray
Parameters:

flags (Union[QgsAbstractGeometry.WkbFlags) –

Return type:

QByteArray

asWkt(self, precision: int = 17) str
Parameters:

precision (int = 17) –

Return type:

str

boundingBoxIntersects(self, rectangle: QgsRectangle) bool
Parameters:

rectangle (QgsRectangle) –

Return type:

bool

calculateBoundingBox(self) QgsRectangle
Return type:

QgsRectangle

calculateBoundingBox3d(self) QgsBox3d

Calculates the minimal 3D bounding box for the geometry.

New in version 3.26.

Return type:

QgsBox3d

centroid(self) QgsPoint
Return type:

QgsPoint

childCount(self) int

Returns number of child geometries (for geometries with child geometries) or child points (for geometries without child geometries - i.e. curve / point)

Note

used for vertex_iterator implementation

New in version 3.0.

childGeometry(self, index: int) QgsAbstractGeometry

Returns pointer to child geometry (for geometries with child geometries - i.e. geom. collection / polygon)

Note

used for vertex_iterator implementation

New in version 3.0.

childPoint(self, index: int) QgsPoint

Returns point at index (for geometries without child geometries - i.e. curve / point)

Note

used for vertex_iterator implementation

New in version 3.0.

clear(self)
clearCache(self)

Clears any cached parameters associated with the geometry, e.g., bounding boxes

clone(self) QgsLineString
Return type:

QgsLineString

close(self)

Closes the line string by appending the first point to the end of the line, if it is not already closed.

closestSegment(self, pt: QgsPoint, epsilon: float = 4 * DBL_EPSILON) Tuple[float, QgsPoint, QgsVertexId, int]
Parameters:
  • pt (QgsPoint) –

  • epsilon (float = 4*DBL_EPSILON) –

Return type:

Tuple[float, QgsPoint, QgsVertexId, int]

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.

New in version 3.16.

Parameters:
  • epsilon (float = 4*DBL_EPSILON) –

  • useZValues (bool = False) –

Return type:

List[QgsVertexId]

compareToSameClass(self, other: QgsAbstractGeometry) int
Parameters:

other (QgsAbstractGeometry) –

Return type:

int

convertTo(self, type: QgsWkbTypes.Type) bool
Parameters:

type (QgsWkbTypes.Type) –

Return type:

bool

createEmptyWithSameType(self) QgsLineString
Return type:

QgsLineString

curveSubstring(self, startDistance: float, endDistance: float) QgsLineString
Parameters:
  • startDistance (float) –

  • endDistance (float) –

Return type:

QgsLineString

curveToLine(self, tolerance: float = M_PI_2 / 90, toleranceType: QgsAbstractGeometry.SegmentationToleranceType = QgsAbstractGeometry.MaximumAngle) QgsLineString

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:

QgsLineString

deleteVertex(self, position: QgsVertexId) bool
Parameters:

position (QgsVertexId) –

Return type:

bool

dimension(self) int
Return type:

int

draw(self, p: QPainter)
Parameters:

p (QPainter) –

drawAsPolygon(self, p: QPainter)
Parameters:

p (QPainter) –

dropMValue(self) bool
Return type:

bool

dropZValue(self) bool
Return type:

bool

endPoint(self) QgsPoint
Return type:

QgsPoint

equals(self, other: QgsCurve) bool
Parameters:

other (QgsCurve) –

Return type:

bool

extend(self, startDistance: float, endDistance: float)

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.

New in version 3.0.

Parameters:
  • startDistance (float) –

  • endDistance (float) –

fromBezierCurve(start: QgsPoint, controlPoint1: QgsPoint, controlPoint2: QgsPoint, end: QgsPoint, segments: int = 30) QgsLineString

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.

New in version 3.10.

Parameters:
Return type:

QgsLineString

fromQPolygonF(polygon: QPolygonF) QgsLineString

Returns a new linestring from a QPolygonF polygon input.

New in version 3.10.

Parameters:

polygon (QPolygonF) –

Return type:

QgsLineString

fromWkb(self, wkb: QgsConstWkbPtr) bool
Parameters:

wkb (QgsConstWkbPtr) –

Return type:

bool

fromWkt(self, wkt: str) bool
Parameters:

wkt (str) –

Return type:

bool

geometryType(self) str
Return type:

str

hasChildGeometries(self) bool

Returns whether the geometry has any child geometries (False for point / curve, True otherwise)

Note

used for vertex_iterator implementation

New in version 3.0.

indexOf(self, point: QgsPoint) int
Parameters:

point (QgsPoint) –

Return type:

int

insertVertex(self, position: QgsVertexId, vertex: QgsPoint) bool
Parameters:
Return type:

bool

interpolatePoint(self, distance: float) QgsPoint
Parameters:

distance (float) –

Return type:

QgsPoint

isClosed(self) bool
Return type:

bool

isClosed2D(self) bool
Return type:

bool

isEmpty(self) bool
Return type:

bool

isValid(self, flags: Qgis.GeometryValidityFlags | Qgis.GeometryValidityFlag = Qgis.GeometryValidityFlags()) Tuple[bool, str]
Parameters:

flags (Union[Qgis.GeometryValidityFlags) –

Return type:

Tuple[bool, str]

length(self) float
Return type:

float

length3D(self) float

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()

New in version 3.10.

Return type:

float

mAt(self, index: int) float

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

moveVertex(self, position: QgsVertexId, newPos: QgsPoint) bool
Parameters:
Return type:

bool

nCoordinates(self) int
Return type:

int

numPoints(self) int
Return type:

int

pointAt(self, node: int, point: QgsPoint) Tuple[bool, Qgis.VertexType]
Parameters:
Return type:

Tuple[bool, Qgis.VertexType]

pointN(self, i: int) QgsPoint

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

points(self) List[QgsPoint]
Return type:

List[QgsPoint]

removeDuplicateNodes(self, epsilon: float = 4 * DBL_EPSILON, useZValues: bool = False) bool
Parameters:
  • epsilon (float = 4*DBL_EPSILON) –

  • useZValues (bool = False) –

Return type:

bool

reversed(self) QgsLineString
Return type:

QgsLineString

scroll(self, firstVertexIndex: int)
Parameters:

firstVertexIndex (int) –

segmentLength(self, startVertex: QgsVertexId) float
Parameters:

startVertex (QgsVertexId) –

Return type:

float

setMAt(self, index: int, m: float)

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])

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)

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)

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)

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) –

setZMTypeFromSubGeometry(self, subggeom: QgsAbstractGeometry, baseGeomType: QgsWkbTypes.Type)

Updates the geometry type based on whether sub geometries contain z or m values.

snappedToGrid(self, hSpacing: float, vSpacing: float, dSpacing: float = 0, mSpacing: float = 0) QgsLineString
Parameters:
  • hSpacing (float) –

  • vSpacing (float) –

  • dSpacing (float = 0) –

  • mSpacing (float = 0) –

Return type:

QgsLineString

sortIndex(self) int

Returns the sort index for the geometry, used in the compareTo() method to compare geometries of different types.

New in version 3.20.

startPoint(self) QgsPoint
Return type:

QgsPoint

sumUpArea(self) float

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)

See also

https()

Return type:

float

swapXy(self)
toCurveType(self) QgsCompoundCurve

Returns the geometry converted to the more generic curve type QgsCompoundCurve

Return type:

QgsCompoundCurve

Returns:

the converted geometry. Caller takes ownership

transform(self, ct: QgsCoordinateTransform, d: Qgis.TransformDirection = Qgis.TransformDirection.Forward, transformZ: bool = False)
transform(self, t: QTransform, zTranslate: float = 0, zScale: float = 1, mTranslate: float = 0, mScale: float = 1) None
transform(self, transformer: QgsAbstractGeometryTransformer, feedback: QgsFeedback = None) bool
Parameters:
  • ct (QgsCoordinateTransform) –

  • d (Qgis.TransformDirection = Qgis.TransformDirection.Forward) –

  • transformZ (bool = False) –

vertexAngle(self, vertex: QgsVertexId) float
Parameters:

vertex (QgsVertexId) –

Return type:

float

wkbSize(self, flags: QgsAbstractGeometry.WkbFlags | QgsAbstractGeometry.WkbFlag = QgsAbstractGeometry.WkbFlags()) int
Parameters:

flags (Union[QgsAbstractGeometry.WkbFlags) –

Return type:

int

xAt(self, index: int) float

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

yAt(self, index: int) float

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

zAt(self, index: int) float

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