pytecplot 1.5.2__py3-none-any.whl

tecplot/session/__init__.py

@@ -0,0 +1,112 @@
+"""|Tecplot Engine| State and |Tecplot License| Management
+
+The `session` module contains methods used to manipulate the |Tecplot Engine|
+such as notification of a `state change` that was done such as adding or
+modifying data. It also contains methods for acquiring and releasing the
+|Tecplot License|.
+
+.. _state change:
+
+State Changes
+-------------
+
+State changes are the method for propagating information when an event occurs.
+A state change can be triggered by many events. Examples include: loading a
+data file, changing the color of a mesh plot, creating a new zone, or changing
+the plot type.
+
+In general, state changes are already handled internally after each call to the
+PyTecplot API. This can cause a script that performs many operations,
+especially those that alter data, to run slowly since the |Tecplot Engine| must
+update it's internal state every time a state change is received. To speed up
+such scripts, it may be necessary to use the `tecplot.session.suspend()`
+context. This will collect state changes for any operation performed and will
+emit the required state changes only upon exit of the context.
+
+Using the `tecplot.session.suspend()` context in combination with Python's
+"-OO" flag which removes many run-time checks in the PyTecplot API is the
+recommended way to run a PyTecplot script which requires faster execution
+time. The user should be aware that, when using the "-OO" flag, errors may
+not be recoverable by the |Tecplot Engine|.
+
+"""
+
+from .aux_data import AuxData
+from .config import configuration
+from .session import (acquire_license, clear_suspend, connect, connected,
+                      disconnect, license_expiration, release_license,
+                      start_roaming, stop, stop_roaming, suspend,
+                      suspend_enter, suspend_exit)
+from .state_changed import connectivity_altered, data_altered, zone_added
+from .style import (Style, SubStyle, get_style, set_style,
+                    IJK, IJKMaxFract, IJKMinFract, IndependentVariableLimits,
+                    Limits, IndexIJK, IndexRange, RectPosition, RectSize,
+                    SplineDerivativeAtEnds, XY, XYZ)
+
+import os
+import platform
+from ..tecutil import _tecutil_connector
+
+
+def tecplot_install_directory():
+    """|Tecplot 360| installation directory.
+
+    Top-level installation directory for |Tecplot 360|. This will
+    typically contain configuration files and the examples directory.
+
+    This directory is platform-dependent and will contain configuration files
+    and the examples directory:
+
+    .. code-block:: python
+        :emphasize-lines: 4
+
+        import os
+        import tecplot
+
+        install_dir = tecplot.session.tecplot_install_directory()
+        infile = os.path.join(install_dir, 'examples', 'SimpleData', 'SpaceShip.lpk')
+
+        tecplot.load_layout(infile)
+        tecplot.export.save_png('spaceship.png', 600, supersample=3)
+
+    .. figure:: /_static/images/spaceship.png
+        :width: 300px
+        :figwidth: 300px
+    """
+    if not _tecutil_connector.connected:
+        _tecutil_connector.start()
+    d = _tecutil_connector.tecsdkhome
+    if d:
+        if platform.system() in ['Darwin', 'Mac']:
+            d = os.path.normpath(os.path.join(d, '..', '..'))
+        return d
+
+
+def tecplot_examples_directory():
+    """|Tecplot 360| examples directory.
+
+    Examples directory that is typically installed with |Tecplot 360|.
+    This may be overridden with the TECPLOT_EXAMPLES environment variable.
+
+    This directory is platform-dependent and by default contains the various
+    examples shipped with |Tecplot 360|:
+
+    .. code-block:: python
+        :emphasize-lines: 4
+
+        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.export.save_png('load_example.png', 600, supersample=3)
+
+    .. figure:: /_static/images/load_example.png
+        :width: 300px
+        :figwidth: 300px
+    """
+    d = tecplot_install_directory()
+    if d:
+        return os.environ.get('TECPLOT_EXAMPLES', os.path.join(d, 'examples'))

tecplot/session/aux_data.py

