QgsLineString class

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

Reference

Base classes

class QgsCurve: Abstract base class for curved geometry type.

Constructors, destructors, conversion operators

QgsLineString(const QVector<QgsPoint>& points): Construct a linestring from a vector of points.
QgsLineString(const QVector<double>& x, const QVector<double>& y, const QVector<double>& z = QVector<double>(), const QVector<double>& m = QVector<double>(), bool is25DType = false): Construct a linestring from arrays of coordinates.
QgsLineString(const QgsPoint& p1, const QgsPoint& p2): Constructs a linestring with a single segment from p1 to p2.
QgsLineString(const QVector<QgsPointXY>& points): Construct a linestring from list of points.
QgsLineString(const QgsLineSegment2D& segment) explicit: Construct a linestring from a single 2d line segment.

Public functions

auto addMValue(double mValue = 0) -> bool override: Adds a measure to the geometry, initialized to a preset value.
void addToPainterPath(QPainterPath& path) const override: Adds a curve to a painter path.
void addVertex(const QgsPoint& pt): Adds a new vertex to the end of the line string.
auto addZValue(double zValue = 0) -> bool override: Adds a z-dimension to the geometry, initialized to a preset value.
void append(const QgsLineString* line): Appends the contents of another line string to the end of this line string.
auto asGml2(QDomDocument& doc, int precision = 17, const QString& ns = "gml", QgsAbstractGeometry::AxisOrder axisOrder = QgsAbstractGeometry::AxisOrder::XY) const -> QDomElement override: Returns a GML2 representation of the geometry.
auto asGml3(QDomDocument& doc, int precision = 17, const QString& ns = "gml", QgsAbstractGeometry::AxisOrder axisOrder = QgsAbstractGeometry::AxisOrder::XY) const -> QDomElement override: Returns a GML3 representation of the geometry.
auto asJson(int precision = 17) const -> QString override: Returns a GeoJSON representation of the geometry.
auto asQPolygonF() const -> QPolygonF override: Returns a QPolygonF representing the points.
auto asWkb() const -> QByteArray override: Returns a WKB representation of the geometry.
auto asWkt(int precision = 17) const -> QString override: Returns a WKT representation of the geometry.
auto cast(const QgsAbstractGeometry* geom) const -> const QgsLineString*: Cast the geom to a QgsLineString.
auto centroid() const -> QgsPoint override: Returns the centroid of the geometry.
void clear() override: Clears the geometry, ie reset it to a null geometry.
auto clone() const -> QgsLineString* override: Clones the geometry by performing a deep copy.
void close(): Closes the line string by appending the first point to the end of the line, if it is not already closed.
auto closestSegment(const QgsPoint& pt, QgsPoint& segmentPt, QgsVertexId& vertexAfter, int* leftOf = nullptr, double epsilon = 4*std::numeric_limits<double>::epsilon()) const -> double override: Searches for the closest segment of the geometry to a given point.
auto convertTo(QgsWkbTypes::Type type) -> bool override: Converts the geometry to a specified type.
auto createEmptyWithSameType() const -> QgsLineString* override: Creates a new geometry with the same class and same WKB type as the original and transfers ownership.
auto curveSubstring(double startDistance, double endDistance) const -> QgsLineString* override: Returns a new curve representing a substring of this curve.
auto curveToLine(double tolerance = M_PI_2/90, SegmentationToleranceType toleranceType = MaximumAngle) const -> QgsLineString* override: Returns a new line string geometry corresponding to a segmentized approximation of the curve.
auto deleteVertex(QgsVertexId position) -> bool override: Deletes a vertex within the geometry.
auto dimension() const -> int override: Returns the inherent dimension of the geometry.
void draw(QPainter& p) const override: Draws the geometry using the specified QPainter.
void drawAsPolygon(QPainter& p) const override: Draws the curve as a polygon on the specified QPainter.
auto dropMValue() -> bool override: Drops any measure values which exist in the geometry.
auto dropZValue() -> bool override: Drops any z-dimensions which exist in the geometry.
auto endPoint() const -> QgsPoint override: Returns the end point of the curve.
auto equals(const QgsCurve& other) const -> bool override: Checks whether this curve exactly equals another curve.
void extend(double startDistance, double endDistance): Extends the line geometry by extrapolating out the start or end of the line by a specified distance.
void filterVertices(const std::function<bool(const QgsPoint&)>& filter) override: Filters the vertices from the geometry in place, removing any which do not return true for the filter function check.
auto fromWkb(QgsConstWkbPtr& wkb) -> bool override: Sets the geometry from a WKB string.
auto fromWkt(const QString& wkt) -> bool override: Sets the geometry from a WKT string.
auto geometryType() const -> QString override: Returns a unique string representing the geometry type.
auto insertVertex(QgsVertexId position, const QgsPoint& vertex) -> bool override: Inserts a vertex into the geometry.
auto interpolatePoint(double distance) const -> QgsPoint* override: Returns an interpolated point on the curve at the specified distance.
auto isEmpty() const -> bool override: Returns true if the geometry is empty.
auto length() const -> double override: Returns the length of the geometry.
auto mAt(int index) const -> double: Returns the m value of the specified node in the line string.
auto mData() const -> const double*: Returns a const pointer to the m vertex data, or a nullptr if the linestring does not have m values.
auto moveVertex(QgsVertexId position, const QgsPoint& newPos) -> bool override: Moves a vertex within the geometry.
auto nCoordinates() const -> int override: Returns the number of nodes contained in the geometry.
auto numPoints() const -> int override: Returns the number of points in the curve.
auto pointAt(int node, QgsPoint& point, QgsVertexId::VertexType& type) const -> bool override: Returns the point and vertex id of a point within the curve.
auto pointN(int i) const -> QgsPoint: Returns the specified point from inside the line string.
void points(QgsPointSequence& pt) const override: Returns a list of points within the curve.
auto removeDuplicateNodes(double epsilon = 4*std::numeric_limits<double>::epsilon(), bool useZValues = false) -> bool override: Removes duplicate nodes from the geometry, wherever removing the nodes does not result in a degenerate geometry.
auto reversed() const -> QgsLineString* override: Returns a reversed copy of the curve, where the direction of the curve has been flipped.
auto segmentLength(QgsVertexId startVertex) const -> double override: Returns the length of the segment of the geometry which begins at startVertex.
void setMAt(int index, double m): Sets the m value of the specified node in the line string.
void setPoints(const QgsPointSequence& points): Resets the line string to match the specified list of points.
void setXAt(int index, double x): Sets the x-coordinate of the specified node in the line string.
void setYAt(int index, double y): Sets the y-coordinate of the specified node in the line string.
void setZAt(int index, double z): Sets the z-coordinate of the specified node in the line string.
auto snappedToGrid(double hSpacing, double vSpacing, double dSpacing = 0, double mSpacing = 0) const -> QgsLineString* override: Makes a new geometry with all the points or vertices snapped to the closest point of the grid.
auto startPoint() const -> QgsPoint override: Returns the starting point of the curve.
void sumUpArea(double& sum) const override: Sums up the area of the curve by iterating over the vertices (shoelace formula).
void swapXy() override: Swaps the x and y coordinates from the geometry.
auto toCurveType() const -> QgsCompoundCurve* override: Returns the geometry converted to the more generic curve type QgsCompoundCurve.
void transform(const QgsCoordinateTransform& ct, QgsCoordinateTransform::TransformDirection d = QgsCoordinateTransform::ForwardTransform, bool transformZ = false) virtual: Transforms the geometry using a coordinate transform.
void transform(const QTransform& t, double zTranslate = 0.0, double zScale = 1.0, double mTranslate = 0.0, double mScale = 1.0) override: Transforms the x and y components of the geometry using a QTransform object t.
void transformVertices(const std::function<QgsPoint(const QgsPoint&)>& transform) override: Transforms the vertices from the geometry in place, applying the transform function to every vertex.
auto vertexAngle(QgsVertexId vertex) const -> double override: Returns approximate angle at a vertex.
auto xAt(int index) const -> double override: Returns the x-coordinate of the specified node in the line string.
auto xData() const -> const double*: Returns a const pointer to the x vertex data.
auto yAt(int index) const -> double override: Returns the y-coordinate of the specified node in the line string.
auto yData() const -> const double*: Returns a const pointer to the y vertex data.
auto zAt(int index) const -> double: Returns the z-coordinate of the specified node in the line string.
auto zData() const -> const double*: Returns a const pointer to the z vertex data, or a nullptr if the linestring does not have z values.

