Skip to content

Latest commit

 

History

History
1134 lines (889 loc) · 53.8 KB

label_settings.rst

File metadata and controls

1134 lines (889 loc) · 53.8 KB

Setting a label

.. only:: html

   .. contents::
      :local:

Labels are textual information you can display on maps. They add details you could not necessarily represent using symbols, and may refer to vector features, raster cells, mesh elements, or simple annotations on the map... Two types of text-related items are available in QGIS:

Formatting the label text

Whether you are configuring a :guilabel:`Text Format` or :guilabel:`Label Settings` item, and depending on the type of layer you are configuring, you will be given the following options:

Properties tab Text format Label settings Vector or mesh layer raster layer
:guilabel:`Text` checkbox checkbox checkbox checkbox
:guilabel:`Formatting` checkbox checkbox checkbox checkbox
:guilabel:`Buffer` checkbox checkbox checkbox checkbox
:guilabel:`Mask`   checkbox checkbox  
:guilabel:`Background` checkbox checkbox checkbox checkbox
:guilabel:`Shadow` checkbox checkbox checkbox checkbox
:guilabel:`Callout`   checkbox checkbox  
:guilabel:`Placement`   checkbox checkbox checkbox
:guilabel:`Rendering`   checkbox checkbox checkbox

Attention!

While for legibility, "feature" is the name used below to indicate the item being labeled, depending on the underlying layer type, it can be replaced by "pixel", "face" or "vertex".

Text tab

img/label_text.png

Labels settings - Text tab

In the text :guilabel:`Text` tab, you can set:

At the bottom of the tab, a widget shows a filterable list of compatible items stored in your :ref:`style manager database <vector_style_manager>`. This allows you to easily configure the current text format or label setting based on an existing one, and also save a new item to the style database: Press the :guilabel:`Save format...` or :guilabel:`Save settings...` button and provide a name and tag(s).

Note

When configuring a :guilabel:`Label Settings` item, text format items are also available in this widget. Select one to quickly overwrite the current :ref:`textual properties <text_format>` of the label. Likewise, you can create/overwrite a text format from there.

Allow HTML Formatting

With :guilabel:`Allow HTML Formatting` enabled, you need to provide the HTML code in the :guilabel:`Value` field. Use whitespaces instead of tabs for any kind of indentation. The expression is parsed and any supported HTML tag overrides its corresponding setting in the labels properties. Because it is impossible to list and detail every HTML tag and CSS property that QGIS currently supports, we invite you to explore and test in your labels the ones supported by the underlying Qt library.

Examples of supported HTML tags:

  • Text formatting, such as italic or bold, e.g.:

    <i>QGIS</i> <b>rocks!</b>

  • Superscript and subscript, where the text will be vertically super or sub aligned and automatically sized to 2/3 of the parent font size. You can also set a fixed font size for the superscript/subscript by including css rules, e.g.:

    <sup style="font-size:33pt">my superscript text</sup>

  • Text horizontal alignment, using either HTML the align="xxx" attribute or center tag. For HTML5 compatibility, prefer using the CSS property text-align.

    Attention!

    Horizontal alignment can not be used for curved labels.

  • Structuring a block of text using header tags (such as h1, h2, ...), or paragraphs (with p, div, br):

    <div class="myDiv">
  <h2>QGIS always rocks!!</h2>
  <p align="center">Let's dive into details of its nice features.</p>
</div>

  • Image insertion: any image format readable by QGIS can be used in HTML label content. It can be served from local file paths, HTTP links, or base64 embedded content, using the src="xxx" attribute. Image sizes can be specified via the width="##" and height="##" attributes, in points unit. If width or height is not specified it will automatically be calculated from the original image size. Images are placed inline only, not as floating images, and not on curved text labels.

    <img src="qgis.png" width=40 height=60>

