.. oe:namespace:: OEShape



.. meta::
   :keywords: OEOverlay, Overlay


.. _OEShape_OEOverlay:

.. oe:class:: OEOverlay

   .. oe:api::


      class OEOverlay

   .. note::

      With the default settings, the :ref:`OEOverlay <OEShape_OEOverlay>` optimizes
      both shape and color.

   The :ref:`OEOverlay <OEShape_OEOverlay>` defined an interface for overlap optimization
   between a reference object (a molecule, grid or a shape query) and a fit molecule 
   conformers.

   The :ref:`OEOverlay <OEShape_OEOverlay>` class defines the following public methods:
    * :oe:meth:`BestOverlay<OEShape::OEOverlay::BestOverlay>`
    * :oe:meth:`GetOverlayOptions<OEShape::OEOverlay::GetOverlayOptions>`
    * :oe:meth:`Overlay<OEShape::OEOverlay::Overlay>`
    * :oe:meth:`SetupRef<OEShape::OEOverlay::SetupRef>`
    * :oe:meth:`SortedOverlay<OEShape::OEOverlay::SortedOverlay>`

   .. oe:method:: Constructors

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

         .. oe:api::

            OEOverlay(const OEOverlayOptions& opts = OEOverlayOptions())
            OEOverlay(const OEOverlay&)

      .. oe:language:: python

         .. oe:api:: python

            OEOverlay(opts: OEOverlayOptions = OEOverlayOptions()) -> OEOverlay
            OEOverlay(arg2: OEOverlay) -> OEOverlay

      Default and copy constructors.

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

      .. oe:api::

         OEOverlay &operator=(const OEOverlay &)

.. _OEShape_OEOverlay_BestOverlay:

      Assignment operator.



   .. oe:method:: BestOverlay

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

         .. oe:api::

            bool BestOverlay(OEBestOverlayScore& score, const OEChem::OEMCMolBase& fitmol,
            const OESystem::OEBinaryPredicate<OEBestOverlayScore, OEBestOverlayScore>& pred = OEHighestTanimotoCombo())

      .. oe:language:: python

         .. oe:api:: python

            BestOverlay(score: OEBestOverlayScore, fitMol: OEMol,
                        pred: OEBestOverlayScoreSorterPred = OEHighestTanimotoCombo()) -> bool

      Method optimizes the overlay between the reference object and the fit
      molecule conformers, and returns the best result, sorted based on the binary predicate ``pred``.  
      The predicate has a default setting of
      :ref:`OEHighestTanimotoCombo <OEShape_OEHighestTanimotoCombo>`. The reference object must 
      be set using the :oe:meth:`SetupRef<OEShape::OEOverlay::SetupRef>` method, prior 
      to calling this method.

.. _OEShape_OEOverlay_GetOverlayOptions:


   .. oe:method:: GetOverlayOptions

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

         .. oe:api::

            const OEOverlayOptions& GetOverlayOptions() const

      .. oe:language:: python

         .. oe:api:: python

            GetOverlayOptions() -> OEOverlayOptions

      Returns a reference to the :ref:`OEOverlayOptions <OEShape_OEOverlayOptions>`
      instance as currently set. This defines options to calculate overlay.

.. _OEShape_OEOverlay_Overlay:


   .. oe:method:: Overlay

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

         .. oe:api::

            OESystem::OEIterBase<OEBestOverlayResults>* Overlay(const OEChem::OEMCMolBase&)

      .. oe:language:: python

         .. oe:api:: python

            Overlay(fitMol: OEMol) -> Iterable[OEBestOverlayResults]

      Method optimizes the overlay between the reference object and the fit
      molecule conformers.  The reference object must be set using the
      :oe:meth:`SetupRef<OEShape::OEOverlay::SetupRef>` method, prior 
      to calling this method.

      .. seealso::

        * :oe:meth:`BestOverlay<OEShape::OEOverlay::BestOverlay>`
        * :oe:meth:`SortedOverlay<OEShape::OEOverlay::SortedOverlay>`

.. _OEShape_OEOverlay_SetupRef:


   .. oe:method:: SetupRef

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

         .. oe:api::

            bool SetupRef(const OEChem::OEMolBase&)
            bool SetupRef(const OESystem::OEScalarGrid&)
            bool SetupRef(const OEShapeQuery&)

      .. oe:language:: python

         .. oe:api:: python

            SetupRef(argRefMol: Union[OEGraphMol,OEMol,OEQMol]) -> bool
            SetupRef(argRefGrid: OEScalarGrid) -> bool
            SetupRef(argQuery: OEShapeQuery) -> bool

      These method defines the interface for setting up the reference system for the 
      :ref:`OEOverlay <OEShape_OEOverlay>` instance with a molecule, grid or a shape query.

.. _OEShape_OEOverlay_SortedOverlay:

   .. oe:method:: SortedOverlay

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

         .. oe:api::

            OESystem::OEIterBase<OEBestOverlayScore>* SortedOverlay(const OEChem::OEMCMolBase& fitmol,
                                                                    const unsigned maxHits,
                                                                    const OESystem::OEBinaryPredicate<OEBestOverlayScore, OEBestOverlayScore>& pred = OEHighestTanimotoCombo())

      .. oe:language:: python

         .. oe:api:: python

            SortedOverlay(fitmol: OEMol, maxHits: int,
                          pred: OEBestOverlayScoreSorterPred = OEHighestTanimotoCombo()) -> Iterable[OEBestOverlayScore]

      Method optimizes the overlay between the reference object and the fit
      molecule conformers, and returns the desired number of top hits defined by ``maxHits``,
      sorted based on the binary predicate ``pred``. The predicate has a default setting of
      :ref:`OEHighestTanimotoCombo <OEShape_OEHighestTanimotoCombo>`. The reference object must 
      be set using the :oe:meth:`SetupRef<OEShape::OEOverlay::SetupRef>` method, prior 
      to calling this method.

      This method is specifically preferred over the :oe:meth:`Overlay<OEShape::OEOverlay::Overlay>`
      method when working with molecules containing a large number of conformers, as the
      burden to store all the results associated with all the conformers can stress the memory
      limits of a machine.

