# Layout

## tecplot.layout

Pages, frames and other layout-related operations.

The “layout” consists of a stack of `Pages` identified by index or `name`. Each `Page` consists of a single “workspace” which holds a collection of `Frames` that are laid out in relation to an area called the `Paper`.

The Tecplot Engine is guaranteed to have at least one `Page` which is holding onto at least one `Frame`. It also has the concept of an active `Frame` and by extension, an active `Page`. Most, if not all operations that require a handle to a `Frame` will use the active `Frame` by default. This includes any function that operates on objects held by a `Frame` such as a `Cartesian3DFieldPlot` or `Dataset`.

## active_frame()

tecplot.active_frame()

  Returns the active frame.

  Returns:

    `Frame` – Currently active frame.

## active_page()

tecplot.active_page()

  Returns the currently active page.

  Returns:

    `Page` – The currently active page.

  Only one `Page` can be active at any given time. As long as the page is not deleted (through a call to `new_layout` or `load_layout` for example) this can be used to bring it back to the active state:

      import tecplot

      page1 = tecplot.active_page()
      page2 = tecplot.add_page()

      # page2 is now active
      assert page2.active

      # we can bring page1 back to the front:
      page1.activate()
      assert page1.active

## add_page()

tecplot.add_page()

  Adds a `Page` to the layout.

  Returns:

    `Page` – The newly created page.

  This will implicitly activate the newly created page:

      import tecplot
      page1 = tecplot.active_page()
      page2 = tecplot.add_page()
      # page2 is now active
      assert page2.active

## delete_page()

tecplot.delete_page(page_to_delete)

  Removes a `Page` from the layout.

  This will render any `Page` object pointing to the deleted `Page` useless. The unique ID will not be used again in the active session and it is up to the user to clear the python object using `The del statement`:

      import tecplot as tp
      from tecplot.exception import TecplotRuntimeError

      page = tp.add_page()
      tp.delete_page(page)

      next_page = tp.active_page()

      assert page != next_page
      assert not page.active

      try:
          # the page is gone so activating
          # will produce an exception
          page.activate()
      except TecplotRuntimeError as e:
          print(e)

      del page # clear the python object

## next_page()

tecplot.next_page()

  Activates and returns the next page.

  Returns:

    `layout.Page` – The next page in the layout.

  `Page` objects are stored in an ordered stack in the Tecplot Engine. This method rotates the stack and returns the resulting active `Page`:

      import tecplot
      from tecplot.layout import next_page

      page1 = tecplot.active_page()
      page2 = tecplot.add_page()
      page3 = next_page()

      # page1 is now the active page
      # and is the same as page3
      assert page1.active
      assert page3 == page1

## new_layout()

tecplot.new_layout()

  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)

  Reads a layout file and replaces the active frame.

  Parameters:

    filename (`str`) – 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 and `connected` modes. One exception to this is paths within a macro command or file which will be relative to the Tecplot Engine’s home directory, which is typically the Tecplot 360 installation directory. Finally, when connected to a remote (non-local) instance of Tecplot 360, only absolute paths are allowed.

  Note that backslashes must be escaped which is especially important for windows paths such as `"C:\\Users"` or `"\\\\server\\path"` which will resolve to `"C:\Users"` and `"\\server\path"` respectively. Alternatively, one may use Python’s raw strings: `r"C:\Users"` and `r"\\server\path"`

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

      import os
      import tecplot as tp

      frame = tp.active_frame()

      examples = tp.session.tecplot_examples_directory()
      layoutfile = os.path.join(examples, 'SimpleData', 'F18.lay')
      tp.load_layout(layoutfile)

      # frame object is no longer usable.
      # the following will print:
      #       <class 'ValueError'> 255 is not a valid PlotType
      try:
          frame.plot_type
      except Exception as e:
          print(type(e),e)

## page()

tecplot.page(pattern)

  Returns the page by name.

  Parameters:

    pattern (`str` or `re.Pattern`) – Case-insensitive `glob-style pattern string` or a compiled `regex pattern instance` used to match the page by name.

  Returns:

    `Page` – The first page identified by pattern.

  Note

  A layout can contain `pages` with identical names and only the first match found is returned. This is not guaranteed to be deterministic and care should be taken to have only `pages` with unique names when this feature is used.

  Example:

      import tecplot
      page11 = tecplot.add_page()
      page11.name = 'Page 11'
      page12 = tecplot.add_page()
      page12.name = 'Page 12'
      assert page12 == tecplot.page('Page 1*')

## pages()

