pytecplot 1.5.2__py3-none-any.whl

tecplot/legend/contour_legend.py

@@ -0,0 +1,516 @@
+from builtins import str, super
+
+from ..tecutil import sv
+from .. import session, constant, tecutil, text
+from . import legend
+
+class LegendHeader(session.Style):
+    """
+    """
+    def __init__(self, legend, *svargs):
+        self.legend = legend
+        super().__init__(legend._sv, sv.HEADER, **legend._kw)
+
+    @property
+    def show(self):
+        """`bool`: Show or hide the contour legend header.
+
+        .. note::
+
+            The header text will display the name of the variable assigned to
+            the contour group or a custom text if the `use_custom_text` is set
+            to True.
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType
+            >>> plot = frame.plot(PlotType.Cartesian3D)
+            >>> legend_header = plot.contour(0).legend.header
+            >>> legend_header.show = True
+        """
+        return self._get_style(bool, sv.SHOW)
+
+    @show.setter
+    def show(self, value):
+        self._set_style(bool(value), sv.SHOW)
+
+    @property
+    def font(self):
+        """`text.Font`: Font used to display the legend header.
+
+        .. note::
+
+            The font `size_units <tecplot.text.Font.size_units>` property
+            may only be set to `Units.Frame` or `Units.Point`.
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType
+            >>> legend = frame.plot(PlotType.Cartesian3D).contour(0).legend
+            >>> legend.header.font.italic = True
+        """
+        return text.LegendFont(self, sv.TEXTSHAPE)
+
+    @property
+    def use_custom_text(self):
+        """ `bool`: Use custom text on the contour legend header.
+
+        If set to `True`, the legend header will be set by the `custom_text`
+        property instead of the variable name assigned to the contour group.
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType
+            >>> plot = frame.plot(PlotType.Cartesian3D)
+            >>> header = plot.contour(0).legend.header
+            >>> header.use_custom_text = True
+            >>> header.custom_text = 'Solution time: &(SOLUTIONTIME) ms'
+
+        See also: `LegendHeader.custom_text`
+
+        .. versionadded:: 2021.2
+
+            The ability to specify custom contour legend header text requires
+            Tecplot 360 2021 R2 or later.
+
+        .. versionadded:: 1.4.2
+        """
+        return self._get_style(bool, sv.USECUSTOMTEXT)
+
+    @use_custom_text.setter
+    def use_custom_text(self, value):
+        self._set_style(bool(value), sv.USECUSTOMTEXT)
+
+    @property
+    def custom_text(self):
+        """ `str`: A string to be used in the contour legend header.
+
+        If the `use_custom_text` property is set to `True`, the legend header
+        will contain this text instead of the name of the variable assigned to
+        the contour group. The text may contain Dynamic Text and formatting
+        tags (see User Manual).
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType
+            >>> plot = frame.plot(PlotType.Cartesian3D)
+            >>> header = plot.contour(0).legend.header
+            >>> header.use_custom_text = True
+            >>> header.custom_text = 'time: &(SOLUTIONTIME) <greek>ms</greek>'
+
+        See also: `LegendHeader.use_custom_text`
+
+        .. versionadded:: 2021.2
+
+            The ability to specify custom contour legend header text requires
+            Tecplot 360 2021 R2 or later.
+
+        .. versionadded:: 1.4.2
+        """
+        return self._get_style(str, sv.CUSTOMTEXT)
+
+    @custom_text.setter
+    def custom_text(self, value):
+        self._set_style(str(value), sv.CUSTOMTEXT)
+
+    @property
+    def text_type(self):
+        """`TextType`: Typesetter for the contour legend header.
+
+        This determines how the header text for the contour legend
+        is rendered. Options are `TextType.Regular` or `TextType.LaTeX`.
+        When using ``LaTeX``, make sure to use Python raw strings so
+        that literal back-slashes are preserved.
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType, TextType
+            >>> plot = frame.plot(PlotType.Cartesian3D)
+            >>> header = plot.contour(0).legend.header
+            >>> header.text_type = TextType.LaTeX
+            >>> header.use_custom_text = True
+            >>> header.custom_text = r'\LaTeX'
+
+        .. versionadded:: 2022.1
+
+            The ability to use LaTeX for contour legend header text requires
+            Tecplot 360 2022 R1 or later.
+
+        .. versionadded:: 1.5.0
+        """
+        return self._get_style(constant.TextType, sv.TEXTTYPE)
+
+    @text_type.setter
+    def text_type(self, value):
+        self._set_style(constant.TextType(value), sv.TEXTTYPE)
+
+
+class ContourLegend(legend.TabularLegend):
+    """Contour legend attributes.
+
+    This class allows you to customize the appearance of the contour legend.
+    The contour legend can be positioned anywhere inside the frame using the
+    `position` attribute of this class.  Example usage:
+
+    .. code-block:: python
+        :emphasize-lines: 21-36
+
+        import os
+        import numpy as np
+
+        import tecplot
+        from tecplot.constant import *
+
+        # By loading a layout many style and view properties are set up already
+        examples_dir = tecplot.session.tecplot_examples_directory()
+        datafile = os.path.join(examples_dir, 'SimpleData', 'RainierElevation.lay')
+        tecplot.load_layout(datafile)
+
+        frame = tecplot.active_frame()
+        plot = frame.plot()
+
+        # Rename the elevation variable
+        frame.dataset.variable('E').name = "Elevation (m)"
+
+        # Set the levels to nice values
+        plot.contour(0).levels.reset_levels(np.linspace(200,4400,22))
+
+        legend = plot.contour(0).legend
+        legend.show = True
+        legend.vertical = False  # Horizontal
+        legend.auto_resize = False
+        legend.label_step = 5
+
+        legend.overlay_bar_grid = False
+        legend.position = (55, 94)  # Frame percentages
+
+        legend.box.box_type = TextBox.None_ # Remove Text box
+
+        legend.header.font.typeface = 'Courier'
+        legend.header.font.bold = True
+
+        legend.number_font.typeface = 'Courier'
+        legend.number_font.bold = True
+
+        tecplot.export.save_png('legend_contour.png', 600, supersample=3)
+
+    .. figure:: /_static/images/legend_contour.png
+        :width: 300px
+        :figwidth: 300px
+    """
+    def __init__(self, contour, *svargs):
+        self.contour = contour
+        super().__init__(contour._sv, sv.LEGEND, **contour._kw)
+
+    @tecutil.inherited_property(legend.Legend)
+    def show(self):
+        """`bool`: Show or hide the legend.
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType
+            >>> legend = frame.plot(PlotType.Cartesian3D).contour(0).legend
+            >>> legend.show = True
+        """
+
+    @tecutil.inherited_property(legend.Legend)
+    def anchor_alignment(self):
+        """`AnchorAlignment`: Anchor location of the legend.
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType, AnchorAlignment
+            >>> legend = frame.plot(PlotType.Cartesian3D).contour(0).legend
+            >>> legend.anchor_alignment = AnchorAlignment.BottomCenter
+        """
+
+    @tecutil.inherited_property(legend.Legend)
+    def text_color(self):
+        """`Color`: Color of legend text.
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType, Color
+            >>> legend = frame.plot(PlotType.Cartesian3D).contour(0).legend
+            >>> legend.text_color = Color.Blue
+        """
+
+    @tecutil.inherited_property(legend.Legend)
+    def position(self):
+        """`tuple`: Position as a percentage of frame width/height.
+
+        The legend is automatically placed for you. You may specify the
+        :math:`(x,y)` position of the legend by setting this value, where
+        :math:`x` is the percentage of frame width, and :math:`y` is a
+        percentage of frame height.
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType
+            >>> legend = frame.plot(PlotType.Cartesian3D).contour(0).legend
+            >>> legend.position = (.1, .3)
+            >>> pos = legend.position
+            >>> pos.x  # == position[0]
+            .1
+            >>> pos.y  # == position[1]
+            .3
+        """
+
+    @tecutil.inherited_property(legend.Legend)
+    def box(self):
+        """`text.TextBox`: Legend box attributes.
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType, Color
+            >>> legend = frame.plot(PlotType.Cartesian3D).contour(0).legend
+            >>> legend.box.color = Color.Blue
+        """
+
+    @tecutil.inherited_property(legend.TabularLegend)
+    def row_spacing(self):
+        """`float`: Spacing between rows in the legend.
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType
+            >>> legend = frame.plot(PlotType.Cartesian3D).contour(0).legend
+            >>> legend.row_spacing = 1.5
+        """
+
+    @property
+    def auto_resize(self):
+        """`bool`: Skip levels to create a reasonably sized legend.
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType
+            >>> legend = frame.plot(PlotType.Cartesian3D).contour(0).legend
+            >>> legend.auto_resize = True
+        """
+        return self._get_style(bool, sv.AUTORESIZE)
+
+    @auto_resize.setter
+    def auto_resize(self, value):
+        self._set_style(bool(value), sv.AUTORESIZE)
+
+    @property
+    def header_font(self):
+        if __debug__:
+            tecutil.api_moved('ContourLegend.header_font',
+                              'ContourLegend.header.font',
+                              '1.4.2', '2021 R1', warning=True)
+        return text.LegendFont(self, sv.HEADERTEXTSHAPE)
+
+    @property
+    def number_font(self):
+        """`text.Font`: Font used to display numbers in the legend.
+
+        .. note::
+            The font `size_units <tecplot.text.Font.size_units>` property
+            may only be set to `Units.Frame` or `Units.Point`.
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType
+            >>> legend = frame.plot(PlotType.Cartesian3D).contour(0).legend
+            >>> legend.number_font.italic = True
+        """
+        return text.LegendFont(self, sv.NUMBERTEXTSHAPE)
+
+    @property
+    def show_cutoff_levels(self):
+        """`bool`: Show color bands for levels affected by color cutoff.
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType
+            >>> legend = frame.plot(PlotType.Cartesian3D).contour(0).legend
+            >>> legend.show_cutoff_levels = True
+        """
+        return self._get_style(bool, sv.INCLUDECUTOFFLEVELS)
+
+    @show_cutoff_levels.setter
+    def show_cutoff_levels(self, value):
+        self._set_style(bool(value), sv.INCLUDECUTOFFLEVELS)
+
+    @property
+    def include_cutoff_levels(self):
+        tecutil.api_moved('ContourLegend.include_cutoff_levels',
+                          'ContourLegend.show_cutoff_levels',
+                          '0.13', '2018 R2')
+
+    @include_cutoff_levels.setter
+    def include_cutoff_levels(self, value):
+        tecutil.api_moved('ContourLegend.include_cutoff_levels',
+                          'ContourLegend.show_cutoff_levels',
+                          '0.13', '2018 R2')
+
+    @property
+    def vertical(self):
+        """`bool`: Orientation of the legend.
+
+        When set to `True`, the legend is vertical. When set to `False`, the
+        legend is horizontal.
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType
+            >>> legend = frame.plot(PlotType.Cartesian3D).contour(0).legend
+            >>> legend.vertical = False  # Show horizontal legend
+        """
+        return self._get_style(bool, sv.ISVERTICAL)
+
+    @vertical.setter
+    def vertical(self, value):
+        self._set_style(bool(value), sv.ISVERTICAL)
+
+    @property
+    def label_increment(self):
+        """`float`: Spacing between labels along the contour legend.
+
+        Labels will be placed on the contour variable range from min to max.
+        The smaller the increment value the more legend labels will be created.
+        If the `label_location` is `ContLegendLabelLocation.Increment`, labels
+        are incremented by this value. For example, a `label_increment` value
+        of .5 will show labels at .5, 1.0, 1.5, etc.
+
+        .. Note::
+
+            This value is only used if `label_location` is set to
+            `ContLegendLabelLocation.Increment`. Otherwise it is ignored.
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType, ContLegendLabelLocation
+            >>> legend = frame.plot(PlotType.Cartesian3D).contour(0).legend
+            >>> legend.label_location = ContLegendLabelLocation.Increment
+            >>> legend.label_increment = .5
+
+        .. seealso:: `label_location`
+        """
+        return self._get_style(float, sv.LABELINCREMENT)
+
+    @label_increment.setter
+    def label_increment(self, value):
+        self._set_style(float(value), sv.LABELINCREMENT)
+
+    @property
+    def label_location(self):
+        """`ContLegendLabelLocation`: Placement of labels on the legend.
+
+        If you have selected `ColorMapDistribution.Continuous` for the contour
+        colormap filter distribution, you have three options for placement of
+        labels on the legend:
+
+        * `ContLegendLabelLocation.ContourLevels` - This option places one
+          label for each contour level. See Contour Levels and Color.
+        * `ContLegendLabelLocation.Increment` - Set `label_increment` to the
+          increment value.
+        * `ContLegendLabelLocation.ColorMapDivisions` - Places one label for
+          each control point on the color map.
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType, ContLegendLabelLocation
+            >>> legend = frame.plot(PlotType.Cartesian3D).contour(0).legend
+            >>> legend.label_location = ContourLevelLabelLocation.Increment
+            >>> legend.label_increment = .5
+
+        .. seealso:: `label_increment`
+        """
+        return self._get_style(constant.ContLegendLabelLocation,
+                               sv.LABELLOCATION)
+
+    @label_location.setter
+    def label_location(self, value):
+        self._set_style(constant.ContLegendLabelLocation(value),
+                        sv.LABELLOCATION)
+
+    @property
+    def overlay_bar_grid(self):
+        """`bool`: Draw a line around each band in the legend color bar.
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType
+            >>> legend = frame.plot(PlotType.Cartesian3D).contour(0).legend
+            >>> legend.overlay_bar_grid = False
+        """
+        return self._get_style(bool, sv.OVERLAYBARGRID)
+
+    @overlay_bar_grid.setter
+    def overlay_bar_grid(self, value):
+        self._set_style(bool(value), sv.OVERLAYBARGRID)
+
+    @property
+    def header(self):
+        """`LegendHeader`: `LegendHeader` associated with a `ContourLegend`.
+
+        This object controls the attributes of the contour legend header.
+
+        .. versionadded:: 1.4.2
+
+            The contour legend header style control has been moved into a new
+            namespace `header`:
+
+            ============================== ==============================
+            Old API                        New API
+            ============================== ==============================
+            ``contour.legend.show_header`` ``contour.legend.header.show``
+            ``contour.legend.header_font`` ``contour.legend.header.font``
+            ============================== ==============================
+
+        Example usage::
+
+            >>> plot.contour(0).legend.header.show = True
+        """
+        return LegendHeader(self)
+
+    @property
+    def show_header(self):
+        if __debug__:
+            tecutil.api_moved('ContourLegend.show_header',
+                              'ContourLegend.header.show',
+                              '1.4.2', '2021 R1', warning=True)
+        return self._get_style(bool, sv.SHOWHEADER)
+
+    @show_header.setter
+    def show_header(self, value):
+        if __debug__:
+            tecutil.api_moved('ContourLegend.show_header',
+                              'ContourLegend.header.show',
+                              '1.4.2', '2021 R1', warning=True)
+        self._set_style(bool(value), sv.SHOWHEADER)
+
+    @property
+    def label_step(self):
+        """`int`: Step size between labels along the legend.
+
+        This is an alias for `ContourLegend.contour.labels.step
+        <ContourLabels.step>`::
+
+            >>> contour = frame.plot().contour(0)
+            >>> contour.legend.label_step = 3
+            >>> print(contour.labels.step)
+            3
+        """
+        return self.contour.labels.step
+
+    @label_step.setter
+    def label_step(self, step):
+        self.contour.labels.step = step
+
+    @property
+    def label_format(self):
+        """`LabelFormat`: Number formatting for labels along the legend.
+
+        This is an alias for `ContourLegend.contour.labels.format
+        <ContourLabels.format>`::
+
+            >>> contour = frame.plot().contour(0)
+            >>> contour.legend.label_format.precision = 3
+            >>> print(contour.labels.format.precision)
+            3
+        """
+        return self.contour.labels.format

