Layout¶

tecplot.layout ¶

Pages, frames and other layout-related operations.

The “layout” consists of a stack of Pages identified by index or name. Each Page consists of a single “workspace” which holds a collection of Frames that are laid out in relation to an area called the Paper.

The Tecplot Engine is guaranteed to have at least one Page which is holding onto at least one Frame. It also has the concept of an active Frame and by extension, an active Page. Most, if not all operations that require a handle to a Frame will use the active Frame by default. This includes any function that operates on objects held by a Frame such as a Cartesian3DFieldPlot or Dataset.

active_frame()¶

tecplot.active_frame()[source]¶

Returns the active frame.

Returns:: Frame – Currently active frame.

active_page()¶

tecplot.active_page()[source]¶

Returns the currently active page.

Returns:: Page – The currently active page.

Only one Page can be active at any given time. As long as the page is not deleted (through a call to new_layout or load_layout for example) this can be used to bring it back to the active state:

import tecplot

page1 = tecplot.active_page()
page2 = tecplot.add_page()

# page2 is now active
assert page2.active

# we can bring page1 back to the front:
page1.activate()
assert page1.active

add_page()¶

tecplot.add_page()[source]¶

Adds a Page to the layout.

Returns:: Page – The newly created page.

This will implicitly activate the newly created page:

import tecplot
page1 = tecplot.active_page()
page2 = tecplot.add_page()
# page2 is now active
assert page2.active

delete_page()¶

tecplot.delete_page(page_to_delete)[source]¶

Removes a Page from the layout.

This will render any Page object pointing to the deleted Page useless. The unique ID will not be used again in the active session and it is up to the user to clear the python object using The del statement:

import tecplot as tp
from tecplot.exception import TecplotRuntimeError

page = tp.add_page()
tp.delete_page(page)

next_page = tp.active_page()

assert page != next_page
assert not page.active

try:
    # the page is gone so activating
    # will produce an exception
    page.activate()
except TecplotRuntimeError as e:
    print(e)

del page # clear the python object

next_page()¶

tecplot.next_page()[source]¶

Activates and returns the next page.

Returns:: layout.Page – The next page in the layout.

Page objects are stored in an ordered stack in the Tecplot Engine. This method rotates the stack and returns the resulting active Page:

import tecplot
from tecplot.layout import next_page

page1 = tecplot.active_page()
page2 = tecplot.add_page()
page3 = next_page()

# page1 is now the active page
# and is the same as page3
assert page1.active
assert page3 == page1

new_layout()¶

tecplot.new_layout()[source]¶

Clears the current layout and creates a blank frame.

This will invalidate any object instances previously obtained:

import tecplot

frame = tecplot.active_frame()
tecplot.new_layout()

# frame object is no longer usable.
# the following will print:
#       <class 'ValueError'> 255 is not a valid PlotType
try:
    frame.plot_type
except Exception as e:
    print(type(e),e)

load_layout()¶

tecplot.load_layout(filename)[source]¶

Reads a layout file and replaces the active frame.

Parameters:

filename (pathlib.Path or str) – The file name of the layout to be loaded. (See note below conerning absolute and relative paths.)

Raises:

TecplotOSError – If file can not be found.
TecplotSystemError – If the file could not be loaded.

Note

Absolute and relative paths with PyTecplot

Relative paths, when used within the PyTecplot API are always from Python’s current working directory which can be obtained by calling os.getcwd(). This is true for batch and connected modes. One exception to this is paths within a macro command or file which will be relative to the Tecplot Engine’s home directory, which is typically the Tecplot 360 installation directory. Finally, when connected to a remote (non-local) instance of Tecplot 360, only absolute paths are allowed.

Note that backslashes must be escaped which is especially important for windows paths such as "C:\\Users" or "\\\\server\\path" which will resolve to "C:\Users" and "\\server\path" respectively. Alternatively, one may use Python’s raw strings: r"C:\Users" and r"\\server\path"

This will replace the current layout and therefore will invalidate any object instances previously obtained:

import os
import tecplot as tp

frame = tp.active_frame()

examples = tp.session.tecplot_examples_directory()
layoutfile = os.path.join(examples, 'SimpleData', 'F18.lay')
tp.load_layout(layoutfile)

# frame object is no longer usable.
# the following will print:
#       <class 'ValueError'> 255 is not a valid PlotType
try:
    frame.plot_type
except Exception as e:
    print(type(e),e)

page()¶

tecplot.page(pattern)[source]¶

Returns the page by name.

Parameters:: pattern (str or re.Pattern) – Case-insensitive glob-style pattern string or a compiled regex pattern instance used to match the page by name.
Returns:: Page – The first page identified by pattern.

Note

A layout can contain pages with identical names and only the first match found is returned. This is not guaranteed to be deterministic and care should be taken to have only pages with unique names when this feature is used.

Example:

import tecplot
page11 = tecplot.add_page()
page11.name = 'Page 11'
page12 = tecplot.add_page()
page12.name = 'Page 12'
assert page12 == tecplot.page('Page 1*')

pages()¶

tecplot.pages(pattern=None)[source]¶

Yields pages matching a specified pattern.

Parameters:: pattern (str or re.Pattern, optional) – Case-insensitive glob-style pattern string or a compiled regex pattern instance used to match page names.
Returns:: Page – Generator of pages identified by pattern or all pages if no pattern is specified.

