.. _chapter_mol_display:

********************************************************************************
Molecule Depiction
********************************************************************************

The previous chapter introduced how to create images and draw basic
geometric elements (such as text, lines rectangles, etc.)
Drawing these basic graphical elements provides a framework to
construct more complex images such as molecular diagrams.

The molecule depiction is divided into two separate steps
(see :ref:`Figure: Process of Molecule Depiction<figure_mol_depiction>` ):

#. Generating 2D coordinates
#. Rendering molecule that involves

   - transforming and scaling coordinates in order to fit the
     molecule into an image with a specific width and height
   - setting atom and bond display properties based on depiction style
   - creating an image (such as drawing lines for bonds, drawing text for
     atomic labels)

.. _figure_mol_depiction:

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

   **Process of molecule depiction**

The next example (:oe:src:`Listing 1<SNIPPET-DEPICT-MOL-SIMPLE-DepictMolSimple>`) demonstrates
how easy is to depict a molecule using the **OEDepict TK**.
After creating a molecule (for example by parsing a SMILES string) the
image can be generated by calling two functions.


#. The :oe:func:`OEDepict::OEPrepareDepiction` function prepares the
   molecule for depiction.  This process may involve perceiving atom
   and bond stereo information and suppressing or adding hydrogens.
   It also calls the :oe:func:`OEDepict::OEDepictCoordinates`
   function to generate the 2D coordinates of the molecule.

#. The :oe:func:`OEDepict::OERenderMolecule` function generates the
   image of the molecule using the default depiction styles and then
   writes the image into the given file.

The image created by :oe:src:`Listing 1<SNIPPET-DEPICT-MOL-SIMPLE-DepictMolSimple>` 
is shown in
:ref:`Figure: Example of depicting a molecule<figure_mol_display_simple>`.

.. oe:source:: DepictMolSimple.py
   :language: python
   :refnum:   1
   :caption:  Example of molecule depiction
   :frag:     SNIPPET-DEPICT-MOL-SIMPLE

.. oe:source:: DepictMolSimple.cpp
   :language: c++
   :refnum:   1
   :caption:  Example of molecule depiction
   :frag:     SNIPPET-DEPICT-MOL-SIMPLE

.. oe:source:: DepictMolSimple.java
   :language: java
   :refnum:   1
   :caption:  Example of molecule depiction
   :frag:     SNIPPET-DEPICT-MOL-SIMPLE

.. oe:source:: DepictMolSimple.cs
   :language: csharp
   :refnum:   1
   :caption:  Example of molecule depiction
   :frag:     SNIPPET-DEPICT-MOL-SIMPLE

.. _figure_mol_display_simple:

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

   **Example of molecule depiction**

.. seealso::

   * :oe:func:`OEDepict::OEPrepareDepiction` function
   * :oe:func:`OEDepict::OERenderMolecule` function


.. _section_mol_display_customize:

Customizing Molecule Depiction
================================================================================

The previous example showed how to generate a molecule diagram with
default parameters.
**OEDepict TK** provides the ability to customize molecule depiction.
The :oe:src:`Listing 2<SNIPPET-DEPICT-MOL-SIZE-DepictMolSize>` example shows how to depict a
molecule width specific width and height parameters.

.. oe:source:: DepictMolSize.py
   :language: python
   :refnum:   2
   :caption:  Example of depicting a molecule
   :frag:     SNIPPET-DEPICT-MOL-SIZE

.. oe:source:: DepictMolSize.cpp
   :language: c++
   :refnum:   2
   :caption:  Example of depicting a molecule
   :frag:     SNIPPET-DEPICT-MOL-SIZE

.. oe:source:: DepictMolSize.java
   :language: java
   :refnum:   2
   :caption:  Example of depicting a molecule
   :frag:     SNIPPET-DEPICT-MOL-SIZE

.. oe:source:: DepictMolSize.cs
   :language: csharp
   :refnum:   2
   :caption:  Example of depicting a molecule
   :frag:     SNIPPET-DEPICT-MOL-SIZE