Examples of supported CSS properties:

  • Font properties (color, font-family, font-size, font-weight, font-style, word-spacing). Note that word-spacing will always use unit points.

  • Text decorations such as underline, overline and line-through (text-decoration)

  • Text alignment (vertical-align, text-align). Horizontal alignment can not be used for curved labels.

  • Line height, in points or percent unit, e.g. "line-height: 40pt" or "line-height: 40%"

  • Background properties such as background-color and background-image. They are supported for block type items (e.g. div) or inline items (e.g. span). For images, the CSS should be formatted as background-image: url(xx) and supports local file paths, HTTP links, or base64 embedded content.

    Attention!

    Backgrounds are not supported for curved text and are always rendered above any background shape for the label, and below drop shadows/buffers properties.

  • Margin properties, available for block type items only, such as div, p, h1,... They can be specified in either the longhand or shorthand way, in points unit only. Negative values can be set for the bottom margin.

    <div class="myDiv">
  <h2 style="margin-left: 5pt; margin-right: 10pt">QGIS still rocks...</h2>
  <p style="margin: 5pt 0pt -10pt 0pt">Thanks to you!!</p>
</div>

CSS properties can be set on HTML tags with the style attribute. The HTML tag span does not apply any formatting to text by itself and is ideal if you just want to apply CSS styling. A CSS property name and its value are separated by a colon (:). Multiple CSS properties are separated by semicolon (;), e.g.:

<span style="text-decoration:underline;text-align:center;color:blue;word-spacing:20">I will be displayed as blue underlined and centered text with increased space between words</span>

Below an example of a HTML-based expression and rendering (applies different colors and underline to the same label):

format(
  '<span style="color:blue">%1</span> ( <span style="color:red"><u>%2 ft</u></span> )',
  title( lower( "Name" ) ),
  round($length)
)
img/label_HTML_formatting.png

Labeling with HTML formatting enabled

Formatting tab

img/label_formatting.png

Label settings - Formatting tab

In the labelformatting :guilabel:`Formatting` tab, you can:

Buffer tab

img/label_buffer.png

Label settings - Buffer tab

To create a buffer around the label, activate the checkbox :guilabel:`Draw text buffer` checkbox in the labelbuffer :guilabel:`Buffer` tab. Then you can:

Background tab

The labelbackground :guilabel:`Background` tab allows you to configure a shape that stays below each label. To add a background, activate the unchecked :guilabel:`Draw Background` checkbox and select the :guilabel:`Shape` type. It can be:

img/label_background.png

Label settings - Background tab

Depending on the selected shape, you need to configure some of the following properties:

Shadow tab

img/label_shadow.png

Label settings - Shadow tab

To add a shadow to the text, enable the labelshadow :guilabel:`Shadow` tab and activate the checkbox :guilabel:`Draw drop shadow`. Then you can:

Configuring interaction with labels

Other than the text formatting settings exposed above, you can also set how labels interact with each others or with the features.

Mask tab

The labelmask :guilabel:`Mask` tab allows you to define a mask area around the labels. This feature is very useful when you have overlapping symbols and labels with similar colors, and you want to make the labels visible. A label mask prevents specified features from drawing within the boundary set for the mask. For example, you could set a label mask so that a specified layer does not draw within 2mm of the label, but allow features from another layer to still show. Label masks are similar to label buffers in that they allow control of the legibility of labels that cover other features. The label buffer draws on top of any underlying features, while the label mask selectively stops other layers from drawing.

img/label_mask.png

Labels settings - Mask tab (with the text sample showing a green background representing another layer being excluded)

To create masking effects on labels:

  1. Activate the checkbox :guilabel:`Enable mask` checkbox in the labelmask tab.
  2. Then you can set:
  3. Select this mask shape as a mask source in the overlapping layer properties labelmask :guilabel:`Mask` tab (see :ref:`vector_mask_menu`).

Callouts tab

A common practice when placing labels on a crowded map is to use callouts - labels which are placed outside (or displaced from) their associated feature are identified with a dynamic line connecting the label and the feature. If one of the two endings (either the label or the feature) is moved, the shape of the connector is recomputed.

img/label_callouts.png

Labels with various callouts settings