This function returns a generator which can only be iterated over once. It can be converted to a list for persistence:

import tecplot

# iterate over all frames in
# all pages and print their names
for page in tecplot.pages():
    for frame in page.frames():
        print(frame.name)

# store a persistent list of pages
pages = list(tecplot.pages())

frames()¶

tecplot.frames(frame_pattern=None, page_pattern=None)[source]¶

Returns a generator of frames matching the specified pattern.

Parameters:

frame_pattern (str or re.Pattern) – Case-insensitive glob-style pattern string or a compiled regex pattern instance used to match the frame by name. All frames are returned if no pattern is specified.
page_pattern (str or re.Pattern) – Case-insensitive glob-style pattern string or a compiled regex pattern instance used to match the page by name. All pages are included if no pattern is specified.

Returns:

Frame – Generator of frames identified by name patterns.

import tecplot

# print name of all frames on all pages
for frame in tecplot.frames():
    print(frame.name)

save_layout()¶

tecplot.save_layout(filename, include_data=None, include_preview=None, use_relative_paths=None, post_layout_commands=None, pages=None)[source]¶

Writes the current layout to a file.

Parameters:

filename (pathlib.Path or str) – The path to the output filename. (See note below conerning absolute and relative paths.)
include_data (bool, optional) – Associated value indicates if the layout should be saved as a layout package where the data is included with the style information or if it should reference linked data. If ‘include_data’ is None and the filename ends with ‘.lpk’, then the file will be saved as a layout package file. (default: None)
include_preview (bool, optional) – Associated value indicates if the layout package should also include a preview image. This argument only applies if the include data option is True. (default: True)
use_relative_paths (bool, optional) – Associated value indicates if the layout should be saved using relative paths. This argument only applies if the include data option is False. (default: False)
post_layout_commands (str, optional) – A character string containing a set of Tecplot macro commands that are appended to the layout or layout package file. These can be almost anything and are generally used to store add-on specific state information using $!EXTENDEDCOMMAND commands. (default: None)
pages (list of Page objects, optional) – If None, all pages are written to the layout, otherwise the specified subset of pages are written. (default: None)

Note

Absolute and relative paths with PyTecplot

Relative paths, when used within the PyTecplot API are always from Python’s current working directory which can be obtained by calling os.getcwd(). This is true for batch and connected modes. One exception to this is paths within a macro command or file which will be relative to the Tecplot Engine’s home directory, which is typically the Tecplot 360 installation directory. Finally, when connected to a remote (non-local) instance of Tecplot 360, only absolute paths are allowed.

Note that backslashes must be escaped which is especially important for windows paths such as "C:\\Users" or "\\\\server\\path" which will resolve to "C:\Users" and "\\server\path" respectively. Alternatively, one may use Python’s raw strings: r"C:\Users" and r"\\server\path"

Note

If you receive an exception with the error message “Journal should be valid in all frames”, then you must save a data file using save_tecplot_ascii or save_tecplot_plt before saving the layout.

In this example, we load an example layout file and then save it as a packaged layout file:

import os
import tecplot

examples_dir = tecplot.session.tecplot_examples_directory()
infile = os.path.join(examples_dir, 'SimpleData', 'F18.lay')

tecplot.load_layout(infile)
tecplot.save_layout('output.lpk')

layout.aux_data()¶

tecplot.layout.aux_data()[source]¶

Auxiliary data for the current layout.

Returns:: AuxData

This is the auxiliary data attached to the entire layout containing all frames and datasets currently held by the Tecplot Engine. Such data is written to the layout file by default and can be retrieved later. Example usage:

import tecplot as tp

aux = tp.layout.aux_data()
aux['info'] = '''        This layout contains a lot of things:
    1. Something
    2. Something else
    3. Also this'''

'''
The following will print (including newlines):
    This layout contains a lot of things:
        1. Something
        2. Something else
        3. Also this
'''
print(aux['info'])

Frame ¶

class tecplot.layout.Frame(uid, page)[source]¶

Frame object within a Page, holding onto a Dataset and a Plot.

Parameters:

uid (int, optional) – This must be a valid unique ID number pointing internally to a Frame object or None. A new Frame is created if set to None. (default: None)
page (Page, optional) – The destination Page of this newly created Frame. If None, the currently active Page is used. (default: None)

Warning

Though it is possible to create a Frame object using the constructor, it is usually sufficient to obtain a frame through tecplot.active_frame() or Page.frame(). One can also create a Frame using a Page handle with Page.add_frame().

The concept of the Frame is central to understanding the Tecplot Engine. The Frame is what connects a Dataset to a Plot handle from which one manipulates the desired image as well as accessing the attached data:

import tecplot

frame = tecplot.active_frame()

# will print: 'Frame "Frame 001"'
print(frame)

Attributes

`active`	Checks if this `Frame` is active.
`aux_data`	Auxiliary data for this frame.
`background_color`	Color of the background.
`border_thickness`	The border thickness in units of `Frame.size_pos_units`.
`dataset`	`Dataset` attached to this `Frame`.
`has_dataset`	Checks to see if the `Frame` as an attached `Dataset`
`header_background_color`	The header's background color.
`height`	The height in units of `Frame.size_pos_units`.
`name`	Returns or sets the name.
`page`	The `Page` containing this Frame.
`plot_type`	Returns or sets the current plot type.
`position`	`(x,y)` position of the `Frame` in inches.
`show_border`	Show or hide the `Frame`'s border.
`show_header`	Show or hide the `Frame`'s header in the border.
`size_pos_units`	The units used for size properties.
`transparent`	Use transparency within this `Frame`.
`width`	The width in units of `Frame.size_pos_units`.

