.. include:: substitutions

.. _chapter_svg:

********************************************************************************
Generating Interactive SVG Images
********************************************************************************

SVG group
================================================================================

SVG `group <https://developer.mozilla.org/en-US/docs/Web/SVG/Element/g>`_ is
a container for grouping and naming collections of SVG drawing elements.
In **OEDepict TK**, the :ref:`OESVGGroup <OEDepict_OESVGGroup>` class is to used
for grouping drawing instructions together.

The code snippet below shows how to create and use an
:ref:`OESVGGroup <OEDepict_OESVGGroup>` object.

.. oe:source:: CreateSVGGroup.py
   :language: python
   :noindent:
   :frag:     SNIPPET-CREATE-GROUP

.. oe:source:: CreateSVGGroup.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-CREATE-GROUP

.. oe:source:: CreateSVGGroup.java
   :language: java
   :noindent:
   :frag:     SNIPPET-CREATE-GROUP

.. oe:source:: CreateSVGGroup.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-CREATE-GROUP

.. only:: oehtml

   .. oe:language:: python

      .. admonition:: Download code

         :download:`CreateSVGGroup.py <../../../../wrappers/python/docexamples/depict/CreateSVGGroup.py>`

   .. oe:language:: c++

      .. admonition:: Download code

         :download:`CreateSVGGroup.cpp <../../../../sublibs/tklibs/depict/examples/docs/CreateSVGGroup.cpp>`

   .. oe:language:: java

      .. admonition:: Download code

         :download:`CreateSVGGroup.java <../../../../wrappers/java/examples/openeye/docexamples/oedepict/CreateSVGGroup.java>`

   .. oe:language:: csharp

      .. admonition:: Download code

         :download:`CreateSVGGroup.cs <../../../../wrappers/csharp/Csharp-Examples/OEDepictDocs/CreateSVGGroup.cs>`


* First an :ref:`OESVGGroup <OEDepict_OESVGGroup>` object is created on the image by
  calling the :oe:meth:`OEDepict::OEImageBase::NewSVGGroup` method.

* The  :ref:`OESVGGroup <OEDepict_OESVGGroup>` object is the can be utilized by
  invoking the :oe:meth:`OEDepict::OEImageBase::PushGroup` method.
  This result in writing the ``<g id='circle'>`` line into the :file:`svg`
  image.

* Each push has to be coupled with a corresponding pop.
  When the :oe:meth:`OEDepict::OEImageBase::PopGroup` method is invoked the
  ``</g>`` closing line will be written into the image file.

The above snippet will generate the following :file:`svg` image:

.. literalinclude:: images/CreateSVGGroup.svg
   :emphasize-lines: 8, 10

The **guideline** below should be followed when using SVG groups
in **OEDepict TK**:

* The name of the :ref:`OESVGGroup <OEDepict_OESVGGroup>` has to be unique for the
  given image and it can only contain alphanumeric, ``_`` or ``-`` characters.

* An :ref:`OESVGGroup <OEDepict_OESVGGroup>` object can be used (pushed / popped) only
  once.

* :ref:`OESVGGroup <OEDepict_OESVGGroup>` objects can be nested.
  They should be used in LIFO (for last in, first out)
  i.e. the group that has been pushed last should be popped first.

.. seealso::

   * `Group SVG element <https://developer.mozilla.org/en-US/docs/Web/SVG/Element/g>`_  section in MDN
   * `Grouping <https://www.w3.org/TR/SVG/struct.html#Groups>`_  section in W3C

SVG class
================================================================================

In **OEDepict TK**, the :ref:`OESVGClass <OEDepict_OESVGClass>` class can be used to add
`class <https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/class>`_
attributes to
`group <https://developer.mozilla.org/en-US/docs/Web/SVG/Element/g>`_
containers.

The code snippet below shows how to create and use an
:ref:`OESVGClass <OEDepict_OESVGClass>` object.

.. oe:source:: CreateSVGClass.py
   :language: python
   :noindent:
   :frag:     SNIPPET-CREATE-CLASS

.. oe:source:: CreateSVGClass.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-CREATE-CLASS

.. oe:source:: CreateSVGClass.java
   :language: java
   :noindent:
   :frag:     SNIPPET-CREATE-CLASS

.. oe:source:: CreateSVGClass.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-CREATE-CLASS