To add a callout to a label, enable the labelcallout :guilabel:`Callouts` tab and activate the checkbox :guilabel:`Draw callouts`. Then you can:

  1. Select the :guilabel:`Style` of connector, one of:

  2. Set the properties of the callout. The following table shows the different properties, with description and compatible connector style.

    Label callout properties

    Property

    Style of callout

    Description

    :guilabel:`Fill style`

    Balloons

    A :ref:`fill symbol <vector_fill_symbols>` with full display capabilities, including layer effects, data-defined settings, ... for drawing the balloon shape.

    :guilabel:`Corner radius`

    Corner radius of the speech bubble

    :guilabel:`Wedge width`

    Sets how large the bubble speech connection with feature's pointer should be

    :guilabel:`Margins`

    Margins around the label's text, in the unit of your choice

    :guilabel:`Line style`

    All but balloons

    A :ref:`line symbol <vector_line_symbols>` with full display capabilities, including layer effects, data-defined settings, ... for drawing the connector line.

    :guilabel:`Curvature`

    Curved lines

    The percentage of curvature of the connection line

    :guilabel:`Orientation`

    Orientation, starting from the label to the feature. It can be :guilabel:`Clockwise`, :guilabel:`Counter-clockwise`, or :guilabel:`Automatic` (determining an optimal orientation for each label).

    :guilabel:`Minimum length`

    All but balloons

    Minimum length of the connector line

    :guilabel:`Draw lines to all feature parts`

    In case of a multi-part feature, indicates whether a connector line should be drawn from the label to each geometry part.

    :guilabel:`Label anchor point`

    Controls where the connector line should join to the label text. Available options:

    :guilabel:`Offset from label area`

    Controls the distance from the label anchor point (where the callout line ends). This avoids drawing lines right up against the text.

    :guilabel:`Offset from feature`

    All

    Controls the distance from the feature (or its anchor point if a polygon) where callout lines end. E.g., this avoids drawing lines right up against the edges of the features.

    :guilabel:`Feature anchor point`

    Where the connector line ends on the (polygon) feature. Available options:

    :guilabel:`End point marker`

    Balloons

    A :ref:`marker symbol <vector_marker_symbols>` with full display capabilities including layer effects, data-defined, ... for rendering a marker symbol below the endpoint of the balloon callout.

    :guilabel:`Blend mode`

    All

    Controls the :ref:`blending <blend-modes>` of the callout.

    Under the :guilabel:`Data defined placement` group, coordinates of the :guilabel:`Origin` (on the label side) and/or :guilabel:`Destination` (on the feature side) points of the callout can be controlled. Callouts can also be controlled manually by using the moveLabel Move Label, Diagram or Callout tool in the :ref:`Labeling Toolbar <label_toolbar>`. The start and end points of each callout can be moved this way. The nodes should be highlighted when the mouse pointer is nearby. If needed the Shift Key can be held during the movement. This will snap the point in a way that the angle between the two callout points increments by 15 degrees.

Placement tab

Choose the labelplacement :guilabel:`Placement` tab for configuring label placement and labeling priority. Note that the placement options differ according to the type of vector or mesh layer, namely point, line or polygon, and are affected by the global :ref:`PAL setting <automated_placement>`.

Placement for point layers

