### Navigation

- ☰
- PyTecplot-0.6 »
- Reference »

# Layout

Pages, frames and other layout-related operations.

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

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

`tecplot.``active_frame`()

  Returns the active frame.

  Returns: | `Frame` – Currently active frame.

`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, but we can
      >>> # bring page1 back to the front:
      >>> page1.activate()

`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

`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.add_page()
      >>> page2 = tecplot.add_page()
      >>> next_page = next_page()
      >>> # page1 is now the active page
      >>> next_page == page1
      True

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

  Reads a layout file and replaces the active frame.

  Parameters: | filename (`string`) – The file name of the layout to be loaded.
  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.``page`(pattern)

  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)

  Yields pages matching a specified pattern.

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

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

      >>> import tecplot
      >>> # iterate over all pages and print their names
      >>> for page in tecplot.pages():
      >>>     print(page.name)
      >>> # store a persistent list of pages
      >>> pages = list(tecplot.pages())

`tecplot.``save_layout`(filename, include_data=None, include_preview=None, use_relative_paths=None, post_layout_commands=None, pages=None)

  Writes the current layout to a file.

  Parameters: | filename (`string`) – The path to the output filename. Relative to the current working directory. include_data (`boolean`, optional) – Associated value indicates if the layout should be saved as a layout package where the data is included with the style information or if it should reference linked data. (default: `False`) include_preview (`boolean`, optional) – Associated value indicates if the layout package should also include a preview image. This argument only applies if the include data option is True. (default: `True`) use_relative_paths (`boolean`, optional) – Associated value indicates if the layout should be saved using relative paths. This argument only applies if the include data option is `False`. (default: `False`) post_layout_commands (`string`, optional) – A character string containing a set of Tecplot macro commands that are appended to the layout or layout package file. These can be almost anything and are generally used to store add-on specific state information using `$!EXTENDEDCOMMAND` commands. (default: `None`) pages (`list` of `Page` objects, optional) – If `None`, all pages are written to the layout, otherwise the specified subset of pages are written. (default: `None`)
  Raises: | `TecplotSystemError`

  Note

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

  Example

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

      >>> import os
      >>> import tecplot
      >>> examples_dir = tecplot.session.tecplot_examples_directory()
      >>> infile = os.path.join(examples_dir, '3D', 'JetSurface.lay')
      >>> outfile = 'jet_surface.png'
      >>> tecplot.load_layout(infile)
      >>> tecplot.save_layout('output.lpk', include_data=True)

## Frame

class `tecplot.layout.``Frame`(uid, page)

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

  Parameters: | uid (`integer`, optional) – This must be a valid unique ID number pointing internally to a Frame object or `None`. A new `Frame` is created if set to `None`. (default: `None`) page (`Page`, optional) – The destination `Page` of this newly created `Frame`. If `None`, the currently active `Page` is used. (default: `None`)

  Warning

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

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

      >>> import tecplot
      >>> frame = tecplot.active_frame()
      >>> frame
      Frame(uid=11, Page(uid=1))
      >>> print(frame)
      Frame 001

  Attributes

  `active` | Checks if this `Frame` is active.
  `aux_data` | Returns the auxiliary data object.
  `background_color` | Color of the background.
  `border_thickness` | The border thickness in units of `Frame.size_pos_units`.
  `current` |
  `dataset` | `Dataset` attached to this `Frame`.
  `has_dataset` | Checks to see if the `Frame` as an attached `Dataset`
  `header_background_color` | The header’s background color.
  `height` | The height in units of `Frame.size_pos_units`.
  `name` | Returns or sets the name.
  `page` | The `Page` containing this Frame.
  `plot_type` | Returns or sets the current plot type.
  `show_border` | Show or hide the `Frame`‘s border.
  `show_header` | Show or hide the `Frame`‘s header in the border.
  `size_pos_units` | The units used for size properties.
  `transparent` | Use transparency within this `Frame`.
  `width` | The width in units of `Frame.size_pos_units`.

  Methods

  `activate`() | Causes this `Frame` to become active.
  `activated`() | Context for temporarily activating this `Frame`.
  `active_zones`(*zones) | Returns or sets the active Zones.
  `add_text`(text[, position, coord_sys, ...]) | Adds a `text` to a `Frame`.
  `create_dataset`(name[, var_names, reset_style]) | Create an empty `Dataset`.
  `geometries`() |
  `images`() |
  `move_to_bottom`() | Moves `Frame` behind all others in `Page`.
  `move_to_top`() | Moves `Frame` in front of all others in `Page`.
  `plot`([plot_type]) | Returns a Plot style-control object.
  `texts`() | Get an iterator for all `Text` objects in the frame.