Methods

`activate`()	Causes this `Frame` to become active.
`activated`()	Context for temporarily activating this `Frame`.
`active_zones`(*zones)	Returns or sets the active Zones.
`add_circle`(center, radius, coord_sys)	Place a circle annotation on the `Frame`.
`add_ellipse`(center, size, coord_sys)	Place an ellipse annotation on the `Frame`.
`add_georeferenced_image`(image_filename, ...)	Add a geographic reference image and world file to the `Frame`.
`add_image`(filename, position, height)	Add an image to the `Frame`.
`add_latex`(text[, position, coord_sys, ...])	Adds a `LaTeX text` annotation to the Frame.
`add_polyline`(points, *kwargs)	Create a polyline annotation on this `Frame`.
`add_rectangle`(corner, size, coord_sys)	Place a rectangle annotation on the `Frame`.
`add_square`(corner, size, coord_sys)	Place a square annotation on the `Frame`.
`add_text`(text[, position, coord_sys, ...])	Adds a `text` to a `Frame`.
`create_dataset`(name[, var_names, reset_style])	Create an empty `Dataset`.
`delete_geometry`(geom)	Delete a geometry or image annotation object from the `Frame`.
`delete_image`(img)	Delete an image annotation object from the `Frame`.
`delete_text`(text)	Delete a `text` object from a frame.
`geometries`()	Get an iterator for all geometry objects in the frame.
`images`()	Get an iterator for all image objects in the frame.
`load_stylesheet`(filename[, plot_style, ...])	Apply a stylesheet settings file to this frame.
`move_to_bottom`()	Moves `Frame` behind all others in `Page`.
`move_to_top`()	Moves `Frame` in front of all others in `Page`.
`plot`([plot_type])	The primary Plot style-control object.
`save_stylesheet`(filename[, plot_style, ...])	Save the frame's current style to a file.
`texts`()	Get an iterator for all `Text` objects in the frame.

Frame.activate()[source]¶

Causes this Frame to become active.

The parent Page is implicitly “activated” as a side-effect of this operation:

import tecplot

page1 = tecplot.active_page()
frame1 = page1.active_frame()
page2 = tecplot.add_page()
frame2 = page2.active_frame()
assert not (frame1.active and page1.active)
assert frame2.active and page2.active

frame1.activate()
assert not (frame2.active or page2.active)
assert frame1.active and page1.active

Frame.activated()[source]¶

Context for temporarily activating this Frame.

Example:

import tecplot

page = tecplot.active_page()
frame1 = page.active_frame()
frame2 = page.add_frame()

assert frame2.active

with frame1.activated():
    # frame1 is active only during this context
    assert frame1.active
    # there is only one frame active at a time
    assert not frame2.active

assert frame2.active

Frame.active¶

Checks if this Frame is active.

Returns:: bool – True if this Frame is the active Frame.

Frame.active_zones(*zones)[source]¶

Returns or sets the active Zones.

Parameters:: zones (Zones, optional) – The Zone objects, which must be in the Dataset attached to this Frame, that will be activated. All other Zones will be deactivated.
Returns:: Zones – This will return a generator of active Zones in this Frame.

This should only be used on frames with an active plot type that contains a dataset with at least one zone.

Frame.add_circle(center, radius, coord_sys)[source]¶

Place a circle annotation on the Frame.

Parameters:

center (tuple of floats) – Position $(x, y)$ of the center of the circle in the coordinates specified by coord_sys.
radius (float) – The size of the radius in the coordinates specified by coord_sys.
coord_sys (CoordSys) – The coordinate system to use for position and size of this annotation.

Returns:

annotation.Circle

Example usage:

import tecplot
from tecplot.constant import CoordSys

frame = tecplot.active_frame()
circle = frame.add_circle((0.2, 0.2), 0.1, CoordSys.Frame)

Frame.add_ellipse(center, size, coord_sys)[source]¶

Place an ellipse annotation on the Frame.

Parameters:

center (tuple of floats) – Position $(x, y)$ of the ellipse in the coordinates specified by coord_sys.
size (tuple of floats) – Lengths $(h_{axis}, v_{axis})$ of the horizontal and vertical axes in the coordinates specified by coord_sys. Both lengths must be non-zero.
coord_sys (CoordSys) – The coordinate system to use for position and size of this annotation.

Returns:

annotation.Ellipse

Example usage:

import tecplot
from tecplot.constant import CoordSys

frame = tecplot.active_frame()
ellipse = frame.add_ellipse((0.5, 0.5), (0.1, 0.2), CoordSys.Frame)

Frame.add_georeferenced_image(image_filename, world_filename)[source]¶

Add a geographic reference image and world file to the Frame.

Parameters:

image_filename (pathlib.Path or str) – The image source file.
world_filename (pathlib.Path or str) – The world file associated with the image.

Returns:

annotation.GeoreferencedImage

Example usage:

