Annotations

Text

class tecplot.annotation.Text(uid, frame)[source]

Text annotation.

Warning

Text objects cannot be created directly. They are returned by the Frame.add_text() method.

Attributes

anchor Anchor location for a text object.
anchor_position Anchor coordinate position (e.g., origin) of the Annotations.
angle Angle of the text box in degrees.
attached Attach the Annotations to a specific Zone or map.
bold Use bold typeface in the text object.
clipping Clipping properties of the Annotations
color Color of the Annotations.
italic Use italic typeface of the text object.
line_spacing Spacing between lines in the text box.
position_coordinate_system Position coordinate system of the text object.
scope The Scope (local or global) of the Annotations.
size The text size in the currently defined text size units.
size_units Units of the text character height.
text_box The text.TextBox object for this Text object.
text_string The text to be displayed in a text box.
typeface The font family used by the Text object.
zone_or_map Zero-based index to the zone or map of this Annotations.
Text.anchor

Anchor location for a text object.

Type:TextAnchor

Specify the anchor point, or fixed point, for the text object. As the text object grows or shrinks, the anchor location is fixed, while the rest of the box adjusts to accommodate the new size. (default = TextAnchor.Left)

There are nine possible anchor position points, corresponding to the left, right, and center positions on the headline, midline, and baseline of the text box.

Example showing how to set the anchor of a text object:

>>> import tecplot as tp
>>> from tecplot.constant import *
>>> text = tp.active_frame().add_text('abc')
>>> text.anchor = TextAnchor.Center
>>> text.anchor
TextAnchor.Center
Text.anchor_position

Anchor coordinate position (e.g., origin) of the Annotations.

Type:2-tuple of floats

This will be \((x,y)\) or \(( heta,r)\) depending on the plot type (Cartesian or polar). This example shows how to set the anchor position of a Text object:

>>> import tecplot as tp
>>> text = tp.active_frame().add_3d_text("abc")
>>> text.anchor_position = (1.0, 2.0)
>>> text.anchor_position.x
1.0
>>> text.anchor_position.y
2.0
Text.angle

Angle of the text box in degrees.

Type:float (degrees counter-clockwise)

The text angle is the orientation of the text relative to the axis. The angle is measured in degrees counter-clockwise from horizontal. Horizontal text is at zero degrees; vertical text is at 90 degrees.

Example showing how to set the angle of a text object:

>>> import tecplot as tp
>>> text = tp.active_frame().add_text('abc')
>>> text.angle = 45
>>> text.angle
45.0
Text.attached

Attach the Annotations to a specific Zone or map.

Type:boolean (default: False)

Example showing how to set the attached property of of a Text object:

>>> import tecplot as tp
>>> text = tp.active_frame().add_text("abc")
>>> text.zone_or_map = 1
>>> text.attached = True
>>> text.zone_or_map
1
>>> text.attached
True
Text.bold

Use bold typeface in the text object.

Type:boolean

Example showing how to set the bold property of a text object:

>>> import tecplot as tp
>>> text = tp.active_frame().add_text('abc')
>>> text.typeface = 'Times'
>>> text.bold = True
>>> text.bold
True
Text.clipping

Clipping properties of the Annotations

Type:Clipping (default: Clipping.ClipToViewport)

Clipping refers to displaying only that portion of an object that falls within a specified clipping region of the plot. If you have specified your text position in the Frame coordinate system, the Annotations will be clipped to the frame.

If you have specified the Grid coordinate system, you can choose to clip your Annotations to the frame or the viewport. The size of the viewport depends on the plot type as follows:

  • 3D Cartesian - The viewport is the same as the frame, so viewport
    clipping is the same as frame clipping.
  • 2D Cartesian/XY Line - The viewport is defined by the extents of
    the X and Y axes.
  • Polar Line/Sketch - By default, the viewport is the same as the
    frame.

Example showing how to set the clipping of a Text:

>>> import tecplot as tp
>>> from tecplot.constant import *
>>> text = tp.active_frame().add_text('abc')
>>> text.clipping = Clipping.ClipToFrame
>>> text.clipping
Clipping.ClipToFrame
Text.color

Color of the Annotations.

Type:Color (default: Color.Black)

Example showing how to set the Color of of a Text object:

>>> import tecplot as tp
>>> from tecplot.constant import *
>>> text = tp.active_frame().add_text("abc")
>>> text.color = Color.Blue
>>> text.Color
Color.Blue
Text.italic

Use italic typeface of the text object.

Type:boolean

Example showing how to set the italic property of a text object:

>>> import tecplot as tp
>>> text = tp.active_frame().add_text('abc')
>>> text.typeface = 'Times'
>>> text.italic = True
>>> text.italic
False
Text.line_spacing

Spacing between lines in the text box.

Type:float (default = 1.0)

