Source code for tecplot.legend.rgb_coloring_legend

from builtins import str, super

from ..constant import *
from ..tecutil import sv
from .. import tecutil
from . import legend


class RGBColoringLegend(legend.Legend):
    """Legend for RGB coloring (multivariate contour) plots.

    .. note::
        The RGB coloring legend will only show when an active fieldmap's
        contour is being flooded by RGB.

    .. code-block:: python
        :emphasize-lines: 46-48

        import os
        import numpy as np

        import tecplot as tp
        from tecplot.constant import *

        def normalize_variable(dataset, varname, nsigma=2):
            '''
            Normalize a variable such that the specified number of standard deviations
            are within the range [0.5, 1] and the mean is transformed to 0.5. The
            new variable will append " normalized" to the original variable's name.
            '''
            with tp.session.suspend():
                newvarname = varname + ' normalized'
                dataset.add_variable(newvarname)
                data = np.concatenate([z.values(varname).as_numpy_array()
                                       for z in dataset.zones()])
                vmin = data.mean() - nsigma * data.std()
                vmax = data.mean() + nsigma * data.std()
                for z in dataset.zones():
                    arr = z.values(varname).as_numpy_array()
                    z.values(newvarname)[:] = (arr - vmin) / (vmax - vmin)


        examples_dir = tp.session.tecplot_examples_directory()
        infile = os.path.join(examples_dir, 'SimpleData', 'HeatExchanger.plt')
        dataset = tp.data.load_tecplot(infile)

        frame = tp.active_frame()
        plot = frame.plot(PlotType.Cartesian2D)
        plot.show_contour = True

        # Variables must be normalized relative to each other
        # to make effective use of RGB coloring.
        normalize_variable(dataset, 'T(K)')
        normalize_variable(dataset, 'P(N)')

        plot.rgb_coloring.mode = RGBMode.SpecifyGB

        # all three channel variables must be set even if
        # we are only contouring on two of them.
        plot.rgb_coloring.red_variable = dataset.variable(0)
        plot.rgb_coloring.green_variable = dataset.variable('P(N) normalized')
        plot.rgb_coloring.blue_variable = dataset.variable('T(K) normalized')

        plot.rgb_coloring.legend.show = True
        plot.rgb_coloring.legend.green_label = 'Pressure'
        plot.rgb_coloring.legend.blue_label = 'Temperature'

        plot.fieldmaps().contour.flood_contour_group = plot.rgb_coloring

        tp.export.save_png('rgb_coloring_legend.png')

    .. figure:: /_static/images/rgb_coloring_legend.png
        :width: 300px
        :figwidth: 300px
    """
    def __init__(self, rgb_coloring):
        self.rgb_coloring = rgb_coloring
        super().__init__(rgb_coloring._sv, sv.LEGEND, **rgb_coloring._kw)

    @tecutil.inherited_property(legend.CategoryLegend)
    def box(self):
        """`text.TextBox`: Legend box attributes.

        Example usage::

            >>> from tecplot.constant import Color
            >>> plot.rgb_coloring.legend.box.fill_color = Color.Yellow
        """

    @tecutil.inherited_property(legend.CategoryLegend)
    def show(self):
        """`bool`: Display the RGB coloring legend.

        Example usage::

            >>> plot.rgb_coloring.legend.show = True
        """

    @tecutil.inherited_property(legend.CategoryLegend)
    def anchor_alignment(self):
        """`AnchorAlignment`: Anchor location of the legend.

        Example usage::

            >>> from tecplot.constant import AnchorAlignment
            >>> legend = plot.rgb_coloring.legend
            >>> legend.anchor_alignment = AnchorAlignment.BottomCenter
        """

    @tecutil.inherited_property(legend.CategoryLegend)
    def text_color(self):
        """`Color`: Color of legend text.

        Example usage::

            >>> from tecplot.constant import Color
            >>> legend = plot.rgb_coloring.legend
            >>> legend.text_color = Color.Blue
        """

    @tecutil.inherited_property(legend.CategoryLegend)
    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::

            >>> plot.rgb_coloring.legend.position = (20, 80)
        """

    @tecutil.inherited_property(legend.CategoryLegend)
    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::

            >>> plot.rgb_coloring.legend.font.italic = True
        """

    @property
    def show_labels(self):
        """`bool`: Show the RGB channel labels.

        Example usage::

            >>> legend = plot.rgb_coloring.legend
            >>> legend.show_labels = True
            >>> legend.red_label = 'Variable A'
            >>> legend.green_label = 'Variable B'
            >>> legend.blue_label = 'Variable C'
        """
        return self._get_style(bool, sv.SHOWLABELS)

    @show_labels.setter
    def show_labels(self, value):
        self._set_style(bool(value), sv.SHOWLABELS)

    @property
    def height(self):
        """`float`: Size of RGB coloring legend

        Example usage::

            >>> plot.rgb_coloring.legend.height = 20
        """
        return self._get_style(float, sv.HEIGHT)

    @height.setter
    def height(self, value):
        self._set_style(float(value), sv.HEIGHT)

    @property
    def orientation(self):
        """`RGBLegendOrientation`: Placement of the RGB channels on the legend.

        The first color is on the bottom left, the second is on the bottom
        right, and the third is on top. Example usage::

            >>> from tecplot.constant import RGBLegendOrientation
            >>> legend = plot.rgb_coloring.legend
            >>> legend.orientation = RGBLegendOrientation.RBG
        """
        return self._get_style(RGBLegendOrientation, sv.RGBLEGENDORIENTATION)

    @orientation.setter
    def orientation(self, value):
        self._set_style(RGBLegendOrientation(value), sv.RGBLEGENDORIENTATION)

    @property
    def use_variable_for_red_label(self):
        """`bool`: Use the `Variable` name for the red channel.

        Example usage::

            >>> plot.rgb_coloring.legend.use_variable_for_red_label = False
            >>> plot.rgb_coloring.legend.red_label = 'gas'
        """
        return self._get_style(bool, sv.USEREDVARNAME)

    @use_variable_for_red_label.setter
    def use_variable_for_red_label(self, value):
        self._set_style(bool(value), sv.USEREDVARNAME)

    @property
    def red_label(self):
        """`str`: Label to use for the red channel.

        This can be set to a string (which may be empty) but the
        `use_variable_for_red_label` property must be set to `False` for this
        label to be shown::

            >>> plot.rgb_coloring.legend.use_variable_for_red_label = False
            >>> plot.rgb_coloring.legend.red_label = 'gas'
        """
        return self._get_style(str, sv.REDCHANNELLABEL)

    @red_label.setter
    def red_label(self, value):
        self._set_style(str(value), sv.REDCHANNELLABEL)

    @property
    def use_variable_for_green_label(self):
        """`bool`: Use the `Variable` name for the green channel.

        Example usage::

            >>> plot.rgb_coloring.legend.use_variable_for_green_label = False
            >>> plot.rgb_coloring.legend.green_label = 'gas'
        """
        return self._get_style(bool, sv.USEGREENVARNAME)

    @use_variable_for_green_label.setter
    def use_variable_for_green_label(self, value):
        self._set_style(bool(value), sv.USEGREENVARNAME)

    @property
    def green_label(self):
        """`str`: Label to use for the green channel.

        This can be set to a string (which may be empty) but the
        `use_variable_for_green_label` property must be set to `False` for this
        label to be shown::

            >>> plot.rgb_coloring.legend.use_variable_for_green_label = False
            >>> plot.rgb_coloring.legend.green_label = 'oil'
        """
        return self._get_style(str, sv.GREENCHANNELLABEL)

    @green_label.setter
    def green_label(self, value):
        self._set_style(str(value), sv.GREENCHANNELLABEL)

    @property
    def use_variable_for_blue_label(self):
        """`bool`: Use the `Variable` name for the blue channel.

        Example usage::

            >>> plot.rgb_coloring.legend.use_variable_for_blue_label = False
            >>> plot.rgb_coloring.legend.blue_label = 'gas'
        """
        return self._get_style(bool, sv.USEBLUEVARNAME)

    @use_variable_for_blue_label.setter
    def use_variable_for_blue_label(self, value):
        self._set_style(bool(value), sv.USEBLUEVARNAME)

    @property
    def blue_label(self):
        """`str`: Label to use for the blue channel.

        This can be set to a string (which may be empty) but the
        `use_variable_for_blue_label` property must be set to `False` for this
        label to be shown::

            >>> plot.rgb_coloring.legend.use_variable_for_blue_label = False
            >>> plot.rgb_coloring.legend.blue_label = 'water'
        """
        return self._get_style(str, sv.BLUECHANNELLABEL)

    @blue_label.setter
    def blue_label(self, value):
        self._set_style(str(value), sv.BLUECHANNELLABEL)