.. _chapter_draw_surface:

********************************************************************************
Drawing a Molecule Surface
********************************************************************************

The 2D representation of the molecule surface is calculated by first
drawing circles around each atom of the molecule and then identifying
the external arc segments that define a continuous surface around the
molecule.
This process is illustrated in the table
:ref:`Table: Calculation of the 2D representation of a molecule surface<table_draw_surface_calc>`

.. _table_draw_surface_calc:

.. list-table:: **Calculation of the 2D representation of a molecule surface**
   :widths: 150 150
   :header-rows: 0

   * - .. image:: images/Draw2DSurface-Step-01.*
          :align:  center
     - .. image:: images/Draw2DSurface-Step-02.*
          :align:  center
   * - .. image:: images/Draw2DSurface-Step-03.*
          :align:  center
     - .. image:: images/Draw2DSurface-Step-04.*
          :align:  center
   * - .. image:: images/Draw2DSurface-Step-05.*
          :align:  center
     - .. image:: images/Draw2DSurface-Step-06.*
          :align:  center

.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   %
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The following :oe:src:`Listing 1<SNIPPET-DRAW-2D-SURFACE-Draw2DSurface>` example shows how to
the display a molecule surface.
After creating an image object and preparing the molecule for 2D
depiction, an arc drawing functor is added to each atom of the
molecule by using the :oe:func:`OEGrapheme::OESetSurfaceArcFxn`
function.
The surface then can be drawn by calling the
:oe:func:`OEGrapheme::OEDraw2DSurface` function that calculates the
arc segments that form a continuous curve around the molecule.
The image created by :oe:src:`Listing 1<SNIPPET-DRAW-2D-SURFACE-Draw2DSurface>` is shown in
:ref:`Figure: Example of surface drawing<figure_draw_surface>`.

.. oe:source:: Draw2DSurface.py
   :language: python
   :refnum:   1
   :noindent:
   :frag:     SNIPPET-DRAW-2D-SURFACE
   :caption:  Example of surface drawing

.. oe:source:: Draw2DSurface.cpp
   :language: c++
   :refnum:   1
   :noindent:
   :frag:     SNIPPET-DRAW-2D-SURFACE
   :caption:  Example of surface drawing

.. oe:source:: Draw2DSurface.java
   :language: java
   :refnum:   1
   :noindent:
   :frag:     SNIPPET-DRAW-2D-SURFACE
   :caption:  Example of surface drawing

.. oe:source:: Draw2DSurface.cs
   :language: csharp
   :refnum:   1
   :noindent:
   :frag:     SNIPPET-DRAW-2D-SURFACE
   :caption:  Example of surface drawing

.. _figure_draw_surface:

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

   **Example of surface drawing**


.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   %
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The :oe:src:`Listing 1<SNIPPET-DRAW-2D-SURFACE-Draw2DSurface>` example uses the
:oe:const:`OEGrapheme::OESurfaceArcStyle::Eyelash` style to draw the
molecule surface.
The following table lists all surface drawing styles that are
available in **Grapheme TK**.


.. list-table:: **Supported surface drawing styles**
   :widths: 150 150 150 150
   :header-rows: 0

   * - .. image:: images/OESurfaceArc_Small_OEAlphaRainbowArcFxn.*
          :align:  left
     - .. image:: images/OESurfaceArc_Small_OEBrickRoadArcFxn.*
          :align:  left
     - .. image:: images/OESurfaceArc_Small_OECastleArcFxn.*
          :align:  left
     - .. image:: images/OESurfaceArc_Small_OECogArcFxn.*
          :align:  left

   * - :ref:`OEAlphaRainbowArcFxn <OEGrapheme_OEAlphaRainbowArcFxn>`
     - :ref:`OEBrickRoadArcFxn <OEGrapheme_OEBrickRoadArcFxn>`
     - :ref:`OECastleArcFxn <OEGrapheme_OECastleArcFxn>`
     - :ref:`OECogArcFxn <OEGrapheme_OECogArcFxn>`

   * - .. image:: images/OESurfaceArc_Small_OEDefaultArcFxn.*
          :align:  left
     - .. image:: images/OESurfaceArc_Small_OEEyelashArcFxn.*
          :align:  left
     - .. image:: images/OESurfaceArc_Small_OEFlowerArcFxn.*
          :align:  left
     - .. image:: images/OESurfaceArc_Small_OENecklaceArcFxn.*
          :align:  left

   * - :ref:`OEDefaultArcFxn <OEGrapheme_OEDefaultArcFxn>`
     - :ref:`OEEyelashArcFxn <OEGrapheme_OEEyelashArcFxn>`
     - :ref:`OEFlowerArcFxn <OEGrapheme_OEFlowerArcFxn>`
     - :ref:`OENecklaceArcFxn <OEGrapheme_OENecklaceArcFxn>`

   * - .. image:: images/OESurfaceArc_Small_OENullArcFxn.*
          :align:  left
     - .. image:: images/OESurfaceArc_Small_OEOliveBranchArcFxn.*
          :align:  left
     - .. image:: images/OESurfaceArc_Small_OEPearlsArcFxn.*
          :align:  left
     - .. image:: images/OESurfaceArc_Small_OERaceTrackArcFxn.*
          :align:  left

   * - :ref:`OENullArcFxn <OEGrapheme_OENullArcFxn>`
     - :ref:`OEOliveBranchArcFxn <OEGrapheme_OEOliveBranchArcFxn>`
     - :ref:`OEPearlsArcFxn <OEGrapheme_OEPearlsArcFxn>`
     - :ref:`OERaceTrackArcFxn <OEGrapheme_OERaceTrackArcFxn>`

   * - .. image:: images/OESurfaceArc_Small_OERailroadTrackArcFxn.*
          :align:  left
     - .. image:: images/OESurfaceArc_Small_OESawArcFxn.*
          :align:  left
     - .. image:: images/OESurfaceArc_Small_OESimpsonArcFxn.*
          :align:  left
     - .. image:: images/OESurfaceArc_Small_OEStitchArcFxn.*
          :align:  left

   * - :ref:`OEStitchArcFxn <OEGrapheme_OEStitchArcFxn>`
     - :ref:`OESunArcFxn <OEGrapheme_OESunArcFxn>`
     - :ref:`OEWreathArcFxn <OEGrapheme_OEWreathArcFxn>`
     - :ref:`OERailroadTrackArcFxn <OEGrapheme_OERailroadTrackArcFxn>`

   * -
     - .. image:: images/OESurfaceArc_Small_OESunArcFxn.*
          :align:  left
     - .. image:: images/OESurfaceArc_Small_OEWreathArcFxn.*
          :align:  left
     -

   * -
     - :ref:`OESawArcFxn <OEGrapheme_OESawArcFxn>`
     - :ref:`OESimpsonArcFxn <OEGrapheme_OESimpsonArcFxn>`
     -