tecplot.pages(pattern=None)

  Yields pages matching a specified pattern.

  Parameters:

    pattern (`str` or `re.Pattern`, optional) – Case-insensitive `glob-style pattern string` or a compiled `regex pattern instance` used to match page names.

  Returns:

    `Page` – Generator of pages identified by pattern or all pages if no pattern is specified.

  This function returns a generator which can only be iterated over once. It can be converted to a `list` for persistence:

      import tecplot

      # iterate over all frames in
      # all pages and print their names
      for page in tecplot.pages():
          for frame in page.frames():
              print(frame.name)

      # store a persistent list of pages
      pages = list(tecplot.pages())

## frames()

tecplot.frames(frame_pattern=None, page_pattern=None)

  Returns a generator of frames matching the specified pattern.

  Parameters:

    - frame_pattern (`str` or `re.Pattern`) – Case-insensitive `glob-style pattern string` or a compiled `regex pattern instance` used to match the frame by name. All frames are returned if no pattern is specified.

    - page_pattern (`str` or `re.Pattern`) – Case-insensitive `glob-style pattern string` or a compiled `regex 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)

  Writes the current layout to a file.

  Parameters:

    - filename (`str`) – The path to the output filename. (See note below conerning absolute and relative paths.)

    - include_data (`bool`, optional) – Associated value indicates if the layout should be saved as a layout package where the data is included with the style information or if it should reference linked data. If ‘include_data’ is None and the filename ends with ‘.lpk’, then the file will be saved as a layout package file. (default: None)

    - include_preview (`bool`, optional) – Associated value indicates if the layout package should also include a preview image. This argument only applies if the include data option is True. (default: `True`)

    - use_relative_paths (`bool`, optional) – Associated value indicates if the layout should be saved using relative paths. This argument only applies if the include data option is `False`. (default: `False`)

    - post_layout_commands (`str`, optional) – A character string containing a set of Tecplot macro commands that are appended to the layout or layout package file. These can be almost anything and are generally used to store add-on specific state information using `$!EXTENDEDCOMMAND` commands. (default: `None`)

    - pages (`list` of `Page` objects, optional) – If `None`, all pages are written to the layout, otherwise the specified subset of pages are written. (default: `None`)

  Note

  Absolute and relative paths with PyTecplot

  Relative paths, when used within the PyTecplot API are always from Python’s current working directory which can be obtained by calling `os.getcwd()`. This is true for batch and `connected` modes. One exception to this is paths within a macro command or file which will be relative to the Tecplot Engine’s home directory, which is typically the Tecplot 360 installation directory. Finally, when connected to a remote (non-local) instance of Tecplot 360, only absolute paths are allowed.

  Note that backslashes must be escaped which is especially important for windows paths such as `"C:\\Users"` or `"\\\\server\\path"` which will resolve to `"C:\Users"` and `"\\server\path"` respectively. Alternatively, one may use Python’s raw strings: `r"C:\Users"` and `r"\\server\path"`

  Note

  If you receive an exception with the error message “Journal should be valid in all frames”, then you must save a data file using `save_tecplot_ascii` or `save_tecplot_plt` before saving the layout.

  In this example, we load an example layout file and then save it as a packaged layout file:

      import os
      import tecplot

      examples_dir = tecplot.session.tecplot_examples_directory()
      infile = os.path.join(examples_dir, 'SimpleData', 'F18.lay')

      tecplot.load_layout(infile)
      tecplot.save_layout('output.lpk')

## layout.aux_data()

tecplot.layout.aux_data()

  Auxiliary data for the current layout.

  Returns:

    `AuxData`

  This is the auxiliary data attached to the entire layout containing all frames and datasets currently held by the Tecplot Engine. Such data is written to the layout file by default and can be retrieved later. Example usage:

      import tecplot as tp

      aux = tp.layout.aux_data()
      aux['info'] = '''        This layout contains a lot of things:
          1. Something
          2. Something else
          3. Also this'''

      '''
      The following will print (including newlines):
          This layout contains a lot of things:
              1. Something
              2. Something else
              3. Also this
      '''
      print(aux['info'])

## Frame

class tecplot.layout.Frame(uid, page)

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

  Parameters:

    - uid (`int`, optional) – This must be a valid unique ID number pointing internally to a Frame object or `None`. A new `Frame` is created if set to `None`. (default: `None`)

    - page (`Page`, optional) – The destination `Page` of this newly created `Frame`. If `None`, the currently active `Page` is used. (default: `None`)

  Warning

  Though it is possible to create a `Frame` object using the constructor, it is usually sufficient to obtain a frame through `tecplot.active_frame()` or `Page.frame()`. One can also create a `Frame` using a `Page` handle with `Page.add_frame()`.

  The concept of the `Frame` is central to understanding the Tecplot Engine. The `Frame` is what connects a `Dataset` to a Plot handle from which one manipulates the desired image as well as accessing the attached data:

      import tecplot

      frame = tecplot.active_frame()

      # will print: 'Frame "Frame 001"'
      print(frame)

  Attributes

  `active` | Checks if this `Frame` is active.
  `aux_data` | Auxiliary data for this frame.
  `background_color` | Color of the background.
  `border_thickness` | The border thickness in units of `Frame.size_pos_units`.
  `dataset` | `Dataset` attached to this `Frame`.
  `has_dataset` | Checks to see if the `Frame` as an attached `Dataset`
  `header_background_color` | The header's background color.
  `height` | The height in units of `Frame.size_pos_units`.
  `name` | Returns or sets the name.
  `page` | The `Page` containing this Frame.
  `plot_type` | Returns or sets the current plot type.
  `position` | `(x,y)` position of the `Frame` in inches.
  `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_circle`(center, radius, coord_sys) | Place a circle annotation on the `Frame`.
  `add_ellipse`(center, size, coord_sys) | Place an ellipse annotation on the `Frame`.
  `add_georeferenced_image`(image_filename, ...) | Add a geographic reference image and world file to the `Frame`.
  `add_image`(filename, position, height) | Add an image to the `Frame`.
  `add_latex`(text[, position, coord_sys, ...]) | Adds a `LaTeX text` annotation to the Frame.
  `add_polyline`(*points, **kwargs) | Create a polyline annotation on this `Frame`.
  `add_rectangle`(corner, size, coord_sys) | Place a rectangle annotation on the `Frame`.
  `add_square`(corner, size, coord_sys) | Place a square annotation on the `Frame`.
  `add_text`(text[, position, coord_sys, ...]) | Adds a `text` to a `Frame`.
  `create_dataset`(name[, var_names, reset_style]) | Create an empty `Dataset`.
  `delete_geometry`(geom) | Delete a geometry or image annotation object from the `Frame`.
  `delete_image`(img) | Delete an image annotation object from the `Frame`.
  `delete_text`(text) | Delete a `text` object from a frame.
  `geometries`() | Get an iterator for all geometry objects in the frame.
  `images`() | Get an iterator for all image objects in the frame.
  `load_stylesheet`(filename[, plot_style, ...]) | Apply a stylesheet settings file to this frame.
  `move_to_bottom`() | Moves `Frame` behind all others in `Page`.
  `move_to_top`() | Moves `Frame` in front of all others in `Page`.
  `plot`([plot_type]) | The primary Plot style-control object.
  `save_stylesheet`(filename[, plot_style, ...]) | Save the frame's current style to a file.
  `texts`() | Get an iterator for all `Text` objects in the frame.

Frame.activate()

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

  Context for temporarily activating this `Frame`.

  Example:

      import tecplot

      page = tecplot.active_page()
      frame1 = page.active_frame()
      frame2 = page.add_frame()

      assert frame2.active

      with frame1.activated():
          # frame1 is active only during this context
          assert frame1.active
          # there is only one frame active at a time
          assert not frame2.active

      assert frame2.active

Frame.active

  Checks if this `Frame` is active.

  Returns:

    `bool` – `True` if this `Frame` is the active `Frame`.

Frame.active_zones(*zones)

  Returns or sets the active Zones.

  Parameters:

    zones (Zones, optional) – The Zone objects, which must be in the `Dataset` attached to this `Frame`, that will be activated. All other Zones will be deactivated.

  Returns:

    Zones – This will return a generator of active Zones in this `Frame`.

  This should only be used on frames with an active plot type that contains a dataset with at least one zone.

Frame.add_circle(center, radius, coord_sys)

  Place a circle annotation on the `Frame`.

  Parameters:

    - center (`tuple` of `floats`) – Position \((x, y)\) of the center of the circle in the coordinates specified by coord_sys.

    - radius (`float`) – The size of the radius in the coordinates specified by coord_sys.

    - coord_sys (`CoordSys`) – The coordinate system to use for position and size of this annotation.

  Returns:

    `annotation.Circle`

  Example usage:

      import tecplot
      from tecplot.constant import CoordSys

      frame = tecplot.active_frame()
      circle = frame.add_circle((0.2, 0.2), 0.1, CoordSys.Frame)

  See also

  `add_ellipse`, `add_rectangle`, `add_square`, `add_polyline`

Frame.add_ellipse(center, size, coord_sys)

  Place an ellipse annotation on the `Frame`.

  Parameters:

    - center (`tuple` of `floats`) – Position \((x, y)\) of the ellipse in the coordinates specified by coord_sys.

    - size (`tuple` of `floats`) – Lengths \((h_{axis}, v_{axis})\) of the horizontal and vertical axes in the coordinates specified by coord_sys. Both lengths must be non-zero.

    - coord_sys (`CoordSys`) – The coordinate system to use for position and size of this annotation.

  Returns:

    `annotation.Ellipse`

  Example usage:

      import tecplot
      from tecplot.constant import CoordSys

      frame = tecplot.active_frame()
      ellipse = frame.add_ellipse((0.5, 0.5), (0.1, 0.2), CoordSys.Frame)

  See also

  `add_circle`, `add_rectangle`, `add_square`, `add_polyline`

Frame.add_georeferenced_image(image_filename, world_filename)

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

  Parameters:

    - image_filename (`str`) – The image source file.

    - world_filename (`str`) – The world file associated with the image.

  Returns:

    `annotation.GeoreferencedImage`

  Example usage:

      >>> frame = tp.active_frame()
      >>> imgfile = 'region.png'
      >>> worldfile = 'region.pgw'
      >>> geoimg = frame.add_georeferenced_image(imgfile, worldfile)

Frame.add_image(filename, position, height)

  Add an image to the `Frame`.

  Parameters:

    - filename (`str`) – The image source file. The format of this file must be Microsoft Windows Bitmap (.bmp), JPEG (.jpg or .jpeg) or Portable Network Graphics (.png).

    - position (`tuple` of `floats`) – Position \((x, y)\) of the image in percentage frame coordinates.

    - height (`float`) – The initial size, or height, of the image in percentage frame units. The initial width in frame units is set automatically based on the width to height aspect ratio of the image.

  Returns:

    `annotation.Image`

  This example adds an image to the upper left quadrant of the frame:

      >>> frame = tp.active_frame()
      >>> img = frame.add_image('myimage.png', (0, 50), 50)

Frame.add_latex(text, position=None, coord_sys=None, size_units=None, size=None, anchor=None, zone=None)

  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 the `Frame`. The text string must have a non-zero length.

    - position (`tuple` of `floats` (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` or `CoordSys.Frame`. (default: `CoordSys.Frame`)

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

    - 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 resulting `text box` object.

  Example

      import tecplot as tp
      from tecplot.constant import TextAnchor

      frame = tp.active_frame()
      frame.add_latex(r'$$\zeta(s) = \sum_{n=1}^\infty\frac{1}{n^s}$$',
                      (50,50), size=64, anchor=TextAnchor.Center)

  See also

  `add_text`, `delete_text`