.. seealso::

   * :ref:`OE2DMolDisplayOptions <OEDepict_OE2DMolDisplayOptions>` class
   * :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` class

Apart from defining the dimensions of a depicted molecule, the
:ref:`OE2DMolDisplayOptions <OEDepict_OE2DMolDisplayOptions>` class stores all properties
that determine how a molecule is depicted.
The following example shows how to set various depiction styles before
initializing the :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object.
The image created by :oe:src:`Listing 3<SNIPPET-DEPICT-MOL-STYLE-DepictMolStyle>` is shown in
:ref:`Figure: Example of customizing depiction style<figure_mol_display_style>`.

.. oe:source:: DepictMolStyle.py
   :language: python
   :refnum:   3
   :caption:  Example of customizing the depiction style
   :frag:     SNIPPET-DEPICT-MOL-STYLE

.. oe:source:: DepictMolStyle.cpp
   :language: c++
   :refnum:   3
   :caption:  Example of customizing the depiction style
   :frag:     SNIPPET-DEPICT-MOL-STYLE

.. oe:source:: DepictMolStyle.java
   :language: java
   :refnum:   3
   :caption:  Example of customizing the depiction style
   :frag:     SNIPPET-DEPICT-MOL-STYLE

.. oe:source:: DepictMolStyle.cs
   :language: csharp
   :refnum:   3
   :caption:  Example of customizing the depiction style
   :frag:     SNIPPET-DEPICT-MOL-STYLE


.. _figure_mol_display_style:

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

   **Example of customizing the depiction style**


Apart from controlling the depiction style through the
:ref:`OE2DMolDisplayOptions <OEDepict_OE2DMolDisplayOptions>` class, **OEDepict TK** also provides
access to manipulate individual atom and bond 2D display properties.
The :oe:meth:`OEDepict::OE2DMolDisplay::GetAtomDisplays` method
returns an iterator over :ref:`OE2DAtomDisplay <OEDepict_OE2DAtomDisplay>` objects
that store atom display information.
Similarly, the :oe:meth:`OEDepict::OE2DMolDisplay::GetBondDisplays` method
returns an iterator over :ref:`OE2DBondDisplay <OEDepict_OE2DBondDisplay>` objects
that store bond display information.

The following example demonstrates how to change atom and bond display
properties and depict the graph of the molecule by ignoring atom
labels and setting bond display styles.
The image created by :oe:src:`Listing 4<SNIPPET-DEPICT-MOL-GRAPH-DepictMolGraph>` is shown in
:ref:`Figure:  Example of molecule graph depiction<figure_mol_display_graph>`.

.. oe:source:: DepictMolGraph.py
   :language: python
   :refnum:   4
   :caption:  Example of molecule graph depiction
   :frag:     SNIPPET-DEPICT-MOL-GRAPH

.. oe:source:: DepictMolGraph.cpp
   :language: c++
   :refnum:   4
   :caption:  Example of molecule graph depiction
   :frag:     SNIPPET-DEPICT-MOL-GRAPH

.. oe:source:: DepictMolGraph.java
   :language: java
   :refnum:   4
   :caption:  Example of molecule graph depiction
   :frag:     SNIPPET-DEPICT-MOL-GRAPH

.. oe:source:: DepictMolGraph.cs
   :language: csharp
   :refnum:   4
   :caption:  Example of molecule graph depiction
   :frag:     SNIPPET-DEPICT-MOL-GRAPH

.. _figure_mol_display_graph:

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

   **Example of molecule graph depiction**

.. hint::

   Even though **OEDepict TK** provides the ability to manipulate
   atom and bond display properties of after the
   :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object is constructed,
   it is highly recommended to set the depiction properties using
   the :ref:`OE2DMolDisplayOptions <OEDepict_OE2DMolDisplayOptions>` class.
   Only by knowing all properties (such as labels, font styles and sizes *etc.*)
   in advance can one ensure the **best depiction layout** *i.e.* that
   the molecule diagram is rendered without any label clippings
   and the labels are displayed with the minimum number of overlaps.

.. seealso::

   * :ref:`OE2DAtomDisplay <OEDepict_OE2DAtomDisplay>` class
   * :ref:`OE2DBondDisplay <OEDepict_OE2DBondDisplay>` class

.. _section_mol_display_size:

Controlling the Size of Depicted Molecules
================================================================================

The dimensions of a depicted molecule are controlled by the width,
height and scale parameters of the :ref:`OE2DMolDisplayOptions <OEDepict_OE2DMolDisplayOptions>`
that is used to initialized the :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object.
(See example in :oe:src:`Listing 2<SNIPPET-DEPICT-MOL-SIZE-DepictMolSize>`)

.. seealso::

   * :oe:meth:`OEDepict::OE2DMolDisplayOptions::SetDimensions` method
   * :oe:meth:`OEDepict::OE2DMolDisplayOptions::SetHeight` method
   * :oe:meth:`OEDepict::OE2DMolDisplayOptions::SetScale` method
   * :oe:meth:`OEDepict::OE2DMolDisplayOptions::SetWidth` method


If the width and the height of the image is not specified (set to be
zero), then scaling value determine the dimensions of the image.
(See examples in :ref:`Examples of image scaling<table_moldisplay_size_scale>`).
The default scale is defined to be :oe:const:`OEDepict::OEScale::Default`
constant, and the image may be enlarged or shrunk by specifying a
floating point scaling value.
For example, the scaling :oe:const:`OEDepict::OEScale::Default` *
``0.5`` generates an image a half of the default size, and scaling
:oe:const:`OEDepict::OEScale::Default` * ``1.5`` generates an image one
and a half times the default.

.. _table_moldisplay_size_scale:

.. list-table:: **Examples of image scaling** *(width = 0.0, height = 0.0)*
   :widths: 250 250 250
   :header-rows: 1

   * - OEScale::Default * 0.5
     - OEScale::Default
     - OEScale::Default * 1.5
   * - .. image:: images/DepictMol-Size-0-0-Half.*
          :align:  center
     - .. image:: images/DepictMol-Size-0-0-Default.*
          :align:  center
     - .. image:: images/DepictMol-Size-0-0-OneAndHalf.*
          :align:  center

If an :ref:`OE2DMolDisplayOptions <OEDepict_OE2DMolDisplayOptions>` object is initialized with
zero width and / or height, then the real dimensions of the image can be
accessed after creating an :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object.

.. oe:source:: DepictMolRealSize.py
   :language: python
   :noindent:
   :frag:     SNIPPET-MOL-DISPLAY-DIMENSIONS

.. oe:source:: DepictMolRealSize.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-MOL-DISPLAY-DIMENSIONS

.. oe:source:: DepictMolRealSize.java
   :language: java
   :noindent:
   :frag:     SNIPPET-MOL-DISPLAY-DIMENSIONS

.. oe:source:: DepictMolRealSize.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-MOL-DISPLAY-DIMENSIONS


The output of the preceding snippet is the following:

.. code-block:: console

   width  137.0
   height 181.0
   scale  50.0

.. seealso::

  :oe:meth:`OEDepict::OE2DMolDisplay::GetHeight` method
  :oe:meth:`OEDepict::OE2DMolDisplay::GetWidth` method
  :oe:meth:`OEDepict::OE2DMolDisplay::GetScale` method


If both the width and the height of are specified, then
:oe:const:`OEDepict::OEScale::AutoScale` scaling indicates
that the molecule is scaled to maximally fit the given dimensions.
The specified width and height will not be altered, not even if the
given scaling would require it *i.e* if necessary the scaling will be
reduced in order to fit the molecule into the given dimension.
(See examples in :ref:`Examples of image scaling<table_moldisplay_size_fixed>`).

.. _table_moldisplay_size_fixed:

.. list-table:: **Examples of fixed sized image** *(width = 120.0, height = 120.0)*
   :widths: 250 250 250
   :header-rows: 1

   * - OEScale::Default * 0.5
     - OEScale::Default
     - OEScale::Default * 1.5
   * - .. image:: images/DepictMol-Size-120-120-Half.*
          :align:  center
     - .. image:: images/DepictMol-Size-120-120-Default.*
          :align:  center
     - .. image:: images/DepictMol-Size-120-120-OneAndHalf.*
          :align:  center

.. note::

   Specifying a width and / or height larger than what is required by the
   scale, causes the molecule to float in the middle of the image of
   the requested size.


If only either the width or the height of the image is specified, then
the unspecified dimension will be set based on the scaling and the
specified width / height, respectively.

.. list-table::
   :widths: 250 250
   :header-rows: 1

   * - OEScale::Default, width = 250.0, height = 0.0
     - OEScale::Default, width = 0.0, height = 250.0
   * - .. image:: images/DepictMol-Size-250-0-Default.*
          :align:  center
     - .. image:: images/DepictMol-Size-0-250-Default.*
          :align:  center

.. _section_mol_display_transparent:

Molecule Depiction with Transparent Background
================================================================================

.. meta:
   :keywords: transparent

The following code snippet shows how to generate a molecule depiction with transparent
background.
First, the :ref:`OEImage <OEDepict_OEImage>` object, onto which the depiction is going to be rendered,
has to be constructed with the :oe:const:`OETransparentColor<OESystem::OESystem::OETransparentColor>`
color.
Then the :oe:func:`OEDepict::OERenderMolecule` function has to be called with a
parameter that ensures that the background in not cleared prior to rendering the molecule.

.. oe:source:: DepictMolTransparent.py
   :language: python
   :noindent:
   :frag:     SNIPPET-DEPICT-MOL-TRANSPARENT

.. oe:source:: DepictMolTransparent.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-DEPICT-MOL-TRANSPARENT

.. oe:source:: DepictMolTransparent.java
   :language: java
   :noindent:
   :frag:     SNIPPET-DEPICT-MOL-TRANSPARENT

.. oe:source:: DepictMolTransparent.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-DEPICT-MOL-TRANSPARENT

.. note:

   The **OEDepict TK** supports transparent background for :file:`png`, :file:`svg` and
   :file:`pdf` image files.

.. _section_mol_display_atom_prop:

Displaying Atom Properties
================================================================================

**OEDepict TK** provides ability the display atom properties as strings.
When a :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object is created, the
positions where atom properties can be displayed are calculated.
(see :ref:`Figure: Example of generating atom property positions<figure_mol_display_atom_prop>`.)

.. _figure_mol_display_atom_prop:

.. figure:: images/OE2DAtomDisplay-GetPropertyOffset.*
   :align:  center

   **Example of generating atom property positions**

The following  example shows how to display the atom indices
by using the :ref:`OEDisplayAtomIdx <OEDepict_OEDisplayAtomIdx>` functor.
The font used to depict the atom property strings also can be
modified by using the
:oe:meth:`OEDepict::OE2DMolDisplayOptions::SetAtomPropLabelFont`
method.
The image created by :oe:src:`Listing 5<SNIPPET-ATOM-PROP-INDEX-AtomPropIndex>` is shown in
:ref:`Figure: Example of displaying atom indices<figure_mol_display_atom_prop_idx>`.

.. oe:source:: AtomPropIndex.py
   :language: python
   :refnum:   5
   :caption:  Example of depicting atom indices
   :frag:     SNIPPET-ATOM-PROP-INDEX

.. oe:source:: AtomPropIndex.cpp
   :language: c++
   :refnum:   5
   :caption:  Example of depicting atom indices
   :frag:     SNIPPET-ATOM-PROP-INDEX

.. oe:source:: AtomPropIndex.java
   :language: java
   :refnum:   5
   :caption:  Example of depicting atom indices
   :frag:     SNIPPET-ATOM-PROP-INDEX

.. oe:source:: AtomPropIndex.cs
   :language: csharp
   :refnum:   5
   :caption:  Example of depicting atom indices
   :frag:     SNIPPET-ATOM-PROP-INDEX

.. _figure_mol_display_atom_prop_idx:

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

   **Example of displaying atom indices**

.. hint::

   It is recommended to use the :oe:meth:`OEDepict::OE2DMolDisplayOptions::SetAtomPropertyFunctor`
   method to define the atom property labels when the :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>`
   object is constructed.
   All labels displayed on the molecule diagram have to be known in advance in order to be
   able to minimize the number of label clashes and clippings when calculating
   the positions of the atom property labels.

