.. _chapter_2D_coordinates:

********************************************************************************
2D Coordinate Generation
********************************************************************************

The :oe:func:`OEChem::OEGenerate2DCoordinates` function **OEChem
TK**'s depiction algorithm is capable of assigning 2D coordinates to
molecules and reactions.  See :ref:`Figure: Schematic representation
of the steps of the 2D coordinate generation
<figure_2D_coordinates_generation>`. The algorithm uses a
**built-in** ring template dictionary to provide aesthetically
pleasing 2D layouts for complex macro-cycles.  In case when no
built-in template exists, the 2D coordinates of the ring system are
generated on-the-fly.  After laying out the ring system(s), the
algorithm assigns coordinates for acyclic chains and functional
groups.  In the last step, the algorithm attempts to resolve atom
clashes using a variety of heuristics.

.. _figure_2D_coordinates_generation:

.. figure:: images/2DCoordinateGgenerationSteps.*
   :align:  center

   **Schematic representation of the steps of the 2D coordinate generation in OEChem TK**

This built-in dictionary currently contains about 3000 ring-systems
that frequently occur in drug-like databases. New ring templates are
continuously being added with each release.

.. note::

   To improve the depiction of the ring systems, please run the
   :ref:`section_example_oechem_extractringtemplates`
   script on a 2D molecule file and send the results to
   support@eyesopen.com. **OpenEye** will be happy to incorporate the
   new ring systems in the **built-in**  dictionary in the next
   release of the toolkits.

.. note::

   :oe:func:`OEChem::OEGenerate2DCoordinates` is a **low-level** function that only
   assigns 2D coordinates to the given molecule.
   It is highly recommended to use the :oe:func:`OEDepict::OEPrepareDepiction`
   function of **OEDepict TK** when generating 2D coordinates for molecular depiction.
   The :oe:func:`OEDepict::OEPrepareDepiction` function, apart from assigning 2D
   coordinates also does the following:

   - suppresses or adds explicit hydrogens
   - perceives atom and bond stereo information
   - optimizes the 2D coordinates for horizontal or vertical rendering

.. _user-defined-ring-dictionary:

User-Defined Ring Dictionary
================================================================================


**OEChem TK** also allows the customization of the 2D coordinate
generation process by providing functionality to extract ring
templates from 2D molecule files, build user-defined ring
dictionaries, and then plug them into the 2D coordinate generation
engine.

The following are the steps to define your own ring dictionaries:

#. Building a ring dictionary from scratch

   .. seealso::

      Example code : :ref:`section_example_oechem_createringdict`

#. Adding new ring templates to an existing ring dictionary

   .. seealso::

      Example code : :ref:`section_example_oechem_appendringdict`

#. Generating 2D coordinates with custom ring templates

   .. seealso::

      Example code : :ref:`section_example_oechem_generate2D`


.. seealso::

   * :ref:`OE2DRingDictionary <OEChem_OE2DRingDictionary>` class
   * :ref:`OE2DRingDictionaryCreatorOptions <OEChem_OE2DRingDictionaryCreatorOptions>` class
   * :oe:func:`OEChem::OEInit2DRingDictionary` function
   * :oe:func:`OEChem::OEIsValid2DRingDictionary` function
   * :oe:func:`OEChem::OEWrite2DRingDictionary` function
