QgsCircularString class

Circular string geometry type.

Reference

Base classes

class QgsCurve: Abstract base class for curved geometry type.

Public static functions

static auto fromTwoPointsAndCenter(const QgsPoint& p1, const QgsPoint& p2, const QgsPoint& center, bool useShortestArc = true) -> QgsCircularString: Creates a circular string with a single arc representing the curve from p1 to p2 with the specified center.

Constructors, destructors, conversion operators

QgsCircularString(): Constructs an empty circular string.
QgsCircularString(const QgsPoint& p1, const QgsPoint& p2, const QgsPoint& p3): Constructs a circular string with a single arc passing through p1, p2 and p3.

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.
auto addZValue(double zValue = 0) -> bool override: Adds a z-dimension to the geometry, initialized to a preset value.
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 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 QgsCircularString*: Cast the geom to a QgsCircularString.
void clear() override: Clears the geometry, ie reset it to a null geometry.
auto clone() const -> QgsCircularString* override: Clones the geometry by performing a deep copy.
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 createEmptyWithSameType() const -> QgsCircularString* 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 -> QgsCircularString* 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 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 hasCurvedSegments() const -> bool override: Returns true if the geometry contains curved segments.
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 moveVertex(QgsVertexId position, const QgsPoint& newPos) -> bool override: Moves a vertex within 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 point at index i within the circular 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 -> QgsCircularString* 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 setPoints(const QgsPointSequence& points): Sets the circular string's points.
auto snappedToGrid(double hSpacing, double vSpacing, double dSpacing = 0, double mSpacing = 0) const -> QgsCircularString* 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.
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 yAt(int index) const -> double override: Returns the y-coordinate of the specified node in the line string.

Protected functions

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

Function documentation

static QgsCircularString QgsCircularString::fromTwoPointsAndCenter(const QgsPoint& p1, const QgsPoint& p2, const QgsPoint& center, bool useShortestArc = true)

Creates a circular string with a single arc representing the curve from p1 to p2 with the specified center.

If useShortestArc is true, then the arc returned will be that corresponding to the shorter arc from p1 to p2. If it is false, the longer arc from p1 to p2 will be used (i.e. winding the other way around the circle).

QgsCircularString::QgsCircularString(const QgsPoint& p1, const QgsPoint& p2, const QgsPoint& p3)

Constructs a circular string with a single arc passing through p1, p2 and p3.

bool QgsCircularString::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

bool QgsCircularString::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

QDomElement QgsCircularString::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 QgsCircularString::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 QgsCircularString::asJson(int precision = 17) const override

Returns a GeoJSON representation of the geometry.

Parameters
precision	number of decimal places for coordinates

QByteArray QgsCircularString::asWkb() const override

Returns a WKB representation of the geometry.

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

Returns a WKT representation of the geometry.

Parameters
precision	number of decimal places for coordinates

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

Cast the geom to a QgsCircularString.

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

double QgsCircularString::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

QgsCircularString* QgsCircularString::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.

QgsCircularString* QgsCircularString::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* QgsCircularString::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

Uses a MaximumAngle tolerance of 1 degrees by default (360 segments in a full circle)

bool QgsCircularString::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 QgsCircularString::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 QgsCircularString::draw(QPainter& p) const override

Draws the geometry using the specified QPainter.

Parameters
p	destination QPainter

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

Draws the curve as a polygon on the specified QPainter.

Parameters
p	destination QPainter

bool QgsCircularString::dropMValue() override

Drops any measure values which exist in the geometry.

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

bool QgsCircularString::dropZValue() override

Drops any z-dimensions which exist in the geometry.

Returns	true if Z values were present and have been removed

QgsPoint QgsCircularString::endPoint() const override

Returns the end point of the curve.

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

Checks whether this curve exactly equals another curve.

void QgsCircularString::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 QgsCircularString::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 QgsCircularString::fromWkt(const QString& wkt) override

Sets the geometry from a WKT string.

QString QgsCircularString::geometryType() const override

Returns a unique string representing the geometry type.

bool QgsCircularString::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* QgsCircularString::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 QgsCircularString::length() const override

Returns the length of the geometry.

bool QgsCircularString::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 QgsCircularString::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

bool QgsCircularString::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.

QgsCircularString* QgsCircularString::reversed() const override

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

double QgsCircularString::segmentLength(QgsVertexId startVertex) const override

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

QgsCircularString* QgsCircularString::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 QgsCircularString::startPoint() const override

Returns the starting point of the curve.

void QgsCircularString::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.

void QgsCircularString::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 QgsCircularString::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 QgsCircularString::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 QgsCircularString::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 QgsCircularString::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

double QgsCircularString::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

QgsRectangle QgsCircularString::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.