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

.. include:: ../substitutions

.. oe:namespace:: OEGrapheme

.. meta::
   :keywords: OERenderShapeOverlap

.. oe:function:: OERenderShapeOverlap

   .. list-table:: **The overloaded versions of the OERenderShapeOverlap function**
      :widths: 100 200
      :header-rows: 1

      * - Link
        - Description

      * - :ref:`OERenderShapeOverlap(image, overlapdisp)<api_OERenderShapeOverlap_image_odisp>`
        - render shape overlap

      * - :ref:`OERenderShapeOverlap(molimage, overlapimage, overlapdisp)<api_OERenderShapeOverlap_image_image_odisp>`
        - render shape overlap into separate images

.. _api_OERenderShapeOverlap_image_odisp:

   .. oe:api::

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

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

   *image*
     The image on which the fit molecule is rendered along with the
     property map and the molecule surface of the reference molecule
     representing the shape overlap.

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

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

   .. oe:source:: RenderShapeOverlap.py
      :language: python
      :noindent:
      :frag:     SNIPPET-RENDER-SHAPE-OVERLAP

   .. oe:source:: RenderShapeOverlap.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-RENDER-SHAPE-OVERLAP

   .. oe:source:: RenderShapeOverlap.java
      :language: java
      :noindent:
      :frag:     SNIPPET-RENDER-SHAPE-OVERLAP

   .. oe:source:: RenderShapeOverlap.cs
      :language: csharp
      :noindent:
      :frag:     SNIPPET-RENDER-SHAPE-OVERLAP


   .. note::

      The shape overlap between the reference and the fit molecule is visualized
      by using a property map (:ref:`OE2DPropMap <OEGrapheme_OE2DPropMap>`), *i.e.*, a 2D grid,
      laid underneath the molecule structure, where the cells of the grid that
      are colored brown indicate good 3D shape overlap between the reference and
      the fit molecules.
      Additionally, clashes between the molecular graph of the fit molecule and
      2D molecule surface of the reference structure imply shape mismatch in 3D.

   .. _table_OERenderShapeOverlap:

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

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

   .. warning::

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

.. _api_OERenderShapeOverlap_image_image_odisp:

   .. oe:api::

       void OERenderShapeOverlap(OEDepict::OEImageBase& molimage,
                                 OEDepict::OEImageBase& overlapimage,
                                 const OEShapeOverlapDisplay& odisp)



   Renders the shape overlap between a reference and a fit molecule into
   to separate images.

   *molimage*
     The image on which the fit molecule is rendered along with the
     surface of the reference molecule.

   *overlapimage*
     The image on which the property map is rendered representing
     the shape overlap.

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

   .. note::

      The background of the molecule image is transparent. By superimposing
      the two images (molecule image on top), the result would be as visualizing
      the shape overlay in one image.

   .. seealso::

      * :ref:`OEShapeOverlapDisplayOptions <OEGrapheme_OEShapeOverlapDisplayOptions>` class
      * :oe:func:`OEGrapheme::OERenderShapeQuery` function
      * :oe:func:`OEGrapheme::OERenderColorOverlap` function

   .. admonition:: Code Example

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