.. _chapter_image_layout:

********************************************************************************
Molecule Layouts
********************************************************************************

The previous chapters described how to depict a single molecule in an image.
This chapter provides examples for drawing multiple molecular diagrams into the
same image.

.. _section_image_layout_frame:

Depicting Molecules in an Arbitrary Position
================================================================================

The :ref:`OEImageFrame <OEDepict_OEImageFrame>` class provides a general framework to
display a molecule in a specific region of the image by defining the following
parameters:

* the reference of the `parent` image
* the width and height of the generated `frame`
* the offset of the `frame` relative to the top-left corner of its
  `parent` (:ref:`OE2DPoint <OEDepict_OE2DPoint>`)

The :oe:src:`Listing 1<SNIPPET-IMAGE-FRAME-ImageFrame>` examples generates an image where the same
molecule is depicted in different regions of the image.
The molecular diagrams are automatically resized in order to fit into
the specific frame, since the corresponding
:ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object is constructed with the width
and height of the :ref:`OEImageFrame <OEDepict_OEImageFrame>` object.
When the :oe:func:`OEDepict::OERenderMolecule` function is called, the
offset of the :ref:`OEImageFrame <OEDepict_OEImageFrame>` object is added to the
coordinates stored in :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` in order to
transfer the molecule into the specific region of the image.
The image created by :oe:src:`Listing 1<SNIPPET-IMAGE-FRAME-ImageFrame>` is shown in
:ref:`Figure: Example of using OEImageFrame<figure_image_frame>`.

.. oe:source:: ImageFrame.py
   :language: python
   :refnum:   1
   :caption:  Example of using OEImageFrame
   :frag:     SNIPPET-IMAGE-FRAME

.. oe:source:: ImageFrame.cpp
   :language: c++
   :refnum:   1
   :caption:  Example of using OEImageFrame
   :frag:     SNIPPET-IMAGE-FRAME

.. oe:source:: ImageFrame.java
   :language: java
   :refnum:   1
   :caption:  Example of using OEImageFrame
   :frag:     SNIPPET-IMAGE-FRAME

.. oe:source:: ImageFrame.cs
   :language: csharp
   :refnum:   1
   :caption:  Example of using OEImageFrame
   :frag:     SNIPPET-IMAGE-FRAME

.. _figure_image_frame:

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

   **Example of using OEImageFrame**

.. seealso::

   * :ref:`OEImageFrame <OEDepict_OEImageFrame>` class
   * :oe:func:`OEDepict::OEDrawBorder` function
   * :oe:func:`OEDepict::OERenderMolecule` function
   * :oe:func:`OEDepict::OEWriteImage` function

.. _section_image_layout_grid:

Depicting Molecules in a Grid
================================================================================

The :ref:`OEImageGrid <OEDepict_OEImageGrid>` class allows molecules to be aligned into
rows and columns.
After generating an :ref:`OEImageGrid <OEDepict_OEImageGrid>` object by specifying its number
of rows and columns, the cells of the grid can be accessed (from left to right, top
to bottom order) by calling the :oe:meth:`OEDepict::OEImageGrid::GetCells` method.
The image created by :oe:src:`Listing 2<SNIPPET-IMAGE-GRID-SIMPLE-ImageGridSimple>` is shown in
:ref:`Figure: Example of using OEImageGrid<figure_image_grid_simple>`.

.. oe:source:: ImageGridSimple.py
   :language: python
   :refnum:   2
   :caption:  Example of using OEImageGrid
   :frag:     SNIPPET-IMAGE-GRID-SIMPLE

.. oe:source:: ImageGridSimple.cpp
   :language: c++
   :refnum:   2
   :caption:  Example of using OEImageGrid
   :frag:     SNIPPET-IMAGE-GRID-SIMPLE

.. oe:source:: ImageGridSimple.java
   :language: java
   :refnum:   2
   :caption:  Example of using OEImageGrid
   :frag:     SNIPPET-IMAGE-GRID-SIMPLE

.. oe:source:: ImageGridSimple.cs
   :language: csharp
   :refnum:   2
   :caption:  Example of using OEImageGrid
   :frag:     SNIPPET-IMAGE-GRID-SIMPLE

.. _figure_image_grid_simple:

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

   **Example of using OEImageGrid**

.. seealso::

   * :ref:`OEImageGrid <OEDepict_OEImageGrid>` class

.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   %
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

When an :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object is initialized, the
dimensions of the depicted molecule is controlled by the width, height
and scale parameters of the :ref:`OE2DMolDisplayOptions <OEDepict_OE2DMolDisplayOptions>`
object.

When only one molecule is depicted then auto scaling of this molecule is preferred
(i.e. scaling the molecule in order to maximally fit it to the given dimensions).
However, when more that one molecule, that are quite different in
sizes, are depicted next to each other, auto scaling of each molecule can be
visually misleading because it emphasizes molecules with greater scaling factors.
See example in :ref:`Figure: Example of using OEImageGrid<figure_image_grid_auto_scale>`
that is generated by :oe:src:`Listing 3<SNIPPET-IMAGE-GRID-AUTO-SCALE-ImageGridAutoScale>`.

.. oe:source:: ImageGridAutoScale.py
   :language: python
   :refnum:   3
   :caption:  Example of auto scaling of molecules
   :frag:     SNIPPET-IMAGE-GRID-AUTO-SCALE

.. oe:source:: ImageGridAutoScale.cpp
   :language: c++
   :refnum:   3
   :caption:  Example of auto scaling of molecules
   :frag:     SNIPPET-IMAGE-GRID-AUTO-SCALE

.. oe:source:: ImageGridAutoScale.java
   :language: java
   :refnum:   3
   :caption:  Example of auto scaling of molecules
   :frag:     SNIPPET-IMAGE-GRID-AUTO-SCALE

.. oe:source:: ImageGridAutoScale.cs
   :language: csharp
   :refnum:   3
   :caption:  Example of auto scaling of molecules
   :frag:     SNIPPET-IMAGE-GRID-AUTO-SCALE

.. _figure_image_grid_auto_scale:

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

   **Example of auto scaling of molecules**

.. seealso::

   :ref:`section_mol_display_size` section


.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   %
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The following example (:oe:src:`Listing 4<SNIPPET-IMAGE-GRID-FIXED-SCALE-ImageGridFixedScale>`) shows
how to ensure that all molecules are depicted using the same scaling
factor.
After initializing the molecules, the minimum scaling factor is
determined by looping over the molecules being depicted and calling
the :oe:func:`OEDepict::OEGetMoleculeScale` function.
This function returns the scaling factor of the molecule considering
the depiction options stored in the given
:ref:`OE2DMolDisplayOptions <OEDepict_OE2DMolDisplayOptions>` object.
After determining the minimum scaling factor, the molecules are
rendered to the cells of the grid by using this fixed scaling factor.
The image created by :oe:src:`Listing 4<SNIPPET-IMAGE-GRID-FIXED-SCALE-ImageGridFixedScale>` is shown in
:ref:`Figure: Example of using OEImageGrid<figure_image_grid_fixed_scale>`.

.. oe:source:: ImageGridFixedScale.py
   :language: python
   :refnum:   4
   :caption:  Example of identical scaling of molecules
   :frag:     SNIPPET-IMAGE-GRID-FIXED-SCALE

.. oe:source:: ImageGridFixedScale.cpp
   :language: c++
   :refnum:   4
   :caption:  Example of identical scaling of molecules
   :frag:     SNIPPET-IMAGE-GRID-FIXED-SCALE

.. oe:source:: ImageGridFixedScale.java
   :language: java
   :refnum:   4
   :caption:  Example of identical scaling of molecules
   :frag:     SNIPPET-IMAGE-GRID-FIXED-SCALE

.. oe:source:: ImageGridFixedScale.cs
   :language: csharp
   :refnum:   4
   :caption:  Example of identical scaling of molecules
   :frag:     SNIPPET-IMAGE-GRID-FIXED-SCALE

.. _figure_image_grid_fixed_scale:

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

   **Example of identical scaling of molecules**

.. seealso::

    * :oe:meth:`OEDepict::OEImageGrid::GetCellHeight` method
    * :oe:meth:`OEDepict::OEImageGrid::GetCellWidth` method


.. _section_image_layout_table:

Depicting Molecules in a Table
================================================================================

The following example demonstrates how to depict molecules and display data
alongside them by using the :ref:`OEImageTable <OEDepict_OEImageTable>`.
The individual cells of an :ref:`OEImageTable <OEDepict_OEImageTable>` object can be accessed
by calling the any of the following methods:

* :oe:meth:`OEDepict::OEImageTable::GetCell`
* :oe:meth:`OEDepict::OEImageTable::GetBodyCell`
* :oe:meth:`OEDepict::OEImageTable::GetHeaderCell`
* :oe:meth:`OEDepict::OEImageTable::GetStubColumnCell`

These methods return an image (:ref:`OEImageBase <OEDepict_OEImageBase>`) on which
molecule can be drawn or text can be displayed using the
:oe:meth:`OEDepict::OEImageTable::DrawText` method.
The image created by :oe:src:`Listing 5<SNIPPET-IMAGE-TABLE-ImageTable>` is shown in
:ref:`Figure: Example of depicting molecules and data using image table<figure_image_table>`.

.. oe:source:: ImageTable.py
   :language: python
   :refnum:   5
   :caption:  Example of depicting molecules and data using image table
   :frag:     SNIPPET-IMAGE-TABLE

.. oe:source:: ImageTable.cpp
   :language: c++
   :refnum:   5
   :caption:  Example of depicting molecules and data using image table
   :frag:     SNIPPET-IMAGE-TABLE

.. oe:source:: ImageTable.java
   :language: java
   :refnum:   5
   :caption:  Example of depicting molecules and data using image table
   :frag:     SNIPPET-IMAGE-TABLE

.. oe:source:: ImageTable.cs
   :language: csharp
   :refnum:   5
   :caption:  Example of depicting molecules and data using image table
   :frag:     SNIPPET-IMAGE-TABLE

.. _figure_image_table:

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

   **Example of depicting molecules and data using image table**