Frame.add_polyline(*points, **kwargs)

  Create a polyline annotation on this `Frame`.

  Parameters:

    *points (`lists` of points) – Arrays of \((x, y)\) or \((x, y, z)\) positions of the points along this polyline in the coordinate system specified by coord_sys. If multiple lists are provided, they must be of the same dimension (2D or 3D), though they may be of different lengths.

  Keyword Parameters:
    coord_sys (`CoordSys`, optional): The coordinate system to use for

      the positions of this annotation. Only 2D polylines may use a coordinate system other than the data-coordinates (“grid”). (default: `CoordSys.Grid`)

  Returns:

    One of `annotation.Polyline2D`, `annotation.Polyline3D`, `annotation.MultiPolyline2D` or `annotation.MultiPolyline3D`.

  Example usage:

      import tecplot

      points = [ [1, 2,  3],
                 [2, 4,  9],
                 [3, 8, 27], ]

      frame = tecplot.active_frame()
      polyline = frame.add_polyline(points)

  See also

  `add_circle`, `add_ellipse`, `add_rectangle`, `add_square`

Frame.add_rectangle(corner, size, coord_sys)

  Place a rectangle annotation on the `Frame`.

  Parameters:

    - center (`tuple` of `floats`) – Position \((x, y)\) of the rectangle in the coordinates specified by coord_sys.

    - size (`tuple` of `floats`) – Size \((width, height)\) of the rectangle in the coordinates specified by coord_sys.

    - coord_sys (`CoordSys`) – The coordinate system to use for position and size of this annotation.

  Returns:

    `annotation.Rectangle`

  Example usage:

      import tecplot
      from tecplot.constant import CoordSys

      frame = tecplot.active_frame()
      rectangle = frame.add_rectangle((0.5, 0.5), (0.1, 0.2), CoordSys.Frame)

  See also

  `add_circle`, `add_ellipse`, `add_square`, `add_polyline`