.. seealso::

   **OEDepict TK** provides the following built-in atom property functors:

   * :ref:`OEDisplayAtomIdx <OEDepict_OEDisplayAtomIdx>` class
   * :ref:`OEDisplayAtomMapIdx <OEDepict_OEDisplayAtomMapIdx>` class
   * :ref:`OEDisplayNoAtomProp <OEDepict_OEDisplayNoAtomProp>` class


In order to display user-defined atom properties, the functor that is
passed to the
:oe:meth:`OEDepict::OE2DMolDisplayOptions::SetAtomPropertyFunctor`
method has to be derived from the :ref:`OEDisplayAtomPropBase <OEDepict_OEDisplayAtomPropBase>`
abstract base class.
The :oe:src:`Listing 6<SNIPPET-ATOM-PROP-USER-AtomPropUser>` example shows 
how to implement a user-defined functor that marks aromatic atoms.
The image created by :oe:src:`Listing 6<SNIPPET-ATOM-PROP-USER-AtomPropUser>` is shown in
:ref:`Figure: Example of displaying user-defined atom properties<figure_mol_display_atom_prop_user>`.

.. oe:source:: AtomPropUser.py
   :language: python
   :refnum:   6
   :caption:  Example of depicting user-defined atom properties
   :frag:     SNIPPET-ATOM-PROP-USER

