.. _chapter_oemolstyle:

********************************************************************************
Molecule Styling
********************************************************************************

.. _section_oe3dmolstyle:

OE3DMolStyle
================================================================================

An :ref:`OEMolBase <OEChem_OEMolBase>` has a default style without the addition 
of an :ref:`OE3DMolStyle <OEChem_OE3DMolStyle>`. The :ref:`OE3DMolStyle <OEChem_OE3DMolStyle>` 
class gives a multitude of customization options for the :ref:`OEMolBase <OEChem_OEMolBase>`, 
from coloring to labeling. Outside of :ref:`OEMolBase <OEChem_OEMolBase>`, :ref:`OE3DMolStyle <OEChem_OE3DMolStyle>` 
can be applied to an :ref:`OEAtomBase <OEChem_OEAtomBase>` and an :ref:`OEConfBase <OEChem_OEConfBase>`. 
There is a hierarchy when applying :ref:`OE3DMolStyle <OEChem_OE3DMolStyle>` to each one of these classes: 
:ref:`OEMolBase <OEChem_OEMolBase>` -> :ref:`OEConfBase <OEChem_OEConfBase>` -> :ref:`OEAtomBase <OEChem_OEAtomBase>`. 

.. _section_oemolstyle_atomlabel:

Atom Labeling
================================================================================

Preset labels can be applied using :ref:`SetAtomLabelType<OEChem_OE3DMolStyle_SetAtomLabelType>`.
Custom labels can be applied to specific atoms utilizing :ref:`SetAtomLabelText<OEChem_OE3DMolStyle_SetAtomLabelText>`.
:ref:`SetAtomLabelType<OEChem_OE3DMolStyle_SetAtomLabelType>` takes in :ref:`OEAtomLabelScheme <OEChem_OEAtomLabelScheme>`.
The example below depicts the B-Factor above each one of the respective atoms in the molecule.

.. oe:language:: c++

   .. code-block:: c++

      OEMolBase mol;
      OE3DMolStyle molSty;
      molSty.SetAtomLabelType(OEAtomLabelScheme::BFactor);
      OESetStyle(mol1, molSty);

.. oe:language:: python

   .. code-block:: python

      mol = oechem.OEMol()
      molSty = oechem.OE3DMolStyle()
      molSty.SetAtomLabelType(oechem.OEAtomLabelScheme_BFactor)
      oechem.OESetStyle(mol, molSty)

.. _section_oemolstyle_stylestypes:

Styling and Typing
================================================================================

There are multiple styling and typing options for an :ref:`OE3DMolStyle <OEChem_OE3DMolStyle>`. 
:ref:`OEAtomStyle <OEChem_OEAtomStyle>` can be set using :ref:`SetAtomStyle<OEChem_OE3DMolStyle_SetAtomStyle>`.
This allows for customization of the visibility of the atoms in a molecule, which ranges from hidden atoms 
to CPK atom styling. In the example below the atoms are set to display as Ball and Stick.

.. oe:language:: c++

   .. code-block:: c++

      OEMolBase mol;
      OE3DMolStyle molSty;
      molSty.SetAtomStyle(OEAtomStyle::BallAndStick);
      OESetStyle(mol1, molSty);

.. oe:language:: python

   .. code-block:: python

      mol = oechem.OEMol()
      molSty = oechem.OE3DMolStyle()
      molSty.SetAtomStyle(oechem.OEAtomStyle_BallAndStick)
      oechem.OESetStyle(mol, molSty)

:ref:`OEProteinStyle <OEChem_OEProteinStyle>` can be set utilizing :ref:`SetProteinStyle<OEChem_OE3DMolStyle_SetProteinStyle>`.
This allows for customization of the protein from hidden to ribbon. The example below set the protein style to CAlpha, which 
depicts the protein with edges at the CAlphas.

.. oe:language:: c++

   .. code-block:: c++

      OEMolBase mol;
      OE3DMolStyle molSty;
      molSty.SetProteinStyle(OEProteinStyle::CAlpha);
      OESetStyle(mol1, molSty);

.. oe:language:: python

   .. code-block:: python

      mol = oechem.OEMol()
      molSty = oechem.OE3DMolStyle()
      molSty.SetProteinStyle(oechem.OEProteinStyle_CAlpha)
      oechem.OESetStyle(mol, molSty)

