QgsGeometryCollection class

Geometry collection.

Reference

Base classes

class QgsAbstractGeometry: Abstract base class for all geometries.

Derived classes

class QgsMultiCurve: Multi curve geometry collection.
class QgsMultiPoint: Multi point geometry collection.
class QgsMultiSurface: Multi surface geometry collection.

Public functions

auto addGeometry(QgsAbstractGeometry* g) -> bool virtual: Adds a geometry and takes ownership. Returns true in case of success.
auto addMValue(double mValue = 0) -> bool override: Adds a measure to the geometry, initialized to a preset value.
auto addZValue(double zValue = 0) -> bool override: Adds a z-dimension to the geometry, initialized to a preset value.
void adjacentVertices(QgsVertexId vertex, QgsVertexId& previousVertex, QgsVertexId& nextVertex) const override: Returns the vertices adjacent to a specified vertex within a geometry.
auto area() const -> double override: Returns the area of the geometry.
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 boundary() const -> QgsAbstractGeometry* override: Returns the closure of the combinatorial boundary of the geometry (ie the topological boundary of the geometry).
auto boundingBox() const -> QgsRectangle override: Returns the minimal bounding box for the geometry.
auto cast(const QgsAbstractGeometry* geom) const -> const QgsGeometryCollection*: Cast the geom to a QgsGeometryCollection.
void clear() override: Clears the geometry, ie reset it to a null geometry.
auto clone() const -> QgsGeometryCollection* 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 coordinateSequence() const -> QgsCoordinateSequence override: Retrieves the sequence of geometries, rings and nodes.
auto createEmptyWithSameType() const -> QgsGeometryCollection* override: Creates a new geometry with the same class and same WKB type as the original and transfers ownership.
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.
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.
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 geometryN(int n) const -> const QgsAbstractGeometry*: Returns a const reference to a geometry from within the collection.
auto geometryN(int n) -> QgsAbstractGeometry*: Returns a geometry from within the collection.
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 insertGeometry(QgsAbstractGeometry* g, int index) -> bool virtual: Inserts a geometry before a specified index and takes ownership.
auto insertVertex(QgsVertexId position, const QgsPoint& vertex) -> bool override: Inserts a vertex into the geometry.
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 nCoordinates() const -> int override: Returns the number of nodes contained in the geometry.
auto nextVertex(QgsVertexId& id, QgsPoint& vertex) const -> bool override: Returns next vertex id and coordinates.
auto numGeometries() const -> int: Returns the number of geometries within the collection.
auto partCount() const -> int override: Returns count of parts contained in the geometry.
auto perimeter() const -> double override: Returns the perimeter of the geometry.
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 removeGeometry(int nr) -> bool virtual: Removes a geometry from the collection.
auto ringCount(int part = 0) const -> int override: Returns the number of rings of which this geometry is built.
auto segmentize(double tolerance = M_PI_2/90, SegmentationToleranceType toleranceType = MaximumAngle) const -> QgsAbstractGeometry* override: Returns a geometry without curves.
auto segmentLength(QgsVertexId startVertex) const -> double override: Returns the length of the segment of the geometry which begins at startVertex.
auto snappedToGrid(double hSpacing, double vSpacing, double dSpacing = 0, double mSpacing = 0) const -> QgsGeometryCollection* override: Makes a new geometry with all the points or vertices snapped to the closest point of the grid.
void swapXy() override: Swaps the x and y coordinates from the geometry.
auto toCurveType() const -> QgsGeometryCollection* override: Returns the geometry converted to the more generic curve type.
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 vertexAt(QgsVertexId id) const -> QgsPoint override: Returns the point corresponding to a specified vertex id.
auto vertexCount(int part = 0, int ring = 0) const -> int override: Returns the number of vertices of which this geometry is built.
auto vertexNumberFromVertexId(QgsVertexId id) const -> int override: Returns the vertex number corresponding to a vertex id.

Protected functions

