QgsPointDistanceRenderer class

An abstract base class for distance based point renderers (e.g., clusterer and displacement renderers).

Reference

QgsPointDistanceRenderer handles calculation of point clusters using a distance based threshold. Subclasses must implement drawGroup() to handle the rendering of individual point clusters in the desired style.

Derived classes

class QgsPointClusterRenderer: A renderer that automatically clusters points with the same geographic position.
class QgsPointDisplacementRenderer: A renderer that automatically displaces points with the same geographic location.

Public types

struct GroupedFeature: Contains properties for a feature within a clustered group.
using ClusteredGroup = QList<QgsPointDistanceRenderer::GroupedFeature>: A group of clustered points (ie features within the distance tolerance).

Constructors, destructors, conversion operators

QgsPointDistanceRenderer(const QString& rendererName, const QString& labelAttributeName = QString()): Constructor for QgsPointDistanceRenderer.

Public functions

auto capabilities() -> QgsFeatureRenderer::Capabilities override: Returns details about internals of this renderer.
void checkLegendSymbolItem(const QString& key, bool state) override: item in symbology was checked
auto embeddedRenderer() const -> const QgsFeatureRenderer* override: Returns the current embedded renderer (subrenderer) for this feature renderer.
auto filter(const QgsFields& fields = QgsFields()) -> QString override: If a renderer does not require all the features this method may be overridden and return an expression used as where clause.
auto filterNeedsGeometry() const -> bool override: Returns true if this renderer requires the geometry to apply the filter.
auto labelAttributeName() const -> QString: Returns the attribute name used for labeling points, or an empty string if no labeling will be done by the renderer.
auto labelColor() const -> QColor: Returns the color used for for labeling points.
auto labelFont() const -> QFont: Returns the font used for labeling points.
auto legendKeysForFeature(const QgsFeature& feature, QgsRenderContext& context) const -> QSet<QString> override: Returns legend keys matching a specified feature.
auto legendSymbolItemChecked(const QString& key) -> bool override: items of symbology items in legend is checked
auto legendSymbolItems() const -> QgsLegendSymbolList override: Returns a list of symbology items for the legend.
auto legendSymbolItemsCheckable() const -> bool override: items of symbology items in legend should be checkable
auto minimumLabelScale() const -> double: Returns the minimum map scale (i.e.
auto originalSymbolForFeature(const QgsFeature& feature, QgsRenderContext& context) const -> QgsSymbol* override: Returns symbol for feature.
auto originalSymbolsForFeature(const QgsFeature& feature, QgsRenderContext& context) const -> QgsSymbolList override: Equivalent of originalSymbolsForFeature() call extended to support renderers that may use more symbols per feature - similar to symbolsForFeature()
auto renderFeature(const QgsFeature& feature, QgsRenderContext& context, int layer = -1, bool selected = false, bool drawVertexMarker = false) -> bool override: Render a feature using this renderer in the given context.
void setEmbeddedRenderer(QgsFeatureRenderer* subRenderer) override: Sets an embedded renderer (subrenderer) for this feature renderer.
void setLabelAttributeName(const QString& name): Sets the attribute name for labeling points.
void setLabelColor(const QColor& color): Sets the color to use for for labeling points.
void setLabelFont(const QFont& font): Sets the font used for labeling points.
void setLegendSymbolItem(const QString& key, QgsSymbol* symbol) override: Sets the symbol to be used for a legend symbol item.
void setMinimumLabelScale(double scale): Sets the minimum map scale (i.e.
void setTolerance(double distance): Sets the tolerance distance for grouping points.
void setToleranceMapUnitScale(const QgsMapUnitScale& scale): Sets the map unit scale object for the distance tolerance.
void setToleranceUnit(QgsUnitTypes::RenderUnit unit): Sets the units for the tolerance distance.
void startRender(QgsRenderContext& context, const QgsFields& fields) override: Must be called when a new render cycle is started.
void stopRender(QgsRenderContext& context) override: Must be called when a render cycle has finished, to allow the renderer to clean up.
auto symbolForFeature(const QgsFeature& feature, QgsRenderContext& context) const -> QgsSymbol* override: To be overridden.
auto symbols(QgsRenderContext& context) const -> QgsSymbolList override: Returns list of symbols used by the renderer.
auto symbolsForFeature(const QgsFeature& feature, QgsRenderContext& context) const -> QgsSymbolList override: Returns list of symbols used for rendering the feature.
auto tolerance() const -> double: Returns the tolerance distance for grouping points.
auto toleranceMapUnitScale() const -> const QgsMapUnitScale&: Returns the map unit scale object for the distance tolerance.
auto toleranceUnit() const -> QgsUnitTypes::RenderUnit: Returns the units for the tolerance distance.
void toSld(QDomDocument& doc, QDomElement& element, const QgsStringMap& props = QgsStringMap()) const override: used from subclasses to create SLD Rule elements following SLD v1.1 specs
auto usedAttributes(const QgsRenderContext& context) const -> QSet<QString> override: Returns a list of attributes required by this renderer.
auto willRenderFeature(const QgsFeature& feature, QgsRenderContext& context) const -> bool override: Returns whether the renderer will render a feature or not.

Protected functions

void drawLabels(QPointF centerPoint, QgsSymbolRenderContext& context, const QList<QPointF>& labelShifts, const ClusteredGroup& group): Renders the labels for a group.

Protected variables

QList<ClusteredGroup> mClusteredGroups: Groups of features that are considered clustered together.
bool mDrawLabels: Whether labels should be drawn for points. This is set internally from startRender() depending on scale denominator.
QMap<QgsFeatureId, int> mGroupIndex: Mapping of feature ID to the feature's group index.
QMap<QgsFeatureId, QgsPointXY> mGroupLocations: Mapping of feature ID to approximate group location.
QString mLabelAttributeName: Attribute name for labeling. An empty string indicates that no labels should be rendered.
QColor mLabelColor: Label text color.
QFont mLabelFont: Label font.
int mLabelIndex: Label attribute index (or -1 if none). This index is not stored, it is requested in the startRender() method.
double mMinLabelScale: Maximum scale denominator for label display. A zero value indicates no scale limitation.
std::unique_ptr<QgsFeatureRenderer> mRenderer: Embedded base renderer. This can be used for rendering individual, isolated points.
QgsSpatialIndex* mSpatialIndex: Spatial index for fast lookup of nearby points.
double mTolerance: Distance tolerance. Points that are closer together than this distance are considered clustered.
QgsMapUnitScale mToleranceMapUnitScale: Map unit scale for distance tolerance.
QgsUnitTypes::RenderUnit mToleranceUnit: Unit for distance tolerance.

Private functions

void drawGroup(QPointF centerPoint, QgsRenderContext& context, const ClusteredGroup& group) =0SIP_FORCE virtual: Draws a group of clustered points.

Function documentation

QgsPointDistanceRenderer::QgsPointDistanceRenderer(const QString& rendererName, const QString& labelAttributeName = QString())

Constructor for QgsPointDistanceRenderer.

Parameters
rendererName	name of renderer for registry
labelAttributeName	optional attribute for labeling points

QgsFeatureRenderer::Capabilities QgsPointDistanceRenderer::capabilities() override

Returns details about internals of this renderer.

E.g. if you only want to deal with visible features:

if not renderer.capabilities().testFlag(QgsFeatureRenderer.Filter) or renderer.willRenderFeature(feature, context):
    deal_with_my_feature()
else:
    skip_the_curren_feature()

void QgsPointDistanceRenderer::checkLegendSymbolItem(const QString& key, bool state) override

item in symbology was checked

const QgsFeatureRenderer* QgsPointDistanceRenderer::embeddedRenderer() const override

Returns the current embedded renderer (subrenderer) for this feature renderer.

The base class implementation does not use subrenderers and will always return null.

QString QgsPointDistanceRenderer::filter(const QgsFields& fields = QgsFields()) override

If a renderer does not require all the features this method may be overridden and return an expression used as where clause.

Returns	An expression used as where clause

This will be called once after startRender() and before the first call to renderFeature(). By default this returns a null string and all features will be requested. You do not need to specify the extent in here, this is taken care of separately and will be combined with a filter returned from this method.

QString QgsPointDistanceRenderer::labelAttributeName() const

Returns the attribute name used for labeling points, or an empty string if no labeling will be done by the renderer.

QColor QgsPointDistanceRenderer::labelColor() const

Returns the color used for for labeling points.

QFont QgsPointDistanceRenderer::labelFont() const

Returns the font used for labeling points.

QSet<QString> QgsPointDistanceRenderer::legendKeysForFeature(const QgsFeature& feature, QgsRenderContext& context) const override

Returns legend keys matching a specified feature.

bool QgsPointDistanceRenderer::legendSymbolItemChecked(const QString& key) override

items of symbology items in legend is checked

QgsLegendSymbolList QgsPointDistanceRenderer::legendSymbolItems() const override

Returns a list of symbology items for the legend.

bool QgsPointDistanceRenderer::legendSymbolItemsCheckable() const override

items of symbology items in legend should be checkable

double QgsPointDistanceRenderer::minimumLabelScale() const

Returns the minimum map scale (i.e.

most "zoomed out") at which points should be labeled by the renderer. The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.

QgsSymbol* QgsPointDistanceRenderer::originalSymbolForFeature(const QgsFeature& feature, QgsRenderContext& context) const override

Returns symbol for feature.

The difference compared to symbolForFeature() is that it returns original symbol which can be used as an identifier for renderer's rule - the former may return a temporary replacement of a symbol for use in rendering.

QgsSymbolList QgsPointDistanceRenderer::originalSymbolsForFeature(const QgsFeature& feature, QgsRenderContext& context) const override

Equivalent of originalSymbolsForFeature() call extended to support renderers that may use more symbols per feature - similar to symbolsForFeature()

bool QgsPointDistanceRenderer::renderFeature(const QgsFeature& feature, QgsRenderContext& context, int layer = -1, bool selected = false, bool drawVertexMarker = false) override

Render a feature using this renderer in the given context.

Must be called between startRender() and stopRender() calls. Default implementation renders a symbol as determined by symbolForFeature() call. Returns true if the feature has been returned (this is used for example to determine whether the feature may be labelled).

If layer is not -1, the renderer should draw only a particula layer from symbols (in order to support symbol level rendering).

void QgsPointDistanceRenderer::setEmbeddedRenderer(QgsFeatureRenderer* subRenderer) override

Sets an embedded renderer (subrenderer) for this feature renderer.

Parameters
subRenderer	the embedded renderer. Ownership will be transferred.

The base class implementation does nothing with subrenderers, but individual derived classes can use these to modify their behavior.

void QgsPointDistanceRenderer::setLabelAttributeName(const QString& name)

Sets the attribute name for labeling points.

Parameters
name	attribute name, or empty string to avoid labeling features by the renderer

void QgsPointDistanceRenderer::setLabelColor(const QColor& color)

Sets the color to use for for labeling points.

Parameters
color	label color

void QgsPointDistanceRenderer::setLabelFont(const QFont& font)

Sets the font used for labeling points.

Parameters
font	label font

void QgsPointDistanceRenderer::setLegendSymbolItem(const QString& key, QgsSymbol* symbol) override

Sets the symbol to be used for a legend symbol item.

Parameters
key	rule key for legend symbol
symbol	new symbol for legend item. Ownership is transferred to renderer.

void QgsPointDistanceRenderer::setMinimumLabelScale(double scale)

Sets the minimum map scale (i.e.

most "zoomed out") at which points should be labeled by the renderer. The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.

void QgsPointDistanceRenderer::setTolerance(double distance)

Sets the tolerance distance for grouping points.

Parameters
distance	tolerance distance

Units are specified using setToleranceUnit().

void QgsPointDistanceRenderer::setToleranceMapUnitScale(const QgsMapUnitScale& scale)

Sets the map unit scale object for the distance tolerance.

Parameters
scale	scale for distance tolerance

This is only used if the toleranceUnit() is set to QgsUnitTypes::RenderMapUnits.

void QgsPointDistanceRenderer::setToleranceUnit(QgsUnitTypes::RenderUnit unit)

Sets the units for the tolerance distance.

Parameters
unit	tolerance distance units

void QgsPointDistanceRenderer::startRender(QgsRenderContext& context, const QgsFields& fields) override

Must be called when a new render cycle is started.

Parameters
context	Additional information passed to the renderer about the job which will be rendered
fields	The fields available for rendering

A call to startRender() must always be followed by a corresponding call to stopRender() after all features have been rendered.

void QgsPointDistanceRenderer::stopRender(QgsRenderContext& context) override

Must be called when a render cycle has finished, to allow the renderer to clean up.

Calls to stopRender() must always be preceded by a call to startRender().

QgsSymbol* QgsPointDistanceRenderer::symbolForFeature(const QgsFeature& feature, QgsRenderContext& context) const override

To be overridden.

Parameters
feature	feature
context	render context
Returns	returns pointer to symbol or 0 if symbol was not found

Must be called between startRender() and stopRender() calls.

QgsSymbolList QgsPointDistanceRenderer::symbols(QgsRenderContext& context) const override

Returns list of symbols used by the renderer.

Parameters
context	render context

QgsSymbolList QgsPointDistanceRenderer::symbolsForFeature(const QgsFeature& feature, QgsRenderContext& context) const override

Returns list of symbols used for rendering the feature.

For renderers that do not support MoreSymbolsPerFeature it is more efficient to use symbolForFeature()

double QgsPointDistanceRenderer::tolerance() const

Returns the tolerance distance for grouping points.

Units are retrieved using toleranceUnit().

const QgsMapUnitScale& QgsPointDistanceRenderer::toleranceMapUnitScale() const

Returns the map unit scale object for the distance tolerance.