.. include:: ../../common/cookbook/cookbook-hyperlinks

.. include:: ../substitutions

.. oe:namespace:: OEGrapheme

.. meta::
   :keywords: OERenderColorOverlap

.. oe:function:: OERenderColorOverlap

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

      .. oe:api::

         void OERenderColorOverlap(OEDepict::OEImageBase& image,
                                   const OEShapeOverlapDisplay& odisp)

   .. oe:language:: python

      .. oe:api:: python

         OERenderColorOverlap(image: OEImageBase, odisp: OEShapeOverlapDisplay) -> None

   Renders the color overlap between a reference and a fit molecule.

   *image*
     The image on which the fit molecule is rendered along with
     circles representing the satisfied and missed color atoms of
     the reference molecule.

   *odisp*
     The :ref:`OEShapeOverlapDisplay <OEGrapheme_OEShapeOverlapDisplay>` object
     that holds the data necessary to depict the color overlap between
     the reference and the fit molecules.

   The following code snippet shows how to use the :oe:func:`OEGrapheme::OERenderColorOverlap`
   function. The image created is shown in
   :ref:`Table: Example of using the OERenderColorOverlap function<table_render_color_overlap>`.

   .. oe:source:: RenderColorOverlap.py
      :language: python
      :noindent:
      :frag:     SNIPPET-RENDER-COLOR-OVERLAP

   .. oe:source:: RenderColorOverlap.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-RENDER-COLOR-OVERLAP

   .. oe:source:: RenderColorOverlap.java
      :language: java
      :noindent:
      :frag:     SNIPPET-RENDER-COLOR-OVERLAP

   .. oe:source:: RenderColorOverlap.cs
      :language: csharp
      :noindent:
      :frag:     SNIPPET-RENDER-COLOR-OVERLAP

   .. note::

      The color atom matches between the reference and the fit molecule are
      represented by circles (or half circles if two color atoms occupy
      the same space in 3D).
      Each circle corresponds to a color atom in the reference molecule.
      The color of the circle indicates the fitness of the color atom
      match in 3D.
      The lighter the color, the smaller the overlap between the reference
      and fit color atoms in 3D.
      Unfilled circles represent unmatched reference color atoms.
      If there is a good color atom match exist for a reference color atom
      in 3D, then the circle representing the color atom is
      positioned to the matching fit color atom in 2D.

   .. _table_render_color_overlap:

   .. list-table:: **Example of using the OERenderColorOverlap function**
      :widths: 150 150
      :header-rows: 0

      * - **(A)** reference molecule (shape query)
        - **(B)** fit molecule
      * - .. image:: ../images/RenderShapeQuery.*
             :align:  center
        - .. image:: ../images/RenderColorOverlap.*
             :align:  center
      * - shape query depicted by the **OERenderShapeQuery** function
        - color atom overlap depicted by the **OERenderColorOverlap** function

   .. warning::

      When calling the :oe:func:`OEGrapheme::OERenderColorOverlap` function
      **no overlay is performed to maximize the color overlap** between the
      reference and the fit molecule, *i.e.*, the function simply calculates
      the color overlap using the given 3D coordinates.

   .. seealso::

      * :ref:`OEColorOverlapDisplayOptions <OEGrapheme_OEColorOverlapDisplayOptions>` class
      * :oe:func:`OEGrapheme::OERenderShapeQuery` function
      * :oe:func:`OEGrapheme::OERenderShapeOverlap` function

   .. admonition:: Code Example

      * :ref:`section_examples_summary_shapeoverlap2pdf` example
      * `Visualizing Shape and Color Overlap`_ **OpenEye Python Cookbook** recipe
