Rule-based labelling in QGIS 2.12

The new QGIS 2.12 (Lyon) will be out soon!

In this release, we have revamped the labelling engine and made it more flexible in-line with the rest of vector styling.  

In this release, we have:

• Revamped the labelling engine
• Added support for mutually exclusive layer tree groups
• Developed raster alignment tool

For users

In previous versions of QGIS, users can select a field value or use an expression as labels for a vector layer. In QGIS 2.12, users can  additionally define rules to label vector layers. Rule-based labelling works in the similar way as "Style". A list of rules will be defined by users and they will be applied from top-to-bottom.

Field based labelling (Click to enlarge)

Rule based labelling (Click to enlarge)

To achieve  the same effect in the earlier versions of QGIS, users should add a complex expression.The example below shows the expression used in earlier versions of QGIS:

CASE WHEN  length( "htmlname" ) > 13 AND strpos("htmlname",' ') > 6  THEN  replace("htmlname",' ','  ') WHEN  length( "htmlname" ) > 20 AND "htmlname"  LIKE '%Golf Course' THEN  regexp_replace("htmlname",'Golf Course',' Golf Course') WHEN  length( "htmlname" ) > 20 AND "htmlname"  LIKE '%Nature Reserve' THEN  regexp_replace("htmlname",'Nature Reserve',' Nature Reserve') WHEN  length( "htmlname" ) > 20 AND "htmlname"  LIKE '%Church Of England%' THEN  regexp_replace("htmlname",'Church Of England',' Church Of England ')  WHEN  length( "htmlname" ) > 13 AND "htmlname"  LIKE '% Of The %' THEN  regexp_replace("htmlname",'Of The','Of The ') WHEN  length( "htmlname" ) > 13 AND "htmlname"  LIKE '% of %' AND  "fontcolour" <> 2 AND  "fontcolour" <>  4 THEN  regexp_replace("htmlname",' of ',' of  ')  WHEN "htmlname" LIKE '%/%' THEN regexp_replace("htmlname",'/','/  ') WHEN  length( "htmlname" ) > 30 THEN  replace("htmlname",' ','  ')  ELSE  "htmlname"  END


As you can see, without rule-based labelling users have to define each case and the labelling text. Additionally, with the cumbersome task of defining each case, users are limited to using specific labelling formats (e.g. font color, font size, visibility range, etc). With the new labelling engine, users can define their labels similarly to styles - in fact they can copy the rules from styling tabs and use it within the new labelling section!

Examples of label rules (Click to enlarge)

For developers

In order to facilitate addition of rule-based labelling, some internal changes were made to the QGIS labelling engine interface. The labelling is now driven by the new class QgsLabelingEngineV2 which may have several label providers associated with it.The label providers are objects derived from QgsAbstractLabelProvider and they are responsiblefor:

1. providing "label features" that define properties of each label and geometry of the feature they represent; and
2. drawing of labels at the positions determined by the engine.

Currently there are label provider implementations for diagrams, simple labelling and rule-based labelling.

The existing labelling engine (QgsPalLabeling class) is now built on top of the new labelling engine and works as a wrapper for it so that existing code that uses QgsPalLabeling still works.

As of now, the API for the new labelling engine is not considered as complete and therefore not available in Python. The idea is to make it easier to use, more polished and better prepared for the future use cases. It will be likely finished during the 2.14 release cycleand some changes may need to be postponed to QGIS 3.0 where backwards incompatible API changes will be allowed (as of now, QGIS 3.0 is being intensively discussed on QGIS developer mailing list).

Funding

This rule-based labeling has been funded by Tuscany Region (Italy). Special thanks also to the QGIS developers for their help with bug fixing.