@@ -0,0 +1,276 @@
+import ctypes
+import itertools as it
+from collections import namedtuple
+from contextlib import contextmanager
+from enum import Enum
+
+from ..tecutil import _tecutil
+from ..constant import *
+from ..exception import *
+from ..tecutil import lock, lock_attributes
+
+
+@lock_attributes
+class AuxData(ctypes.c_void_p):
+    """Auxiliary data.
+
+    The |Tecplot Engine| can hold auxiliary data attached to one of the
+    following objects:
+
+        - `Layout <layout.aux_data>`
+        - `Page <Page.aux_data>`
+        - `Frame <Frame.aux_data>`
+        - `Dataset <Dataset.aux_data>`
+        - `Variable <Variable.aux_data>`
+        - `Zone <OrderedZone.aux_data>`
+        - `Linemap <XYLinemap.aux_data>`
+
+    Auxiliary data is an ordered key-value pair that behaves like an ordered
+    dictionary, or `OrderedDict <collections.OrderedDict>`. Keys are strings
+    which are ordered alphabetically and values can additionally be access by
+    index. The keys must be alphanumeric (special characters "." and "_" are
+    allowed), must not contain spaces, and must begin with a non-numeric
+    character or underscore. Values, on the other hand, are arbitrary strings
+    and can contain anything except the null character. In this example, we
+    query the auxiliary data attached to the dataset and add some information
+    to it. Notice that the stored order is alphabetical:
+
+    .. code-block:: python
+
+        import tecplot as tp
+
+        aux = tp.active_frame().aux_data
+        aux['info'] = 'Here is some information.'
+        aux['Xavg'] = 3.14159
+        aux['note'] = 'Aux data values are always converted to strings.'
+
+        '''
+        The following code will print:
+            info: Here is some information.
+            note: Aux data values are always converted to strings.
+            Xavg: 3.14159
+        '''
+        for k, v in aux.items():
+            print('{}: {}'.format(k,v))
+    """
+    def __init__(self, parent, object_type, object_index=None):
+        self.parent = parent
+        self.object_type = object_type
+        self.getref_args = [] if object_index is None else [object_index + 1]
+        super().__init__(self._native_reference)
+
+    @property
+    def _native_reference(self):
+        _dispatch = {
+            AuxDataObjectType.Dataset: _tecutil.AuxDataDataSetGetRef,
+            AuxDataObjectType.Frame: _tecutil.AuxDataFrameGetRef,
+            AuxDataObjectType.Layout: _tecutil.AuxDataLayoutGetRef,
+            AuxDataObjectType.Linemap: _tecutil.AuxDataLineMapGetRef,
+            AuxDataObjectType.Page: _tecutil.AuxDataPageGetRef,
+            AuxDataObjectType.Variable: _tecutil.AuxDataVarGetRef,
+            AuxDataObjectType.Zone: _tecutil.AuxDataZoneGetRef}
+        with self._activated_parent():
+            return _dispatch[self.object_type](*self.getref_args)
+
+    @contextmanager
+    def _activated_parent(self):
+        if self.parent:
+            with self.parent.activated():
+                yield
+        else:
+            yield
+
+    @contextmanager
+    def assignment(self):
+        _tecutil.AuxDataBeginAssign()
+        try:
+            yield
+        finally:
+            _tecutil.AuxDataEndAssign()
+
+    def index(self, key):
+        """Returns the zero-based index of the element based on key.
+
+        Example usage::
+
+            >>> frame = tp.active_frame()
+            >>> frame.aux_data['result'] = '3.1415'
+            >>> frame.aux_data['other_info'] = '128'
+            >>> print(frame.aux_data.index('other_info'))
+            0
+            >>> print(frame.aux_data.index('result'))
+            1
+        """
+        try:
+            success, index = _tecutil.AuxDataGetItemIndex(self, key)
+            index -= 1
+            if not success:
+                raise TecplotKeyError
+        except TecplotSystemError:
+            raise TecplotKeyError
+        return index
+
+    _Item = namedtuple('Item', ['key', 'value', 'dtype', 'retain'])
+
+    def _item(self, index):
+        res =_tecutil.AuxDataGetItemByIndex(self, index + 1)
+        key, value, dtype, retain = res
+        if dtype is AuxDataType.String:
+            value = ctypes.cast(value, ctypes.c_char_p).value.decode('utf-8')
+        else:
+            # if we ever add another type to AuxDataType, this would
+            # need to be expanded as well as setitem which currently
+            # just converts every input to a string.
+            raise TecplotNotImplementedError
+        return AuxData._Item(key, value, dtype, retain)
+
+    def key(self, index):
+        """Returns the key at a specific zero-based index.
+
+        Example usage::
+
+            >>> frame = tp.active_frame()
+            >>> frame.aux_data['result'] = '3.1415'
+            >>> frame.aux_data['other_info'] = '128'
+            >>> print(frame.aux_data.key(0))
+            other_info
+            >>> print(frame.aux_data.key(1))
+            result
+        """
+        return self._item(index).key
+
+    def __getitem__(self, key):
+        if isinstance(key, str):
+            key = self.index(key)
+        return self._item(key).value
+
+    @lock()
+    def __setitem__(self, key, value):
+        if isinstance(key, int):
+            try:
+                key = self.key(key)
+            except:
+                raise TecplotIndexError
+        if not _tecutil.AuxDataSetItem(self, key, str(value),
+                                       AuxDataType.String.value, True):
+            raise TecplotSystemError()
+
+    @lock()
+    def __delitem__(self, key):
+        if isinstance(key, str):
+            key = self.index(key)
+        _tecutil.AuxDataDeleteItemByIndex(self, key + 1)
+
+    def __len__(self):
+        return _tecutil.AuxDataGetNumItems(self)
+
+    def __iter__(self):
+        self._current_index = -1
+        self._current_length = len(self)
+        return self
+
+    def __next__(self):
+        self._current_index += 1
+        if self._current_index < self._current_length:
+            return self.key(self._current_index)
+        else:
+            raise StopIteration
+
+    def next(self):
+        return self.__next__()
+
+    def items(self):
+        """Yields all key/value pairs of the Aux Data attached to the parent.
+
+        Elements are always ordered alphabetically by the keys. Example usage::
+
+            >>> frame = tp.active_frame()
+            >>> frame.aux_data['result'] = '3.1415'
+            >>> frame.aux_data['other_info'] = '128'
+            >>> for key, value in frame.aux_data.items():
+            ...     print(key, value)
+            other_info 128
+            result 3.1415
+        """
+        for i in range(len(self)):
+            item = self._item(i)
+            yield item.key, item.value
+
+    def keys(self):
+        """Yields all keys of the Aux Data attached to the parent.
+
+        Elements are always ordered alphabetically by the keys. Example usage::
+
+            >>> frame = tp.active_frame()
+            >>> frame.aux_data['result'] = '3.1415'
+            >>> frame.aux_data['other_info'] = '128'
+            >>> for value in frame.aux_data.keys():
+            ...     print(value)
+            other_info
+            result
+        """
+        for key in self:
+            yield key
+
+    def values(self):
+        """Yields all values of the Aux Data attached to the parent.
+
+        Elements are always ordered alphabetically by the keys. Example usage::
+
+            >>> frame = tp.active_frame()
+            >>> frame.aux_data['result'] = '3.1415'
+            >>> frame.aux_data['other_info'] = '128'
+            >>> for value in frame.aux_data.values():
+            ...     print(value)
+            128
+            3.1415
+        """
+        for _, value in self.items():
+            yield value
+
+    def as_dict(self):
+        """Returns a Python dict of the Aux Data attached to the parent.
+
+        Note that this will remove the alphabetical ordering guarantee that Aux
+        Data has since Python dict objects are unordered. Example usage::
+
+            >>> frame = tp.active_frame()
+            >>> frame.aux_data['result'] = '3.1415'
+            >>> frame.aux_data['other_info'] = '128'
+            >>> aux = frame.aux_data.as_dict()
+            >>> print(aux)
+            {'result': '3.1415', 'other_info': '128'}
+        """
+        return {k: v for k, v in self.items()}
+
+    def __str__(self):
+        return str(self.as_dict())
+
+    def update(self, *other, **kwargs):
+        """Update Aux Data with key/value pairs from another Aux Data or dict.
+
+        Example usage::
+
+            >>> frame = tp.active_frame()
+            >>> frame.aux_data.update({'result': '3.1415', 'other_info': '128'})
+            >>> print(frame.aux_data)
+            {'result': '3.1415', 'other_info': '128'}
+        """
+        with self.assignment():
+            for d in it.chain(other, [kwargs]):
+                for k, v in d.items():
+                    self[k] = v
+
+    def clear(self):
+        """Deletes all Aux Data from the associated object.
+
+        Example usage::
+
+            >>> print(frame.aux_data)
+            {'bb': 'test bb', 'cc': 'test cc', 'aa': 'test aa'}
+            >>> frame.aux_data.clear()
+            >>> print(frame.aux_data)
+            {}
+        """
+        for key in list(self.keys()):
+            del self[key]