Frame.add_square(corner, size, coord_sys)

  Place a square annotation on the `Frame`.

  Parameters:

    - corner (`tuple` of `floats`) – Position \((x, y)\) of the lower-left corner of the square in the coordinates specified by coord_sys.

    - size (`float`) – Side-length of the square in the coordinates specified by coord_sys.

    - coord_sys (`CoordSys`) – The coordinate system to use for position and size of this annotation.

  Returns:

    `annotation.Square`

  Example usage:

      import tecplot
      from tecplot.constant import CoordSys

      frame = tecplot.active_frame()
      square = frame.add_square((0.2, 0.2), 0.1, CoordSys.Frame)

  See also

  `add_circle`, `add_ellipse`, `add_rectangle`, `add_polyline`

Frame.add_text(text, position=None, coord_sys=None, text_type=None, typeface=None, bold=None, italic=None, size_units=None, size=None, color=None, angle=None, line_spacing=None, anchor=None, box_type=None, line_thickness=None, box_color=None, fill_color=None, margin=None, zone=None)

  Adds a `text` to a `Frame`.

  Parameters:

    - text (`str`) – The text to add to the `Frame`. The text string must have a non-zero length.

    - position (`tuple` of `floats` (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` or `CoordSys.Frame`. (default: `CoordSys.Frame`)

    - text_type (`TextType`, optional) – Type of text object to create. Options are `TextType.Regular` (default) and `TextType.LaTeX`. If set to `TextType.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 to `TextType.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` 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: `constant.TextBox.None_`, `constant.TextBox.Filled` or `constant.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. 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, color=Color.Blue)

  See also

  `add_latex`, `delete_text`

Frame.aux_data

  Auxiliary data for this frame.

  Returns:

    `AuxData`

  This is the auxiliary data attached to the frame. Such data is written to the layout file by default and can be retrieved later. Example usage:

      >>> aux = tp.active_frame().aux_data
      >>> aux['Result'] = '3.14159'
      >>> print(aux['Result'])
      3.14159

Frame.background_color

  Color of the background.

  Type:

    `Color`

Frame.border_thickness

  The border thickness in units of `Frame.size_pos_units`.

  Type:

    `float`

Frame.create_dataset(name, var_names=None, reset_style=True)

  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 new `Dataset`. This does not have to be unique.

    - var_names (`list` of `strings`, optional) – `Variable` names. This only sets the names and not the data type or location. See `add_variable`. (default: `None`)

    - reset_style (`bool`) – Reset style of the active `Frame` before loading the `Dataset`. (default: `True`)

  Returns:

    `Dataset` – The newly created `Dataset`.

  Note

  Relationships between `Frame` and `Dataset`

  A `Frame` may only hold a single `Dataset`, though this `Dataset` may be shared between several `Frames`. Therefore, this method will only replace the current dataset when reset_style is set to `True` and will fail otherwise. If this `Frame` already has a `Dataset`, it may be more efficient to do one of the following instead:

  > - Add a new (blank) frame with `Page.add_frame()` and create a `Dataset` for this.

  > - Add new zones to the existing `Dataset` with `Dataset.add_ordered_zone()`, `Dataset.add_fe_zone()` or `Dataset.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 this `Frame`.

  Returns:

    `Dataset` – The object holding onto the data associated with this `Frame`.

  If no `Dataset` has been created for this `Frame`, a new one is created and returned:

      >>> dataset = frame.dataset

Frame.delete_geometry(geom)

  Delete a geometry or image annotation object from the `Frame`.

  Parameters:

    geom (`Circle`, `Image` or similar instance) – The annotation instance to be removed from the `Frame`.

  Warning

  After the annotation is deleted, all handles to it will no longer be valid and all accessing any properties of the object will result in a `TecplotLogicError` being raised.

  Example usage:

      import tecplot
      from tecplot.constant import CoordSys

      frame = tecplot.active_frame()
      rectangle = frame.add_rectangle((0.5, 0.5), (0.1, 0.2), CoordSys.Frame)
      frame.delete_geometry(rectangle)

Frame.delete_image(img)

  Delete an image annotation object from the `Frame`.

  Parameters:

    img (`Image` or `GeoreferencedImage`) – The annotation instance to be removed from the `Frame`.

  Warning

  After the annotation is deleted, all handles to it will no longer be valid and all accessing any properties of the object will result in a `TecplotLogicError` being raised.

  See also

  `delete_geometry()`

Frame.delete_text(text)

  Delete a `text` object from a frame.

  When deleted, the text object is no longer displayed in the frame and is permanently invalid. To display the text in the frame again, a new text object must be created by calling `add_text`.

  Warning

  Use this method with care. After a text object has been deleted by calling this method, it is no longer valid, and all properties of the deleted text object will throw `TecplotLogicError` when accessed.

  Example usage:

      import tecplot as tp

      text = tp.active_frame().add_text("abc")
      tp.active_frame().delete_text(text)

      # The text object is no longer valid.
      # Any property access will throw TecplotLogicError
      try:
          print(text.text_string)
      except tp.exception.TecplotLogicError as e:
          print(e)

  See also

  `add_text`

Frame.geometries()

  Get an iterator for all geometry objects in the frame.

  This method provides access to all geometric shape instances attached to this `Frame`. This includes `Circle`, `Polyline2D`, `Polyline3D` and all similar objects:

      >>> for geom in frame.geometries():
      ...     print(type(geom))
      <class 'tecplot.annotation.geometry.Circle'>
      <class 'tecplot.annotation.polyline.Polyline2D'>

Frame.has_dataset

  Checks to see if the `Frame` as an attached `Dataset`

  Example usage:

      >>> if not frame.has_dataset:
      ...     dataset = frame.create_dataset('Dataset', ['x','y','z','p'])

  Type:

    `bool`

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

  Get an iterator for all image objects in the frame.

  This method provides access to all `Image` and `GeoreferencedImage` instances attached to this `Frame`:

      >>> for image in frame.images():
      ...     print(image.filename)
      image1.png
      image2.png

Frame.load_stylesheet(filename, plot_style=True, text=True, geom=True, streams=True, contours=True, frame_geom=False, merge=False)

  Apply a stylesheet settings file to this frame.

  Parameters:

    - filename (`str`) – The path to a stylesheet file. (See note below conerning absolute and relative paths.)

    - plot_style (`bool`, optional) – Apply the stylesheet’s plot style. (default: `True`)

    - text (`bool`, optional) – Include the stylesheet’s text objects. (default: `True`)

    - geom (`bool`, optional) – Include the stylesheet’s geometry objects. (default: `True`)

    - streams (`bool`, optional) – Include the stylesheet’s stream traces. (default: `True`)

    - contours (`bool`, optional) – Include the stylesheet’s contour levels. (default: `True`)

    - frame_geom (`bool`, optional) – Apply the stylesheet’s frame position and size. (default: `False`)

    - merge (`bool`, optional) – Merge with the frame’s current style. (default: `False`)

  Note

  Absolute and relative paths with PyTecplot

  Relative paths, when used within the PyTecplot API are always from Python’s current working directory which can be obtained by calling `os.getcwd()`. This is true for batch and `connected` modes. One exception to this is paths within a macro command or file which will be relative to the Tecplot Engine’s home directory, which is typically the Tecplot 360 installation directory. Finally, when connected to a remote (non-local) instance of Tecplot 360, only absolute paths are allowed.

  Note that backslashes must be escaped which is especially important for windows paths such as `"C:\\Users"` or `"\\\\server\\path"` which will resolve to `"C:\Users"` and `"\\server\path"` respectively. Alternatively, one may use Python’s raw strings: `r"C:\Users"` and `r"\\server\path"`

  Example usage:

      >>> frame = tecplot.active_frame()
      >>> frame.load_stylesheet('my_style.sty')

Frame.move_to_bottom()

  Moves `Frame` behind all others in `Page`.

Frame.move_to_top()

  Moves `Frame` in front of all others in `Page`.

Frame.name

  Returns or sets the name.

  This is the name used when searching for `Frame` objects in `Page.frames` and `Page.frame`. It does not have to be unique, even for multiple frames in a single `Page`:

      import tecplot

      frame = tecplot.active_frame()
      frame.name = '3D Data View'

      # will print: "this frame: 3D Data View"
      print('this frame:', frame.name)

  Type:

    `str`

Frame.page

  The `Page` containing this Frame.

  This provides access to the parent `Page`:

      import tecplot

      frame = tecplot.active_frame()
      page = frame.page

      # Will print: "Page 001"
      print(page.name)

Frame.plot(plot_type=PlotType.Automatic)

  The primary Plot style-control object.

  Returns:

    Plot – One of the possible Plot subclasses, depending on the `plot_type` specified. By default, the active plot type, obtained from `Frame.plot_type`, is used.

  The Plot object is the handle through which one can manipulate the style and visual representation of the `Dataset`. Possible return types are: `SketchPlot`, `Cartesian2DFieldPlot`, `Cartesian3DFieldPlot`, `PolarLinePlot` and `XYLinePlot`. Each of these have their own specific set of attributes and methods:

      import os
      import tecplot
      from tecplot.constant import PlotType

      install_dir = tecplot.session.tecplot_install_directory()
      infile = os.path.join(install_dir, 'examples', 'SimpleData', 'SpaceShip.lpk')
      tecplot.load_layout(infile)

      frame = tecplot.active_frame()
      assert frame.plot_type is PlotType.Cartesian3D

      plot3d = frame.plot()
      plot3d.show_contour = True

Frame.plot_type

  Returns or sets the current plot type.

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

      import os
      import tecplot
      from tecplot.constant import PlotType

      frame = tecplot.active_frame()
      assert frame.plot_type is PlotType.Sketch

      install_dir = tecplot.session.tecplot_install_directory()
      infile = os.path.join(install_dir, 'examples', 'SimpleData', 'SpaceShip.lpk')
      tecplot.load_layout(infile)

      frame = tecplot.active_frame()
      assert frame.plot_type is PlotType.Cartesian3D

      frame.plot_type = PlotType.Cartesian2D
      assert frame.plot_type is PlotType.Cartesian2D

  Note

  Plot type cannot be set to `constant.PlotType.Automatic`.

  Type:

    `constant.PlotType`

Frame.position

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

  The `Frame` x position is relative to the left side of the paper. The `Frame` y position is relative to the top of the paper.

  If x is `None`, the `Frame` x position is not changed. If y is `None`, the `Frame` y position is not changed.

  Set `Frame` position 1 inch from the left side of the paper and two inches from the top of the paper:

      >>> tp.active_frame().position=(1.0, 2.0)

  Move the active `Frame` one inch to the right:

      >>> tp.active_frame().position=(tp.active_frame().position.x+1, None)

  Type:

    `tuple`

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)

  Save the frame’s current style to a file.

  Parameters:

    - filename (`str`) – The path to a stylesheet file. (See note below conerning absolute and relative paths.)

    - plot_style (`bool`, optional) – Include the frame’s plot style. (default: `True`)

    - aux_data (`bool`, optional) – Include auxiliary data. (default: `True`)

    - text (`bool`, optional) – Include text objects. (default: `True`)

    - geom (`bool`, optional) – Include geometry objects. (default: `True`)

    - streams (`bool`, optional) – Include stream traces. (default: `True`)

    - contours (`bool`, optional) – Include contour levels. (default: `True`)

    - defaults (`bool`, optional) – Include all factory defaults used by the current style. (default: `False`)

    - relative_paths (`bool`, optional) – Use relative paths. (default: `True`)

    - compress (`bool`, optional) – Compress the output of the style. (default: `False`)

  Note

  Absolute and relative paths with PyTecplot

  Relative paths, when used within the PyTecplot API are always from Python’s current working directory which can be obtained by calling `os.getcwd()`. This is true for batch and `connected` modes. One exception to this is paths within a macro command or file which will be relative to the Tecplot Engine’s home directory, which is typically the Tecplot 360 installation directory. Finally, when connected to a remote (non-local) instance of Tecplot 360, only absolute paths are allowed.

  Note that backslashes must be escaped which is especially important for windows paths such as `"C:\\Users"` or `"\\\\server\\path"` which will resolve to `"C:\Users"` and `"\\server\path"` respectively. Alternatively, one may use Python’s raw strings: `r"C:\Users"` and `r"\\server\path"`

  Example usage:

      >>> frame = tecplot.active_frame()
      >>> frame.save_stylesheet('my_style.sty')

Frame.show_border

  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.

  Possible values: `Paper`, `Workspace`.

  Type:

    `FrameSizePosUnits`

Frame.texts()

  Get an iterator for all `Text` objects in the frame.

  This example shows how to obtain a list of all red `Text` objects:

      >>> from tecplot.constant import Color
      >>> all_red_text_objects = [T for T in tp.active_frame().texts()
      ...                         if T.color == Color.Red]

Frame.transparent

  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)

  `Page` object within a layout, holding onto one or more `Frames`.

  Parameters:

    uid (`int`, optional) – This must be a valid unique ID number pointing internally to a `Page` object or `None`. A new `Page` is created if set to `None`. (default: `None`)

  Warning

  Though it is possible to create a `Page` object using the constructor, it is usually sufficient to obtain a page through `tecplot.add_page`, `tecplot.active_page`, `tecplot.page` or `tecplot.pages`.

  A `Page` can be thought of like a canvas onto which one or more `Frames` can be laid out. The engine guarantees there will always be at least one `Page` in the layout which can be accessed via `tecplot.active_page`:

      import tecplot

      page = tecplot.active_page()
      page.name = 'Page 001'

      # prints: "Page 001"
      print(page.name)

      # prints: "Frame 001"
      for frame in page.frames():
          print(frame.name)

  Attributes

  `active` | Checks if this `Page` is active.
  `aux_data` | Auxiliary data for this page.
  `exists` | Checks if the `Page` exists in the current layout.
  `name` | Name of the page.
  `paper` | The `Paper` defined in this `Page`.
  `position` | Index of the Page

  Methods

  `activate`() | Activates the `Page`.
  `active_frame`() | Returns the active `Frame`.
  `add_frame`([position, size]) | Creates a new `Frame` in this `Page`.
  `delete_frame`(frame) | Removes the frame from this `Page`.
  `frame`(pattern) | Returns the `Frame` by name.
  `frames`([pattern]) | Returns a `list` of `Frames` matching the specified pattern.
  `tile_frames`([mode]) | Tile frames based on a certain mode.