Point labels placement modes available are:

  • :guilabel:`Cartographic`: point labels are generated with a better visual relationship with the point feature, following ideal cartographic placement rules. Labels can be placed:

    • at a set :guilabel:`Distance` in :ref:`supported units <unit_selector>`, either from the point feature itself or from the bounds of the symbol used to represent the feature (set in :guilabel:`Distance offset from`). The latter option is especially useful when the symbol size isn't fixed, e.g. if it's set by a data defined size or when using different symbols in a :ref:`categorized <categorized_renderer>` renderer.

    • within a :guilabel:`Maximum Distance` from the feature, which is an optional setting that allows you to control how far a label can be placed from the feature it's labeling. This works alongside the :guilabel:`Distance` setting to create a range for label placement, adding flexibility to position labels more effectively, especially on busy maps, ensuring they fit neatly around their corresponding features.

    • using the :guilabel:`Prioritize Placement` option, which decides what's more important when placing labels. There are two options:

      • :guilabel:`Prefer closer labels`: By default, labels are kept close to the feature.
      • :guilabel:`Prefer position ordering`: The label will try to stay in a specific position (like top left or top right), even if it's a bit farther away from the feature. The label only moves to other positions if there's no room within the maximum distance at your preferred position.

    • following a :guilabel:`Position priority` which dictates placement candidates for anchoring labels around and (centered) over the point feature, and the order in which the positions are tested. The default order, based on guidelines from Krygier and Wood (2011) and other cartographic textbooks, is as follows:

      1. top right
      2. top left
      3. bottom right
      4. bottom left
      5. middle right
      6. middle left
      7. top, slightly right
      8. bottom, slightly left.

      Using the dataDefine Data-defined override button, you can provide a comma separated list of placements in order of priority. This also allows only certain placements to be used, for certain features only, so e.g., for coastal features you can prevent labels being placed over the land.

  • :guilabel:`Around Point`: labels are placed in a circle around the feature with an equal radius set in :guilabel:`Distance`. Additionally you can set :guilabel:`Maximum Distance` from the feature, to control how far a label can be placed from the feature it's labeling. The placement priority is clockwise from the "top right". The position can be constrained using the data-defined :guilabel:`Quadrant` option.

  • :guilabel:`Offset from Point`: labels are placed at an :guilabel:`Offset X,Y` distance from the point feature, in various units, or preferably over the feature. You can use a data-defined :guilabel:`Quadrant` to constrain the placement and can assign a :guilabel:`Rotation` to the label.

Placement for line layers

Label modes for line layers include:

img/line_label_placement.png

Label placement examples for lines

Next to placement modes, you can set:

Placement for polygon layers

You can choose one of the following modes for placing labels of polygons:

img/polygon_label_placement.png

Label placement examples for polygons

Common placement settings

Some label placement settings are available for all layer geometry types:

Geometry Generator

The :guilabel:`Geometry Generator` section allows a user to alter the underlying geometry used to place and render the label, by using :ref:`expressions <vector_expressions>`. This can be useful to perform displacement of the geometry dynamically or to convert it to another geometry (type).

In order to use the geometry generator:

  1. Check the checkbox :guilabel:`Geometry generator` option
  2. Enter the expression generating the geometry to rely on
  3. If relevant, select the geometry type of the expression output: the label geometry-based settings such as placement or rendering are updated to match the new geometry type capabilities.

Some use cases include:

  • Use a geometry which is saved in another field "label_position"

  • Use the :ref:`generated geometry <geometry_generator_symbol>` from the symbology also for labeling

  • Use the @map_scale variable to calculate distances / sizes be zoom level independent.

  • Combined with the curved placement mode, creates a circular label around a point feature:

    exterior_ring(make_circle($geometry, 20))

  • Add a label at the start and the end of a line feature:

    collect_geometries( start_point($geometry), end_point($geometry) )

  • Rely on a smoothed line of a river to get more room for label placement:

    smooth( $geometry, iterations:=30, offset:=0.25, min_length:=10 )
Data Defined

The :guilabel:`Data Defined` group provides direct control on labels placement, on a feature-by-feature basis. It relies on their attributes or an expression to set:

  • the :guilabel:`X` and :guilabel:`Y` coordinate

  • the text alignment over the custom position set above:

  • the text :guilabel:`Rotation`. Rotation is defined as clockwise angle with 0° pointing in the direction of East for Horizontal oriented text and with 0° pointing in North direction for Vertical oriented text. Different units can be defined for the labeling rotation (e.g. degrees, minutes of arc, turns). Check the :guilabel:`Preserve data rotation values` entry if you want to keep the rotation value in the associated field and apply it to the label, whether the label is pinned or not. If unchecked, unpinning the label rotation is reset and its value cleared from the attribute table.

    Note

    Data-defined rotation with polygon features is currently supported only with the :guilabel:`Around centroid` placement mode.

Note

Expressions can not be used in combination with the labels map tools (ie the :guilabel:`Rotate label` and :guilabel:`Move label` tools) to :ref:`data-define <data_defined>` labels placement. The widget will be reset to the corresponding :ref:`auxiliary storage field <vector_auxiliary_storage>`.

Priority

In the :guilabel:`Priority` section you can define the placement priority rank of each label, ie if there are different diagrams or labels candidates for the same location, the item with the higher priority will be displayed and the others could be left out.

