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 callingaddVertex()
If the
z
vector is filled, then the geometry type will either be a LineStringZ(M) or LineString25D depending on theis25DType
argument. Ifis25DType
isTrue
(and them
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
andy
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 fromp1
top2
.New in version 3.2.
QgsLineString(
QgsLineString
)Methods
- param mValue:
- param path:
Adds a new vertex to the end of the line string.
- param zValue:
Appends the contents of another line string to the end of this line string.
- param doc:
- param doc:
- param precision:
- rtype:
QPolygonF
- param flags:
- param precision:
- param rectangle:
- rtype:
QgsRectangle
- rtype:
QgsPoint
Returns number of child geometries (for geometries with child geometries) or child points (for geometries without child geometries - i.e. curve / point).
Returns pointer to child geometry (for geometries with child geometries - i.e. geom.
Returns point at index (for geometries without child geometries - i.e. curve / point).
Clears any cached parameters associated with the geometry, e.g., bounding boxes
- rtype:
QgsLineString
Closes the line string by appending the first point to the end of the line, if it is not already closed.
- param pt:
Returns a list of any duplicate nodes contained in the geometry, within the specified tolerance.
- param other:
- param type:
- rtype:
QgsLineString
- param startDistance:
Returns a new line string geometry corresponding to a segmentized approximation of the curve.
- param position:
- rtype:
int
- param p:
- param p:
- rtype:
bool
- rtype:
bool
- rtype:
QgsPoint
- param other:
Extends the line geometry by extrapolating out the start or end of the line by a specified distance.
Returns a new linestring created by segmentizing the bezier curve between
start
andend
, with the specified control points.Returns a new linestring from a QPolygonF
polygon
input.- param wkb:
- param wkt:
- rtype:
str
Returns whether the geometry has any child geometries (
False
for point / curve,True
otherwise)- param point:
- param position:
- param distance:
- rtype:
bool
- rtype:
bool
- rtype:
bool
- param flags:
- rtype:
float
Returns the length in 3D world of the line string.
Returns the m-coordinate of the specified node in the line string.
- param position:
- rtype:
int
- rtype:
int
- param node:
Returns the point at the specified index.
- rtype:
List[QgsPoint]
- param epsilon:
- rtype:
QgsLineString
- param firstVertexIndex:
- param startVertex:
Sets the m-coordinate of the specified node in the line string.
Resets the line string to match the specified list of points.
Sets the x-coordinate of the specified node in the line string.
Sets the y-coordinate of the specified node in the line string.
Sets the z-coordinate of the specified node in the line string.
Updates the geometry type based on whether sub geometries contain z or m values.
- param hSpacing:
Returns the sort index for the geometry, used in the
compareTo()
method to compare geometries of different types.- rtype:
QgsPoint
- rtype:
float
Returns the geometry converted to the more generic curve type
QgsCompoundCurve
- param ct:
- param vertex:
- param flags:
Returns the x-coordinate of the specified node in the line string.
Returns the y-coordinate of the specified node in the line string.
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:
- 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:
- 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
isTrue
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:
- curveSubstring(self, startDistance: float, endDistance: float) QgsLineString ¶
- Parameters:
startDistance (float) –
endDistance (float) –
- Return type:
- 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:
- 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
- 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
andend
, 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:
- fromQPolygonF(polygon: QPolygonF) QgsLineString ¶
Returns a new linestring from a QPolygonF
polygon
input.New in version 3.10.
- Parameters:
polygon (QPolygonF) –
- Return type:
- 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.
- insertVertex(self, position: QgsVertexId, vertex: QgsPoint) bool ¶
- Parameters:
position (QgsVertexId) –
vertex (QgsPoint) –
- Return type:
bool
- 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
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:
position (QgsVertexId) –
newPos (QgsPoint) –
- 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:
node (int) –
point (QgsPoint) –
- 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:
- 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:
- 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
- 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
- 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
- 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
- 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:
- 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.
- sumUpArea(self) float ¶
- Return type:
float
- swapXy(self)¶
- toCurveType(self) QgsCompoundCurve ¶
Returns the geometry converted to the more generic curve type
QgsCompoundCurve
- Return type:
- 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