>>> frame = tp.active_frame()
>>> imgfile = 'region.png'
>>> worldfile = 'region.pgw'
>>> geoimg = frame.add_georeferenced_image(imgfile, worldfile)

Frame.add_image(filename, position, height)[source]¶

Add an image to the Frame.

Parameters:

filename (pathlib.Path or str) – The image source file. The format of this file must be Microsoft Windows Bitmap (.bmp), JPEG (.jpg or .jpeg) or Portable Network Graphics (.png).
position (tuple of floats) – Position $(x, y)$ of the image in percentage frame coordinates.
height (float) – The initial size, or height, of the image in percentage frame units. The initial width in frame units is set automatically based on the width to height aspect ratio of the image.

Returns:

annotation.Image

This example adds an image to the upper left quadrant of the frame:

>>> frame = tp.active_frame()
>>> img = frame.add_image('myimage.png', (0, 50), 50)

Frame.add_latex(text, position=None, coord_sys=None, size_units=None, size=None, anchor=None, zone=None)[source]¶

Adds a LaTeX text annotation to the Frame.

LaTeX is a computer language designed for typesetting. The most popular use of LaTeX is math and Greek fonts for technical purposes. See the User Manual for instruction on how to setup LaTeX for use with Tecplot 360. Once LaTeX is configured for the GUI version of Tecplot 360 no additional changes are needed for PyTecplot.

Parameters:

text (str) – The text to add to the Frame. The text string must have a non-zero length.
position (tuple of floats (x,y), optional) – The position of the anchor as a percentage of the specified coordinates. (default: (0,0))
coord_sys (CoordSys, optional) – Coordinate system used to position the anchor of the text object. The possible values are: CoordSys.Grid or CoordSys.Frame. (default: CoordSys.Frame)
size_units (Units, optional) – Text sizing units. Possible values are: Units.Grid, Units.Frame or Units.Point. (default: Units.Point)
size (float, optional) – Text height in the specified units. (default: 14)
anchor (TextAnchor, optional) – Anchor position with respect to the text box. Possible values are: TextAnchor.Left, TextAnchor.Center, TextAnchor.Right, TextAnchor.MidLeft, TextAnchor.MidCenter, TextAnchor.MidRight, TextAnchor.HeadLeft, TextAnchor.HeadCenter, TextAnchor.HeadRight, TextAnchor.OnSide (default: TextAnchor.Left)
zone (Zone, optional) – Zone or XYLinemap to which the text will be attached. (default: None)

Returns:

annotation.Text – The resulting text box object.

Example

import tecplot as tp
from tecplot.constant import TextAnchor

frame = tp.active_frame()
frame.add_latex(r'$$\zeta(s) = \sum_{n=1}^\infty\frac{1}{n^s}$$',
                (50,50), size=64, anchor=TextAnchor.Center)

See also

add_text, delete_text

Frame.add_polyline(*points, **kwargs)[source]¶

Create a polyline annotation on this Frame.

Parameters:: *points (lists of points) – Arrays of $(x, y)$ or $(x, y, z)$ positions of the points along this polyline in the coordinate system specified by coord_sys. If multiple lists are provided, they must be of the same dimension (2D or 3D), though they may be of different lengths.

Keyword Parameters:

coord_sys (CoordSys, optional): The coordinate system to use for: the positions of this annotation. Only 2D polylines may use a coordinate system other than the data-coordinates (“grid”). (default: CoordSys.Grid)

Returns:: One of annotation.Polyline2D, annotation.Polyline3D, annotation.MultiPolyline2D or annotation.MultiPolyline3D.

Example usage:

import tecplot

points = [ [1, 2,  3],
           [2, 4,  9],
           [3, 8, 27], ]

frame = tecplot.active_frame()
polyline = frame.add_polyline(points)

Frame.add_rectangle(corner, size, coord_sys)[source]¶

Place a rectangle annotation on the Frame.

Parameters:

center (tuple of floats) – Position $(x, y)$ of the rectangle in the coordinates specified by coord_sys.
size (tuple of floats) – Size $(width, height)$ of the rectangle in the coordinates specified by coord_sys.
coord_sys (CoordSys) – The coordinate system to use for position and size of this annotation.

Returns:

annotation.Rectangle

Example usage:

import tecplot
from tecplot.constant import CoordSys

frame = tecplot.active_frame()
rectangle = frame.add_rectangle((0.5, 0.5), (0.1, 0.2), CoordSys.Frame)

Frame.add_square(corner, size, coord_sys)[source]¶

Place a square annotation on the Frame.

Parameters:

corner (tuple of floats) – Position $(x, y)$ of the lower-left corner of the square in the coordinates specified by coord_sys.
size (float) – Side-length of the square in the coordinates specified by coord_sys.
coord_sys (CoordSys) – The coordinate system to use for position and size of this annotation.

Returns:

annotation.Square

Example usage:

import tecplot
from tecplot.constant import CoordSys

frame = tecplot.active_frame()
square = frame.add_square((0.2, 0.2), 0.1, CoordSys.Frame)

Frame.add_text(text, position=None, coord_sys=None, text_type=None, typeface=None, bold=None, italic=None, size_units=None, size=None, color=None, angle=None, line_spacing=None, anchor=None, box_type=None, line_thickness=None, box_color=None, fill_color=None, margin=None, zone=None)[source]¶