Protected functions

auto calculateBoundingBox() const -> QgsRectangle override: Default calculator for the minimal bounding box for the geometry.

Function documentation

QgsLineString::QgsLineString(const QVector<QgsPoint>& points)

Construct a linestring from a vector of points.

Z and M type will be set based on the type of the first point in the vector.

QgsLineString::QgsLineString(const QVector<double>& x, const QVector<double>& y, const QVector<double>& z = QVector<double>(), const QVector<double>& m = QVector<double>(), bool is25DType = 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.

QgsLineString::QgsLineString(const QgsPoint& p1, const QgsPoint& p2)

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

QgsLineString::QgsLineString(const QVector<QgsPointXY>& points)

Construct a linestring from list of points.

This constructor is more efficient then calling setPoints() or repeatedly calling addVertex()

QgsLineString::QgsLineString(const QgsLineSegment2D& segment) explicit

Construct a linestring from a single 2d line segment.

bool QgsLineString::addMValue(double mValue = 0) override

Adds a measure to the geometry, initialized to a preset value.

Parameters
mValue	initial m-value for all nodes
Returns	true on success

void QgsLineString::addVertex(const QgsPoint& pt)

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

Parameters
pt	vertex to add

bool QgsLineString::addZValue(double zValue = 0) override

Adds a z-dimension to the geometry, initialized to a preset value.

Parameters
zValue	initial z-value for all nodes
Returns	true on success

void QgsLineString::append(const QgsLineString* line)

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

Parameters
line	line to append. Ownership is not transferred.

QDomElement QgsLineString::asGml2(QDomDocument& doc, int precision = 17, const QString& ns = "gml", QgsAbstractGeometry::AxisOrder axisOrder = QgsAbstractGeometry::AxisOrder::XY) const override

Returns a GML2 representation of the geometry.

Parameters
doc	DOM document
precision	number of decimal places for coordinates
ns	XML namespace
axisOrder	Axis order for generated GML

QDomElement QgsLineString::asGml3(QDomDocument& doc, int precision = 17, const QString& ns = "gml", QgsAbstractGeometry::AxisOrder axisOrder = QgsAbstractGeometry::AxisOrder::XY) const override

Returns a GML3 representation of the geometry.

Parameters
doc	DOM document
precision	number of decimal places for coordinates
ns	XML namespace
axisOrder	Axis order for generated GML

QString QgsLineString::asJson(int precision = 17) const override

Returns a GeoJSON representation of the geometry.

Parameters
precision	number of decimal places for coordinates

QByteArray QgsLineString::asWkb() const override

Returns a WKB representation of the geometry.

QString QgsLineString::asWkt(int precision = 17) const override

Returns a WKT representation of the geometry.

Parameters
precision	number of decimal places for coordinates

const QgsLineString* QgsLineString::cast(const QgsAbstractGeometry* geom) const

Cast the geom to a QgsLineString.

Should be used by qgsgeometry_cast<QgsLineString *>( geometry ).

double QgsLineString::closestSegment(const QgsPoint& pt, QgsPoint& segmentPt, QgsVertexId& vertexAfter, int* leftOf = nullptr, double epsilon = 4*std::numeric_limits<double>::epsilon()) const override

Searches for the closest segment of the geometry to a given point.

Parameters
pt	specifies the point to find closest segment to
segmentPt	storage for the closest point within the geometry
vertexAfter	storage for the ID of the vertex at the end of the closest segment
leftOf	indicates whether the point lies on the left side of the geometry (-1 if point is to the left of the geometry, +1 if the point is to the right of the geometry, or 0 for cases where left/right could not be determined, e.g. point exactly on a line) false if point is to right of segment)
epsilon	epsilon for segment snapping
Returns	squared distance to closest segment or negative value on error