tecplot/legend/legend.py

@@ -0,0 +1,141 @@
+from builtins import super
+
+from ..constant import *
+from ..exception import *
+from ..tecutil import  sv
+from .. import session, tecutil, text
+
+
+class Legend(session.Style):
+    @property
+    def box(self):
+        """`text.TextBox`: Legend box attributes.
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType, Color
+            >>> plot = frame.plot(PlotType.XYLine)
+            >>> plot.legend.box.color = Color.Blue
+        """
+        return text.TextBox(self)
+
+    @property
+    def show(self):
+        """`bool`: Show or hide the legend.
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType
+            >>> legend = frame.plot(PlotType.XYLine).legend
+            >>> legend.show = True
+        """
+        return self._get_style(bool, sv.SHOW)
+
+    @show.setter
+    def show(self, value):
+        self._set_style(bool(value), sv.SHOW)
+
+    @property
+    def anchor_alignment(self):
+        """`AnchorAlignment`: Anchor location of the legend.
+
+        Example usage::
+
+            >>> from tecplot.constant import AnchorAlignment, PlotType
+            >>> legend = frame.plot(PlotType.XYLine).legend
+            >>> legend.anchor_alignment = AnchorAlignment.BottomCenter
+        """
+        return self._get_style(AnchorAlignment, sv.ANCHORALIGNMENT)
+
+    @anchor_alignment.setter
+    def anchor_alignment(self, value):
+        self._set_style(AnchorAlignment(value), sv.ANCHORALIGNMENT)
+
+    @property
+    def text_color(self):
+        """`Color`: Color of legend text.
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType, Color
+            >>> legend = frame.plot(PlotType.XYLine).legend
+            >>> legend.text_color = Color.Blue
+        """
+        return self._get_style(Color, sv.TEXTCOLOR)
+
+    @text_color.setter
+    def text_color(self, value):
+        self._set_style(Color(value), sv.TEXTCOLOR)
+
+    @property
+    def position(self):
+        """`tuple`: Position as a percentage of frame width/height.
+
+        The legend is automatically placed for you. You may specify the
+        :math:`(x,y)` position of the legend by setting this value, where
+        :math:`x` is the percentage of frame width, and :math:`y` is a
+        percentage of frame height.
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType
+            >>> legend = frame.plot(PlotType.XYLine).legend
+            >>> legend.position = (10, 30)
+        """
+        return session.XY(self, sv.XYPOS)
+
+    @position.setter
+    def position(self, pos):
+        session.XY(self, sv.XYPOS)[:] = pos
+
+
+class TabularLegend(Legend):
+    @property
+    def row_spacing(self):
+        """`float`: Spacing between rows in the legend.
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType
+            >>> legend = frame.plot(PlotType.XYLine).legend
+            >>> legend.row_spacing = 1.5
+        """
+        return self._get_style(float, sv.ROWSPACING)
+
+    @row_spacing.setter
+    def row_spacing(self, value):
+        self._set_style(float(value), sv.ROWSPACING)
+
+
+class CategoryLegend(TabularLegend):
+    @property
+    def show_text(self):
+        """`bool`: Show/hide mapping names in the legend.
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType
+            >>> plot = frame.plot(PlotType.XYLine)
+            >>> plot.legend.show_text = True
+        """
+        return self._get_style(bool, sv.SHOWTEXT)
+
+    @show_text.setter
+    def show_text(self, value):
+        self._set_style(bool(value), sv.SHOWTEXT)
+
+    @property
+    def font(self):
+        """`text.Font`: Legend font attributes.
+
+        .. note::
+            The font `size_units <tecplot.text.Font.size_units>` property
+            may only be set to `Units.Frame` or `Units.Point`.
+
+        Example usage::
+
+            >>> from tecplot.constant import PlotType
+            >>> plot = frame.plot(PlotType.XYLine)
+            >>> plot.legend.font.italic = True
+        """
+        return text.LegendFont(self)