
.. include:: ../substitutions

.. oe:namespace:: OEDepict

.. meta::
   :keywords: OEPrepareDepiction

.. _OEDepict_OEPrepareDepiction:


.. oe:function:: OEPrepareDepiction


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

      * - Link
        - Description

      * - :ref:`OEPrepareDepiction(mol, clearccords, suppressH)<api_OEPrepareDepiction_mol_bool_bool>`
        - prepare depiction

      * - :ref:`OEPrepareDepiction(mol, opts)<api_OEPrepareDepiction_mol_opts>`
        - prepare depiction according to options

.. _api_OEPrepareDepiction_mol_bool_bool:

   .. oe:api::

      bool OEPrepareDepiction(OEChem::OEMolBase& mol, bool clearcoords = false,
                              bool suppressH = true)

   Prepares a molecule before depiction that involves suppressing or
   adding explicit hydrogens, perceiving atom and bond stereo information
   and calculating 2D coordinates.

   *mol*
      The molecule being manipulated.

   *clearcoords*
      If true, than the 2D coordinates of the molecule are re-calculated.
      If false and the molecule has 2D coordinates than these coordinates
      are kept.

      If the molecule has no 2D coordinates, then the 2D coordinates are
      always generated by calling the :oe:func:`OEDepict::OEDepictCoordinates`
      function regardless of the value of the *clearcoords* parameter.

   *suppressH*
      If true, than explicit hydrogens are suppressed in the input molecule
      by calling the :oe:func:`OEDepict::OESuppressNonDepictionHydrogens` function.
      See example in :ref:`Figure: Example of the molecule depictions with
      kept and suppressed hydrogens
      <figure_OEPrepareDepiction_HydrogenHandling>`.

   .. _figure_OEPrepareDepiction_HydrogenHandling:

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

      **Example of the molecule depictions with kept and suppressed hydrogens**

   .. note::

      The :oe:func:`OEDepict::OEPrepareDepiction` function generates
      canonical 2D coordinates (when the *clearcoords* parameter is true)
      i.e. the layout of the same molecules will be identical regardless of
      their atom and bond orderings.

      The following code shows how to generate non-canonical 2D coordinates:

      .. oe:source:: PrepareDepiction.py
         :language: python
         :noindent:
         :frag:     SNIPPET-PREPARE-DEPICTION

      .. oe:source:: PrepareDepiction.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-PREPARE-DEPICTION

      .. oe:source:: PrepareDepiction.java
         :language: java
         :noindent:
         :frag:     SNIPPET-PREPARE-DEPICTION

      .. oe:source:: PrepareDepiction.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-PREPARE-DEPICTION

   .. seealso::

      * :oe:func:`OEDepict::OEAddDepictionHydrogens` function
      * :oe:func:`OEDepict::OEDepictCoordinates` function

.. _api_OEPrepareDepiction_mol_opts:

   .. oe:api::

      bool OEPrepareDepiction(OEChem::OEMolBase& mol,
                              const OEPrepareDepictionOptions& opts)

   Prepares a molecule before depiction.

   *mol*
      The molecule being manipulated.

   *opts*
      The :ref:`OEPrepareDepictionOptions <OEDepict_OEPrepareDepictionOptions>` object that stores
      properties that influence how the molecule is prepared.