bool QgsLineString::convertTo(QgsWkbTypes::Type type) override

Converts the geometry to a specified type.

Returns	true if conversion was successful

QgsLineString* QgsLineString::createEmptyWithSameType() const override

Creates a new geometry with the same class and same WKB type as the original and transfers ownership.

To create it, the geometry is default constructed and then the WKB is changed.

QgsLineString* QgsLineString::curveSubstring(double startDistance, double endDistance) const override

Returns a new curve representing a substring of this curve.

The startDistance and endDistance arguments specify the length along the curve which the substring should start and end at. If the endDistance is greater than the total length of the curve then any "extra" length will be ignored.

If z or m values are present, the output z and m will be interpolated using the existing vertices' z or m values.

QgsLineString* QgsLineString::curveToLine(double tolerance = M_PI_2/90, SegmentationToleranceType toleranceType = MaximumAngle) const override

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

Parameters
tolerance	segmentation tolerance
toleranceType	maximum segmentation angle or maximum difference between approximation and curve

bool QgsLineString::deleteVertex(QgsVertexId position) override

Deletes a vertex within the geometry.

Parameters
position	vertex id for vertex to delete
Returns	true if delete was successful

int QgsLineString::dimension() const override

Returns the inherent dimension of the geometry.

For example, this is 0 for a point geometry, 1 for a linestring and 2 for a polygon.

void QgsLineString::draw(QPainter& p) const override

