Layouts

Layouts

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 Returns the active frame.
active_page Returns the currently active page.
add_page Adds a Page to the layout.
export_image Exports image to file.
new_layout Clears the current layout and creates a blank frame.
load_layout Reads a layout file and replaces the active frame.
page Returns the page by name.
pages Yields pages matching a specified pattern.
save_layout Writes the current layout to a file.
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.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)
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.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.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.active_frame()[source]

Returns the active frame.

Returns:Frame – Currently active frame.

Frame

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

Frame object within a Page, holding onto a Dataset and a Plotting Style Manipulation.

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 Plotting Style Manipulation 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.
background_color Color of the background.
border_thickness The border thickness in units of Frame.size_pos_units.
dataset Dataset attached to this Frame.
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.
active_zones Returns or sets the active Zones.
add_text Adds a text to a Frame.
create_dataset Create an empty Dataset.
move_to_bottom Moves Frame behind all others in Page.
move_to_top Moves Frame in front of all others in Page.
plot Returns a Plotting Style Manipulation style-control object.

Special Methods

__str__ Brief string representation.
__repr__ Executable string representation.
__eq__ Checks for Frame equality in the Tecplot Engine.
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.active

Checks if this Frame is active.

Returns:bool – True if this Frame is the active 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.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.page

The Page containing this Frame.

This provides access to the parent Page:

>>> frame = tecplot.active_frame()
>>> page = frame.page
>>> page.name
Page 001

Data and Zones

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

Plot, Annotations and Style

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.plot(plot_type=None)[source]

Returns a Plotting Style Manipulation style-control object.

Type:
Plotting Style Manipulation:

One of the possible Plotting Style Manipulation classes, depending on the plot_type specified. By default, the active plot type, obtained from Frame.plot_type, is used.

The Plotting Style Manipulation 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.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 in 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.height

The height in units of Frame.size_pos_units.

Type:float
Frame.width

The width in units of Frame.size_pos_units.

Type:float
Frame.size_pos_units

The units used for size properties.

Type:FrameSizePosUnits

Possible values: Paper, Workspace.

Frame.show_header

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

Type:bool
Frame.header_background_color

The header’s background color.

Type:Color
Frame.transparent

Use transparency within this Frame.

Type:bool
Frame.background_color

Color of the background.

Type:Color
Frame.show_border

Show or hide the Frame‘s border.

Type:bool
Frame.border_thickness

The border thickness in units of Frame.size_pos_units.

Type:float

Special Methods

Frame.__str__()[source]

Brief string representation.

Returns:string – Brief representation of this Frame.
Example::
>>> import tecplot
>>> frame = tecplot.active_frame()
>>> print(frame)
Frame: "Frame 001"
Frame.__repr__()[source]

Executable string representation.

Returns:string – Internal representation of this Frame.

The string returned can be executed to generate an identical copy of this Frame object:

>>> import tecplot
>>> frame = tecplot.active_frame()
>>> frame_copy = None
>>> print(repr(frame))
Frame(uid=11, page=Page(uid=1))
>>> exec('frame_copy = '+repr(frame))
>>> frame_copy
Frame(uid=11, page=Page(uid=1))

>>> # frame_copy is not technically a copy.
>>> # it is the same object as the original frame:
>>> frame == frame_copy
True
Frame.__eq__(other)[source]

Checks for Frame equality in the Tecplot Engine.

Returns:bool – True if the unique ID numbers are the same for both Frames.
Example::
>>> import tecplot
>>> page = tecplot.active_page()
>>> frame1 = page.active_frame()
>>> frame2 = page.add_frame()
>>> frame1 == frame2
False
>>> page.active_frame() == frame2
True

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.
name Returns or sets the name.
paper The Paper defined in this Page.

Methods

activate Activates the Page.
active_frame Returns the active Frame.
add_frame Creates a new Frame in this Page.
frame Returns the Frame by name.
frames Returns a list of Frames matching the specified pattern.

Special Methods

__str__ Brief string representation.
__repr__ Executable string representation.
__eq__ Checks for Page equality in the Tecplot Engine.
__contains__
__getitem__
__iter__
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.active

Checks if this Page is active.

Returns:bool – True if active.
Page.activate()[source]

Activates the Page.

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

Accessing and Creating Frames

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.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 = frames()
>>> print([f.name for f in frame])
['Frame 001', 'Frame 002']
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.

Special Methods

Page.__str__()[source]

Brief string representation.

Returns:string – Brief representation of this Page.
Example::
>>> import tecplot
>>> page = tecplot.active_page()
>>> print(page)
Page: "Page 001"
Page.__repr__()[source]

Executable string representation.

Returns:string – Internal representation of this Page.

The string returned can be executed to generate an identical copy of this Page object:

>>> import tecplot
>>> page = tecplot.active_page()
>>> page_copy=None
>>> print(repr(page))
Page(uid=1)
>>> exec('page_copy = '+repr(page))
>>> page_copy
Page(uid=11, page=Page(uid=1))

>>> # page_copy is not technically a copy.
>>> # it is the same object as the original page:
>>> page == page_copy
True
Page.__eq__(other)[source]

Checks for Page equality in the Tecplot Engine.

Returns:bool – True if the unique ID numbers are the same for both Pages.

Example:

>>> import tecplot
>>> page1 = tecplot.active_page()
>>> page2 = tecplot.add_page()
>>> page1 == page2
False
>>> tecplot.active_page() == page2
True
Page.__contains__(frame)[source]
Page.__getitem__(pattern)[source]
Page.__iter__()[source]

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.