.. _chapter_highlighting:

********************************************************************************
Highlighting
********************************************************************************

Atoms and bonds of a molecule can be highlighted by using the
:oe:func:`OEDepict::OEAddHighlighting` functions.
**OEDepict TK** provides four built-in highlighting styles:

**color**
  This style is associated with the
  :oe:const:`OEDepict::OEHighlightStyle::Color`
  constant.
  See :ref:`Figure: Example of highlighting using the 'color' style<figure_highlighting_color>`.

  .. _figure_highlighting_color:

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

     **Example of highlighting using the 'color' style**

**stick**
  This style is associated with the
  :oe:const:`OEDepict::OEHighlightStyle::Stick`
  constant.
  See :ref:`Figure: Example of highlighting using the 'stick' style<figure_highlighting_stick>`.

  .. _figure_highlighting_stick:

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

     **Example of highlighting using the 'stick' style**


**ball and stick**
  This style is associated with the
  :oe:const:`OEDepict::OEHighlightStyle::BallAndStick`
  constant.
  See :ref:`Figure: Example of highlighting using the 'ball and stick' style<figure_highlighting_ball_and_stick>`.

  .. _figure_highlighting_ball_and_stick:

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

     **Example of highlighting using the 'ball and stick' style**

**cogwheel**
  This style is associated with the
  :oe:const:`OEDepict::OEHighlightStyle::Cogwheel`
  constant.
  See :ref:`Figure: Example of highlighting using the 'cogwheel' style<figure_highlighting_cogwheel>`.

  .. _figure_highlighting_cogwheel:

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

     **Example of highlighting using the 'cogwheel' style**

**lasso**
  This style is associated with the
  :oe:const:`OEDepict::OEHighlightStyle::Lasso`
  constant.
  See :ref:`Figure: Example of highlighting using the 'lasso' style<figure_highlighting_lasso>`.

  .. _figure_highlighting_lasso:

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

     **Example of highlighting using the 'lasso' style**


Using Highlighting Styles
================================================================================

The following example (:oe:src:`Listing 1<SNIPPET-HIGHLIGHT-SIMPLE-HighlightSimple>`) shows how
to use the built-in highlighting styles.
The :oe:func:`OEDepict::OEAddHighlighting` function takes an
:ref:`OEMatchBase <OEChem_OEMatchBase>` object and highlights each of its target
atoms and bonds using the given style.
In this case, the two pyridine rings in the target structure are
highlighted by red color using the **stick** style.
The image created by :oe:src:`Listing 1<SNIPPET-HIGHLIGHT-SIMPLE-HighlightSimple>` is shown in
:ref:`Figure: Example of using 'stick' highlighting style<figure_highlighting_simple>`.

.. oe:source:: HighlightSimple.py
   :language: python
   :refnum:   1
   :caption:  Example of using highlighting style
   :frag:     SNIPPET-HIGHLIGHT-SIMPLE

.. oe:source:: HighlightSimple.cpp
   :language: c++
   :refnum:   1
   :caption:  Example of using highlighting style
   :frag:     SNIPPET-HIGHLIGHT-SIMPLE

.. oe:source:: HighlightSimple.java
   :language: java
   :refnum:   1
   :caption:  Example of using highlighting style
   :frag:     SNIPPET-HIGHLIGHT-SIMPLE

.. oe:source:: HighlightSimple.cs
   :language: csharp
   :refnum:   1
   :caption:  Example of using highlighting style
   :frag:     SNIPPET-HIGHLIGHT-SIMPLE


.. _figure_highlighting_simple:

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

   **Example of using 'stick' highlighting style**

.. seealso::

   * :oe:constns:`OEDepict::OEHighlightStyle` namespace
   * :oe:func:`OEDepict::OEAddHighlighting` function
   * :ref:`section_examples_summary_match2img` example

Using Highlighting Classes
================================================================================

**OEDepict TK** also provides the highlighting classes that correspond to
the highlighting styles.
Each highlighting style can be customized by using the corresponding class:

* :ref:`OEHighlightByColor <OEDepict_OEHighlightByColor>`
* :ref:`OEHighlightByStick <OEDepict_OEHighlightByStick>`
* :ref:`OEHighlightByBallAndStick <OEDepict_OEHighlightByBallAndStick>`
* :ref:`OEHighlightByCogwheel <OEDepict_OEHighlightByCogwheel>`
* :ref:`OEHighlightByLasso <OEDepict_OEHighlightByLasso>`

The next example (:oe:src:`Listing 2<SNIPPET-HIGHLIGHT-STYLE-HighlightStyle>`) shows how
the  **stick** style can be customized by using the corresponding
:ref:`OEHighlightByStick <OEDepict_OEHighlightByStick>` class.
The image created by :oe:src:`Listing 2<SNIPPET-HIGHLIGHT-STYLE-HighlightStyle>` is shown in
:ref:`Figure: Example of customizing the 'stick' highlighting style<figure_highlighting_style>`.

.. oe:source:: HighlightStyle.py
   :language: python
   :refnum:   2
   :caption:  Example of using highlighting class
   :frag:     SNIPPET-HIGHLIGHT-STYLE

