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

.. oe:namespace:: OEDepict

.. meta::
   :keywords: OERenderMolecule

.. _OEDepict_OERenderMolecule:

.. oe:function:: OERenderMolecule

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

      * - Link
        - Description

      * - :ref:`OERenderMolecule(image, disp)<api_OERenderMolecule_OEImageBase_OE2DMolDisplay>`
        - renders a molecule display into an image

      * - :ref:`OERenderMolecule(image, mol)<api_OERenderMolecule_OEImageBase_OEMolBase>`
        - renders molecule into an image using the **default** depiction style

      * - :ref:`OERenderMolecule(filename, disp)<api_OERenderMolecule_filename_OE2DMolDisplay>`
        - writes a molecule display into a file

      * - :ref:`OERenderMolecule(filename, mol)<api_OERenderMolecule_filename_OEMolBase>`
        - writes a molecule into a file using the **default** depiction style

      * - :ref:`OERenderMolecule(stream, ext, disp)<api_OERenderMolecule_oeostream_OE2DMolDisplay>`
        - writes a molecule display into an output stream

      * - :ref:`OERenderMolecule(stream, ext, mol)<api_OERenderMolecule_oeostream_OEMolBase>`
        - writes a molecule into an output stream using the **default** depiction style

   .. hint::

      Setting the `clearbackground` option to false, allows the generation of images with transparent background.

      .. list-table::
         :header-rows: 1

         * - clearbackground [#f1]_
           - effect
         * - true (default)
           - clears the image by drawing a rectangle underneath the molecule with the background color [#f2]_ before molecule rendering
         * - false
           - does **not** clear the image, enabling the generation of transparent images (for example PNG, SVG)

      .. [#f1] option of the :oe:func:`OEDepict::OERenderMolecule` function
      .. [#f2] background color can be set with the :oe:meth:`OEDepict::OE2DMolDisplayOptions::SetBackgroundColor` method
         (default is :oe:const:`OEWhite<OESystem::OESystem::OEWhite>`)

      See the :ref:`Generating Transparent PNG <section_depiction_transparent>` Python cookbook example.


   .. _api_OERenderMolecule_OEImageBase_OE2DMolDisplay:

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

      .. oe:api::

         bool OERenderMolecule(OEImageBase& image, const OE2DMolDisplay& disp,
                               bool clearbackground = true)

   .. oe:language:: python

      .. oe:api:: python

         OERenderMolecule(image: OEImageBase, disp: OE2DMolDisplay,
                          clearbackground: bool = True) -> bool

   Renders the molecule display into an image.

   *image*
      The image in which the molecule is drawn.

   *disp*
      The :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object that holds the
      data necessary to depict the molecule with which it is
      initialized.

   *clearbackground*
      Determines whether or not the image is cleared
      (by calling :oe:meth:`OEDepict::OEImageBase::Clear` method)
      prior to rendering the molecule; as a result, by default a white rectangle will be
      drawn underneath the molecule.

   **Example:**

   .. oe:source:: OERenderMolecule_image_disp.py
      :language: python
      :noindent:
      :frag:     SNIPPET-OEDEPICTMOLECULE-IMAGE-DISP

   .. oe:source:: OERenderMolecule_image_disp.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-OEDEPICTMOLECULE-IMAGE-DISP

   .. oe:source:: OERenderMolecule_image_disp.java
      :language: java
      :noindent:
      :frag:     SNIPPET-OEDEPICTMOLECULE-IMAGE-DISP

   .. oe:source:: OERenderMolecule_image_disp.cs
      :language: csharp
      :noindent:
      :frag:     SNIPPET-OEDEPICTMOLECULE-IMAGE-DISP

   .. seealso::

      * :ref:`OEImageBase <OEDepict_OEImageBase>` class
      * :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` class


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

   .. _api_OERenderMolecule_OEImageBase_OEMolBase:

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

      .. oe:api::

         bool OERenderMolecule(OEImageBase& image,
                               const OEChem::OEMolBase& mol,
                               bool clearbackground = true)

   .. oe:language:: python

      .. oe:api:: python

         OERenderMolecule(image: OEImageBase,
                          mol: Union[OEGraphMol,OEMol,OEQMol],
                          clearbackground: bool = True) -> bool

   Renders a molecule into an image using the **default** depiction style.

   *image*
      The image in which the molecule is drawn.

   *mol*
      The molecule being rendered has to have valid 2D coordinates
      before calling the :oe:func:`OEDepict::OERenderMolecule`
      function.

   *clearbackground*
      Determines whether or not the image is cleared
      (by calling :oe:meth:`OEDepict::OEImageBase::Clear` method)
      prior to rendering the molecule; as a result, by default a white rectangle will be
      drawn underneath the molecule.

   **Example:**

   .. oe:source:: OERenderMolecule_image_mol.py
      :language: python
      :noindent:
      :frag:     SNIPPET-OEDEPICTMOLECULE-IMAGE-MOL

   .. oe:source:: OERenderMolecule_image_mol.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-OEDEPICTMOLECULE-IMAGE-MOL

   .. oe:source:: OERenderMolecule_image_mol.java
      :language: java
      :noindent:
      :frag:     SNIPPET-OEDEPICTMOLECULE-IMAGE-MOL

   .. oe:source:: OERenderMolecule_image_mol.cs
      :language: csharp
      :noindent:
      :frag:     SNIPPET-OEDEPICTMOLECULE-IMAGE-MOL

   .. seealso::

      * :ref:`OEImageBase <OEDepict_OEImageBase>` class


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

   .. _api_OERenderMolecule_filename_OE2DMolDisplay:

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

      .. oe:api::

         bool OERenderMolecule(const std::string& filename,
                               const OE2DMolDisplay& disp,
                               bool clearbackground = true)

   .. oe:language:: python

      .. oe:api:: python

         OERenderMolecule(filename: str, disp: OE2DMolDisplay,
                          clearbackground: bool = True) -> bool

   Writes the molecule display into a file.

   *filename*
      The name of the file into which the molecule display is being
      written.
      The extension of the filename determine the type of the image.

   *disp*
      The :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object that holds the
      data necessary to depict the molecule with which it is
      initialized.

   *clearbackground*
      Determines whether or not the image is cleared
      (by calling :oe:meth:`OEDepict::OEImageBase::Clear` method)
      prior to rendering the molecule; as a result, by default a white rectangle will be
      drawn underneath the molecule.

   **Example:**

   .. oe:source:: OERenderMolecule_fname_disp.py
      :language: python
      :noindent:
      :frag:     SNIPPET-OEDEPICTMOLECULE-FNAME-DISP

   .. oe:source:: OERenderMolecule_fname_disp.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-OEDEPICTMOLECULE-FNAME-DISP

   .. oe:source:: OERenderMolecule_fname_disp.java
      :language: java
      :noindent:
      :frag:     SNIPPET-OEDEPICTMOLECULE-FNAME-DISP

   .. oe:source:: OERenderMolecule_fname_disp.cs
      :language: csharp
      :noindent:
      :frag:     SNIPPET-OEDEPICTMOLECULE-FNAME-DISP

   .. seealso::

      * :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` class


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

   .. _api_OERenderMolecule_filename_OEMolBase:

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

      .. oe:api::

         bool OERenderMolecule(const std::string& filename,
                               const OEChem::OEMolBase& mol,
                               bool clearbackground = true)

   .. oe:language:: python

      .. oe:api:: python

         OERenderMolecule(filename: str, mol: Union[OEGraphMol,OEMol,OEQMol],
                          clearbackground: bool = True) -> bool

   Writes a molecule into a file using the **default** depiction style.

   *filename*
      The name of the file into which the molecule is written.
      The extension of the filename determine the type of the image.

   *mol*
      The molecule being rendered  has to have valid 2D coordinates
      before calling the :oe:func:`OEDepict::OERenderMolecule`
      function.

   *clearbackground*
      Determines whether or not the image is cleared
      (by calling :oe:meth:`OEDepict::OEImageBase::Clear` method)
      prior to rendering the molecule; as a result, by default a white rectangle will be
      drawn underneath the molecule.

   **Example:**

   .. oe:source:: OERenderMolecule_fname_mol.py
      :language: python
      :noindent:
      :frag:     SNIPPET-OEDEPICTMOLECULE-FNAME-MOL

   .. oe:source:: OERenderMolecule_fname_mol.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-OEDEPICTMOLECULE-FNAME-MOL

   .. oe:source:: OERenderMolecule_fname_mol.java
      :language: java
      :noindent:
      :frag:     SNIPPET-OEDEPICTMOLECULE-FNAME-MOL

   .. oe:source:: OERenderMolecule_fname_mol.cs
      :language: csharp
      :noindent:
      :frag:     SNIPPET-OEDEPICTMOLECULE-FNAME-MOL


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

   .. _api_OERenderMolecule_oeostream_OE2DMolDisplay:

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

      .. oe:api::

         bool OERenderMolecule(OEPlatform::oeostream& os,
                               const std::string& extension,
                               const OE2DMolDisplay& disp,
                               bool clearbackground = true)

   .. oe:language:: python

      .. oe:api:: python

         OERenderMolecule(os: oeostream, extension: str, disp: OE2DMolDisplay,
                          clearbackground: bool = True) -> bool

   Writes the molecule display into a stream.

   *os*
      The stream into which the molecule display is being written.

   *ext*
      The extension which determine the type of the image.

   *disp*
      The :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object that holds the
      data necessary to depict the molecule with which it is
      initialized.

   *clearbackground*
      Determines whether or not the image is cleared
      (by calling :oe:meth:`OEDepict::OEImageBase::Clear` method)
      prior to rendering the molecule; as a result, by default a white rectangle will be
      drawn underneath the molecule.

   **Example:**

   .. oe:source:: OERenderMolecule_stream_disp.py
      :language: python
      :noindent:
      :frag:     SNIPPET-OEDEPICTMOLECULE-STREAM-DISP

   .. oe:source:: OERenderMolecule_stream_disp.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-OEDEPICTMOLECULE-STREAM-DISP

   .. oe:source:: OERenderMolecule_stream_disp.java
      :language: java
      :noindent:
      :frag:     SNIPPET-OEDEPICTMOLECULE-STREAM-DISP

   .. oe:source:: OERenderMolecule_stream_disp.cs
      :language: csharp
      :noindent:
      :frag:     SNIPPET-OEDEPICTMOLECULE-STREAM-DISP

   .. seealso::

      * :ref:`oeostream <OEPlatform_oeostream>` class in the **OEChem TK** manual
      * :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` class


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

   .. _api_OERenderMolecule_oeostream_OEMolBase:

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

      .. oe:api::

         bool OERenderMolecule(OEPlatform::oeostream& os,
                               const std::string& extension,
                               const OEChem::OEMolBase& mol,
                               bool clearbackground = true)

   .. oe:language:: python

      .. oe:api:: python

         OERenderMolecule(os: oeostream, extension: str,
                          mol: Union[OEGraphMol,OEMol,OEQMol],
                          clearbackground: bool = True) -> bool


   Writes a molecule into a stream using the **default** depiction style.

   *os*
      The stream into which the molecule is being written.

   *ext*
      The extension which determine the type of the image.

   *mol*
      The molecule being rendered  has to have valid 2D coordinates
      before calling the :oe:func:`OEDepict::OERenderMolecule`
      function.

   *clearbackground*
      Determines whether or not the image is cleared
      (by calling :oe:meth:`OEDepict::OEImageBase::Clear` method)
      prior to rendering the molecule; as a result, by default a white rectangle will be
      drawn underneath the molecule.

   **Example:**

   .. oe:source:: OERenderMolecule_stream_mol.py
      :language: python
      :noindent:
      :frag:     SNIPPET-OEDEPICTMOLECULE-STREAM-MOL

   .. oe:source:: OERenderMolecule_stream_mol.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-OEDEPICTMOLECULE-STREAM-MOL

   .. oe:source:: OERenderMolecule_stream_mol.java
      :language: java
      :noindent:
      :frag:     SNIPPET-OEDEPICTMOLECULE-STREAM-MOL

   .. oe:source:: OERenderMolecule_stream_mol.cs
      :language: csharp
      :noindent:
      :frag:     SNIPPET-OEDEPICTMOLECULE-STREAM-MOL

   .. seealso::

      * :ref:`oeostream <OEPlatform_oeostream>` class in the **OEChem TK** manual
