.. include:: ../macros.hrst .. include:: ../abbreviations.hrst .. _chapter:Annotations: Annotations ########### Explicit labeling and annotation of particular data values is often an important element in data visualization and analysis. ParaView provides a variety of mechanisms to enable annotation in renderings ranging from free floating text rendered alongside other visual elements in the render view to data values associated with particular points or cells. Annotation sources ================== Several types of text annotations can be added through the :guilabel:`Sources > Alphabetical` menu. Text from these sources is drawn on top of 3D elements in the render view. All annotation sources share some common properties under the ``Display`` :index:`\ `\ section of the ``Properties`` :index:`\ `\ panel. These include ``Font Properties`` :index:`\ `\ such as the font to use, the size of the text, its color, opacity, and justification, as well as text effects to apply such as making it bold, italic, or shadowed. .. figure:: ../images/FontProperties.png :name: fig:FontProperties :width: 60% :align: center Font property controls in annotation sources and filters. There are three fonts available in |ParaView|: Arial, Courier, and Times. You can also supply an arbitrary TrueType font file (\*.ttf) to use by selecting the ``File`` :index:`\ `\ entry in the popup menu under ``Font Properties`` :index:`\ `\ and clicking on the ``...`` :index:`\ <...>`\ button to the right of the font file text field. A file selection dialog will appear letting you choose a font file from the file system on which |paraview| (or |pvpython|) is running. The remaining display properties control where the text is placed in the render view. There are two modes for placement, one that uses predefined positions relative to the render view, and one that enables arbitrary interactive placement in the render view. The first mode is active when the ``Use Window Location`` :index:`\ `\ checkbox is selected. It enables the annotation to be placed in one of the four corners of the render view or centered horizontally at the top or bottom of the render view. Buttons with icons representing the location are shown in the ``Pipeline`` :index:`\ `\ browser. These buttons correspond to locations in the render view as depicted in :numref:`fig:AnnotationLocations`. .. figure:: ../images/AnnotationLocations.png :name: fig:AnnotationLocations :width: 80% :align: center Annotation placement buttons and where they place the annotation. The second mode, activated by clicking the ``Lower Left Corner`` :index:`\ `\ checkbox, lets you arbitrarily place the annotation. If the ``Interactivity`` :index:`\ `\ property is enabled, you can click and drag the annotation in the render view to place it, or you can manually enter a location where the lower left corner of the annotation's bounding box should be placed. The coordinates are defined in terms of fractional coordinates that range from [0, 1] in the x and y dimensions. The coordinate system of the render view has a lower left origin, so a ``Lower Left Corner`` :index:`\ `\ value of [0, 0] will place the annotation in the lower left corner of the render view. ``Text`` source ^^^^^^^^^^^^^^^ The ``Text`` :index:`\ `\ source enables you to add a text annotation in the render view. It has one property defining what text is displayed. Text can be multiline, and it can contain numbers and unicode characters. Text may also contain Mathtex expressions between starting and ending dollar signs. Mathtext expressions are a subset of TeX math expressions :cite:`mathtext` . When Mathtext is used, the text can only be on a single line. .. figure:: ../images/TextSource.png :name: fig:TextSource :width: 80% :align: center An example of the ``Text`` :index:`\ `\ source annotation in the upper left corner with a math expression rendered from a Mathtext :cite:`mathtext` expression. ``Annotate Time`` source ^^^^^^^^^^^^^^^^^^^^^^^^ The ``Annotate Time`` :index:`\ `\ source is nearly identical to the ``Text`` :index:`\ `\ source, but it also offers access to the current time value set in ParaView. The time value is placed in the first format specifier in the ``Format`` :index:`\ `\ text property. The format specifier can be any number format valid for ``printf`` and related functions in the C standard library. The default format results in renderig the time value with six decimal digits of precision. Only one format specifier is valid in the property. Additional specifiers after the first will produce undefined results in the annotation text. Annotation filters ================== The annotation sources described in the previous section are available for adding text annotations tht do not depend on any loaded datasets. To create annotations that show values from an available data source in the ``Pipeline Browser`` :index:`\ `\ , several annotation filters are available. The properties available to change the text font and annotation location are exactly the same as those available for the annotation sources described in the previous section. ``Annotate Attribute Data`` filter ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``Annotate Attribute Data`` :index:`\ `\ makes it possible to create an annotation with a data value from an array (or attribute) in a dataset. To use the filter, first select the data array with the data of interest in the ``Select Input Array`` :index:`\ `\ popup menu shows the available field data arrays. The ``Prefix`` :index:`\ `\ and ``Suffix`` :index:`\ `\ properties come before and after the data value in the annotation, respectively. The ``Format`` :index:`\ `\ property is a C language number format specifier. ``Annotate Time Filter`` ^^^^^^^^^^^^^^^^^^^^^^^^ A nice feature of |ParaView| is that it supports data sources that produce different data at different times. Examples include file readers that read in data for a requested time step and certain temporal filters. Each data source advertises to |ParaView| the time values for which it can produce data. The data produced and displayed in ParaView depends on the time you set in the |ParaView| ``VCR Controls`` :index:`\ `\ or ``Time Inspector`` :index:`\