.. only:: oehtml

   .. oe:language:: python

      .. admonition:: Download code

         :download:`CreateSVGClass.py <../../../../wrappers/python/docexamples/depict/CreateSVGClass.py>`

   .. oe:language:: c++

      .. admonition:: Download code

         :download:`CreateSVGClass.cpp <../../../../sublibs/tklibs/depict/examples/docs/CreateSVGClass.cpp>`

   .. oe:language:: java

      .. admonition:: Download code

         :download:`CreateSVGClass.java <../../../../wrappers/java/examples/openeye/docexamples/oedepict/CreateSVGClass.java>`

   .. oe:language:: csharp

      .. admonition:: Download code

         :download:`CreateSVGClass.cs <../../../../wrappers/csharp/Csharp-Examples/OEDepictDocs/CreateSVGClass.cs>`


* First two :ref:`OESVGGroup <OEDepict_OESVGGroup>` objects are created on the image,
  followed by creating a :ref:`OESVGClass <OEDepict_OESVGClass>` object by calling the
  :oe:meth:`OEDepict::OEImageBase::NewSVGClass` method.

* The :ref:`OESVGClass <OEDepict_OESVGClass>` object then can be added to any groups
  by calling :oe:meth:`OEDepict::OESVGGroup::AddSVGClass` method.

* When a :ref:`OESVGGroup <OEDepict_OESVGGroup>` object is pushed classes
  associated with it will be written into the :file:`svg` file:
  ``<g id='circle' class='object'>`` and ``<g id='rectangle' class='object'>``.

The above snippet will generate the following :file:`svg` image:

.. literalinclude:: images/CreateSVGClass.svg
   :emphasize-lines: 8, 10-11, 13

The **guideline** below should be followed when using SVG
classes in **OEDepict TK**:

* The name of the :ref:`OESVGClass <OEDepict_OESVGClass>` has to be unique for the
  given image and it can only contain alphanumeric, ``_`` or ``-`` characters.

* An :ref:`OESVGClass <OEDepict_OESVGClass>` object can be associated with
  multiple :ref:`OESVGGroup <OEDepict_OESVGGroup>` objects.

* An :ref:`OESVGGroup <OEDepict_OESVGGroup>` object can be associated with
  multiple :ref:`OESVGClass <OEDepict_OESVGClass>` objects.

.. seealso::

   * `MDN Class attribute <https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/class>`_ section in MDN
   * `WSC Class attribute <https://www.w3.org/TR/SVG/styling.html#ClassAttribute>`_ section in WSC

Examples of Generating Interactive SVG Images
================================================================================

**OEDepict TK** also provides high-level APIs that are not only group SVG
elements together but also adds styles and events to them to generate
interactive images.

See the following **OEDepict TK** API:

* :oe:func:`OEDepict::OEAddSVGHover` and :oe:func:`OEDepict::OEAddSVGToggle`
  low-level functions that allow to add effects to any objects.

* :oe:func:`OEDepict::OEAddSVGClickEvent` low-level functions that allows
  to add click event to any objects.

* :oe:func:`OEDepict::OEDrawSVGHoverText` function that displays a text
  associated with an atom or bond when the mouse is hovering over their
  position on the image.

* :oe:func:`OEDepict::OEDrawSVGToggleText` function that displays a
  text associated with an atom or bond when clicking at their position on
  the image.

.. only:: oehtml


   .. list-table:: **Gallery of OEDepict TK examples of interactive SVG images**
      :widths: 150 150

      * - Hover the mouse over any atom
        - Click on any atom

      * - .. raw:: html

             <p align="center">
             <object data="../_images/HoverAtomText.svg" type="image/svg+xml"  width = "300" ></object>
             <p>

        - .. raw:: html

             <p align="center">
             <object data="../_images/ToggleAtomText.svg" type="image/svg+xml"  width = "300" ></object>
             <p>

      * - Hover the mouse over any bond
        - Click on the middle on any bond

      * - .. raw:: html

             <p align="center">
             <object data="../_images/HoverBondText.svg" type="image/svg+xml"  width = "300" ></object>
             <p>

        - .. raw:: html

             <p align="center">
             <object data="../_images/ToggleBondText.svg" type="image/svg+xml"  width = "300" ></object>
             <p>

   .. the above tiny images are necessary to copy them into the build subdirectory

   .. image:: images/HoverAtomText.svg
      :width: 1 pt

   .. image:: images/ToggleAtomText.svg
      :width: 1 pt

   .. image:: images/HoverBondText.svg
      :width: 1 pt

   .. image:: images/ToggleBondText.svg
      :width: 1 pt

