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: TecplotOSError
– If file can not be found.TecplotSystemError
– If the file could not be loaded.
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 isFalse
. (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
ofPage
objects, optional) – IfNone
, all pages are written to the layout, otherwise the specified subset of pages are written. (default:None
)
Raises: 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
orsave_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)
- filename (
-
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 tonew_layout
orload_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 yieldedPage
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())
Frame¶
-
class
tecplot.layout.
Frame
(uid, page)[source]¶ Frame
object within aPage
, holding onto aDataset
and a Plotting Style Manipulation.Parameters: Warning
Though it is possible to create a
Frame
object using the constructor, it is usually sufficient to obtain a frame throughtecplot.active_frame()
orPage.frame()
. One can also create aFrame
using aPage
handle withPage.add_frame()
.The concept of the
Frame
is central to understanding the Tecplot Engine. TheFrame
is what connects aDataset
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 thisFrame
.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 aFrame
.create_dataset
Create an empty Dataset
.move_to_bottom
Moves Frame
behind all others inPage
.move_to_top
Moves Frame
in front of all others inPage
.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 inPage.frames
andPage.frame
. It does not have to be unique, even for multiple frames in a singlePage
.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 thisFrame
is the activeFrame
.
-
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.
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 thisFrame
.Returns: Dataset
– The object holding onto the data associated with thisFrame
.If no
Dataset
has been created for thisFrame
, 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: - name (
string
) – Title of the newDataset
. This does not have to be unique. - var_names (
list
ofstrings
, optional) –Variable
names. This only sets the names and not the data type or location. Seeadd_variable
. (default:None
) - reset_style (
boolean
) – Reset style of the activeFrame
before loading theDataset
. (default:False
)
Returns: Raises: - name (
-
Frame.
active_zones
(*zones)[source]¶ Returns or sets the active
Zones
.Parameters: *zones ( Zone
orlist
ofZones
, optional) – TheZone
objects, which must be in theDataset
attached to thisFrame
, that will be activated. All otherZones
will be deactivated.Yields: Zones
– This will return a generator of activeZones
in thisFrame
.
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 byconstant.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 fromFrame.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
andXYLinePlot
. 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]¶ -
Parameters: - text (
string
) – The text to add to theFrame
. The text string must have a non-zero length. - position (
tuple
offloats
(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
orCoordSys.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
orUnits.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
orTextBox.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. SeeColor
for possible values. (default:Color.Black
) - fill_color (
Color
, optional) – Text box fill color. SeeColor
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
orXYLinemap
to which the text will be attached. (default: None)
Returns: annotation.Text
– The resultingtext 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)
- text (
-
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
-
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 thisFrame
.- Example::
>>> import tecplot >>> frame = tecplot.active_frame() >>> print(frame) Frame: "Frame 001"
-
Frame.
__repr__
()[source]¶ Executable string representation.
Returns: string
– Internal representation of thisFrame
.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 bothFrames
.- 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 moreFrames
.Parameters: uid ( integer
, optional) – This must be a valid unique ID number pointing internally to aPage
object orNone
. A newPage
is created if set toNone
. (default:None
)Warning
Though it is possible to create a
Page
object using the constructor, it is usually sufficient to obtain a page throughtecplot.add_page
,tecplot.active_page
,tecplot.page
ortecplot.pages
.A
Page
can be thought of like a canvas onto which one or moreFrames
can be laid out. The engine guarantees there will always be at least onePage
in the layout which can be accessed viatecplot.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 thisPage
.Methods
activate
Activates the Page
.active_frame
Returns the active Frame
.add_frame
Creates a new Frame
in thisPage
.frame
Returns the Frame
by name.frames
Returns a list
ofFrames
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 intecplot.pages
andtecplot.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.
activate
()[source]¶ Activates the
Page
.Raises: TecplotRuntimeError
– Page does not exist.TecplotSystemError
– Could not activate the page.
-
Page.
paper
¶ The
Paper
defined in thisPage
.Type: Paper
Every
Page
has the concept of a workspace which includes allFrames
as well as a sub-area of the workspace called thePaper
. The limits of thePaper
with respect to the placement ofFrames
is used when exporting certain image formats.
Accessing and Creating Frames¶
-
Page.
active_frame
()[source]¶ Returns the active
Frame
.Returns: Frame
– The activeFrame
.This implicitly activates this
Page
and returns the activeFrame
attached to it.
-
Page.
frame
(pattern)[source]¶ Returns the
Frame
by name.Parameters: pattern ( string
) –glob-style
pattern.Returns: Frame
– The firstFrame
identified by pattern.Note
A
Page
can containFrames
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 onlyFrames
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
ofFrames
matching the specified pattern.Parameters: pattern ( string
, optional) –Glob-style pattern
used to match the names of the yieldedFrame
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 thisPage
.Returns: Raises: TecplotRuntimeError
– Could not find active frame.TecplotSystemError
– Could not create a new frame.
This implicitly activates the
Page
and creates and activates a newFrame
.
Special Methods¶
-
Page.
__str__
()[source]¶ Brief string representation.
Returns: string
– Brief representation of thisPage
.- Example::
>>> import tecplot >>> page = tecplot.active_page() >>> print(page) Page: "Page 001"
-
Page.
__repr__
()[source]¶ Executable string representation.
Returns: string
– Internal representation of thisPage
.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 bothPages
.Example:
>>> import tecplot >>> page1 = tecplot.active_page() >>> page2 = tecplot.add_page() >>> page1 == page2 False >>> tecplot.active_page() == page2 True
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.