`Frame.``activate`()

  Causes this `Frame` to become active.

  Raises: | `TecplotSystemError`

  The parent `Page` is implicitly “activated” as a side-effect of this operation:

      >>> import tecplot
      >>> page1 = tecplot.active_page()
      >>> frame1 = page1.active_frame()
      >>> page2 = tecplot.add_page()
      >>> frame2 = page2.active_frame()
      >>> frame1.active and page1.active
      False
      >>> frame2.active and page2.active
      True
      >>> frame1.activate()
      >>> frame2.active or page2.active
      False
      >>> frame1.active and page1.active
      True

`Frame.``activated`()

  Context for temporarily activating this `Frame`.

  Example:

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

`Frame.``active`

  Checks if this `Frame` is active.

  Returns: | `bool` – `True` if this `Frame` is the active `Frame`.

`Frame.``active_zones`(*zones)

  Returns or sets the active Zones.

  Parameters: | *zones (Zone or `list` of Zones, optional) – The Zone objects, which must be in the `Dataset` attached to this `Frame`, that will be activated. All other Zones will be deactivated.
  Yields: | Zones – This will return a generator of active Zones in this `Frame`.

`Frame.``add_text`(text, position=None, coord_sys=None, 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 (`string`) – The text to add to the `Frame`. The text string must have a non-zero length. position (`tuple` of `floats` (x,y) – The position of the anchor as a percentage of the specified coordinates. (default: (0,0)) coord_sys (`CoordSys`, optional) – Coordinate system used to position the anchor of the text object. The possible values are: `CoordSys.Grid` or `CoordSys.Frame`. (default: `CoordSys.Frame`) typeface (`string`, 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 (`boolean`, optional) – Use the bold variation of the specified typeface. (default: `True`) italic (`boolean`, 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: `TextBox.None_`, `TextBox.Filled` or `TextBox.Hollow`. (default: `TextBox.None_`) line_thickness (`float`, optional) – Text box boarder line thickness may be a value in the range from 0.0001 to 100. (default: 0.1) box_color (`Color`, optional) – Text box border line color. See `Color` for possible values. (default: `Color.Black`) fill_color (`Color`, optional) – Text box fill color. See `Color` for possible values. (default: `White`) margin (`float`, optional) – Margin between the text and text box. May be in the range from 0 to 2000. (default: 20) zone (Zone, optional) – Zone or `XYLinemap` to which the text will be attached. (default: None)
  Returns: | `annotation.Text` – The resulting `text box` object.

  Example:

      >>> import tecplot
      >>> from tecplot.constant import Color
      >>> frame = tecplot.active_frame()
      >>> frame.add_text('Hello, World!', position=(35, 50),
      ...   bold=True, italic=False, text_color=Color.Blue)

`Frame.``aux_data`

  Returns the auxiliary data object.

  Type: | `data.AuxData`

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

`Frame.``background_color`

  Color of the background.

  Type: | `Color`

`Frame.``border_thickness`

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

  Type: | `float`

`Frame.``create_dataset`(name, var_names=None, reset_style=False)

  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 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 (`boolean`) – Reset style of the active `Frame` before loading the `Dataset`. (default: `False`)
  Returns: | `Dataset` – The newly created `Dataset`.
  Raises: | `TecplotSystemError`

`Frame.``current`

`Frame.``dataset`

  `Dataset` attached to this `Frame`.

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

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

      >>> dataset = frame.dataset

`Frame.``geometries`()

`Frame.``has_dataset`

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

  Type: | `boolean`

  Example usage:

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

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

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

  Type: | `string`

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

  Example:

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

`Frame.``page`

  The `Page` containing this Frame.

  This provides access to the parent `Page`:

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

`Frame.``plot`(plot_type=<PlotType.Automatic: 0>)

  Returns a Plot style-control object.

  Type: | Plot: One of the possible Plot classes, depending on the `plot_type` specified. By default, the active plot type, obtained from `Frame.plot_type`, is used.

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

  Example:

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

`Frame.``plot_type`

  Returns or sets the current plot type.

  Type: | `constant.PlotType`
  Raises: | `TecplotSystemError`

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

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

      >>> tecplot.load_layout('mylayout.lay')
      >>> frame = tecplot.active_frame()
      >>> frame.plot_type
      <PlotType.Sketch: 4>
      >>> frame.plot_type = PlotType.Cartesian3D
      >>> frame.plot_type
      <PlotType.Cartesian3D: 1>

`Frame.``show_border`

  Show or hide the `Frame`‘s border.

  Type: | `bool`

`Frame.``show_header`

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

  Type: | `bool`

`Frame.``size_pos_units`

  The units used for size properties.

  Type: | `FrameSizePosUnits`

  Possible values: `Paper`, `Workspace`.

`Frame.``texts`()

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

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

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

`Frame.``transparent`

  Use transparency within this `Frame`.

  Type: | `bool`

`Frame.``width`

  The width in units of `Frame.size_pos_units`.

  Type: | `float`

## Page

class `tecplot.layout.``Page`(uid)

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

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

  Warning

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

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

      >>> import tecplot
      >>> page = tecplot.active_page()
      >>> page
      Page(uid=1)
      >>> for frame in page.frames():
      ...   print(frame)
      Frame 001

  Attributes

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

  Methods

  `activate`() | Activates the `Page`.
  `activated`() |
  `active_frame`() | Returns the active `Frame`.
  `add_frame`() | Creates a new `Frame` in this `Page`.
  `delete_frame`(frame) | Removes the frame from this `Page`.
  `frame`(pattern) | Returns the `Frame` by name.
  `frames`([pattern]) | Returns a `list` of `Frames` matching the specified pattern.
  `next`() |
  `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.``activated`()

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

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

  Returns: | `Frame` – The newly created and activated `Frame`.
  Raises: | `TecplotRuntimeError` – Could not find active frame. `TecplotSystemError` – Could not create a new frame.

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

`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()
        >>> page.exists
        True
        >>> page.delete()
        >>> page.exists
        False

`Page.``frame`(pattern)

  Returns the `Frame` by name.

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

  Note

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

  Example

      >>> import tecplot
      >>> page = tecplot.active_page()
      >>> frameA = page.add_frame('A')
      >>> frameB = page.add_frame('B')
      >>> frameA == page.frame('A')
      True

`Page.``frames`(pattern=None)

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

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

  Example:

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

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

`Page.``name`

  Returns or sets the name.

  Type: | `string`

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

  Example:

      >>> import tecplot
      >>> page = tecplot.active_page()
      >>> page.name = 'My Data'
      >>> print('this page:', page.name)
      this page: My Data

`Page.``next`()

`Page.``paper`

  The `Paper` defined in this `Page`.

  Type: | `Paper`

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

`Page.``position`

  Returns the position of the Page

  Type: | `Index`

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

`Page.``tile_frames`(mode=<TileMode.Grid: 'TILEFRAMESSQUARE'>)

  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.

`Paper.``dimensions`

  Width and height.

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

### Navigation

- index
- modules |
- next |
- previous |