Adds a text to a Frame.

Parameters:

text (str) – The text to add to the Frame. The text string must have a non-zero length.
position (tuple of floats (x,y), optional) – The position of the anchor as a percentage of the specified coordinates. (default: (0,0))
coord_sys (CoordSys, optional) – Coordinate system used to position the anchor of the text object. The possible values are: CoordSys.Grid or CoordSys.Frame. (default: CoordSys.Frame)
text_type (TextType, optional) – Type of text object to create. Options are TextType.Regular (default) and TextType.LaTeX. If set to TextType.LaTeX, most style-related options will be saved but ignored when the text is rendered. These options will only be used if the type of the text object is later changed to TextType.Regular.
typeface (str, optional) – The typeface name. For consistency across various platforms, Tecplot guarantees that the following standard typeface names are available: “Helvetica”, “Times”, “Courier”, “Greek”, “Math”, and “User Defined”. Other typefaces may or may not be available depending on the TrueType fonts available. If the typeface name or style is not available, a suitable replacement will be selected. (default: “Helvetica”)
bold (bool, optional) – Use the bold variation of the specified typeface. (default: True)
italic (bool, optional) – Use the italic variation of the specified typeface. (default: False)
size_units (Units, optional) – Text sizing units. Possible values are: Units.Grid, Units.Frame or Units.Point. (default: Units.Point)
size (float, optional) – Text height in the specified units. (default: 14)
color (Color, optional) – Color of the text (default: Color.Black)
angle (float, optional) – Angle of the text baseline in degrees from -360 to 360. (default: 0)
line_spacing (float, optional) – Line spacing in units of line size. Can take values from 0 to 50. (default: 1)
anchor (TextAnchor, optional) – Anchor position with respect to the text box. Possible values are: TextAnchor.Left, TextAnchor.Center, TextAnchor.Right, TextAnchor.MidLeft, TextAnchor.MidCenter, TextAnchor.MidRight, TextAnchor.HeadLeft, TextAnchor.HeadCenter, TextAnchor.HeadRight, TextAnchor.OnSide (default: TextAnchor.Left)
box_type (constant.TextBox, optional) – Type of text box can be one of: constant.TextBox.None_, constant.TextBox.Filled or constant.TextBox.Hollow. (default: constant.TextBox.None_)
line_thickness (float, optional) – Text box boarder line thickness may be a value in the range from 0.0001 to 100. (default: 0.1)
box_color (Color, optional) – Text box border line color. See Color for possible values. (default: Color.Black)
fill_color (Color, optional) – Text box fill color. See Color for possible values. (default: White)
margin (float, optional) – Margin between the text and text box. May be in the range from 0 to 2000. (default: 20)
zone (Zone, optional) – Zone or XYLinemap to which the text will be attached. (default: None)

Returns:

annotation.Text – The resulting text box object.

Example:

import tecplot
from tecplot.constant import Color

frame = tecplot.active_frame()
frame.add_text('Hello, World!', position=(35, 50),
               bold=True, italic=False, color=Color.Blue)

See also

add_latex, delete_text

Frame.aux_data¶

Auxiliary data for this frame.

Returns:: AuxData

This is the auxiliary data attached to the frame. Such data is written to the layout file by default and can be retrieved later. Example usage:

>>> aux = tp.active_frame().aux_data
>>> aux['Result'] = '3.14159'
>>> print(aux['Result'])
3.14159

Frame.background_color¶

Color of the background.

Type:: Color

Frame.border_thickness¶

The border thickness in units of Frame.size_pos_units.

Type:: float

Frame.create_dataset(name, var_names=None, reset_style=True)[source]¶

Create an empty Dataset.

This will create a new Dataset and replace the existing one, destroying all data associated with it.

Parameters:

name (str) – Title of the new Dataset. This does not have to be unique.
var_names (list of strings, optional) – Variable names. This only sets the names and not the data type or location. See add_variable. (default: None)
reset_style (bool) – Reset style of the active Frame before loading the Dataset. (default: True)

Returns:

Dataset – The newly created Dataset.

Note

Relationships between Frame and Dataset

A Frame may only hold a single Dataset, though this Dataset may be shared between several Frames. Therefore, this method will only replace the current dataset when reset_style is set to True and will fail otherwise. If this Frame already has a Dataset, it may be more efficient to do one of the following instead:

Add a new (blank) frame with Page.add_frame() and create a Dataset for this.

Add new zones to the existing Dataset with Dataset.add_ordered_zone(), Dataset.add_fe_zone() or Dataset.add_poly_zone().

Change the existing data in-place.

Note

Performance considerations for data manipulations.

When performing many data-manipulation operations including adding zones, adding variables, modifying field data or connectivity, and especially in connected mode, it is recommended to do this all with the tecplot.session.suspend(). This will prevent the Tecplot engine from trying to “keep up” with the changes. Tecplot will be notified of all changes made upon exit of this context. This may result in significant performance gains for long operations.

Frame.dataset¶

Dataset attached to this Frame.

Returns:: Dataset – The object holding onto the data associated with this Frame.

If no Dataset has been created for this Frame, a new one is created and returned:

>>> dataset = frame.dataset

Frame.delete_geometry(geom)[source]¶

Delete a geometry or image annotation object from the Frame.