Draws the geometry using the specified QPainter.

Parameters
p	destination QPainter

void QgsLineString::drawAsPolygon(QPainter& p) const override

Draws the curve as a polygon on the specified QPainter.

Parameters
p	destination QPainter

bool QgsLineString::dropMValue() override

Drops any measure values which exist in the geometry.

Returns	true if m-values were present and have been removed

bool QgsLineString::dropZValue() override

Drops any z-dimensions which exist in the geometry.

Returns	true if Z values were present and have been removed

QgsPoint QgsLineString::endPoint() const override

Returns the end point of the curve.

bool QgsLineString::equals(const QgsCurve& other) const override

Checks whether this curve exactly equals another curve.

void QgsLineString::extend(double startDistance, double endDistance)

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.

void QgsLineString::filterVertices(const std::function<bool(const QgsPoint&)>& filter) override

Filters the vertices from the geometry in place, removing any which do not return true for the filter function check.

Has no meaning when called on a single point geometry.

Depending on the filter used, this may result in an invalid geometry.

bool QgsLineString::fromWkb(QgsConstWkbPtr& wkb) override

Sets the geometry from a WKB string.

After successful read the wkb argument will be at the position where the reading has stopped.

bool QgsLineString::fromWkt(const QString& wkt) override

Sets the geometry from a WKT string.

QString QgsLineString::geometryType() const override

Returns a unique string representing the geometry type.

bool QgsLineString::insertVertex(QgsVertexId position, const QgsPoint& vertex) override

Inserts a vertex into the geometry.

Parameters
position	vertex id for position of inserted vertex
vertex	vertex to insert
Returns	true if insert was successful

QgsPoint* QgsLineString::interpolatePoint(double distance) const override

Returns an interpolated point on the curve at the specified distance.

If z or m values are present, the output z and m will be interpolated using the existing vertices' z or m values.

If distance is negative, or is greater than the length of the curve, a nullptr will be returned.

double QgsLineString::length() const override

Returns the length of the geometry.

double QgsLineString::mAt(int index) const

Returns the m value of the specified node in the line string.

Parameters
index	index of node, where the first node in the line is 0
Returns	m value of node, or `nan` if index is out of bounds or the line does not have m values

const double* QgsLineString::mData() const

Returns a const pointer to the m vertex data, or a nullptr if the linestring does not have m values.

bool QgsLineString::moveVertex(QgsVertexId position, const QgsPoint& newPos) override

Moves a vertex within the geometry.

Parameters
position	vertex id for vertex to move
newPos	new position of vertex
Returns	true if move was successful

bool QgsLineString::pointAt(int node, QgsPoint& point, QgsVertexId::VertexType& type) const override

Returns the point and vertex id of a point within the curve.

Parameters
node	node number, where the first node is 0
point	will be set to point at corresponding node in the curve
type	will be set to the vertex type of the node
Returns	true if node exists within the curve

QgsPoint QgsLineString::pointN(int i) const

Returns the specified point from inside the line string.

Parameters
i	index of point, starting at 0 for the first point

bool QgsLineString::removeDuplicateNodes(double epsilon = 4*std::numeric_limits<double>::epsilon(), bool useZValues = false) override

Removes duplicate nodes from the geometry, wherever removing the nodes does not result in a degenerate geometry.

The epsilon parameter specifies the tolerance for coordinates when determining that vertices are identical.

By default, z values are not considered when detecting duplicate nodes. E.g. two nodes with the same x and y coordinate but different z values will still be considered duplicate and one will be removed. If useZValues is true, then the z values are also tested and nodes with the same x and y but different z will be maintained.

Note that duplicate nodes are not tested between different parts of a multipart geometry. E.g. a multipoint geometry with overlapping points will not be changed by this method.

The function will return true if nodes were removed, or false if no duplicate nodes were found.

QgsLineString* QgsLineString::reversed() const override

Returns a reversed copy of the curve, where the direction of the curve has been flipped.

double QgsLineString::segmentLength(QgsVertexId startVertex) const override

Returns the length of the segment of the geometry which begins at startVertex.

void QgsLineString::setMAt(int index, double m)

Sets the m value of the specified node in the line string.

Parameters
index	index of node, where the first node in the line is 0. Corresponding node must already exist in line string, and the line string must have m values.
m	m value of node

void QgsLineString::setPoints(const QgsPointSequence& points)

Resets the line string to match the specified list of points.

Parameters
points	new points for line string. If empty, line string will be cleared.

The line string will inherit the dimensionality of the first point in the list.

void QgsLineString::setXAt(int index, double x)

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