.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   %
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

User-defined surface drawing functors can be implemented by deriving
from the :ref:`OESurfaceArcFxnBase <OEGrapheme_OESurfaceArcFxnBase>` abstract base class.
In the :oe:src:`Listing 2<SNIPPET-DRAW-2D-SURFACE-USER-DEFINED-Draw2DSurfaceUserDefined>` example,
a user defined arc drawing functor is implemented that colors the
*eyelash* arcs according to the atom they belong to.
The image created by :oe:src:`Listing 2<SNIPPET-DRAW-2D-SURFACE-USER-DEFINED-Draw2DSurfaceUserDefined>` is shown in
:ref:`Figure: Example of user-defined surface drawing<figure_draw_surface_user_defined>`.

.. oe:source:: Draw2DSurfaceUserDefined.py
   :language: python
   :refnum:   2
   :frag:     SNIPPET-DRAW-2D-SURFACE-USER-DEFINED
   :caption:  Example of user-defined surface drawing

.. oe:source:: Draw2DSurfaceUserDefined.cpp
   :language: c++
   :refnum:   2
   :frag:     SNIPPET-DRAW-2D-SURFACE-USER-DEFINED
   :caption:  Example of user-defined surface drawing

.. oe:source:: Draw2DSurfaceUserDefined.java
   :language: java
   :refnum:   2
   :noindent:
   :frag:     SNIPPET-DRAW-2D-SURFACE-USER-DEFINED
   :caption:  Example of user-defined surface drawing

.. oe:source:: Draw2DSurfaceUserDefined.cs
   :language: csharp
   :refnum:   2
   :noindent:
   :frag:     SNIPPET-DRAW-2D-SURFACE-USER-DEFINED
   :caption:  Example of user-defined surface drawing

.. _figure_draw_surface_user_defined:

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

   **Example of user-defined surface drawing**

.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   %
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The :oe:src:`Listing 3<SNIPPET-DRAW-2D-SURFACE-PARTIAL-CHARGE-Draw2DSurfacePartialCharge>` example shows
how to project atom properties, such as partial charges into the molecule
surface.
The image created by :oe:src:`Listing 3<SNIPPET-DRAW-2D-SURFACE-PARTIAL-CHARGE-Draw2DSurfacePartialCharge>` is shown in
:ref:`Figure: Example of depicting atom properties<figure_draw_surface_partial_charge>`.

.. oe:source:: Draw2DSurfacePartialCharge.py
   :language: python
   :refnum:   3
   :frag:     SNIPPET-DRAW-2D-SURFACE-PARTIAL-CHARGE
   :caption:  Example of depicting atom properties on the molecule surface

.. oe:source:: Draw2DSurfacePartialCharge.cpp
   :language: c++
   :refnum:   3
   :frag:     SNIPPET-DRAW-2D-SURFACE-PARTIAL-CHARGE
   :caption:  Example of depicting atom properties on the molecule surface