Parameters:: geom (Circle, Image or similar instance) – The annotation instance to be removed from the Frame.

Warning

After the annotation is deleted, all handles to it will no longer be valid and all accessing any properties of the object will result in a TecplotLogicError being raised.

Example usage:

import tecplot
from tecplot.constant import CoordSys

frame = tecplot.active_frame()
rectangle = frame.add_rectangle((0.5, 0.5), (0.1, 0.2), CoordSys.Frame)
frame.delete_geometry(rectangle)

Frame.delete_image(img)[source]¶

Delete an image annotation object from the Frame.

Parameters:: img (Image or GeoreferencedImage) – The annotation instance to be removed from the Frame.

Warning

After the annotation is deleted, all handles to it will no longer be valid and all accessing any properties of the object will result in a TecplotLogicError being raised.

See also

delete_geometry()

Frame.delete_text(text)[source]¶

Delete a text object from a frame.

When deleted, the text object is no longer displayed in the frame and is permanently invalid. To display the text in the frame again, a new text object must be created by calling add_text.

Warning

Use this method with care. After a text object has been deleted by calling this method, it is no longer valid, and all properties of the deleted text object will throw TecplotLogicError when accessed.

Example usage:

import tecplot as tp

text = tp.active_frame().add_text("abc")
tp.active_frame().delete_text(text)

# The text object is no longer valid.
# Any property access will throw TecplotLogicError
try:
    print(text.text_string)
except tp.exception.TecplotLogicError as e:
    print(e)

See also

add_text

Frame.geometries()[source]¶

Get an iterator for all geometry objects in the frame.

This method provides access to all geometric shape instances attached to this Frame. This includes Circle, Polyline2D, Polyline3D and all similar objects:

>>> for geom in frame.geometries():
...     print(type(geom))
<class 'tecplot.annotation.geometry.Circle'>
<class 'tecplot.annotation.polyline.Polyline2D'>

Frame.has_dataset¶

Checks to see if the Frame as an attached Dataset

Example usage:

>>> if not frame.has_dataset:
...     dataset = frame.create_dataset('Dataset', ['x','y','z','p'])

Type:: bool

Frame.header_background_color¶

The header’s background color.

Type:: Color

Frame.height¶

The height in units of Frame.size_pos_units.

Type:: float

Frame.images()[source]¶

Get an iterator for all image objects in the frame.

This method provides access to all Image and GeoreferencedImage instances attached to this Frame:

>>> for image in frame.images():
...     print(image.filename)
image1.png
image2.png

Frame.load_stylesheet(filename, plot_style=True, text=True, geom=True, streams=True, contours=True, frame_geom=False, merge=False)[source]¶

Apply a stylesheet settings file to this frame.

Parameters:

filename (pathlib.Path or str) – The path to a stylesheet file. (See note below conerning absolute and relative paths.)
plot_style (bool, optional) – Apply the stylesheet’s plot style. (default: True)
text (bool, optional) – Include the stylesheet’s text objects. (default: True)
geom (bool, optional) – Include the stylesheet’s geometry objects. (default: True)
streams (bool, optional) – Include the stylesheet’s stream traces. (default: True)
contours (bool, optional) – Include the stylesheet’s contour levels. (default: True)
frame_geom (bool, optional) – Apply the stylesheet’s frame position and size. (default: False)
merge (bool, optional) – Merge with the frame’s current style. (default: False)

Note

Absolute and relative paths with PyTecplot

Relative paths, when used within the PyTecplot API are always from Python’s current working directory which can be obtained by calling os.getcwd(). This is true for batch and connected modes. One exception to this is paths within a macro command or file which will be relative to the Tecplot Engine’s home directory, which is typically the Tecplot 360 installation directory. Finally, when connected to a remote (non-local) instance of Tecplot 360, only absolute paths are allowed.

Note that backslashes must be escaped which is especially important for windows paths such as "C:\\Users" or "\\\\server\\path" which will resolve to "C:\Users" and "\\server\path" respectively. Alternatively, one may use Python’s raw strings: r"C:\Users" and r"\\server\path"

Example usage:

>>> frame = tecplot.active_frame()
>>> frame.load_stylesheet('my_style.sty')

Frame.move_to_bottom()[source]¶: Moves Frame behind all others in Page.

Frame.move_to_top()[source]¶: Moves Frame in front of all others in Page.

Frame.name¶

Returns or sets the name.

This is the name used when searching for Frame objects in Page.frames and Page.frame. It does not have to be unique, even for multiple frames in a single Page:

import tecplot

frame = tecplot.active_frame()
frame.name = '3D Data View'

# will print: "this frame: 3D Data View"
print('this frame:', frame.name)

Type:: str

Frame.page¶

The Page containing this Frame.

This provides access to the parent Page:

import tecplot

frame = tecplot.active_frame()
page = frame.page

# Will print: "Page 001"
print(page.name)

Frame.plot(plot_type=PlotType.Automatic)[source]¶

The primary Plot style-control object.

Returns:: Plot – One of the possible Plot subclasses, depending on the plot_type specified. By default, the active plot type, obtained from Frame.plot_type, is used.

The Plot object is the handle through which one can manipulate the style and visual representation of the Dataset. Possible return types are: SketchPlot, Cartesian2DFieldPlot, Cartesian3DFieldPlot, PolarLinePlot and XYLinePlot. Each of these have their own specific set of attributes and methods:

