.. include:: ../../toolkit-substitutions
.. include:: ../substitutions

.. oe:namespace:: OEDepict

.. meta::
   :keywords: OEAddLabel

.. _OEDepict_OEAddLabel:


.. oe:function:: OEAddLabel


   Adds label to an image or molecule display.

   .. list-table:: **The overloaded versions of the OEAddLabel function**
      :widths: 100 200
      :header-rows: 1

      * - Link
        - Description

      * - :ref:`OEAddLabel(image, position, label)<api_OEAddLabel_OEImageBase_OE2DPoint_OEHighlightLabel>`
        - adding label to an image

      * - :ref:`OEAddLabel(disp, label, match)<api_OEAddLabel_OE2DMolDisplay_OEHighlightLabel_OEMatchBase>`
        - adding label to atoms of a match

      * - :ref:`OEAddLabel(disp, label, abset)<api_OEAddLabel_OE2DMolDisplay_OEHighlightLabel_OEAtomBondSet>`
        - adding label to set of atoms

      * - :ref:`OEAddLabel(disp, label, atompred)<api_OEAddLabel_OE2DMolDisplay_OEHighlightLabel_AtomPredicate>`
        - adding label to atoms specified by a predicate

   .. note::

      When adding label associated with atoms it is recommended to use the
      :oe:func:`OEDepict::OEAddLabel` along with the :oe:func:`OEDepict::OEAddHighlighting`
      function for visual clarity.

   .. _api_OEAddLabel_OEImageBase_OE2DPoint_OEHighlightLabel:

   .. oe:language:: c++ java csharp

      .. oe:api::

         void OEAddLabel(OEImageBase& image, const OE2DPoint& center,
                         const OEHighlightLabel& label)

   .. oe:language:: python

      .. oe:api:: python

         OEAddLabel(image: OEImageBase, center: OE2DPoint,
                    label: OEHighlightLabel) -> None

   *image*
      The image in which the label is drawn.

   *center*
      The center of the label on the image.

   *label*
      The :ref:`OEHighlightLabel <OEDepict_OEHighlightLabel>` object that stores properties that
      determine the styles of the label along with the text of the label itself.

   **Example:**

   .. oe:source:: OEAddLabel.py
      :language: python
      :noindent:
      :frag:     SNIPPET-OEADDLABEL-TO-IMAGE

   .. oe:source:: OEAddLabel.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-OEADDLABEL-TO-IMAGE

   .. oe:source:: OEAddLabel.java
      :language: java
      :noindent:
      :frag:     SNIPPET-OEADDLABEL-TO-IMAGE

   .. oe:source:: OEAddLabel.cs
      :language: csharp
      :noindent:
      :frag:     SNIPPET-OEADDLABEL-TO-IMAGE

   .. _figure_OEAddLabel_OEImageBase:

   .. figure:: ../images/OEAddLabel-OEImageBase.*
      :align:  center

      **Example of adding labels to an image**

   .. _api_OEAddLabel_OE2DMolDisplay_OEHighlightLabel_OEMatchBase:

   .. oe:language:: c++ java csharp

      .. oe:api::

         void OEAddLabel(OE2DMolDisplay& disp, const OEHighlightLabel& label,
                         const OEChem::OEMatchBase& match)

   .. oe:language:: python

      .. oe:api:: python

         OEAddLabel(disp: OE2DMolDisplay, label: OEHighlightLabel,
                    match: OEMatchBase) -> None

   Adds label to atoms of an :ref:`OEMatchBase <OEChem_OEMatchBase>` object that can be
   initialized by substructure search or maximum common substructure search.

   *disp*
      The :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object on which the label is going to
      be positioned.

   *label*
      The :ref:`OEHighlightLabel <OEDepict_OEHighlightLabel>` object that stores properties that
      determine the styles of the label along with the text of the label itself.

   *match*
      The label is positioned  based on the target atoms of the
      :ref:`OEMatchBase <OEChem_OEMatchBase>` object.

   **Example:**

   .. oe:source:: OEAddLabel.py
      :language: python
      :noindent:
      :frag:     SNIPPET-OEADDLABEL-OEMATCH

   .. oe:source:: OEAddLabel.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-OEADDLABEL-OEMATCH

   .. oe:source:: OEAddLabel.java
      :language: java
      :noindent:
      :frag:     SNIPPET-OEADDLABEL-OEMATCH

   .. oe:source:: OEAddLabel.cs
      :language: csharp
      :noindent:
      :frag:     SNIPPET-OEADDLABEL-OEMATCH

   .. _figure_OEAddLabel_OEMatchBase:

   .. figure:: ../images/OEAddLabel-OEMatch.*
      :align:  center

      **Example of adding label to 6-membered aromatic ring**

   .. _api_OEAddLabel_OE2DMolDisplay_OEHighlightLabel_OEAtomBondSet:

   .. oe:language:: c++ java csharp

      .. oe:api::

         void OEAddLabel(OE2DMolDisplay& disp, const OEHighlightLabel& label,
                         const OEChem::OEAtomBondSet& abset)

   .. oe:language:: python

      .. oe:api:: python

         OEAddLabel(disp: OE2DMolDisplay, label: OEHighlightLabel,
                    abset: OEAtomBondSet) -> None

   Adds label to atoms stored in the :ref:`OEAtomBondSet <OEChem_OEAtomBondSet>` object.

   *disp*
      The :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object on which the label is going to
      be positioned.

   *label*
      The :ref:`OEHighlightLabel <OEDepict_OEHighlightLabel>` object that stores properties that
      determine the styles of the label along with the text of the label itself.

   *abset*
      The label is positioned based on the atoms stored in the
      :ref:`OEAtomBondSet <OEChem_OEAtomBondSet>` object.

   **Example:**

   .. oe:source:: OEAddLabel.py
      :language: python
      :noindent:
      :frag:     SNIPPET-OEADDLABEL-OEATOMBONDSET

   .. oe:source:: OEAddLabel.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-OEADDLABEL-OEATOMBONDSET

   .. oe:source:: OEAddLabel.java
      :language: java
      :noindent:
      :frag:     SNIPPET-OEADDLABEL-OEATOMBONDSET

   .. oe:source:: OEAddLabel.cs
      :language: csharp
      :noindent:
      :frag:     SNIPPET-OEADDLABEL-OEATOMBONDSET

   .. _figure_OEAddLabel_OEAtomBondSet:

   .. figure:: ../images/OEAddLabel-OEAtomBondSet.*
      :align:  center

      **Example of adding label to ring and chain components of a molecule**

   .. _api_OEAddLabel_OE2DMolDisplay_OEHighlightLabel_AtomPredicate:

   .. oe:language:: c++ java csharp

      .. oe:api::

         void OEAddLabel(OE2DMolDisplay& disp, const OEHighlightLabel& label,
                         const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>& atompred)

   .. oe:language:: python

      .. oe:api:: python

         OEAddLabel(disp: OE2DMolDisplay, label: OEHighlightLabel,
                    atompred: OEUnaryAtomPred) -> None

   Adds label to atoms for which the given atom predicate returns `true`.

   *disp*
      The :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object on which the label is going to
      be positioned.

   *label*
      The :ref:`OEHighlightLabel <OEDepict_OEHighlightLabel>` object that stores properties that
      determine the styles of the label along with the text of the label itself.

   *atompred*
      The label is positioned based on the atoms for which the given
      atom predicate returns `true`.

   **Example:**

   .. oe:source:: OEAddLabel.py
      :language: python
      :noindent:
      :frag:     SNIPPET-OEADDLABEL-PREDICATE

   .. oe:source:: OEAddLabel.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-OEADDLABEL-PREDICATE

   .. oe:source:: OEAddLabel.java
      :language: java
      :noindent:
      :frag:     SNIPPET-OEADDLABEL-PREDICATE

   .. oe:source:: OEAddLabel.cs
      :language: csharp
      :noindent:
      :frag:     SNIPPET-OEADDLABEL-PREDICATE

   .. _figure_OEAddLabel_AtomPredicate:

   .. figure:: ../images/OEAddLabel-Predicate.*
      :align:  center

      **Example of adding label to ring and chain components of a molecule**