See also the following **OEGrapheme TK** APIs that generate interactive
SVG images:

* :oe:func:`OEGrapheme::OERenderContactMap` function that generated an
  interactive protein-ligand contact map image.
  Clicking on any residue will highlight those ligand atoms that are interacting
  with the residue.

.. only:: oehtml

   .. raw:: html

      <p align="center">
      <b>click on any residue circles</b>
      </p>

      <p align="center">
      <object data="../_images/RenderContactMap.svg" type="image/svg+xml"  width = "400" ></object>
      <p>

   .. the above tiny image is necessary to copy it into the build subdirectory

   .. image:: ../graphemetk/images/RenderContactMap.svg
      :width: 1pt

* :oe:func:`OEGrapheme::OEDrawIridiumData` function
* :oe:func:`OEGrapheme::OEDrawPeptide` function
* :oe:func:`OEGrapheme::OERenderRamachandranPlot` function
* :oe:func:`OEGrapheme::OERenderBFactorMap` function

.. _section_svg_insert_html:

Inserting SVG Images into HTML
================================================================================

The interactive :file:`svg` image generated by **OEDepict TK**
and **Grapheme TK** can inserted into HTML files with the SVG MIME type:

.. code-block:: console

   <object data="<imagename>.svg" type="image/svg+xml"></object>

The following example inserts two :file:`svg` images into an HTML table:

.. literalinclude:: images/svg/InsertSVG/insert-index.html
   :emphasize-lines: 16-17

Download the following three files and open the ``insert-index.html`` file
in a browser.

.. only:: oehtml

   .. admonition:: Download code

      :download:`insert-index.html <images/svg/InsertSVG/insert-index.html>`
      :download:`hover-atom-text.svg <images/svg/InsertSVG/hover-atom-text.svg>`
      :download:`toggle-atom-text.svg <images/svg/InsertSVG/toggle-atom-text.svg>`

.. _section_svg_event:

How to Catch SVG Events
================================================================================

The example in this section illustrates how to throw a mouse event in an
:file:`.svg` image and how to catch it in a :file:`html` file.

The code below shows how to create an :file:`.svg` image where each atom is
associated with an SVG event.  When clicking on an atom in the image, a
`click <https://developer.mozilla.org/en-US/docs/Web/Events/click>`_  event is
fired with the message specified in the :oe:func:`OEDepict::OEAddSVGClickEvent`
function.

.. oe:source:: AddAtomClickEvent.cpp
   :language: c++
   :frag:     SNIPPET-ADDATOMCLICKEVENT

.. oe:source:: AddAtomClickEvent.py
   :language: python
   :frag:     SNIPPET-ADDATOMCLICKEVENT

The events thrown by the :file:`AddAtomClickEvent.svg` image can be caught
in the :file:`html` file that contains the image.  The following :file:`html`
file illustrates how to catch the events and display the messages that were
associated with the atoms using the
:oe:func:`OEDepict::OEAddSVGClickEvent` function.

.. literalinclude:: images/svg/AddAtomClickEvent/index.html
   :emphasize-lines: 10-14, 22

To try it out follow the instructions below:

1. Generate a directory (such as ``test``) that contains both the
   :download:`AddAtomClickEvent.svg <images/svg/AddAtomClickEvent/AddAtomClickEvent.svg>`
   and the :download:`index.html <images/svg/AddAtomClickEvent/index.html>`
   file (click on them to download).

2. Start up a HTTP server inside ``test`` directory

   .. code-block:: console

      prompt> python -m http.server


3. Open http://0.0.0.0:8000 in your browser (see image below)

4. Click on any atom on the image and the message specified by the
   :oe:func:`OEDepict::OEAddSVGClickEvent` function will be
   displayed below the image.

.. figure:: images/svg/AddAtomClickEvent/ScreenShot-AddAtomClickEven.png
   :align:  center
   :width: 300 pt

   **Screenshot of the OEAddSVGClickEvent example in the browser**