:ref:`OEContourStyle <OEChem_OEContourStyle>` can be set utilizing :ref:`SetContourStyle<OEChem_OE3DMolStyle_SetContourStyle>`.
This allows for customization of the contour from hidden to solid. :ref:`SetGridType<OEChem_OE3DMolStyle_SetGridType>`
takes in the :ref:`OEStyleGridType <OEChem_OEStyleGridType>` constant to specify the type of the grid being depicted. The example below
set the grid style to mesh and the drid type to electrostatic. This will depict the grid in mesh form for better visibility of 
the other components of the molecule.

.. oe:language:: c++

   .. code-block:: c++

      OEMolBase mol;
      OE3DMolStyle molSty;
      molSty.SetContourStyle(OEContourStyle::Mesh);
      molSty.SetGridType(OEStyleGridType::Electrostatic);
      OESetStyle(mol1, molSty);

.. oe:language:: python

   .. code-block:: python

      mol = oechem.OEMol()
      molSty = oechem.OE3DMolStyle()
      molSty.SetContourStyle(oechem.OEContourStyle_Mesh)
      molSty.SetGridType(oechem.OEStyleGridType_Electrostatic)
      oechem.OESetStyle(mol, molSty)

:ref:`SetSurfaceStyle<OEChem_OE3DMolStyle_SetSurfaceStyle>` utilizes :ref:`OEChem_OESurfaceStyle` to
depict the surface by mesh, point, and solid. :ref:`OESurfaceType <OEChem_OESurfaceType>` allows for surface typing when
set by :ref:`SetSurfaceType<OEChem_OE3DMolStyle_SetSurfaceType>`. The example below style a molecular surface
to be depicted in points.

.. oe:language:: c++

   .. code-block:: c++

      OEMolBase mol;
      OE3DMolStyle molSty;
      molSty.SetSurfaceStyle(OESurfaceStyle::Points);
      molSty.SetSurfaceType(OESurfaceType::Molecular);
      OESetStyle(mol1, molSty);

.. oe:language:: python

   .. code-block:: python

      mol = oechem.OEMol()
      molSty = oechem.OE3DMolStyle()
      molSty.SetSurfaceStyle(oechem.OESurfaceStyle_Points)
      molSty.SetSetSurfaceTypeGridType(oechem.OESurfaceType_Molecular)
      oechem.OESetStyle(mol, molSty)

Hydrogen visibility is customizable by utilizing :ref:`OEHydrogenVisibility <OEChem_OEHydrogenVisibility>` in
:ref:`SetHydrogenVisibility<OEChem_OE3DMolStyle_SetHydrogenVisibility>`. This allows for all
hydrogen, polar hydrogen, and hidden hydrogen depictions. In the example below sets up an 
:ref:`OE3DMolStyle <OEChem_OE3DMolStyle>` to only depict the polar hydrogens in the molecule. 

.. oe:language:: c++

   .. code-block:: c++

      OEMolBase mol;
      OE3DMolStyle molSty;
      molSty.SetHydrogenVisibility(OEHydrogenVisibility::Polar);
      OESetStyle(mol1, molSty);

.. oe:language:: python

   .. code-block:: python

      mol = oechem.OEMol()
      molSty = oechem.OE3DMolStyle()
      molSty.SetHydrogenVisibility(oechem.OEHydrogenVisibility_Polar)
      oechem.OESetStyle(mol, molSty)

Atom to atom interactions is depicted using arrows from one atom to another. By default this is set to off. 
:ref:`SetInteractionStyle<OEChem_OE3DMolStyle_SetInteractionStyle>` utilizes :ref:`OEInteractionStyle <OEChem_OEInteractionStyle>`
to toggle between intermolecular hydrogen bond interaction depiction, intramolecular hydrogen bond interaction depiction, 
and no bond interaction depiction. In this example we set the the interaction style to intramolecular hydrogen bond depiction.

.. oe:language:: c++

   .. code-block:: c++

      OEMolBase mol;
      OE3DMolStyle molSty;
      molSty.SetInteractionStyle(OEInteractionStyle::IntramolecularHBonds);
      OESetStyle(mol1, molSty);

.. oe:language:: python

   .. code-block:: python

      mol = oechem.OEMol()
      molSty = oechem.OE3DMolStyle()
      molSty.SetInteractionStyle(oechem.OEInteractionStyle_IntramolecularHBonds)
      oechem.OESetStyle(mol, molSty)

.. _section_oemolstyle_colorer:

Colorer
================================================================================

Multple aspects of the molecule can be colored when :ref:`OE3DMolStyle <OEChem_OE3DMolStyle>` 
takes advantage of :ref:`OEMolStyleColorer <OEChem_OEMolStyleColorer>`. There are preset color 
schemes for all parts of the molecule from atoms to protein, but custom colors can also be added for 
better personalization of the molecule.