import os
import tecplot
from tecplot.constant import PlotType

install_dir = tecplot.session.tecplot_install_directory()
infile = os.path.join(install_dir, 'examples', 'SimpleData', 'SpaceShip.lpk')
tecplot.load_layout(infile)

frame = tecplot.active_frame()
assert frame.plot_type is PlotType.Cartesian3D

plot3d = frame.plot()
plot3d.show_contour = True

Frame.plot_type¶

Returns or sets the current plot type.

A Frame can have only one active plot type at any given time. The types are enumerated by constant.PlotType:

import os
import tecplot
from tecplot.constant import PlotType

frame = tecplot.active_frame()
assert frame.plot_type is PlotType.Sketch

install_dir = tecplot.session.tecplot_install_directory()
infile = os.path.join(install_dir, 'examples', 'SimpleData', 'SpaceShip.lpk')
tecplot.load_layout(infile)

frame = tecplot.active_frame()
assert frame.plot_type is PlotType.Cartesian3D

frame.plot_type = PlotType.Cartesian2D
assert frame.plot_type is PlotType.Cartesian2D

Note

Plot type cannot be set to constant.PlotType.Automatic.

Type:: constant.PlotType

Frame.position¶

(x,y) position of the Frame in inches.

The Frame x position is relative to the left side of the paper. The Frame y position is relative to the top of the paper.

If x is None, the Frame x position is not changed. If y is None, the Frame y position is not changed.

Set Frame position 1 inch from the left side of the paper and two inches from the top of the paper:

>>> tp.active_frame().position=(1.0, 2.0)

Move the active Frame one inch to the right:

>>> tp.active_frame().position=(tp.active_frame().position.x+1, None)

Type:: tuple

Frame.save_stylesheet(filename, plot_style=True, aux_data=True, text=True, geom=True, streams=True, contours=True, defaults=False, relative_paths=True, compress=False)[source]¶

Save the frame’s current style to a file.

Parameters:

filename (pathlib.Path or str) – The path to a stylesheet file. (See note below conerning absolute and relative paths.)
plot_style (bool, optional) – Include the frame’s plot style. (default: True)
aux_data (bool, optional) – Include auxiliary data. (default: True)
text (bool, optional) – Include text objects. (default: True)
geom (bool, optional) – Include geometry objects. (default: True)
streams (bool, optional) – Include stream traces. (default: True)
contours (bool, optional) – Include contour levels. (default: True)
defaults (bool, optional) – Include all factory defaults used by the current style. (default: False)
relative_paths (bool, optional) – Use relative paths. (default: True)
compress (bool, optional) – Compress the output of the style. (default: False)

Note

Absolute and relative paths with PyTecplot

Relative paths, when used within the PyTecplot API are always from Python’s current working directory which can be obtained by calling os.getcwd(). This is true for batch and connected modes. One exception to this is paths within a macro command or file which will be relative to the Tecplot Engine’s home directory, which is typically the Tecplot 360 installation directory. Finally, when connected to a remote (non-local) instance of Tecplot 360, only absolute paths are allowed.

Note that backslashes must be escaped which is especially important for windows paths such as "C:\\Users" or "\\\\server\\path" which will resolve to "C:\Users" and "\\server\path" respectively. Alternatively, one may use Python’s raw strings: r"C:\Users" and r"\\server\path"

Example usage:

>>> frame = tecplot.active_frame()
>>> frame.save_stylesheet('my_style.sty')

Frame.show_border¶

Show or hide the Frame’s border.

Type:: bool

Frame.show_header¶

Show or hide the Frame’s header in the border.

Type:: bool

Frame.size_pos_units¶

The units used for size properties.

Possible values: Paper, Workspace.

Type:: FrameSizePosUnits

Frame.texts()[source]¶

Get an iterator for all Text objects in the frame.

This example shows how to obtain a list of all red Text objects:

>>> from tecplot.constant import Color
>>> all_red_text_objects = [T for T in tp.active_frame().texts()
...                         if T.color == Color.Red]

Frame.transparent¶

Use transparency within this Frame.

Type:: bool

Frame.width¶

The width in units of Frame.size_pos_units.

Type:: float

Page ¶

class tecplot.layout.Page(uid)[source]¶

Page object within a layout, holding onto one or more Frames.

Parameters:: uid (int, optional) – This must be a valid unique ID number pointing internally to a Page object or None. A new Page is created if set to None. (default: None)

Warning

Though it is possible to create a Page object using the constructor, it is usually sufficient to obtain a page through tecplot.add_page, tecplot.active_page, tecplot.page or tecplot.pages.

A Page can be thought of like a canvas onto which one or more Frames can be laid out. The engine guarantees there will always be at least one Page in the layout which can be accessed via tecplot.active_page:

import tecplot

page = tecplot.active_page()
page.name = 'Page 001'

# prints: "Page 001"
print(page.name)

# prints: "Frame 001"
for frame in page.frames():
    print(frame.name)

Attributes

`active`	Checks if this `Page` is active.
`aux_data`	Auxiliary data for this page.
`exists`	Checks if the `Page` exists in the current layout.
`name`	Name of the page.
`paper`	The `Paper` defined in this `Page`.
`position`	Index of the Page

