.. include:: ../substitutions

.. oe:namespace:: OEDepict

.. meta::
   :keywords: OEPrepareAlignedDepiction

.. _OEDepict_OEPrepareAlignedDepiction:

.. oe:function:: OEPrepareAlignedDepiction

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

      * - Link
        - Description

      * - :ref:`OEPrepareAlignedDepiction(fitmol, refmol, match, clearcoords, suppressH)<api_OEPrepareAlignedDepiction_fit_ref_match>`
        - aligns a molecule to the reference

      * - :ref:`OEPrepareAlignedDepiction(fitmol, refmol, match, opts)<api_OEPrepareAlignedDepiction_fit_ref_match_opts>`
        - aligns a molecule to the reference according to options

      * - :ref:`OEPrepareAlignedDepiction(fitmol, mcss, opts)<api_OEPrepareAlignedDepiction_fit_mcss_opts>`
        - aligns a molecule to the reference based on maximum common substructure search

      * - :ref:`OEPrepareAlignedDepiction(fitmol, subsrc, opts)<api_OEPrepareAlignedDepiction_fit_ss_opts>`
        - aligns a molecule to the reference based on substructure search

      * - :ref:`OEPrepareAlignedDepiction(fitmol, refmol, matches, opts)<api_OEPrepareAlignedDepiction_fit_ref_iter_opts>`
        - aligns a molecule to the reference based on matches


   .. seealso:

      * :oe:func:`OEChem::OEPrepareMultiAlignedDepiction` function


   .. _api_OEPrepareAlignedDepiction_fit_ref_match:

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

      .. oe:api::

         bool OEPrepareAlignedDepiction(OEChem::OEMolBase& fitmol,
                                        const OEChem::OEMolBase& refmol,
                                        const OEChem::OEMatchBase& match,
                                        bool clearCoords = true,
                                        bool suppressH = true)

   .. oe:language:: python

      .. oe:api:: python

         OEPrepareAlignedDepiction(fitmol: Union[OEGraphMol,OEMol,OEQMol],
                                   refmol: Union[OEGraphMol,OEMol,OEQMol],
                                   match: OEMatchBase,
                                   clearCoords: bool = True,
                                   suppressH: bool = True) -> bool

   Generates the 2D coordinates of a molecule by maximizing its overlap
   with a reference 2D molecule based on the given match between the
   two molecules.

   *fitmol*
      The molecule being fitted to be aligned to the reference molecule.

   *refmol*
      The reference molecule of which 2D coordinates are remain unchanged.

   *match*
      The match determines the atoms of the *fitmol* that will be aligned
      to the atoms of the *refmol*.
      The match can be generated by hand, or with any of **OEChem TK**‘s matching
      algorithms such as :ref:`OESubSearch <OEChem_OESubSearch>` or
      :ref:`OEMCSSearch <OEChem_OEMCSSearch>`.

   *clearcoords*
      If `true`, than the 2D coordinates of the fitted molecule are re-calculated
      by calling the :oe:func:`OEDepict::OEPrepareDepiction` function.
      After generating the coordinates, the alignment between the two molecules
      is maximized by rotating the single bonds of the fitted molecule
      while avoiding atom clashes.
      See example (C) in :ref:`Figure: Example of the molecule alignment
      <figure_OEPrepareAlignedDepiction_ClearCoords>`.

      If *clearcoords* is `false` and the *fitmol* has 2D coordinates than
      these coordinates are kept.
      In this case only 2D rotation and translation of the fitted molecule is
      allowed (*i.e.* no rotations around bonds) in order to align it
      to the reference molecule.
      See example (B) in :ref:`Figure: Example of the molecule alignment
      <figure_OEPrepareAlignedDepiction_ClearCoords>`.

   *suppressH*
      If true, than explicit hydrogens are suppressed in the input molecule
      by calling the :oe:func:`OEDepict::OESuppressNonDepictionHydrogens` function.

   .. _figure_OEPrepareAlignedDepiction_ClearCoords:

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

      **Example of the molecule alignment**

      *(A) molecule with no alignment;
      (B) aligning the fit molecule to the reference molecule by allowing
      only 2D rotations (original coordinates are kept);
      (C) aligning the fit molecule to the reference by allowing rotation
      around single bonds (coordinates are regenerate)*

   .. seealso::

      * :ref:`chapter_molalign` chapter

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

   .. _api_OEPrepareAlignedDepiction_fit_ref_match_opts:

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

      .. oe:api::

         bool OEPrepareAlignedDepiction(OEChem::OEMolBase& fitmol,
                                        const OEChem::OEMolBase& refmol,
                                        const OEChem::OEMatchBase& match,
                                        const OEAlignmentOptions& opts)

   .. oe:language:: python

      .. oe:api:: python

         OEPrepareAlignedDepiction(fitmol: Union[OEGraphMol,OEMol,OEQMol],
                                   refmol: Union[OEGraphMol,OEMol,OEQMol],
                                   match: OEMatchBase, opts: OEAlignmentOptions) -> bool

   Generates the 2D coordinates of a molecule by maximizing its overlap
   with a reference 2D molecule based on the given match between the
   two molecules.

   *fitmol*
      The molecule being fitted to be aligned to the reference molecule.

   *refmol*
      The reference molecule of which 2D coordinates are remain unchanged.

   *match*
      The match determines the atoms of the *fitmol* that will be aligned
      to the atoms of the *refmol*.
      The match can be generated by hand, or with any of **OEChem TK**‘s matching
      algorithms such as :ref:`OESubSearch <OEChem_OESubSearch>` or
      :ref:`OEMCSSearch <OEChem_OEMCSSearch>`.

   *opts*
      The :ref:`OEAlignmentOptions <OEDepict_OEAlignmentOptions>` object that stores
      properties that influence how the molecule alignment is performed.

   .. seealso::

      * :ref:`chapter_molalign` chapter

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

   .. _api_OEPrepareAlignedDepiction_fit_mcss_opts:

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

      .. oe:api::

         OEAlignmentResult OEPrepareAlignedDepiction(OEChem::OEMolBase& fitmol,
                                                     const OEChem::OEMCSSearch& mcss,
                                                     const OEAlignmentOptions& opts = OEAlignmentOptions())

   .. oe:language:: python

      .. oe:api:: python

         OEPrepareAlignedDepiction(fitmol: Union[OEGraphMol,OEMol,OEQMol],
                                   mcss: OEMCSSearch,
                                   opts: OEAlignmentOptions = OEAlignmentOptions()) -> OEAlignmentResult

   Generates the 2D coordinates of a molecule by maximizing its overlap
   based on the maximum common substructure initialized with a
   reference 2D molecule.

   *fitmol*
      The molecule being fitted to be aligned to the reference molecule.

   *mcss*
      The :ref:`OEMCSSearch <OEChem_OEMCSSearch>` object stores the reference
      molecule.
      The molecule alignments are performed based on the
      maximum common substructure(s) detected between the fit and the
      reference molecule.

   *opts*
      The :ref:`OEAlignmentOptions <OEDepict_OEAlignmentOptions>` object that stores
      properties that influence how the molecule alignment is performed.

   .. warning::

      The reference molecule has to have 2D coordinates prior to
      initializing the :ref:`OEMCSSearch <OEChem_OEMCSSearch>` object.

   .. seealso::

      * :ref:`OEMCSSearch <OEChem_OEMCSSearch>` class in the **OEChem TK** manual
      * :oe:src:`Listing 1<SNIPPET-MCS-ALIGN-MCSAlign>` example code in :ref:`chapter_molalign` chapter


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

   .. _api_OEPrepareAlignedDepiction_fit_ss_opts:

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

      .. oe:api::

         OEAlignmentResult OEPrepareAlignedDepiction(OEChem::OEMolBase& fitmol,
                                                     const OEChem::OESubSearch& subsrc,
                                                     const OEAlignmentOptions& opts = OEAlignmentOptions())

   .. oe:language:: python

      .. oe:api:: python

         OEPrepareAlignedDepiction(fitmol: Union[OEGraphMol,OEMol,OEQMol],
                                   subsrc: OESubSearch,
                                   opts: OEAlignmentOptions = OEAlignmentOptions()) -> OEAlignmentResult

   Generates the 2D coordinates of a molecule by maximizing its overlap
   based on substructure search initialized with a reference 2D molecule.

   In case of a successful alignment, the returned :ref:`OEAlignmentResult <OEDepict_OEAlignmentResult>`
   object stores the match between fit and reference molecules.

   *fitmol*
      The molecule being fitted to be aligned to the reference molecule.

   *subsrc*
      The :ref:`OESubSearch <OEChem_OESubSearch>` object stores the reference
      molecule.
      The molecule alignments are performed based on the
      substructure(s) detected between the fit and the
      reference molecule.

   *opts*
      The :ref:`OEAlignmentOptions <OEDepict_OEAlignmentOptions>` object that stores
      properties that influence how the molecule alignment is performed.

   .. warning::

      The reference molecule has to have 2D coordinates prior to
      initializing the :ref:`OESubSearch <OEChem_OESubSearch>` object.

   .. seealso::

      * :ref:`OESubSearch <OEChem_OESubSearch>` class in the **OEChem TK** manual
      * :oe:src:`Listing 2<SNIPPET-SUB-SEARCH-ALIGN-SubSearchAlign>` code example in :ref:`chapter_molalign` chapter


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

   .. _api_OEPrepareAlignedDepiction_fit_ref_iter_opts:

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

      .. oe:api::

         OEAlignmentResult OEPrepareAlignedDepiction(OEChem::OEMolBase& fitmol,
                                                     const OEChem::OEMolBase& refmol,
                                                     OESystem::OEIter<const OEChem::OEMatchBase>& miter,
                                                     const OEAlignmentOptions& opts = OEAlignmentOptions())
         OEAlignmentResult OEPrepareAlignedDepiction(OEChem::OEMolBase& fitmol,
                                                     const OEChem::OEMolBase& refmol,
                                                     OESystem::OEIterBase<const OEChem::OEMatchBase>* miter,
                                                     const OEAlignmentOptions& opts = OEAlignmentOptions())

   .. oe:language:: python

      .. oe:api:: python

         OEPrepareAlignedDepiction(fitmol: Union[OEGraphMol,OEMol,OEQMol],
                                   refmol: Union[OEGraphMol,OEMol,OEQMol],
                                   opts: OEAlignmentOptions = OEAlignmentOptions()) -> OEAlignmentResult

   Generates the 2D coordinates of a molecule by maximizing its overlap
   with a reference 2D molecule based on the given matches between the
   two molecules.

   *fitmol*
      The molecule being fitted to be aligned to the reference molecule.

   *refmol*
      The reference molecule of which 2D coordinates are remain unchanged.

   *miter*
      The iterator that stores the matches on which the molecule
      alignment is based on.

   *opts*
      The :ref:`OEAlignmentOptions <OEDepict_OEAlignmentOptions>` object that stores
      properties that influence how the molecule alignment is performed.

   .. seealso::

      * :ref:`chapter_molalign` chapter
