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()¶
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 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 assert page2.active # we can bring page1 back to the front: page1.activate() assert page1.active
add_page()¶
delete_page()¶
- tecplot.delete_page(page_to_delete)[source]¶
Removes a
Page
from the layout.This will render any
Page
object pointing to the deletedPage
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 usingThe 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 activePage
: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
orstr
) – The file name of the layout to be loaded. (See note below conerning absolute and relative paths.)- Raises:
TecplotOSError – If file can not be found.
TecplotSystemError – If the file could not be loaded.
Note
Absolute and relative paths with PyTecplot
Relative paths, when used within the PyTecplot API are always from Python’s current working directory which can be obtained by calling
os.getcwd()
. This is true for batch andconnected
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"
andr"\\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
orre.Pattern
) – Case-insensitiveglob-style pattern string
or a compiledregex 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 onlypages
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
orre.Pattern
, optional) – Case-insensitiveglob-style pattern string
or a compiledregex pattern instance
used to match page names.- Returns:
Page
– Generator of pages identified by pattern or all pages if no pattern is specified.
This function returns a generator which can only be iterated over once. It can be converted to a
list
for persistence:import tecplot # iterate over all frames in # all pages and print their names for page in tecplot.pages(): for frame in page.frames(): print(frame.name) # store a persistent list of pages pages = list(tecplot.pages())
frames()¶
- tecplot.frames(frame_pattern=None, page_pattern=None)[source]¶
Returns a generator of frames matching the specified pattern.
- Parameters:
frame_pattern (
str
orre.Pattern
) – Case-insensitiveglob-style pattern string
or a compiledregex pattern instance
used to match the frame by name. All frames are returned if no pattern is specified.page_pattern (
str
orre.Pattern
) – Case-insensitiveglob-style pattern string
or a compiledregex pattern instance
used to match the page by name. All pages are included if no pattern is specified.
- Returns:
Frame
– Generator of frames identified by name patterns.
import tecplot # print name of all frames on all pages for frame in tecplot.frames(): print(frame.name)
save_layout()¶
- tecplot.save_layout(filename, include_data=None, include_preview=None, use_relative_paths=None, post_layout_commands=None, pages=None)[source]¶
Writes the current layout to a file.
- Parameters:
filename (
pathlib.Path
orstr
) – 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 isFalse
. (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
ofPage
objects, optional) – IfNone
, 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 andconnected
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"
andr"\\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
orsave_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:
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 aPage
, holding onto aDataset
and a Plot.- 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 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
Checks if this
Frame
is active.Auxiliary data for this frame.
Color of the background.
The border thickness in units of
Frame.size_pos_units
.The header's background color.
The height in units of
Frame.size_pos_units
.Returns or sets the name.
The
Page
containing this Frame.Returns or sets the current plot type.
(x,y)
position of theFrame
in inches.Show or hide the
Frame
's border.Show or hide the
Frame
's header in the border.The units used for size properties.
Use transparency within this
Frame
.The width in units of
Frame.size_pos_units
.Methods
activate
()Causes this
Frame
to become active.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, ...])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.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.
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_zones(*zones)[source]¶
Returns or sets the active Zones.
- Parameters:
zones (Zones, optional) – The Zone objects, which must be in the
Dataset
attached to thisFrame
, 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:
- Returns:
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
- Frame.add_ellipse(center, size, coord_sys)[source]¶
Place an ellipse annotation on the
Frame
.- Parameters:
center (
tuple
offloats
) – Position \((x, y)\) of the ellipse in the coordinates specified by coord_sys.size (
tuple
offloats
) – 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:
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
- Frame.add_georeferenced_image(image_filename, world_filename)[source]¶
Add a geographic reference image and world file to the
Frame
.- Parameters:
image_filename (
pathlib.Path
orstr
) – The image source file.world_filename (
pathlib.Path
orstr
) – The world file associated with the image.
- Returns:
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
orstr
) – 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
offloats
) – 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:
This example adds an image to the upper left quadrant of the frame:
>>> frame = tp.active_frame() >>> img = frame.add_image('myimage.png', (0, 50), 50)
- Frame.add_latex(text, position=None, coord_sys=None, size_units=None, size=None, anchor=None, zone=None)[source]¶
Adds a
LaTeX text
annotation to the Frame.LaTeX is a computer language designed for typesetting. The most popular use of LaTeX is math and Greek fonts for technical purposes. See the User Manual for instruction on how to setup LaTeX for use with Tecplot 360. Once LaTeX is configured for the GUI version of Tecplot 360 no additional changes are needed for PyTecplot.
- Parameters:
text (
str
) – The text to add to theFrame
. The text string must have a non-zero length.position (
tuple
offloats
(x,y), optional) – The position of the anchor as a percentage of the specified coordinates. (default: (0,0))coord_sys (
CoordSys
, optional) – Coordinate system used to position the anchor of the text object. The possible values are:CoordSys.Grid
orCoordSys.Frame
. (default:CoordSys.Frame
)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)anchor (
TextAnchor
, optional) – Anchor position with respect to the text box. Possible values are:TextAnchor.Left
,TextAnchor.Center
,TextAnchor.Right
,TextAnchor.MidLeft
,TextAnchor.MidCenter
,TextAnchor.MidRight
,TextAnchor.HeadLeft
,TextAnchor.HeadCenter
,TextAnchor.HeadRight
,TextAnchor.OnSide
(default:TextAnchor.Left
)zone (Zone, optional) – Zone or
XYLinemap
to which the text will be attached. (default: None)
- Returns:
annotation.Text
– The resultingtext box
object.
Example
import tecplot as tp from tecplot.constant import TextAnchor frame = tp.active_frame() frame.add_latex(r'$$\zeta(s) = \sum_{n=1}^\infty\frac{1}{n^s}$$', (50,50), size=64, anchor=TextAnchor.Center)
See also
- 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
)
- coord_sys (
- Returns:
One of
annotation.Polyline2D
,annotation.Polyline3D
,annotation.MultiPolyline2D
orannotation.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
- Frame.add_rectangle(corner, size, coord_sys)[source]¶
Place a rectangle annotation on the
Frame
.- Parameters:
center (
tuple
offloats
) – Position \((x, y)\) of the rectangle in the coordinates specified by coord_sys.size (
tuple
offloats
) – 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:
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
- Frame.add_square(corner, size, coord_sys)[source]¶
Place a square annotation on the
Frame
.- Parameters:
corner (
tuple
offloats
) – 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:
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
- 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]¶
-
- Parameters:
text (
str
) – The text to add to theFrame
. The text string must have a non-zero length.position (
tuple
offloats
(x,y), optional) – The position of the anchor as a percentage of the specified coordinates. (default: (0,0))coord_sys (
CoordSys
, optional) – Coordinate system used to position the anchor of the text object. The possible values are:CoordSys.Grid
orCoordSys.Frame
. (default:CoordSys.Frame
)text_type (
TextType
, optional) – Type of text object to create. Options areTextType.Regular
(default) andTextType.LaTeX
. If set toTextType.LaTeX
, most style-related options will be saved but ignored when the text is rendered. These options will only be used if the type of the text object is later changed toTextType.Regular
.typeface (
str
, optional) – The typeface name. For consistency across various platforms, Tecplot guarantees that the following standard typeface names are available: “Helvetica”, “Times”, “Courier”, “Greek”, “Math”, and “User Defined”. Other typefaces may or may not be available depending on the TrueType fonts available. If the typeface name or style is not available, a suitable replacement will be selected. (default: “Helvetica”)bold (
bool
, optional) – Use the bold variation of the specified typeface. (default:True
)italic (
bool
, optional) – Use the italic variation of the specified typeface. (default:False
)size_units (
Units
, optional) – Text sizing units. Possible values are:Units.Grid
,Units.Frame
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:constant.TextBox.None_
,constant.TextBox.Filled
orconstant.TextBox.Hollow
. (default:constant.TextBox.None_
)line_thickness (
float
, optional) – Text box boarder line thickness may be a value in the range from 0.0001 to 100. (default: 0.1)box_color (
Color
, optional) – Text box border line color. 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 or
XYLinemap
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, color=Color.Blue)
See also
- Frame.aux_data¶
Auxiliary data for this frame.
- Returns:
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.border_thickness¶
The border thickness in units of
Frame.size_pos_units
.- Type:
- Frame.create_dataset(name, var_names=None, reset_style=True)[source]¶
Create an empty
Dataset
.This will create a new
Dataset
and replace the existing one, destroying all data associated with it.- Parameters:
name (
str
) – Title of the 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 (
bool
) – Reset style of the activeFrame
before loading theDataset
. (default:True
)
- Returns:
Note
Relationships between
Frame
andDataset
A
Frame
may only hold a singleDataset
, though thisDataset
may be shared between severalFrames
. Therefore, this method will only replace the current dataset when reset_style is set toTrue
and will fail otherwise. If thisFrame
already has aDataset
, it may be more efficient to do one of the following instead:Add a new (blank) frame with
Page.add_frame()
and create aDataset
for this.Add new zones to the existing
Dataset
withDataset.add_ordered_zone()
,Dataset.add_fe_zone()
orDataset.add_poly_zone()
.Change the existing data
in-place
.
Note
Performance considerations for data manipulations.
When performing many data-manipulation operations including adding zones, adding variables, modifying field data or connectivity, and especially in connected mode, it is recommended to do this all with the
tecplot.session.suspend()
. This will prevent the Tecplot engine from trying to “keep up” with the changes. Tecplot will be notified of all changes made upon exit of this context. This may result in significant performance gains for long operations.
- Frame.dataset¶
Dataset
attached to thisFrame
.If no
Dataset
has been created for thisFrame
, 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 theFrame
.
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
orGeoreferencedImage
) – The annotation instance to be removed from theFrame
.
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
- 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
- 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 includesCircle
,Polyline2D
,Polyline3D
and all similar objects:>>> for geom in frame.geometries(): ... print(type(geom)) <class 'tecplot.annotation.geometry.Circle'> <class 'tecplot.annotation.polyline.Polyline2D'>
- Frame.has_dataset¶
Checks to see if the
Frame
as an attachedDataset
Example usage:
>>> if not frame.has_dataset: ... dataset = frame.create_dataset('Dataset', ['x','y','z','p'])
- Type:
- Frame.height¶
The height in units of
Frame.size_pos_units
.- Type:
- Frame.images()[source]¶
Get an iterator for all image objects in the frame.
This method provides access to all
Image
andGeoreferencedImage
instances attached to thisFrame
:>>> 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
orstr
) – 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 andconnected
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"
andr"\\server\path"
Example usage:
>>> frame = tecplot.active_frame() >>> frame.load_stylesheet('my_style.sty')
- Frame.name¶
Returns or sets the name.
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
:import tecplot frame = tecplot.active_frame() frame.name = '3D Data View' # will print: "this frame: 3D Data View" print('this frame:', frame.name)
- Type:
- 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 fromFrame.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
andXYLinePlot
. 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 byconstant.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:
- Frame.position¶
(x,y)
position of theFrame
in inches.The
Frame
x position is relative to the left side of the paper. TheFrame
y position is relative to the top of the paper.If x is
None
, theFrame
x position is not changed. If y isNone
, theFrame
y position is not changed.Set
Frame
position 1 inch from the left side of the paper and two inches from the top of the paper:>>> tp.active_frame().position=(1.0, 2.0)
Move the active
Frame
one inch to the right:>>> tp.active_frame().position=(tp.active_frame().position.x+1, None)
- Type:
- 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
orstr
) – 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 andconnected
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"
andr"\\server\path"
Example usage:
>>> frame = tecplot.active_frame() >>> frame.save_stylesheet('my_style.sty')
- 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.width¶
The width in units of
Frame.size_pos_units
.- Type:
Page¶
- class tecplot.layout.Page(uid)[source]¶
Page
object within a layout, holding onto one or moreFrames
.- Parameters:
uid (
int
, 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.name = 'Page 001' # prints: "Page 001" print(page.name) # prints: "Frame 001" for frame in page.frames(): print(frame.name)
Attributes
Checks if this
Page
is active.Auxiliary data for this page.
Checks if the
Page
exists in the current layout.Name of the page.
Index of the Page
Methods
activate
()Activates the
Page
.Returns the active
Frame
.add_frame
([position, size])delete_frame
(frame)Removes the frame from this
Page
.frame
(pattern)Returns the
Frame
by name.frames
([pattern])tile_frames
([mode])Tile frames based on a certain mode.
- Page.activate()[source]¶
Activates the
Page
.- Raises:
TecplotRuntimeError – Page does not exist.
TecplotSystemError – Could not activate the page.
- Page.active_frame()[source]¶
Returns the active
Frame
.This implicitly activates this
Page
and returns the activeFrame
attached to it.
- Page.add_frame(position=None, size=None)[source]¶
Creates a new
Frame
in thisPage
.- Parameters:
- Returns:
This implicitly activates the
Page
and creates and activates a newFrame
.import tecplot as tp frame = tp.active_page().add_frame(position=(1, 0.25), size=(8, 9))
- Page.aux_data¶
Auxiliary data for this page.
Returns:
AuxData
This is the auxiliary data attached to the page. Such data is written to the layout file by default and can be retrieved later. Example usage:
>>> aux = tp.active_page().aux_data >>> aux['Result'] = '3.14159' >>> print(aux['Result']) 3.14159
- Page.delete_frame(frame)[source]¶
Removes the frame from this
Page
.- Raises:
TecplotRuntimeError – If
Frame
is not in thisPage
.TecplotSystemError – Could not delete the frame.
- Page.exists¶
Checks if the
Page
exists in the current layout.This will return
False
after thePage
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
orre.Pattern
) – Case-insensitiveglob-style pattern string
or a compiledregex pattern instance
used to match the frame by name.- Returns:
Note
A
Page
can containFrames
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 onlyFrames
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
ofFrames
matching the specified pattern.- Parameters:
pattern (
str
orre.Pattern
, optional) – Case-insensitiveglob-style pattern string
or a compiledregex 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 intecplot.pages
andtecplot.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:
- Page.paper¶
The
Paper
defined in thisPage
.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.- Type:
- 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:
- 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
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.