.. oe:source:: AtomPropUser.cpp
   :language: c++
   :refnum:   6
   :caption:  Example of depicting user-defined atom properties
   :frag:     SNIPPET-ATOM-PROP-USER

.. oe:source:: AtomPropUser.java
   :language: java
   :refnum:   6
   :caption:  Example of depicting user-defined atom properties
   :frag:     SNIPPET-ATOM-PROP-USER

.. oe:source:: AtomPropUser.cs
   :language: csharp
   :refnum:   6
   :caption:  Example of depicting user-defined atom properties
   :frag:     SNIPPET-ATOM-PROP-USER

.. _figure_mol_display_atom_prop_user:

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

   **Example of displaying user-defined atom properties**

.. seealso::

   * :ref:`OEDisplayAtomPropBase <OEDepict_OEDisplayAtomPropBase>` class

.. _section_mol_display_bond_prop:

Displaying Bond Properties
================================================================================

Similarly to atom properties, bond properties can be
displayed as strings.
(see :ref:`Figure: Example of generating bond property positions<figure_mol_display_bond_prop>`.)

.. _figure_mol_display_bond_prop:

.. figure:: images/OE2DBondDisplay-GetPropertyOffset.*
   :align:  center

   **Example of generating bond property positions**

The :oe:src:`Listing 7<SNIPPET-BOND-PROP-INDEX-BondPropIndex>` demonstrates how to 
display bond indices by using the :ref:`OEDisplayBondIdx <OEDepict_OEDisplayBondIdx>` functor.
The font used to depict the bond property strings can be
set by using the :oe:meth:`OEDepict::OE2DMolDisplayOptions::SetBondPropLabelFont`
method.
The image created by :oe:src:`Listing 7<SNIPPET-BOND-PROP-INDEX-BondPropIndex>` is shown in
:ref:`Figure: Example of displaying bond indices<figure_mol_display_bond_prop_idx>`.