Page.activate()

  Activates the `Page`.

  Raises:

    - TecplotRuntimeError – Page does not exist.

    - TecplotSystemError – Could not activate the page.

Page.active

  Checks if this `Page` is active.

  Returns:

    `bool` – `True` if active.

Page.active_frame()

  Returns the active `Frame`.

  Returns:

    `Frame` – The active `Frame`.

  This implicitly activates this `Page` and returns the active `Frame` attached to it.

Page.add_frame(position=None, size=None)

  Creates a new `Frame` in this `Page`.

  Parameters:

    - position (`tuple` of `floats` (x,y), optional) – The position (in inches) of the frame relative to the top left corner of the paper. If supplied, size must also be supplied.

    - size (`tuple` of `floats` (width,height), optional) – The size (in inches) of the frame. If supplied, position must also be supplied.

  Returns:

    `Frame` – The newly created and activated `Frame`.

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

      import tecplot as tp

      frame = tp.active_page().add_frame(position=(1, 0.25), size=(8, 9))

Page.aux_data

  Auxiliary data for this page.

  Returns: `AuxData`

  This is the auxiliary data attached to the page. Such data is written to the layout file by default and can be retrieved later. Example usage:

      >>> aux = tp.active_page().aux_data
      >>> aux['Result'] = '3.14159'
      >>> print(aux['Result'])
      3.14159