Line spacing is dependent on the height of the text and the size unit system in which it is drawn. This example shows how to set the line spacing of a text object:

>>> import tecplot as tp
>>> text = tp.active_frame().add_text('abc')
>>> text.line_spacing = 4
>>> text.line_spacing
4.0
Text.position_coordinate_system

Position coordinate system of the text object.

The text object may be positioned using either the grid coordinate system or the frame coordinate system.

If the position_coordinate_system is CoordSys.Frame, then the size_units property must be Units.Frame or Units.Point.

The text object’s position and text height are adjusted so that it remains identical to its visual appearance in the original coordinate and unit system.

Type:CoordSys, must be either CoordSys.Frame or CoordSys.Grid

If the size units are Units.Grid and the position coordinate system is changed to CoordSys.Frame, then the size units will be changed to Units.Frame. (default = CoordSys.Frame)

Example showing how to set the position coordinate system for a text object:

>>> import tecplot as tp
>>> from tecplot.constant import *
>>> text = tp.active_frame().add_text("abc")
>>> text.position_coordinate_system = CoordSys.Grid
>>> text.position_coordinate_system
CoordSys.Grid

Example showing side effect if size units are CoordSys.Grid and the coordinate system is changed to CoordSys.Frame:

>>> import tecplot as tp
>>> text = tp.active_frame().add_text("abc")
>>> text.size_units = Units.Grid
>>> text.size_units
Units.Grid
>>> # Setting the coord sys to frame will change units to frame.
>>> text.position_coordinate_system = CoordSys.Frame
>>> text.position_coordinate_system
CoordSys.Frame
>>> text.size_units
Units.Frame
Text.scope

The Scope (local or global) of the Annotations.

Type:Scope

Annotations with local scope are displayed only in the frame in which they are created. If the annotation is defined as having global scope, it will appear in all “like” frames. That is, those frames using the same data set as the one in which the annotation was created. (default: Scope.Local)

Example showing how to set the scope of a Text object:

>>> import tecplot as tp
>>> from tecplot.constant import *
>>> text = tp.active_frame().add_text("abc")
>>> text.scope = Scope.Global
>>> text.scope
Scope.Global
Text.size

The text size in the currently defined text size units.

Type:integer

Example showing how to set the text size of a text object:

>>> import tecplot as tp
>>> from tecplot.constant import *
>>> text = tp.active_frame().add_text('abc')
>>> text.size_units = Units.Point
>>> text.size = 14
>>> text.size
14
Text.size_units

Units of the text character height.

Type:Units

Units may be one of the following:

  • Units.Point: Specify character height in points.
  • Units.Frame: Specify character height as a percentage of frame
    height
  • Units.Grid: Specify character height in grid units.

(default = Units.Point)

Notes::

Example showing how to set the units of the character height for a text object:

>>> import tecplot as tp
>>> from tecplot.constant import *
>>> text = tp.active_frame().add_text("abc")
>>> text.position_coordinate_system = CoordSys.Grid
>>> text.size_units = Units.Point
>>> text.size_units
Units.Point
Text.text_box

The text.TextBox object for this Text object.

The text box is a box that is drawn around the text. Note that in order to show the text box, you must set TextBox.type to a value other than TextBox.None.
Type:text.TextBox

Note

This property is read-only.

Example showing how to enable the text box for a text object:

>>> import tecplot as tp
>>> from tecplot.constant import *
>>> text = tp.active_frame().add_text("abc")
>>> text.text_box.type = TextBox.Filled # Show the text box
Text.text_string

The text to be displayed in a text box.

Type:string

You can embed Greek, Math, and User-defined characters into English-font strings by enclosing them with text formatting tags, together with the keyboard characters.

The text formatting tags and their effects are as follows. Format tags are not case sensitive and may be either upper or lower case:

  • <b>…</b> - Boldface
  • <i>…</i> - Italic
  • <verbatim>…</verbatim> - Verbatim
  • <sub>…</sub> - Subscripts
  • <sup>…</sup> - Superscripts
  • <greek>…</greek> - Greek font.
  • <math>…</math> - Math font.
  • <userdef>…</userdef> - User-defined font.
  • <helvetica>…</helvetica> - Helvetica font.
  • <times>…</times> - Times font.
  • <courier>…</courier> - Courier font.

Not all fonts have Bold and/or Italic variants. For fonts that do not have these styles, the <b> and/or <i> tags may have no effect.

Embedding and escaping special characters work only in English-font text; they have no effect in text created in Greek, Math, or User-defined character sets.

You can produce subscripts or superscripts by enclosing any characters with <sub>…</sub> or <sup>…</sup>, respectively. Tecplot 360 has only one level of superscripts and subscripts. Expressions requiring additional levels must be created by hand using multiple text objects. If you alternate subscripts and superscripts, Tecplot 360 positions the superscript directly above the subscript. To produce consecutive superscripts, enclose all superscript characters in a single pair of tags.