.. oe:source:: BondPropIndex.py
   :language: python
   :refnum:   7
   :caption:  Example of depicting bond indices
   :frag:     SNIPPET-BOND-PROP-INDEX

.. oe:source:: BondPropIndex.cpp
   :language: c++
   :refnum:   7
   :caption:  Example of depicting bond indices
   :frag:     SNIPPET-BOND-PROP-INDEX

.. oe:source:: BondPropIndex.java
   :language: java
   :refnum:   7
   :caption:  Example of depicting bond indices
   :frag:     SNIPPET-BOND-PROP-INDEX

.. oe:source:: BondPropIndex.cs
   :language: csharp
   :refnum:   7
   :caption:  Example of depicting bond indices
   :frag:     SNIPPET-BOND-PROP-INDEX

.. _figure_mol_display_bond_prop_idx:

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

   **Example of displaying bond indices**

.. hint::

   It is recommended to use the :oe:meth:`OEDepict::OE2DMolDisplayOptions::SetBondPropertyFunctor`
   method to define the bond property labels when the :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>`
   object is constructed.
   All labels displayed on the molecule diagram have to be known in advance in order to be
   able to minimize the number of label clashes and clippings when calculating
   the positions of the bond property labels.

.. seealso::

   **OEDepict TK** provides the following built-in bond property functors:

   * :ref:`OEDisplayBondIdx <OEDepict_OEDisplayBondIdx>` class
   * :ref:`OEDisplayNoBondProp <OEDepict_OEDisplayNoBondProp>` class


In order to display user-defined bond properties, the functor that is
passed to the
:oe:meth:`OEDepict::OE2DMolDisplayOptions::SetBondPropertyFunctor`
method has to be derived from the :ref:`OEDisplayBondPropBase <OEDepict_OEDisplayBondPropBase>`
abstract base class.
The :oe:src:`Listing 8<SNIPPET-BOND-PROP-USER-BondPropUser>` example shows how to implement a
user-defined functor that marks chain and ring bonds.
The image created by :oe:src:`Listing 8<SNIPPET-BOND-PROP-USER-BondPropUser>` is shown in
:ref:`Figure: Example of displaying user-defined bond properties<figure_mol_display_bond_prop_user>`.

.. oe:source:: BondPropUser.py
   :language: python
   :refnum:   8
   :caption:  Example of depicting user-defined bond properties
   :frag:     SNIPPET-BOND-PROP-USER

.. oe:source:: BondPropUser.cpp
   :language: c++
   :refnum:   8
   :caption:  Example of depicting user-defined bond properties
   :frag:     SNIPPET-BOND-PROP-USER

.. oe:source:: BondPropUser.java
   :language: java
   :refnum:   8
   :caption:  Example of depicting user-defined bond properties
   :frag:     SNIPPET-BOND-PROP-USER

.. oe:source:: BondPropUser.cs
   :language: csharp
   :refnum:   8
   :caption:  Example of depicting user-defined bond properties
   :frag:     SNIPPET-BOND-PROP-USER

.. _figure_mol_display_bond_prop_user:

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

   **Example of displaying user-defined bond properties**

.. seealso::

   * :ref:`OEDisplayBondPropBase <OEDepict_OEDisplayBondPropBase>` class

Hiding Atoms and Bonds
================================================================================

**OEDepict TK** provides ability the suppress the display of specific atom and bonds.
When a :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object is created, the
visibility of every atom is evaluated.  Bonds with both atom endpoints visible are also displayed.
(see :ref:`Figure: Example of hiding a portion of a structure<figure_rxn_display_hidden>`.)

The following  example shows how to selectively display only
a portion of the structure by using a custom class derived from
the :oe:cls:`OEUnaryAtomPred<OESystem::OEUnaryPredicate>` functor.
The images created by :oe:src:`Listing 9<SNIPPET-ATOM-VISIBILITY-AtomVisibility>` is shown in
:ref:`Figure: Example of hiding a portion of a structure<figure_rxn_display_hidden>`.

.. hint::

   It is recommended to use the :oe:meth:`OEDepict::OE2DMolDisplayOptions::SetAtomVisibilityFunctor`
   method to identify the visible atoms when the :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>`
   object is constructed. All objects displayed on the molecule diagram have to be known in advance in order to be
   able to correctly size and scale the molecule.