.. oe:source:: Draw2DSurfacePartialCharge.java
   :language: java
   :refnum:   3
   :noindent:
   :frag:     SNIPPET-DRAW-2D-SURFACE-PARTIAL-CHARGE
   :caption:  Example of depicting atom properties on the molecule surface

.. oe:source:: Draw2DSurfacePartialCharge.cs
   :language: csharp
   :refnum:   3
   :noindent:
   :frag:     SNIPPET-DRAW-2D-SURFACE-PARTIAL-CHARGE
   :caption:  Example of depicting atom properties on the molecule surface

.. _figure_draw_surface_partial_charge:

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

   **Example of depicting atom properties**

.. seealso::

   * :ref:`OELinearColorGradient <OESystem_OELinearColorGradient>` class in the **OEDepict TK** manual

.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   %
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

It is also possible to draw multiple 2D surfaces arc-by-arc.
In the :oe:src:`Listing 4<SNIPPET-DRAW-MULTIPLE-2D-SURFACES-DrawMultiple2DSurfaces>` example below the
arcs returned by the :oe:func:`OEGrapheme::OEGet2DSurfaceArcs` function
for the given atom display and radius are directly rendered below
the molecule diagram.
In this case it is important to call the :oe:func:`OEGrapheme::OEGetMoleculeSurfaceScale`
function with the largest radius scale of the 2D surfaces drawn.
This reduces the scaling of the molecule in order to able to fit the
molecule diagram and all of the arcs of the 2D surfaces into the image.
The image created by :oe:src:`Listing 4<SNIPPET-DRAW-MULTIPLE-2D-SURFACES-DrawMultiple2DSurfaces>` is shown in
:ref:`Figure: Example of drawing multiple 2D surfaces<figure_draw_surface_multiple>`.

.. oe:source:: DrawMultiple2DSurfaces.py
   :language: python
   :refnum:   4
   :frag:     SNIPPET-DRAW-MULTIPLE-2D-SURFACES
   :caption:  Example of drawing multiple 2D surfaces

.. oe:source:: DrawMultiple2DSurfaces.cpp
   :language: c++
   :refnum:   4
   :frag:     SNIPPET-DRAW-MULTIPLE-2D-SURFACES
   :caption:  Example of drawing multiple 2D surfaces

.. oe:source:: DrawMultiple2DSurfaces.java
   :language: java
   :refnum:   4
   :noindent:
   :frag:     SNIPPET-DRAW-MULTIPLE-2D-SURFACES
   :caption:  Example of drawing multiple 2D surfaces

.. oe:source:: DrawMultiple2DSurfaces.cs
   :language: csharp
   :refnum:   4
   :noindent:
   :frag:     SNIPPET-DRAW-MULTIPLE-2D-SURFACES
   :caption:  Example of drawing multiple 2D surfaces

.. _figure_draw_surface_multiple:

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

   **Example of drawing multiple 2D surfaces**

.. seealso::

   :oe:constns:`OEGrapheme::OESurfaceArcScale` namespace

.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   %
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The last :oe:src:`Listing 5<SNIPPET-DRAW-2D-SURFACE-VARIOUS-RADII-Draw2DSurfaceVariousRadii>` example shows how to
draw a 2D surface with various radii.
It draws two surfaces one with a minimum radius scale and one with various radius
depending on the covalent radius of the atoms.
The :oe:func:`OEGrapheme::OEGetMoleculeSurfaceScale` function has to be called
in this example too with the largest radius scale in order to able to fit the molecule diagram
and all of the arcs of the 2D surfaces into the image.
The image created by :oe:src:`Listing 5<SNIPPET-DRAW-2D-SURFACE-VARIOUS-RADII-Draw2DSurfaceVariousRadii>` is shown in
:ref:`Figure: Example of drawing 2D surface with various radii<figure_draw_surface_various_radii>`.

.. oe:source:: Draw2DSurfaceVariousRadii.py
   :language: python
   :refnum:   5
   :frag:     SNIPPET-DRAW-2D-SURFACE-VARIOUS-RADII
   :caption:  Example of drawing 2D surface with various radii

.. oe:source:: Draw2DSurfaceVariousRadii.cpp
   :language: c++
   :refnum:   5
   :frag:     SNIPPET-DRAW-2D-SURFACE-VARIOUS-RADII
   :caption:  Example of drawing 2D surface with various radii

.. oe:source:: Draw2DSurfaceVariousRadii.java
   :language: java
   :refnum:   5
   :frag:     SNIPPET-DRAW-2D-SURFACE-VARIOUS-RADII
   :caption:  Example of drawing 2D surface with various radii

.. oe:language:: csharp

.. oe:source:: Draw2DSurfaceVariousRadii.cs
   :language: csharp
   :refnum:   5
   :frag:     SNIPPET-DRAW-2D-SURFACE-VARIOUS-RADII
   :caption:  Example of drawing 2D surface with various radii


.. _figure_draw_surface_various_radii:

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

   **Example of drawing 2D surface with various radii**

.. seealso::

   :oe:func:`OEChem::OEGetCovalentRadius` function in the **OEChem TK** manual