Methods

`activate`()	Activates the `Page`.
`active_frame`()	Returns the active `Frame`.
`add_frame`([position, size])	Creates a new `Frame` in this `Page`.
`delete_frame`(frame)	Removes the frame from this `Page`.
`frame`(pattern)	Returns the `Frame` by name.
`frames`([pattern])	Returns a `list` of `Frames` matching the specified pattern.
`tile_frames`([mode])	Tile frames based on a certain mode.

Page.activate()[source]¶

Activates the Page.

Raises:

TecplotRuntimeError – Page does not exist.
TecplotSystemError – Could not activate the page.

Page.active¶

Checks if this Page is active.

Returns:: bool – True if active.

Page.active_frame()[source]¶

Returns the active Frame.

Returns:: Frame – The active Frame.

This implicitly activates this Page and returns the active Frame attached to it.

Page.add_frame(position=None, size=None)[source]¶

Creates a new Frame in this Page.

Parameters:

position (tuple of floats (x,y), optional) – The position (in inches) of the frame relative to the top left corner of the paper. If supplied, size must also be supplied.
size (tuple of floats (width,height), optional) – The size (in inches) of the frame. If supplied, position must also be supplied.

Returns:

Frame – The newly created and activated Frame.

This implicitly activates the Page and creates and activates a new Frame.

import tecplot as tp

frame = tp.active_page().add_frame(position=(1, 0.25), size=(8, 9))

Page.aux_data¶

Auxiliary data for this page.

Returns: AuxData

This is the auxiliary data attached to the page. Such data is written to the layout file by default and can be retrieved later. Example usage:

>>> aux = tp.active_page().aux_data
>>> aux['Result'] = '3.14159'
>>> print(aux['Result'])
3.14159

Page.delete_frame(frame)[source]¶

Removes the frame from this Page.

Raises:

TecplotRuntimeError – If Frame is not in this Page.
TecplotSystemError – Could not delete the frame.

Page.exists¶

Checks if the Page exists in the current layout.

This will return False after the Page has been deleted:

import tecplot as tp
page = tp.add_page()
assert page.exists
tp.delete_page(page)
assert not page.exists

Page.frame(pattern)[source]¶

Returns the Frame by name.

Parameters:: pattern (str or re.Pattern) – Case-insensitive glob-style pattern string or a compiled regex pattern instance used to match the frame by name.
Returns:: Frame – The first Frame identified by pattern.

Note

A Page can contain Frames with identical names and only the first match found is returned. This is not guaranteed to be deterministic and care should be taken to have only Frames with unique names when this feature is used.

Example:

import tecplot
page = tecplot.active_page()

frameA = page.add_frame()
frameA.name = 'A'

frameB = page.add_frame()
frameB.name = 'B'

assert frameB.active
assert frameA == page.frame('A')

Page.frames(pattern=None)[source]¶

Returns a list of Frames matching the specified pattern.

Parameters:: pattern (str or re.Pattern, optional) – Case-insensitive glob-style pattern string or a compiled regex pattern instance used to match frame names.
Returns:: list – Frames identified by pattern or all frames if no pattern is specified.

Example:

import tecplot

page = tecplot.active_page()
page.add_frame()  # create a second frame

# iterate over all frames and print their names
for frame in page.frames():
    print(frame.name)

# store a persistent list of frames
frames = page.frames()

# prints: ['Frame 001', 'Frame 002']
print([f.name for f in frames])

Page.name¶

Name of the page.

This is the name used when searching for Page objects in tecplot.pages and tecplot.page. It does not have to be unique.

Example:

import tecplot

page = tecplot.active_page()
page.name = 'My Data'

# prints: "this page: My Data"
print('this page:', page.name)

Type:: str

Page.paper¶

The Paper defined in this Page.

Every Page has the concept of a workspace which includes all Frames as well as a sub-area of the workspace called the Paper. The limits of the Paper with respect to the placement of Frames is used when exporting certain image formats.

Type:: Paper

Page.position¶

Index of the Page

The page positions are 0 based positions relative to the current page, where the current page has a position value of 0, the next page 1, the page after that 2, and so on.

Type:: Index

Page.tile_frames(mode=TileMode.Grid)[source]¶

Tile frames based on a certain mode.

Parameters:: mode (TileMode, optional) – Direction and layout mode for tiling frames. Possible values: TileMode.Grid (default), TileMode.Columns, TileMode.Rows, TileMode.Wrap.

Example usage:

>>> from tecplot.constant import TileMode
>>> page.tile_frame(TileMode.Wrap)

Paper ¶

class tecplot.layout.Paper(page)[source]¶

The Paper boundary defined on a workspace.

This is the area used for certain image output formats. It is defined for a specific Page. Frames can be laid out in reference to this sub-area of the workspace.

Attributes

dimensions

Width and height (read-only).

Paper.dimensions¶

Width and height (read-only).

the dimensions, (width, height) in inches, of the currently defined paper in the Tecplot workspace.

Layout¶

tecplot.layout ¶

active_frame()¶

active_page()¶

add_page()¶

delete_page()¶

next_page()¶

new_layout()¶

load_layout()¶

page()¶

pages()¶

frames()¶

save_layout()¶

layout.aux_data()¶

Frame ¶

Page ¶

Paper ¶

Table of Contents

This Page