The priority rank is also used to evaluate whether a label could be omitted due to a greater weighted :ref:`obstacle feature <labels_obstacles>`.

Obstacles

In some contexts (eg, high density labels, overlapping features...), the labels placement can result in labels being placed over unrelated features.

An obstacle is a feature over which QGIS avoids placing other features' labels or diagrams. This can be controlled from the :guilabel:`Obstacles` section:

  1. Activate the checkbox :guilabel:`Features act as obstacles` option to decide that features of the layer should act as obstacles for any label and diagram (including items from other features in the same layer).

    Instead of the whole layer, you can select a subset of features to use as obstacles, using the dataDefine Data-defined override control next to the option.

  2. Use the :guilabel:`Settings` button to tweak the obstacle's weighting.

    • For every potential obstacle feature you can assign an :guilabel:`Obstacle weight`: any :ref:`label <labels_priority>` or :ref:`diagram <diagram_placement>` whose placement priority rank is greater than this value can be placed over. Labels or diagrams with lower rank will be omitted if no other placement is possible.

      This weighting can also be data-defined, so that within the same layer, certain features are more likely to be covered than others.

    • For polygon layers, you can choose the kind of obstacle the feature is:

      • over the feature's interior: avoids placing labels over the interior of the polygon (prefers placing labels totally outside or just slightly inside the polygon)
      • or over the feature's boundary: avoids placing labels over the boundary of the polygon (prefers placing labels outside or completely inside the polygon). This can be useful for layers where the features cover the whole area (administrative units, categorical coverages, ...). In this case, it is impossible to avoid placing labels within these features, and it looks much better when placing them over the boundaries between features is avoided.

Rendering tab

In the render :guilabel:`Rendering` tab, you can tune when the labels can be rendered and their interaction with other labels and features.

Label options

Under :guilabel:`Label options`:

  • You find the :ref:`scale-based <label_scaledepend>` and the :guilabel:`Pixel size-based` visibility settings.

  • The :guilabel:`Label z-index` determines the order in which labels are rendered, as well in relation with other feature labels in the layer (using data-defined override expression), as with labels from other layers. Labels with a higher z-index are rendered on top of labels (from any layer) with lower z-index.

    Additionally, the logic has been tweaked so that if two labels have matching z-indexes, then:

    • if they are from the same layer, the smaller label will be drawn above the larger label
    • if they are from different layers, the labels will be drawn in the same order as their layers themselves (ie respecting the order set in the map legend).

    Note

    This setting doesn't make labels to be drawn below the features from other layers, it just controls the order in which labels are drawn on top of all the layers' features.

  • :guilabel:`Allow inferior fallback placements`: By default QGIS tries to render labels at their best placement, following your settings. Check this mode to allow features to fallback to worse placement options when there's no other choice, e.g. when a line is too short to fit a curved label text then the label may be placed horizontally just over the feature's center point.

  • With data-defined expressions in :guilabel:`Show label` and :guilabel:`Always Show` you can fine tune which labels should be rendered.

  • Allow to :guilabel:`Show upside-down labels`: alternatives are Never, when rotation defined or always.

  • The :guilabel:`Overlapping labels` group allows you to control whether overlapping labels are permitted for features in the layer and how each of them should be handled:

    • :guilabel:`Never overlap`: never ever place overlapping labels for the layer, even if it means some labels will be missing
    • :guilabel:`Allow overlaps if required`: if the label can't otherwise be placed, draw an overlapping label. This mode will cause the label to be moved to a less ideal placement if possible, e.g. moving the label further from the center of a line or polygon, IF doing so will avoid overlapping labels. But if there's no other positions possible, then draw the label overlapping.
    • :guilabel:`Allow overlaps without penalty`: It doesn't matter at all if the label overlaps other labels or obstacles, that's fine to do and the best placement (e.g most central placement) should always be used even if an alternate further placement is possible which avoids overlaps entirely.

    Allowing both overlapping labels and fallback placements options will guarantee that all features in the layer are labeled... not necessarily at their best rendering!

Feature options

Under :guilabel:`Feature options`: