.. _chapter_annotation:

********************************************************************************
Annotating Atoms and Bonds
********************************************************************************

The **Grapheme TK** provides a framework to annotate atoms and bonds *i.e.*
mark them based on their properties.
The following :oe:src:`Listing 1<SNIPPET-ANNOTATE-ATOM-PROPERTY-AnnotateAtomPredicate>` example shows
how to mark :math:`sp^2` and :math:`sp^3` hybridized atoms of
depicted molecules.
After preparing the molecule for 2D depiction and calculating the
atom hybridizations, the molecule display object is created
(:ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>`) that stores the depiction
information of a molecule
The :oe:func:`OEGrapheme::OEAddGlyph` function is then called to
add *glyph* to those atoms for which the given
:ref:`OEIsAtomHybridization <OEChem_OEIsAtomHybridization>` functor returns `true`.
In this example, the built-in :ref:`OEAtomGlyphCircle <OEGrapheme_OEAtomGlyphCircle>`
class is used to mark atoms by drawings a circle around them with a
specific style (:oe:constns:`OEGrapheme::OECircleStyle`).
Finally, the image is written out to a file by calling the
:oe:func:`OEDepict::OEWriteImage` function.
The image created by :oe:src:`Listing 1<SNIPPET-ANNOTATE-ATOM-PROPERTY-AnnotateAtomPredicate>` example
is shown in
:ref:`Figure: Example of atom annotation<figure_annotate_atom_predicate>`.

.. oe:source:: AnnotateAtomPredicate.py
   :language: python
   :refnum:   1
   :frag:     SNIPPET-ANNOTATE-ATOM-PROPERTY
   :caption:  Example of using a built-in atom annotation style

.. oe:source:: AnnotateAtomPredicate.cpp
   :language: c++
   :refnum:   1
   :frag:     SNIPPET-ANNOTATE-ATOM-PROPERTY
   :caption:  Example of using a built-in atom annotation style

.. oe:source:: AnnotateAtomPredicate.java
   :language: java
   :refnum:   1
   :frag:     SNIPPET-ANNOTATE-ATOM-PROPERTY
   :caption:  Example of using a built-in atom annotation style

.. oe:source:: AnnotateAtomPredicate.cs
   :language: csharp
   :refnum:   1
   :frag:     SNIPPET-ANNOTATE-ATOM-PROPERTY
   :caption:  Example of using a built-in atom annotation style

.. _figure_annotate_atom_predicate:

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

   **Example of atom annotation**

.. seealso::

   * :oe:func:`OEGrapheme::OEAddGlyph` function
   * :ref:`OEAtomGlyphCircle <OEGrapheme_OEAtomGlyphCircle>` class
   * :oe:constns:`OEGrapheme::OECircleStyle` namespace
   * :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` class and
     :oe:func:`OEDepict::OEWriteImage` function in the **OEDepict TK** manual


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

Similarly, the following example shows how to annotate bonds.
The bonds being highlighted are specified by the bond predicate passed
to the :oe:func:`OEGrapheme::OEAddGlyph` function.
For each bond the predicate returns ``true``, *i.e.* if it is a
rotatable bond, the :oe:meth:`OEGrapheme::OEBondGlyphArrow::RenderGlyph`
method is invoked that draws an arrow across the middle of the specific bond.
The image created by :oe:src:`Listing 2<SNIPPET-ANNOTATE-BOND-PROPERTY-AnnotateBondPredicate>` is shown in
:ref:`Figure: Example of bond annotation<figure_annotate_bond_predicate>`.


.. oe:source:: AnnotateBondPredicate.py
   :language: python
   :refnum:   2
   :frag:     SNIPPET-ANNOTATE-BOND-PROPERTY
   :caption:  Example of using a built-in bond annotation style

.. oe:source:: AnnotateBondPredicate.cpp
   :language: c++
   :refnum:   2
   :frag:     SNIPPET-ANNOTATE-BOND-PROPERTY
   :caption:  Example of using a built-in bond annotation style

.. oe:source:: AnnotateBondPredicate.java
   :language: java
   :refnum:   2
   :frag:     SNIPPET-ANNOTATE-BOND-PROPERTY
   :caption:  Example of using a built-in bond annotation style

.. oe:source:: AnnotateBondPredicate.cs
   :language: csharp
   :refnum:   2
   :frag:     SNIPPET-ANNOTATE-BOND-PROPERTY
   :caption:  Example of using a built-in bond annotation style

.. _figure_annotate_bond_predicate:

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

   **Example of bond annotation**

The following table lists the customizable bond glyphs that are currently
available in **Grapheme TK**.


.. list-table:: **Supported bond glyphs**
   :widths: 200 200 200 200
   :header-rows: 0

   * - .. image:: images/OEBondGlyphArrow_Default.*
          :align:  left
     - .. image:: images/OEBondGlyphCircle_Default.*
          :align:  left
     - .. image:: images/OEBondGlyphCross_Default.*
          :align:  left
     - .. image:: images/OEBondGlyphCurvedArrow_Default.*
          :align:  left

   * - :ref:`OEBondGlyphArrow <OEGrapheme_OEBondGlyphArrow>`
     - :ref:`OEBondGlyphCircle <OEGrapheme_OEBondGlyphCircle>`
     - :ref:`OEBondGlyphCross <OEGrapheme_OEBondGlyphCross>`
     - :ref:`OEBondGlyphCurvedArrow <OEGrapheme_OEBondGlyphCurvedArrow>`

   * - .. image:: images/OEBondGlyphScissors_Default.*
          :align:  left
     - .. image:: images/OEBondGlyphStitch_Default.*
          :align:  left
     - .. image:: images/OEBondGlyphZigZag_Default.*
          :align:  left
     -

   * - :ref:`OEBondGlyphScissors <OEGrapheme_OEBondGlyphScissors>`
     - :ref:`OEBondGlyphStitch <OEGrapheme_OEBondGlyphStitch>`
     - :ref:`OEBondGlyphZigZag <OEGrapheme_OEBondGlyphZigZag>`
     -

.. seealso::

   * :oe:func:`OEGrapheme::OEAddGlyph` function

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

The last example shows how to depict *non-boolean* properties by implementing
a user-defined annotation style.
User-defined atom and bond annotations can be implemented by deriving
from the :ref:`OEAtomGlyphBase <OEGrapheme_OEAtomGlyphBase>` and the
:ref:`OEBondGlyphBase <OEGrapheme_OEBondGlyphBase>` abstract classes and implementing
the :oe:meth:`OEGrapheme::OEAtomGlyphBase::RenderGlyph` and the
:oe:meth:`OEGrapheme::OEBondGlyphBase::RenderGlyph` methods,
respectively.

In the :oe:src:`Listing 3<SNIPPET-ANNOTATE-PARTIAL-CHARGE-AnnotatePartialCharge>` example, after
calculating the MMFF charges, the atoms are annotated by their charge
using the :ref:`OELinearColorGradient <OESystem_OELinearColorGradient>` class that
interpolates colors. Atoms with negative and positive charge are
highlighted by red and blue colors, respectively.
The image created by :oe:src:`Listing 3<SNIPPET-ANNOTATE-PARTIAL-CHARGE-AnnotatePartialCharge>` is shown in
:ref:`Figure: Example of user-defined annotation<figure_annotate_partial_charge>`.

.. oe:source:: AnnotatePartialCharge.py
   :language: python
   :refnum:   3
   :frag:     SNIPPET-ANNOTATE-PARTIAL-CHARGE
   :caption:  Example of user-defined annotation

.. oe:source:: AnnotatePartialCharge.cpp
   :language: c++
   :refnum:   3
   :frag:     SNIPPET-ANNOTATE-PARTIAL-CHARGE
   :caption:  Example of user-defined annotation

.. oe:source:: AnnotatePartialCharge.java
   :language: java
   :refnum:   3
   :frag:     SNIPPET-ANNOTATE-PARTIAL-CHARGE
   :caption:  Example of user-defined annotation

.. oe:source:: AnnotatePartialCharge.cs
   :language: csharp
   :refnum:   3
   :frag:     SNIPPET-ANNOTATE-PARTIAL-CHARGE
   :caption:  Example of user-defined annotation

.. _figure_annotate_partial_charge:

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

   **Example of user-defined annotation**

.. seealso::

   * :ref:`OEAtomGlyphBase <OEGrapheme_OEAtomGlyphBase>` class
   * :ref:`OEBondGlyphBase <OEGrapheme_OEBondGlyphBase>` class
   * :oe:func:`OEGrapheme::OEAddGlyph` function
   * :ref:`OELinearColorGradient <OESystem_OELinearColorGradient>` class
