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:

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:
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

bool: 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

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

show_border

bool: Show or hide the Frame's border.

show_header

bool: Show or hide the Frame's header in the border.

size_pos_units

The units used for size properties.

transparent

bool: 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)

See also

add_ellipse, add_rectangle, add_square, add_polyline

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)

See also

add_circle, add_rectangle, add_square, add_polyline

Frame.add_georeferenced_image(image_filename, world_filename)[source]

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

Parameters:
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:
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)
../_images/frame_add_latex.png

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)

See also

add_circle, add_ellipse, add_rectangle, add_square

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)

See also

add_circle, add_ellipse, add_square, add_polyline

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)

See also

add_circle, add_ellipse, add_rectangle, add_polyline

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:
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:
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:

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

bool: 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'])
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

tuple: (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)
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

bool: Show or hide the Frame’s border.

Frame.show_header

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

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

bool: Use transparency within this Frame.

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

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:
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:
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

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.

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.