To insert a tag into text literally, precede the first angle bracket with a backslash (“”). To insert a backslash in the text, just type two backslashes (“”). This example shows how to set the text string of a text object:

>>> import tecplot as tp
>>> text = tp.active_frame().add_text('abc')
>>> text.text_string
'abc'
>>> text.text_string ='def'
>>> text.text_string
'def'
Text.typeface

The font family used by the Text object.

Type:string

For consistency across various platforms, Tecplot 360 guarantees that the following standard typeface names are available:

  • “Helvetica”
  • “Times”
  • “Courier”
  • “Greek”
  • “Math”
  • “User Defined”

Other typefaces may or may not be available depending on the TrueType fonts available. If the typeface or style is not available, a suitable replacement will be selected. This example shows how to set the typeface of a text object to ‘Times’:

>>> import tecplot as tp
>>> text = tp.active_frame().add_text('abc')
>>> text.typeface = 'Times'
>>> text.typeface
'Times'
Text.zone_or_map

Zero-based index to the zone or map of this Annotations.

Type:Index

Example showing how to set the zone or map Index of a Text object:

>>> import tecplot as tp
>>> text = tp.active_frame().add_text("abc")
>>> text.zone_or_map = 1
>>> text.zone_or_map
1

TextBox

class tecplot.annotation.TextBox(uid, frame)[source]

The Box surrounding a Text object.

Warning

annotation.TextBox objects cannot be created directly. They are returned by the annotation.Text.text_box read-only property.

Attributes

color Border line color of the text box.
fill_color Background fill color of the text box.
line_thickness Border line thickness.
margin Margin between the text and the surrounding border.
position Position of the four corners of the text box.
text_box_type The type of the box surrounding the text object
TextBox.color

Border line color of the text box.

Type:Color (default: Color.Black)

Example showing how to set the outline color of the text box for a text object:

>>> import tecplot as tp
>>> from tecplot.constant import *
>>> text = tp.active_frame().add_text("abc")
>>> text.text_box.type = TextBox.Filled
>>> text.text_box.color = Color.Blue
>>> text.text_box.color
Color.Blue
TextBox.fill_color

Background fill color of the text box.

Type:Color

Example showing how to set the fill color of the text box for a text object:

>>> import tecplot as tp
>>> from tecplot.constant import *
>>> text = tp.active_frame().add_text("abc")
>>> text.text_box.type = TextBox.Filled
>>> text.text_box.fill_color = Color.Blue
>>> text.text_box.fill_color
Color.Blue
TextBox.line_thickness

Border line thickness.

Type:float (greater than 0, default: 0.1)

Example showing how to set the line thickness of the text box for a Text object:

>>> import tecplot as tp
>>> from tecplot.constant import *
>>> text = tp.active_frame().add_text("abc")
>>> text.text_box.type = TextBox.Filled
>>> text.text_box.line_thickness = 0.5
>>> text.text_box.line_thickness
0.5
TextBox.margin

Margin between the text and the surrounding border.

Specify the margin as a percentage of the text character height. Margin must be greater than or equal to 0.0, and may be greater than 100. (default = 20.0)

Type:float

Example showing how to set the margin of the text box for a text object:

>>> import tecplot as tp
>>> from tecplot.constant import *
>>> text = tp.active_frame().add_text("abc")
>>> text.text_box.type = TextBox.Filled
>>> text.text_box.margin = 0.5
>>> text.text_box.margin
0.5
TextBox.position

Position of the four corners of the text box.

Note: This property is read-only.

Type:

8-tuple of floats

There is no default, position will vary with text box properties. Example showing how to query position of the text box for a text object:

>>> import tecplot as tp
>>> from tecplot.constant import *
>>> text = tp.active_frame().add_text("abc")
>>> text.text_box.type = TextBox.Filled
>>> x1,y1,x2,y2,x3,y3,x4,y4 = text.text_box.position
>>> # x1,...,y4 contain the corners of the text box
TextBox.text_box_type

The type of the box surrounding the text object

Type:constant.TextBox

The text box type can be set to the following:

  • None_ - (default) Select this option to specify that no box is
    drawn around the text.
  • Filled - Select this option to specify a filled box around the
    text. A filled box is opaque; if you place it over another Tecplot 360 object, the underlying object cannot be seen.
  • Hollow - Select this to specify a plain box around the text.

Example showing how to set the type of the text box for a text object:

>>> import tecplot as tp
>>> from tecplot.constant import *
>>> text = tp.active_frame().add_text("abc")
>>> text.text_box.text_box_type = TextBox.Filled
>>> text.text_box.text_box_type
TextBox.Filled