.. oe:source:: AtomVisibility.py
   :language: python
   :refnum:   9
   :caption:  Example of selectively displaying atoms
   :frag:     SNIPPET-ATOM-VISIBILITY

.. oe:source:: AtomVisibility.cpp
   :language: c++
   :refnum:   9
   :caption:  Example of selectively displaying atoms
   :frag:     SNIPPET-ATOM-VISIBILITY

.. oe:source:: AtomVisibility.java
   :language: java
   :refnum:   9
   :caption:  Example of selectively displaying atoms
   :frag:     SNIPPET-ATOM-VISIBILITY

.. oe:source:: AtomVisibility.cs
   :language: csharp
   :refnum:   9
   :caption:  Example of selectively displaying atoms
   :frag:     SNIPPET-ATOM-VISIBILITY

.. _figure_rxn_display_hidden:

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

   **Example of hiding a portion of a structure**

Configuring Molecule Display
================================================================================

**OEDepict TK** provides a mechanism to generate a standard interface that
allows configuration of molecule displays.
By calling the :oe:func:`OEDepict::OEConfigureImageOptions` function,
"-height" and "width" parameters are added to the interface
(:ref:`OEInterface <OESystem_OEInterface>`), at run-time the value of these
parameters can be obtained by calling the
:oe:func:`OEDepict::OEGetImageHeight` and
:oe:func:`OEDepict::OEGetImageWidth` functions, respectively.
(See the standard interface displayed when calling  the 
:oe:src:`Listing 10<SNIPPET-MOL-CONFIGURE-DepictMolConfigure>` example
with the "--help" parameter)

