.. oe:namespace:: OESystem


.. meta::
   :keywords: OEColorGradientBase, ColorGradientBase


.. _OESystem_OEColorGradientBase:

.. oe:class:: OEColorGradientBase

   .. oe:api::

      class OEColorGradientBase

   :ref:`OEColorGradientBase <OESystem_OEColorGradientBase>`  is an abstract class
   used for interpolating between colors that are defined by using the
   :ref:`OEColorStop <OESystem_OEColorStop>` class.

   The following classes derive from this class:
    * :ref:`OEExponentColorGradient <OESystem_OEExponentColorGradient>`
    * :ref:`OEExponentialColorGradient <OESystem_OEExponentialColorGradient>`
    * :ref:`OELinearColorGradient <OESystem_OELinearColorGradient>`
    * :ref:`OELogarithmicColorGradient <OESystem_OELogarithmicColorGradient>`

   .. ################################################################
      # Constructors
      ################################################################

   .. oe:method:: Constructors

      .. oe:api::

         OEColorGradientBase()

      Default constructor that creates an "empty" color gradient.

      .. note::

         An "empty" color gradient always returns the :oe:const:`OEBlack<OESystem::OESystem::OEBlack>`
         color, when calling the :oe:meth:`OESystem::OEColorGradientBase::GetColorAt`,
         the :oe:meth:`OESystem::OEColorGradientBase::GetMinColor` or
         the :oe:meth:`OESystem::OEColorGradientBase::GetMaxColor` methods.

      .. oe:api::

         OEColorGradientBase(const OEColorStop& oneStop)

      Creates an :ref:`OEColorGradientBase <OESystem_OEColorGradientBase>` object with
      one color stop. An :ref:`OEColorGradientBase <OESystem_OEColorGradientBase>`
      object that has only one color stop will always return that
      color when calling the
      :oe:meth:`OESystem::OEColorGradientBase::GetColorAt` method.

      .. oe:api::

         OEColorGradientBase(const OEColorStop& bgnStop,
                             const OEColorStop& endStop)

      Creates an :ref:`OEColorGradientBase <OESystem_OEColorGradientBase>` object with
      interpolation range between the two specified color stops.

      .. oe:api::

         OEColorGradientBase(const OEColorGradientBase& rhs)

      Copy constructor.


   .. oe:method:: operator=
      :language: c++

      .. oe:api::

         OEColorGradientBase& operator=(const OEColorGradientBase& rhs)

      Assignment operator.

   .. oe:method:: AddStop

      .. oe:language:: c++ java csharp

         .. oe:api::

            bool AddStop(const OEColorStop& stop)

      .. oe:language:: python

         .. oe:api:: python

            AddStop(stop: OEColorStop) -> bool

      Add a new color stop to the color gradient.

   .. oe:method:: DeleteStop

      .. oe:language:: c++ java csharp

         .. oe:api::

            bool DeleteStop(unsigned int stopidx)

      .. oe:language:: python

         .. oe:api:: python

            DeleteStop(stopidx: int) -> bool

      Deletes the color stop at ``idx`` and returns ``true``. If the
      color gradient only has one color stop or the ``idx`` is
      not between ``0`` and
      :oe:meth:`NumStops()<OESystem::OEColorGradientBase::NumStops>`,
      then :oe:meth:`OESystem::OEColorGradientBase::DeleteStop`
      throws a warning and returns ``false``.

   .. oe:method:: GetColorAt

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEColor GetColorAt(double value) const

      .. oe:language:: python

         .. oe:api:: python

            GetColorAt(value: float) -> OEColor

      Returns the interpolated color at ``value`` defined by
      the color stops in the color gradient.
      Returns :oe:meth:`OESystem::OEColorGradientBase::GetMinColor`
      if the ``value`` is less than
      :oe:meth:`OESystem::OEColorGradientBase::GetMinValue`.
      Returns :oe:meth:`OESystem::OEColorGradientBase::GetMaxColor`
      if the ``value`` is greater than
      :oe:meth:`OESystem::OEColorGradientBase::GetMinValue`.


   .. oe:method:: GetMaxColor

      .. oe:language:: c++ java csharp

         .. oe:api::

            const OEColor& GetMaxColor() const

      .. oe:language:: python

         .. oe:api:: python

            GetMaxColor() -> OEColor

      Returns the color associated with the value returned by the
      :oe:meth:`OESystem::OEColorGradientBase::GetMaxValue`
      method.


   .. oe:method:: GetMaxValue

      .. oe:language:: c++ java csharp

         .. oe:api::

            double GetMaxValue() const

      .. oe:language:: python

         .. oe:api:: python

            GetMaxValue() -> float

      Returns the highest value stored in any of the color stops of the
      color gradient.


   .. oe:method:: GetMinColor

      .. oe:language:: c++ java csharp

         .. oe:api::

            const OEColor& GetMinColor() const

      .. oe:language:: python

         .. oe:api:: python

            GetMinColor() -> OEColor

      Returns the color associated with the value returned by the
      :oe:meth:`OESystem::OEColorGradientBase::GetMinValue` method.


   .. oe:method:: GetMinValue

      .. oe:language:: c++ java csharp

         .. oe:api::

            double GetMinValue() const

      .. oe:language:: python

         .. oe:api:: python

            GetMinValue() -> float

      Returns the lowest value stored in any of the color stops of the
      color gradient.


   .. oe:method:: GetStops

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEIterBase< OEColorStop >* GetStops() const

      .. oe:language:: python

         .. oe:api:: python

            GetStops() -> Iterable[OEColorStop]

      Returns an iterator over all color stops of the color gradient.
      The iterator is invariant to further modifications of
      the :ref:`OEColorGradientBase <OESystem_OEColorGradientBase>` object.


   .. oe:method:: IsEmpty

      .. oe:language:: c++ java csharp

         .. oe:api::

            bool IsEmpty() const

      .. oe:language:: python

         .. oe:api:: python

            IsEmpty() -> bool

      Returns ``true`` if no color stop has been added to the
      :ref:`OEColorGradientBase <OESystem_OEColorGradientBase>` object that has been
      created by the default constructor, otherwise it returns ``false``.


   .. oe:method:: NumStops

      .. oe:language:: c++ java csharp

         .. oe:api::

            unsigned int NumStops() const

      .. oe:language:: python

         .. oe:api:: python

            NumStops() -> int

      Returns the number of color stops of the color gradient.


   .. oe:method:: TransformValue

      .. oe:language:: c++ java csharp

         .. oe:api::

            double TransformValue(double value) const = 0

      .. oe:language:: python

         .. oe:api:: python

            TransformValue(value: float) -> float

      This is a virtual const method that is implemented in the concrete
      color gradient derived classes.
      This method is called by :oe:meth:`OESystem::OEColorGradientBase::GetColorAt`
      method to transform a value before performing color interpolation.