:ref:`OEAtomColorScheme <OEChem_OEAtomColorScheme>` provides multple preset atom color schemes when specified in the construction
of an :ref:`OEMolStyleColorer <OEChem_OEMolStyleColorer>`. :ref:`SetAtomColorer<OEChem_OE3DMolStyle_SetAtomColorer>`
takes in the :ref:`OEMolStyleColorer <OEChem_OEMolStyleColorer>`. Atoms are colored by element by default, but this allows 
for coloring by b factor, residues, formal charge, and other aspects of the atoms and/or molecule. The labels of an atom can 
also be colored when an :ref:`OEMolStyleColorer <OEChem_OEMolStyleColorer>` with a default color and/or custom colors by atom 
name or atomic number. The color of a grid can also be set with a default color specified in an :ref:`OEMolStyleColorer <OEChem_OEMolStyleColorer>`.
The :ref:`OEMolStyleColorer <OEChem_OEMolStyleColorer>` with the default color can be set to the :ref:`OE3DMolStyle <OEChem_OE3DMolStyle>` 
with :ref:`SetGridContourColorer<OEChem_OE3DMolStyle_SetGridContourColorer>`.

:ref:`OESurfaceColorScheme <OEChem_OESurfaceColorScheme>` provides customization of surfaces with preset color schemes. These color schemes
are applied similarly to how atom color schemes are applied but by utilizing :ref:`SetSurfaceColorer<OEChem_OE3DMolStyle_SetSurfaceColorer>`.
When a color scheme isn't specified the surface is colored by the default color, by default the surface is colored blue.

Proteins can be colored utilizing a color scheme from :ref:`OEProteinColorScheme <OEChem_OEProteinColorScheme>` but it can also colored
with a constant from :ref:`OEAtomColorScheme <OEChem_OEAtomColorScheme>`. The :ref:`OEMolStyleColorer <OEChem_OEMolStyleColorer>` utilized for the protein
can be set to the :ref:`OE3DMolStyle <OEChem_OE3DMolStyle>` with :ref:`SetProteinColorer<OEChem_OE3DMolStyle_SetProteinColorer>`.
The example below adds the different coloring options to the molecule. The protein is colored by residue. The atoms are colored by element, 
with a default color of white, but the :ref:`OEMolStyleColorer <OEChem_OEMolStyleColorer>` also overwrites preset colors of certain atoms by atomic number. 
The grid is colored pink and the surface is colored by surface potential.

.. oe:language:: c++

   .. code-block:: c++

      OEMolBase mol;
      OE3DMolStyle molSty;
      OEMolStyleColorer protCol(OEAtomColorScheme::Residue);
      OEMolStyleColorer atomCol(OEAtomColorScheme::Element, OEWhite);
      OEMolStyleColorer gridCol(OEPink);
      OEMolStyleColorer surfCol(OESurfaceColorScheme::SurfacePotential);

      atomCol.AddColor(6, OEGreen);
      atomCol.AddColor(7, OERed);
      atomCol.AddColor(8, OEBlue);

      molSty.SetAtomColorer(atomCol);
      molSty.SetProteinColorer(protCol);
      molSty.SetGridContourColorer(gridCol);
      molSty.SetSurfaceColorer(surfCol);
      OESetStyle(mol1, molSty);

.. oe:language:: python

   .. code-block:: python

      mol = oechem.OEMol()
      molSty = oechem.OE3DMolStyle()
      protCol = oechem.OEMolStyleColorer(oechem.OEAtomColorScheme_Residue)
      atomCol = oechem.OEMolStyleColorer(oechem.OEAtomColorScheme_Element, oechem.OEWhite)
      gridCol = oechem.OEMolStyleColorer(OEPink)
      surfCol = oechem.OEMolStyleColorer(OESurfaceColorScheme::SurfacePotential)

      atomCol.AddColor(6, oechem.OEGreen)
      atomCol.AddColor(7, oechem.OERed)
      atomCol.AddColor(8, oechem.OEBlue)
    

      molSty.SetAtomColorer(atomCol)
      molSty.SetProteinColorer(protCol)
      molSty.SetGridContourColorer(gridCol)
      molSty.SetSurfaceColorer(surfCol)
      oechem.OESetStyle(mol, molSty)


.. seealso::

   * :ref:`basicStyle<section_example_oechem_basicmolstyle>` example
   * :ref:`bFactorStyle<section_example_oechem_bFactorStyle>` example
   * :ref:`styleHierarchy<section_oechem_example_stylehierarchy>` example