.. oe:namespace:: OEDepict


.. oe:constnamespace:: OEHighlightOverlayStyle

   This namespace contains constants representing various styles
   of overlay highlighting.

   .. seealso::

      * :oe:func:`OEDepict::OEAddHighlightOverlay` function
      * :ref:`OEHighlightOverlayBase <OEDepict_OEHighlightOverlayBase>` class
      * :ref:`section_highlighting_overlap` section

   The :oe:constns:`OEDepict::OEHighlightOverlayStyle` namespace contains the
   following constants:

   .. ################################################################
      #
      ################################################################

   .. oe:constant:: Default

      The default highlighting style is
      :oe:const:`OEDepict::OEHighlightOverlayStyle::BallAndStick`.


   .. ################################################################
      #
      ################################################################

   .. oe:constant:: BallAndStick

      See example in :ref:`Figure: Example of overlay highlighting using the 'BallAndStick' style<figure_Overlay_BallAndStick>`.

      * Atoms are highlighted by depicting spheres underneath them.
        If an atom is part of more than one patterns, then all the
        colors associated with the patterns are used by turns to color
        pie segments of the sphere.

      * Bonds are highlighted by depicting sticks underneath them.
        If a bond is part of more than one patterns, then all the
        colors associated with the patterns are used by turns to color
        line segments of the stick.

      .. _figure_Overlay_BallAndStick:

      .. figure:: ../images/OEHighlightOverlayStyle_BallAndStick.*
         :align:  center

         **Example of overlay highlighting using the 'BallAndStick' style**

      The radius of the spheres and the width of the sticks are automatically
      scaled with the molecule.
      See example in :ref:`Figure: Example of scaling the 'BallAndStick' style highlighting along with the molecule<figure_Overlay_BallAndStick_Scaling>`.

      .. _figure_Overlay_BallAndStick_Scaling:

      .. figure:: ../images/HighlightOverlayScaling_BallAndStick.*
         :align:  center

         **Example of scaling the 'BallAndStick' style highlighting along with the molecule**

      .. seealso::

         * :ref:`OEHighlightOverlayByBallAndStick <OEDepict_OEHighlightOverlayByBallAndStick>` class

      .. note::

         It is recommended to select colors with high contrast when highlighting overlapped
         patterns with the :oe:const:`OEDepict::OEHighlightOverlayStyle::BallAndStick`
         style.

         .. seealso::

            * :oe:func:`OESystem::OEGetContrastColors` function

      Even though there is no limit on the number of overlapping patterns that can
      be highlighted simultaneously, attempting to highlight too many patterns will
      result in a complex image that will be difficult to visually interpret.
      See example in :ref:`Figure: Example of highlighting extremely overlapping patterns<figure_Overlay_BallAndStick_ManyPatterns>`
      In this image, all unique 'phenol' substructures of a molecule are
      highlighted simultaneously.

      .. _figure_Overlay_BallAndStick_ManyPatterns:

      .. figure:: ../images/HighlightOverlayManyPatterns_BallAndStick.*
         :align:  center

         **Example of highlighting extremely overlapping patterns**