The :oe:func:`OEDepict::OEConfigure2DMolDisplayOptions` function
generates an interface that allows setting of various molecule display
options (such as aromatic style, atom and bond coloring etc.)
The :ref:`OE2DMolDisplayOptions <OEDepict_OE2DMolDisplayOptions>` object, that stores
properties determine the molecule depiction style, can initialized
based on to the command line parameters by calling the
:oe:func:`OEDepict::OESetup2DMolDisplayOptions` function.

.. oe:source:: DepictMolConfigure.py
   :language: python
   :refnum:   10
   :caption:  Example of configuring mol display
   :frag:     SNIPPET-MOL-CONFIGURE

.. oe:source:: DepictMolConfigure.cpp
   :language: c++
   :refnum:   10
   :caption:  Example of configuring mol display
   :frag:     SNIPPET-MOL-CONFIGURE

.. oe:source:: DepictMolConfigure.java
   :language: java
   :refnum:   10
   :caption:  Example of configuring mol display
   :frag:     SNIPPET-MOL-CONFIGURE

.. oe:source:: DepictMolConfigure.cs
   :language: csharp
   :refnum:   10
   :caption:  Example of configuring mol display
   :frag:     SNIPPET-MOL-CONFIGURE

.. oe:language:: c++

   .. code-block:: bash

      prompt> DepictMolConfigure --help

.. oe:language:: python

   .. code-block:: bash

      prompt> python DepictMolConfigure.py --help

.. oe:language:: java

   .. code-block:: bash

      prompt> java DepictMolConfigure --help

.. oe:language:: csharp

   .. code-block:: bash

      prompt> DepictMolConfigure --help

will generate the following standard interface:

.. code-block:: console

   Simple parameter list
       image options
         -height : Height of output image
         -width : Width of output image

       input/output
         -in : Input filename
         -out : Output filename

       molecule display options
         -aromstyle : Aromatic ring display style
         -atomcolor : Atom coloring style
         -atomprop : Atom property display
         -atomstereostyle : Atom stereo display style
         -bondcolor : Bond coloring style
         -bondprop : Bond property display
         -bondstereostyle : Bond stereo display style
         -hydrstyle : Hydrogen display style
         -linewidth : Default bond line width
         -protgroupdisp : Protective group display style
         -scale : Scaling of the depicted molecule
         -superdisp : Super atom display style
         -titleloc : Location of the molecule title

.. seealso::

   * :ref:`OEInterface <OESystem_OEInterface>` class in the **OEChem TK** manual
   * :ref:`oedepict_chapter_examples_summary` chapter


**OEDepict TK** provides the following high-level functions to build
standard interface of depiction applications:

.. list-table::
   :widths: 250 250
   :header-rows: 1

   * - Function name
     - Builds standard interface for ..

   * - :oe:func:`OEDepict::OEConfigure2DMolDisplayOptions`
     - molecule depiction style

   * - :oe:func:`OEDepict::OEConfigureHighlightParams`
     - highlighting

   * - :oe:func:`OEDepict::OEConfigureImageGridParams`
     - image grid

   * - :oe:func:`OEDepict::OEConfigureImageOptions`
     - image

   * - :oe:func:`OEDepict::OEConfigureMultiPageParams`
     - multi-page image

   * - :oe:func:`OEDepict::OEConfigurePrepareDepictionOptions`
     - preparing molecules for 2D depiction

   * - :oe:func:`OEDepict::OEConfigureReportOptions`
     -  multi-page report