auto calculateBoundingBox() const -> QgsRectangle override: Default calculator for the minimal bounding box for the geometry.
auto childCount() const -> int override: Returns number of child geometries (for geometries with child geometries) or child points (for geometries without child geometries - i.e.
auto childGeometry(int index) const -> QgsAbstractGeometry* override: Returns pointer to child geometry (for geometries with child geometries - i.e.
void clearCache() const override: Clears any cached parameters associated with the geometry, e.g., bounding boxes.
auto fromCollectionWkt(const QString& wkt, const QVector<QgsAbstractGeometry*>& subtypes, const QString& defaultChildWkbType = QString()) -> bool: Reads a collection from a WKT string.
auto wktOmitChildType() const -> bool virtual: Returns whether child type names are omitted from Wkt representations of the collection.

Function documentation

bool QgsGeometryCollection::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 QgsGeometryCollection::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 QgsGeometryCollection::adjacentVertices(QgsVertexId vertex, QgsVertexId& previousVertex, QgsVertexId& nextVertex) const override

Returns the vertices adjacent to a specified vertex within a geometry.

double QgsGeometryCollection::area() const override

Returns the area of the geometry.

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

Returns a GeoJSON representation of the geometry.

Parameters
precision	number of decimal places for coordinates

QByteArray QgsGeometryCollection::asWkb() const override

Returns a WKB representation of the geometry.

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

Returns a WKT representation of the geometry.

Parameters
precision	number of decimal places for coordinates

QgsAbstractGeometry* QgsGeometryCollection::boundary() const override

Returns the closure of the combinatorial boundary of the geometry (ie the topological boundary of the geometry).

Returns	boundary for geometry. May be null for some geometry types.

For instance, a polygon geometry will have a boundary consisting of the linestrings for each ring in the polygon.

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

Cast the geom to a QgsGeometryCollection.

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

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

QgsCoordinateSequence QgsGeometryCollection::coordinateSequence() const override

Retrieves the sequence of geometries, rings and nodes.

Returns	coordinate sequence

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

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

Draws the geometry using the specified QPainter.

Parameters
p	destination QPainter

bool QgsGeometryCollection::dropMValue() override

Drops any measure values which exist in the geometry.

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

bool QgsGeometryCollection::dropZValue() override

Drops any z-dimensions which exist in the geometry.

Returns	true if Z values were present and have been removed

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

Sets the geometry from a WKT string.

const QgsAbstractGeometry* QgsGeometryCollection::geometryN(int n) const

Returns a const reference to a geometry from within the collection.

Parameters
n	index of geometry to return

QgsAbstractGeometry* QgsGeometryCollection::geometryN(int n)

Returns a geometry from within the collection.

Parameters
n	index of geometry to return

QString QgsGeometryCollection::geometryType() const override

Returns a unique string representing the geometry type.

bool QgsGeometryCollection::insertGeometry(QgsAbstractGeometry* g, int index) virtual

Inserts a geometry before a specified index and takes ownership.

Parameters
g	geometry to insert. Ownership is transferred to the collection.
index	position to insert geometry before

Returns true in case of success.

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

double QgsGeometryCollection::length() const override

Returns the length of the geometry.

bool QgsGeometryCollection::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 QgsGeometryCollection::nextVertex(QgsVertexId& id, QgsPoint& vertex) const override

Returns next vertex id and coordinates.

Parameters
id	initial value should be the starting vertex id. The next vertex id will be stored in this variable if found.
vertex	container for found node
Returns	false if at end

int QgsGeometryCollection::partCount() const override

Returns count of parts contained in the geometry.

double QgsGeometryCollection::perimeter() const override

Returns the perimeter of the geometry.

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

bool QgsGeometryCollection::removeGeometry(int nr) virtual

Removes a geometry from the collection.

Parameters
nr	index of geometry to remove
Returns	true if removal was successful.

QgsAbstractGeometry* QgsGeometryCollection::segmentize(double tolerance = M_PI_2/90, SegmentationToleranceType toleranceType = MaximumAngle) const override

Returns a geometry without curves.

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

Caller takes ownership

double QgsGeometryCollection::segmentLength(QgsVertexId startVertex) const override

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

QgsGeometryCollection* QgsGeometryCollection::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).

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

QgsGeometryCollection* QgsGeometryCollection::toCurveType() const override

Returns the geometry converted to the more generic curve type.

Returns	the converted geometry. Caller takes ownership

E.g. QgsLineString -> QgsCompoundCurve, QgsPolygon -> QgsCurvePolygon, QgsMultiLineString -> QgsMultiCurve, QgsMultiPolygon -> QgsMultiSurface

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

int QgsGeometryCollection::vertexNumberFromVertexId(QgsVertexId id) const override

Returns the vertex number corresponding to a vertex id.

The vertex numbers start at 0, so a return value of 0 corresponds to the first vertex.

Returns -1 if a corresponding vertex could not be found.

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

int QgsGeometryCollection::childCount() const override protected

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

curve / point)

QgsAbstractGeometry* QgsGeometryCollection::childGeometry(int index) const override protected

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

geom. collection / polygon)

bool QgsGeometryCollection::wktOmitChildType() const virtual protected

Returns whether child type names are omitted from Wkt representations of the collection.