Parameters
index	index of node, where the first node in the line is 0. Corresponding node must already exist in line string.
x	x-coordinate of node

void QgsLineString::setYAt(int index, double y)

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

Parameters
index	index of node, where the first node in the line is 0. Corresponding node must already exist in line string.
y	y-coordinate of node

void QgsLineString::setZAt(int index, double z)

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

Parameters
index	index of node, where the first node in the line is 0. Corresponding node must already exist in line string, and the line string must have z-dimension.
z	z-coordinate of node

QgsLineString* QgsLineString::snappedToGrid(double hSpacing, double vSpacing, double dSpacing = 0, double mSpacing = 0) const override

Makes a new geometry with all the points or vertices snapped to the closest point of the grid.

Parameters
hSpacing	Horizontal spacing of the grid (x axis). 0 to disable.
vSpacing	Vertical spacing of the grid (y axis). 0 to disable.
dSpacing	Depth spacing of the grid (z axis). 0 (default) to disable.
mSpacing	Custom dimension spacing of the grid (m axis). 0 (default) to disable.

Ownership is transferred to the caller.

If the gridified geometry could not be calculated a nullptr will be returned. It may generate an invalid geometry (in some corner cases). It can also be thought as rounding the edges and it may be useful for removing errors. Example: geometry->snappedToGrid(1, 1); In this case we use a 2D grid of 1x1 to gridify. In this case, it can be thought like rounding the x and y of all the points/vertices to full units (remove all decimals).

QgsPoint QgsLineString::startPoint() const override

Returns the starting point of the curve.

void QgsLineString::swapXy() override

Swaps the x and y coordinates from the geometry.

This can be used to repair geometries which have accidentally had their latitude and longitude coordinates reversed.

QgsCompoundCurve* QgsLineString::toCurveType() const override

Returns the geometry converted to the more generic curve type QgsCompoundCurve.

Returns	the converted geometry. Caller takes ownership

void QgsLineString::transform(const QgsCoordinateTransform& ct, QgsCoordinateTransform::TransformDirection d = QgsCoordinateTransform::ForwardTransform, bool transformZ = false) virtual

Transforms the geometry using a coordinate transform.

Parameters
ct	coordinate transform
d	transformation direction
transformZ	set to true to also transform z coordinates. This requires that the z coordinates in the geometry represent height relative to the vertical datum of the source CRS (generally ellipsoidal heights) and are expressed in its vertical units (generally meters). If false, then z coordinates will not be changed by the transform.

void QgsLineString::transform(const QTransform& t, double zTranslate = 0.0, double zScale = 1.0, double mTranslate = 0.0, double mScale = 1.0) override

Transforms the x and y components of the geometry using a QTransform object t.

Optionally, the geometry's z values can be scaled via zScale and translated via zTranslate. Similarly, m-values can be scaled via mScale and translated via mTranslate.

void QgsLineString::transformVertices(const std::function<QgsPoint(const QgsPoint&)>& transform) override

Transforms the vertices from the geometry in place, applying the transform function to every vertex.

Depending on the transform used, this may result in an invalid geometry.

Transform functions are not permitted to alter the dimensionality of vertices. If a transform which adds (or removes) z/m values is desired, first call the corresponding addZValue() or addMValue() function to change the geometry's dimensionality and then transform.

double QgsLineString::vertexAngle(QgsVertexId vertex) const override

Returns approximate angle at a vertex.

Parameters
vertex	the vertex id
Returns	rotation in radians, clockwise from north

This is usually the average angle between adjacent segments, and can be pictured as the orientation of a line following the curvature of the geometry at the specified vertex.

double QgsLineString::xAt(int index) const override

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

Parameters
index	index of node, where the first node in the line is 0
Returns	x-coordinate of node, or 0.0 if index is out of bounds

const double* QgsLineString::xData() const

Returns a const pointer to the x vertex data.

double QgsLineString::yAt(int index) const override

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

Parameters
index	index of node, where the first node in the line is 0
Returns	y-coordinate of node, or 0.0 if index is out of bounds

const double* QgsLineString::yData() const

Returns a const pointer to the y vertex data.

double QgsLineString::zAt(int index) const

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

Parameters
index	index of node, where the first node in the line is 0
Returns	z-coordinate of node, or `nan` if index is out of bounds or the line does not have a z dimension

const double* QgsLineString::zData() const

Returns a const pointer to the z vertex data, or a nullptr if the linestring does not have z values.

QgsRectangle QgsLineString::calculateBoundingBox() const override protected

Default calculator for the minimal bounding box for the geometry.

Derived classes should override this method if a more efficient bounding box calculation is available.