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.

tecplot.active_frame()[source]

Returns the active frame.

Returns:Frame – Currently active frame.
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, but we can
>>> # bring page1 back to the front:
>>> page1.activate()
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
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 is no longer usable:
>>> try:
...   frame.plot_type
... except Exception as e:
...   print(type(e),e)
...
<class 'ValueError'> 255 is not a valid PlotType
tecplot.load_layout(filename)[source]

Reads a layout file and replaces the active frame.

Raises:

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

>>> import tecplot
>>> frame = tecplot.active_frame()
>>> tecplot.load_layout('analysis.lay')
>>> # frame is no longer usable
tecplot.page(pattern)[source]

Returns the page by name.

Parameters:pattern (string) – Glob-style pattern.
Returns:Page – The first page identified by pattern.

Note

A layout can contain pages with identical names. When the parameter pattern is a string, 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'
>>> page12 == tecplot.page('Page 1*')
True
tecplot.pages(pattern=None)[source]

Yields pages matching a specified pattern.

Parameters:pattern (string, optional) – Glob-style pattern used to match the names of the yielded Page objects. All pages are returned if no pattern is specified. (default: None)
Yields:Page – Generator of pages identified by pattern.

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 pages and print their names
>>> for page in tecplot.pages():
>>>     print(page.name)
>>> # store a persistent list of pages
>>> pages = list(tecplot.pages())
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 (string) – The path to the output filename. Relative to the current working directory.
  • include_data (boolean, 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. (default: False)
  • include_preview (boolean, 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 (boolean, 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 (string, 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)
Raises:

TecplotSystemError

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_binary before saving the layout.

Example

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, '3D', 'JetSurface.lay')
>>> outfile = 'jet_surface.png'
>>> tecplot.load_layout(infile)
>>> tecplot.save_layout('output.lpk', include_data=True)

Frame

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

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

Parameters:
  • uid (integer, 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()
>>> frame
Frame(uid=11, Page(uid=1))
>>> print(frame)
Frame 001

Attributes

active Checks if this Frame is active.
aux_data Returns the auxiliary data object.
background_color Color of the background.
border_thickness The border thickness in units of Frame.size_pos_units.
current
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.
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_text(text[, position, coord_sys, ...]) Adds a text to a Frame.
create_dataset(name[, var_names, reset_style]) Create an empty Dataset.
geometries()
images()
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]) Returns a Plot style-control object.
texts() Get an iterator for all Text objects in the frame.
Frame.activate()[source]

Causes this Frame to become active.

Raises:TecplotSystemError

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()
>>> frame1.active and page1.active
False
>>> frame2.active and page2.active
True
>>> frame1.activate()
>>> frame2.active or page2.active
False
>>> frame1.active and page1.active
True
Frame.activated()[source]

Context for temporarily activating this Frame.

Example:

>>> import tecplot
>>> page = tecplot.active_page()
>>> frame1 = page.active_frame()
>>> frame2 = page.add_frame()
>>> print(frame2.active)
True
>>> with frame1.activated():
>>>     print(frame1.active)
True
>>> print(frame2.active)
True
Frame.active

Checks if this Frame is active.

Returns:boolTrue if this Frame is the active Frame.
Frame.active_zones(*zones)[source]

Returns or sets the active Zones.

Parameters:*zones (Zone or list of 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.
Yields:Zones – This will return a generator of active Zones in this Frame.
Frame.add_text(text, position=None, coord_sys=None, font_family=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 (string) – The text to add to the Frame. The text string must have a non-zero length.
  • position (tuple of floats (x,y) – 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)
  • font_family (string, optional) – The typeface family name. For consistency across various platforms, Tecplot guarantees that the following standard typeface family names are available: “Helvetica”, “Times”, “Courier”, “Greek”, “Math”, and “User Defined”. Other typeface family names may or may not be available depending on the TrueType fonts available. If the typeface family name or style is not available, a suitable replacement will be selected. (default: “Helvetica”)
  • bold (boolean, optional) – Use the bold typeface of the specified font family. (default: True)
  • italic (boolean, optional) – Use the italic typeface of the specified font family. (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: TextBox.None_, TextBox.Filled or TextBox.Hollow. (default: 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, text_color=Color.Blue)
Frame.aux_data

Returns the auxiliary data object.

Type:data.AuxData

This is a generic container for arbitrary data attached to this Frame. See AuxData for more details.

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=False)[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.

Raises:

TecplotSystemError

Frame.current
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.

Frame.geometries()[source]
Frame.has_dataset

Checks to see if the Frame as an attached Dataset

Returns:boolTrue if the Frame has a Dataset
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]
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.

Type:string

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.

Example:

>>> import tecplot
>>> frame = tecplot.active_frame()
>>> frame.name = '3D Data View'
>>> print('this frame:', frame.name)
this frame: 3D Data View
Frame.page

The Page containing this Frame.

This provides access to the parent Page:

>>> frame = tecplot.active_frame()
>>> page = frame.page
>>> page.name
Page 001
Frame.plot(plot_type=<PlotType.Automatic: 0>)[source]

Returns a Plot style-control object.

Type:
Plot:

One of the possible Plot classes, 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.

Example:

>>> frame = tecplot.active_frame()
>>> frame.plot_type
<PlotType.Cartesian3D: 1>
>>> plot3d = frame.plot()
>>> plot3d.show_contour = True
Frame.plot_type

Returns or sets the current plot type.

Type:constant.PlotType
Raises:TecplotSystemError

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

>>> import tecplot
>>> from tecplot.constant import PlotType

>>> tecplot.load_layout('mylayout.lay')
>>> frame = tecplot.active_frame()
>>> frame.plot_type
<PlotType.Sketch: 4>
>>> frame.plot_type = PlotType.Cartesian3D
>>> frame.plot_type
<PlotType.Cartesian3D: 1>
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.

Type:FrameSizePosUnits

Possible values: Paper, Workspace.

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:

>>> import tecplot as tp
>>> 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 (integer, 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
Page(uid=1)
>>> for frame in page.frames():
...   print(frame)
Frame 001

Attributes

active Checks if this Page is active.
exists Checks if the Page exists in the current layout.
name Returns or sets the name.
paper The Paper defined in this Page.
position Returns the position of the Page

Methods

activate() Activates the Page.
activated()
active_frame() Returns the active Frame.
add_frame() 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.activated()[source]
Page.active

Checks if this Page is active.

Returns:boolTrue 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()[source]

Creates a new Frame in this Page.

Returns:

Frame – The newly created and activated Frame.

Raises:

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

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()
>>> page.exists
True
>>> page.delete()
>>> page.exists
False
Page.frame(pattern)[source]

Returns the Frame by name.

Parameters:pattern (string) – glob-style pattern.
Returns:Frame – The first Frame identified by pattern.

Note

A Page can contain Frames with identical names. When the parameter pattern is a string, 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('A')
>>> frameB = page.add_frame('B')
>>> frameA == page.frame('A')
True
Page.frames(pattern=None)[source]

Returns a list of Frames matching the specified pattern.

Parameters:pattern (string, optional) – Glob-style pattern used to match the names of the yielded Frame objects. All frames are returned if no pattern is specified. (default: None)
Returns:`list` (Frame) – Frames identified by pattern.

Example:

>>> import tecplot
>>> page = tecplot.active_page()

>>> # iterate over all frames and print their names
>>> for frame in page.frames():
>>>     print(frame.name)
Frame 001
Frame 002
>>> # store a persistent list of frames
>>> frames = page.frames()
>>> print([f.name for f in frames])
['Frame 001', 'Frame 002']
Page.name

Returns or sets the name.

Type:string

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'
>>> print('this page:', page.name)
this page: My Data
Page.paper

The Paper defined in this Page.

Type:Paper

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

Returns the position of the Page :type: Index

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.

Page.tile_frames(mode=<TileMode.Grid: 'TILEFRAMESSQUARE'>)[source]

Tile frames based on a certain mode.

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.
Paper.dimensions

Width and height.

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