tecplot/session/config.py

@@ -0,0 +1,92 @@
+r"""
+.. function:: tecplot.session.configuration()
+
+    Run-time configuration parameters can be accessed and changed through the
+    configuration instance returned by ``tecplot.session.configuration()``::
+
+        >>> conf = tecplot.session.configuration()
+        >>> print(conf.latex.command)
+        pdflatex -interaction=batchmode -output-directory=@OUTDIR @INFILE
+        >>> conf.latex.preamble = '\usepackage{amsmath}'
+
+The default settings have been tested with MiKTeX and TeXLive engines and
+should work without the need for any changes to the session configuration.
+However, you may wish to change the LaTeX packages which are loaded by default
+or use a different LaTeX engine. See the Tecplot user manual for guidance in
+changing your LaTeX configuration file so changes persist across sessions.
+
+Available configuration parameters:
+
+..  contents::
+    :local:
+    :depth: 1
+
+``latex.command``
+^^^^^^^^^^^^^^^^^
+
+The system command used to compile LaTeX text objects. Parameters ``@OUTDIR``
+and ``@INFILE`` are replaced with appropriate strings to coordinate the
+creation of the final rendered text.
+
+Type:
+    `str`
+Default:
+    "latex -interaction=batchmode -output-directory=\@OUTDIR @INFILE"
+
+``latex.dvipng_command``
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The system command used to convert the output from the LaTeX command from DVI
+to PNG. The parameters ``@DPI``, ``@PAGERANGE``, ``@OUTFILE`` and ``@INFILE``
+are replaced with appropriate strings to coordinate the creation fo the final
+rendered text.
+
+Type:
+    `str`
+Default:
+    "dvipng -bg Transparent -D @DPI -pp @PAGERANGE -T tight -o @OUTFILE @INFILE"
+
+``latex.preamble``
+^^^^^^^^^^^^^^^^^^
+
+Code that will be placed before the ``\begin{document}`` section of the LaTeX
+source to be compiled. This primarily used for loading LaTeX packages.
+
+Type:
+    `str`
+Default:
+    "\\usepackage{amsfonts}\\usepackage{amsmath}\\usepackage{amssymb}\\usepackage{amsthm}"
+
+"""
+from builtins import str
+
+from ..tecutil import sv
+from .style import StyleConfig, style_property
+
+
+class ConfigLaTeX(StyleConfig):
+    command = style_property(str, sv.LATEXCMD)
+    preamble = style_property(str, sv.PREAMBLE)
+    dvipng_command = style_property(str, sv.DVIPNGCMD)
+
+
+class ConfigLimits(StyleConfig):
+    load_on_demand_threshold_min = style_property(
+                                    float, sv.LODTHRESHOLDMINFRACT)
+    load_on_demand_threshold_max = style_property(
+                                    float, sv.LODTHRESHOLDMAXFRACT)
+
+
+class ConfigOpenGL(StyleConfig):
+    run_display_lists_after_building = style_property(
+                                        bool, sv.RUNDISPLAYLISTSAFTERBUILDING)
+
+
+class ConfigInterface(StyleConfig):
+    opengl = ConfigOpenGL('interface.opengl', sv.INTERFACE, sv.OPENGLCONFIG)
+
+
+class configuration(StyleConfig):
+    latex = ConfigLaTeX('latex', sv.LATEX)
+    limits = ConfigLimits('limits', sv.LIMITS)
+    interface = ConfigInterface('interface', sv.INTERFACE)