.. _section_examples_summary_mol2img:

Depicting a Single Molecule
================================================================================


A program that converts a molecular structure into an image file.

Command Line Interface
--------------------------------------------------------------------------------

A description of the command line interface can be obtained by
executing the program with the --help argument.

.. oe:language:: c++

   .. code-block:: console

      prompt> mol2img --help

.. oe:language:: python

   .. code-block:: console

      prompt> python mol2img.py --help

.. oe:language:: java

   .. code-block:: console

      prompt> java Mol2Img --help

.. oe:language:: csharp

   .. code-block:: console

      prompt> Mol2Img --help


will generate the following output:

.. code-block:: console

   Simple parameter list
    image options :
      -height : Height of output image
      -width : Width of output image

    input/output options :
      -in : Input filename
      -out : Output filename
      -ringdict : User-defined 2D ring dictionary

    molecule display options :
      -aromstyle : Aromatic ring display style
      -atomcolor : Atom coloring style
      -atomlabelfontscale : Atom label font scale
      -atomprop : Atom property display
      -atomstereostyle : Atom stereo display style
      -bondcolor : Bond coloring style
      -bondprop : Bond property display
      -bondstereostyle : Bond stereo display style
      -hydrstyle : Hydrogen display style
      -linewidth : Default bond line width
      -protgroupdisp : Protective group display style
      -scale : Scaling of the depicted molecule
      -superdisp : Super atom display style
      -titleloc : Location of the molecule title

    prepare depiction options :
      -clearcoords : Clear and regenerate 2D coordinates of molecule(s)
      -orientation : Set the preferred orientation of 2D coordinates
      -suppressH : Suppress explicit hydrogens of molecule(s)

Code
--------------------------------------------------------------------------------

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`mol2img.cpp <../../../../sublibs/tklibs/depict/examples/mol2img.cpp>`
         and
         :download:`mol2img.txt <../../../../sublibs/tklibs/depict/examples/mol2img.txt>`
         interface file

   .. only:: oepdf

      .. oe:source:: mol2img.cpp
         :language: c++

      with interface file

      .. oe:source:: mol2img.txt
         :language: c++

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`mol2img.py <../../../../wrappers/python/examples/depict/mol2img.py>`

      .. literalinclude:: ../../../../wrappers/python/examples/depict/mol2img.py


   .. only:: oepdf

      .. oe:source:: mol2img.py
         :language: python


.. oe:language:: java

   .. only:: oehtml

      .. admonition:: Download code

         :download:`Mol2Img.java <../../../../wrappers/java/examples/openeye/examples/oedepict/Mol2Img.java>`
         and
         :download:`Mol2Img.txt <../../../../wrappers/java/examples/openeye/examples/oedepict/Mol2Img.txt>`
         interface file

   .. only:: oepdf

      .. oe:source:: Mol2Img.java
         :language: java

      with interface file

      .. oe:source:: Mol2Img.txt
         :language: java

.. oe:language:: csharp

   .. only:: oehtml

      .. admonition:: Download code

         :download:`Mol2Img.cs <../../../../wrappers/csharp/Csharp-Examples/OEDepict/Mol2Img.cs>`

   .. only:: oepdf

      .. oe:source:: Mol2Img.cs
         :language: csharp