Page.delete_frame(frame)

  Removes the frame from this `Page`.

  Raises:

    - TecplotRuntimeError – If `Frame` is not in this `Page`.

    - TecplotSystemError – Could not delete the frame.

Page.exists

  Checks if the `Page` exists in the current layout.

  This will return `False` after the `Page` has been deleted:

      import tecplot as tp
      page = tp.add_page()
      assert page.exists
      tp.delete_page(page)
      assert not page.exists

Page.frame(pattern)

  Returns the `Frame` by name.

  Parameters:

    pattern (`str` or `re.Pattern`) – Case-insensitive `glob-style pattern string` or a compiled `regex pattern instance` used to match the frame by name.

  Returns:

    `Frame` – The first `Frame` identified by pattern.

  Note

  A `Page` can contain `Frames` with identical names and only the first match found is returned. This is not guaranteed to be deterministic and care should be taken to have only `Frames` with unique names when this feature is used.

  Example:

      import tecplot
      page = tecplot.active_page()

      frameA = page.add_frame()
      frameA.name = 'A'

      frameB = page.add_frame()
      frameB.name = 'B'

      assert frameB.active
      assert frameA == page.frame('A')

Page.frames(pattern=None)

  Returns a `list` of `Frames` matching the specified pattern.

  Parameters:

    pattern (`str` or `re.Pattern`, optional) – Case-insensitive `glob-style pattern string` or a compiled `regex pattern instance` used to match frame names.

  Returns:

    `list` – `Frames` identified by pattern or all frames if no pattern is specified.

  Example:

      import tecplot

      page = tecplot.active_page()
      page.add_frame()  # create a second frame

      # iterate over all frames and print their names
      for frame in page.frames():
          print(frame.name)

      # store a persistent list of frames
      frames = page.frames()

      # prints: ['Frame 001', 'Frame 002']
      print([f.name for f in frames])

Page.name

  Name of the page.

  This is the name used when searching for `Page` objects in `tecplot.pages` and `tecplot.page`. It does not have to be unique.

  Example:

      import tecplot

      page = tecplot.active_page()
      page.name = 'My Data'

      # prints: "this page: My Data"
      print('this page:', page.name)

  Type:

    `str`

Page.paper

  The `Paper` defined in this `Page`.

  Every `Page` has the concept of a workspace which includes all `Frames` as well as a sub-area of the workspace called the `Paper`. The limits of the `Paper` with respect to the placement of `Frames` is used when exporting certain image formats.

  Type:

    `Paper`

Page.position

  Index of the Page

  The page positions are 0 based positions relative to the current page, where the current page has a position value of 0, the next page 1, the page after that 2, and so on.

  Type:

    `Index`

Page.tile_frames(mode=TileMode.Grid)

  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)

  The `Paper` boundary defined on a workspace.

  This is the area used for certain image output formats. It is defined for a specific `Page`. `Frames` can be laid out in reference to this sub-area of the workspace.

  Attributes

  `dimensions` | Width and height (read-only).

Paper.dimensions

  Width and height (read-only).

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