Text
====

.. _fig_text_actor:
.. figure:: ./figs/text/actorref_text.webp
    :figwidth: 100%
    :align: left
    :alt: Two text labels placed in the scene.

    Text actor with two labels placed in the scene.

The text actor places one or more text labels into the scene. Labels can be used to
annotate specific locations, display metadata such as time steps or variable names,
or add any textual information to a visualization.

Creating and Editing Labels
---------------------------

Click **Add text** in the actor configuration to add a new label. Each added label
appears as a sub-entry (**Text 1**, **Text 2**, ...) with its own settings:

* **Text**: the label content. Placeholders are supported (see below).
* **Font**: selects the font from system-installed fonts.
* **Font size** / **Font colour**: appearance of the text.
* **Background**: optional coloured background box behind the text.
* **Coordinate space**: determines how the label is placed in the scene (see below).
* **Anchor**: controls which part of the label is used as the reference point for
  positioning. Options include baseline, upper, lower, and middle, each in left,
  right, and centre variants.

Labels can be removed via the right-click context menu on the **Text N** property.

Coordinate Spaces
-----------------

Each label is placed in one of three coordinate spaces:

* **Clip Space**: the label is anchored to the screen in normalized viewport
  coordinates and stays fixed regardless of camera motion. Suitable for titles,
  timestamps, or other HUD-style overlays.
* **Graphics Space**: the label is placed at a 3-D position in world space and moves
  with the scene as the camera changes.
* **Lon-Lat-P**: the label is anchored to a geographic location specified by
  longitude, latitude, and pressure (hPa). Useful for annotating meteorological
  features at a known geographic position.

In actor interaction mode, labels can be repositioned by dragging them in the viewport.

Placeholders
------------

The text content can include placeholders that are dynamically replaced at render time:

* ``%tN``: replaced by the time of time control N (where N is 0-9). The format of the
  displayed time is set via the **Datetime format** sub-property, which appears when a
  time placeholder is detected. The format string uses the following letters:
  ``d`` (day), ``M`` (month), ``y`` (year), ``h`` (hour), ``m`` (minute), ``s``
  (second). For example, ``ddd yyyy-MM-dd hh:mm`` produces ``Mon 2016-09-22 12:00``.
* ``{%tN-%tM}u``: replaced by the time difference between time controls N and M,
  in unit ``u``. Supported units: ``s`` (seconds), ``m`` (minutes), ``h`` (hours).
* ``%eN``: replaced by the ensemble member of ensemble control N (where N is 0-9).