.. oe:source:: HighlightStyle.cpp
   :language: c++
   :refnum:   2
   :caption:  Example of using highlighting class
   :frag:     SNIPPET-HIGHLIGHT-STYLE

.. oe:source:: HighlightStyle.java
   :language: java
   :refnum:   2
   :caption:  Example of using highlighting class
   :frag:     SNIPPET-HIGHLIGHT-STYLE

.. oe:source:: HighlightStyle.cs
   :language: csharp
   :refnum:   2
   :caption:  Example of using highlighting class
   :frag:     SNIPPET-HIGHLIGHT-STYLE

.. _figure_highlighting_style:

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

   **Example of customizing the 'stick' highlighting style**

.. seealso::

   * :oe:func:`OEDepict::OEAddHighlighting` function

.. _section_highlighting_overlap:

Highlighting Overlapped Patterns
================================================================================

If more than one part of a molecule is highlighted, these highlights
can overlap resulting in loss of information.
For example, highlighting the matches of the `c1cc[c,n]cc1` SMARTS
pattern will produce the following image.

.. _figure_highlighting_all_in_one:

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

   **Example of highlighting multiple matches in the same image**

There are two ways how this can be avoided and correctly
highlight overlapping parts of a molecule.
The first example demonstrates how to depict multiple matches in
different image cells one by one.
The image created by :oe:src:`Listing 3<SNIPPET-HIGHLIGHT-MULTI-HighlightMulti>` is shown in
:ref:`Figure: Example of highlighting multiple matches one by one<figure_highlighting_multi>`.

.. oe:source:: HighlightMulti.py
   :language: python
   :refnum:   3
   :caption:  Example of highlighting multiple matches one by one
   :frag:     SNIPPET-HIGHLIGHT-MULTI

.. oe:source:: HighlightMulti.cpp
   :language: c++
   :refnum:   3
   :caption:  Example of highlighting multiple matches one by one
   :frag:     SNIPPET-HIGHLIGHT-MULTI

.. oe:source:: HighlightMulti.java
   :language: java
   :refnum:   3
   :caption:  Example of highlighting multiple matches one by one
   :frag:     SNIPPET-HIGHLIGHT-MULTI

.. oe:source:: HighlightMulti.cs
   :language: csharp
   :refnum:   3
   :caption:  Example of highlighting multiple matches one by one
   :frag:     SNIPPET-HIGHLIGHT-MULTI

.. _figure_highlighting_multi:

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

   **Example of highlighting multiple matches one by one**

.. seealso::

    * :ref:`OEImageGrid <OEDepict_OEImageGrid>` class
    * :ref:`section_image_layout_grid` section

The second example (:oe:src:`Listing 4<SNIPPET-HIGHLIGHT-OVERLAY-HighlightOverlay>`) illustrates how
to highlight overlapping matches at once using the
:ref:`OEHighlightOverlayByBallAndStick <OEDepict_OEHighlightOverlayByBallAndStick>` class.
In this example, the :oe:func:`OEDepict::OEAddHighlightOverlay` function takes
all matches being highlighted and colors the overlapped atoms and bonds
using the colors by turn.
The colors used for highlighting are determined when the
:ref:`OEHighlightOverlayByBallAndStick <OEDepict_OEHighlightOverlayByBallAndStick>` object is constructed.
The image created by :oe:src:`Listing 4<SNIPPET-HIGHLIGHT-OVERLAY-HighlightOverlay>` is shown in
:ref:`Figure: Example of highlighting overlapping matches at once<figure_highlighting_overlay>`.

.. oe:source:: HighlightOverlay.py
   :language: python
   :refnum:   4
   :caption:  Example of highlighting multiple matches simultaneously
   :frag:     SNIPPET-HIGHLIGHT-OVERLAY

.. oe:source:: HighlightOverlay.cpp
   :language: c++
   :refnum:   4
   :caption:  Example of highlighting multiple matches simultaneously
   :frag:     SNIPPET-HIGHLIGHT-OVERLAY

.. oe:source:: HighlightOverlay.java
   :language: java
   :refnum:   4
   :caption:  Example of highlighting multiple matches simultaneously
   :frag:     SNIPPET-HIGHLIGHT-OVERLAY

.. oe:source:: HighlightOverlay.cs
   :language: csharp
   :refnum:   4
   :caption:  Example of highlighting multiple matches simultaneously
   :frag:     SNIPPET-HIGHLIGHT-OVERLAY

.. _figure_highlighting_overlay:

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

   **Example of highlighting overlapping matches at once**

.. seealso::

    * :ref:`OEHighlightOverlayBase <OEDepict_OEHighlightOverlayBase>` base class
    * :ref:`OEHighlightOverlayByBallAndStick <OEDepict_OEHighlightOverlayByBallAndStick>` class
    * :oe:constns:`OEDepict::OEHighlightOverlayStyle` namespace
    * :oe:func:`OESystem::OEGetColors`, :oe:func:`OESystem::OEGetContrastColors`,
      :oe:func:`OESystem::OEGetDeepColors`, :oe:func:`OESystem::OEGetLightColors` and
      :oe:func:`OESystem::OEGetVividColors` functions