.. seealso::

   * :ref:`chapter_mol_display` chapter

   * :oe:func:`OEDepict::OEConfigureImageOptions` function
   * :oe:func:`OEDepict::OEConfigurePrepareDepictionOptions` function
   * :oe:func:`OEDepict::OEConfigure2DMolDisplayOptions` function
   * :oe:func:`OEDepict::OEIsRegisteredImageFile` function
   * :ref:`OEPrepareDepictionOptions <OEDepict_OEPrepareDepictionOptions>` class
   * :oe:func:`OEDepict::OESetupPrepareDepictionOptions` function
   * :oe:func:`OEDepict::OEPrepareDepiction` function
   * :oe:func:`OEDepict::OEGetImageWidth` and :oe:func:`OEDepict::OEGetImageHeight` functions
   * :ref:`OE2DMolDisplayOptions <OEDepict_OE2DMolDisplayOptions>` class
   * :oe:func:`OEDepict::OESetup2DMolDisplayOptions` function
   * :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` class
   * :oe:func:`OEDepict::OERenderMolecule` function

Examples
--------------------------------------------------------------------------------

.. oe:language:: c++

   .. code-block:: console

      prompt> mol2img -in nexium.ism -out image.png

.. oe:language:: python

   .. code-block:: console

      prompt> python mol2img.py -in nexium.ism -out image.png

.. oe:language:: java

   .. code-block:: console

      prompt> java Mol2Img -in nexium.ism -out image.png

.. oe:language:: csharp

   .. code-block:: console

      prompt> Mol2img -in nexium.ism -out image.png

will generate the image shown in
:ref:`Figure: Example of using the program with default parameters<figure_mol2img_01>`.

.. _figure_mol2img_01:

.. figure:: images/mol2img-01.*
   :align:  center

   **Example of using the program with default parameters**

.. -----------------------------------------------------------------------------

.. oe:language:: c++

   .. code-block:: console

      prompt> mol2img -in nexium.ism -out image.png -atomcolor WhiteMonochrome

.. oe:language:: python

   .. code-block:: console

      prompt> python mol2img.py -in nexium.ism -out image.png -atomcolor WhiteMonochrome

.. oe:language:: java

   .. code-block:: console

      prompt> java Mol2Img -in nexium.ism -out image.png -atomcolor WhiteMonochrome

.. oe:language:: csharp

   .. code-block:: console

      prompt> Mol2Img -in nexium.ism -out image.png -atomcolor WhiteMonochrome

will generate the image shown in
:ref:`Figure: Example of using the program with the white monochrome atom coloring style<figure_mol2img_02>`.

.. _figure_mol2img_02:

.. figure:: images/mol2img-02.*
   :align:  center

   **Example of using the program with the white monochrome atom coloring style**


.. -----------------------------------------------------------------------------

.. oe:language:: c++

   .. code-block:: console

      prompt> mol2img -in nexium.ism -out image.png -aromstyle Circle

.. oe:language:: python

   .. code-block:: console

      prompt> python mol2img.py -in nexium.ism -out image.png -aromstyle Circle

.. oe:language:: java

   .. code-block:: console

      prompt> java Mol2Img -in nexium.ism -out image.png -aromstyle Circle

.. oe:language:: csharp

   .. code-block:: console

      prompt> Mol2Img -in nexium.ism -out image.png -aromstyle Circle

will generate the image shown in
:ref:`Figure: Example of using the program with aromaticity style 'Circle' <figure_mol2img_03>`.

.. _figure_mol2img_03:

.. figure:: images/mol2img-03.*
   :align:  center

   **Example of using the program with aromaticity style 'Circle'**

.. -----------------------------------------------------------------------------

.. oe:language:: c++

   .. code-block:: console

     prompt> mol2img -in nexium.ism -out image.png -atomstereostyle "AtomStereo|CIPAtomStereo"

.. oe:language:: python

   .. code-block:: console

     prompt> python mol2img.py -in nexium.ism -out image.png -atomstereostyle "AtomStereo|CIPAtomStereo"

.. oe:language:: java

   .. code-block:: console

     prompt> java Mol2Img -in nexium.ism -out image.png -atomstereostyle "AtomStereo|CIPAtomStereo"

.. oe:language:: csharp

   .. code-block:: console

     prompt> Mol2Img -in nexium.ism -out image.png -atomstereostyle "AtomStereo|CIPAtomStereo"

will generate the image shown in
:ref:`Figure: Example of the mol2img program with CIP atom stereo option<figure_mol2img_04>`.

.. _figure_mol2img_04:

.. figure:: images/mol2img-04.*
   :align:  center

   **Example of using the program with CIP atom stereo option**

.. -----------------------------------------------------------------------------

.. oe:language:: c++

   .. code-block:: console

      prompt> mol2img -in nexium.ism -out image.png -linewidth 4

.. oe:language:: python

   .. code-block:: console

      prompt> python mol2img.py -in nexium.ism -out image.png -linewidth 4

.. oe:language:: java

   .. code-block:: console

      prompt> java Mol2Img -in nexium.ism -out image.png -linewidth 4

.. oe:language:: csharp

   .. code-block:: console

      prompt> Mol2Img -in nexium.ism -out image.png -linewidth 4

will generate the image shown in
:ref:`Figure: Example of using the program with user-defined line width<figure_mol2img_05>`.

.. _figure_mol2img_05:

.. figure:: images/mol2img-05.*
   :align:  center

   **Example of using the program with user-defined line width**


.. -----------------------------------------------------------------------------

.. oe:language:: c++

   .. code-block:: console

      prompt> mol2img -in nexium.ism -out image.png -superdisp All

.. oe:language:: python

   .. code-block:: console

      prompt> python mol2img.py -in nexium.ism -out image.png -superdisp All

.. oe:language:: java

   .. code-block:: console

      prompt> java Mol2Img -in nexium.ism -out image.png -superdisp All

.. oe:language:: csharp

   .. code-block:: console

      prompt> Mol2Img -in nexium.ism -out image.png -superdisp All


will generate the image shown in
:ref:`Figure: Example of using the program with superatom style<figure_mol2img_06>`.

.. _figure_mol2img_06:

.. figure:: images/mol2img-06.*
   :align:  center

   **Example of using the  program with superatom style**

.. note::

   The above program can generate 2D coordinates with user-defined 2D ring layouts when using the
   **-ringdict** parameter.

   See also the :ref:`section_example_oechem_2D_coordinate_generation` section of
   the **OEChem TK** manual that shows examples about how to generate and
   utilize user-defined ring dictionaries.

.. seealso::

   * :ref:`chapter_mol_display` chapter

