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

.. oe:namespace:: OEDepict

.. meta::
   :keywords: OEImage


.. _OEDepict_OEImage:

.. oe:class:: OEImage

   .. oe:api::

      class OEImage : public OEImageBase

   :ref:`OEImage <OEDepict_OEImage>` class is implemented as a **display list** i.e.
   a container of drawing commands.
   For example, when the :oe:meth:`OEDepict::OEImage::DrawLine` method is
   called, rather than immediately drawing a line specified by the parameters,
   a line drawing operation is created that copies all parameters for later
   execution.

   When the :oe:meth:`OEDepict::OEImage::Render` method is invoked, the
   drawing commands stored in the :ref:`OEImage <OEDepict_OEImage>` object are
   executed in the same order in which they were issued.

   The following methods are publicly inherited from :ref:`OEImageBase <OEDepict_OEImageBase>`:

   ========================================================================= ========================================================================== =========================================================================
   :oe:meth:`Clear<OEDepict::OEImageBase::Clear>`                            :oe:meth:`DrawPie<OEDepict::OEImageBase::DrawPie>`                         :oe:meth:`DrawTriangle<OEDepict::OEImageBase::DrawTriangle>`
   :oe:meth:`DrawArc<OEDepict::OEImageBase::DrawArc>`                        :oe:meth:`DrawPoint<OEDepict::OEImageBase::DrawPoint>`                     :oe:meth:`GetGlobalOffset<OEDepict::OEImageBase::GetGlobalOffset>`
   :oe:meth:`DrawCircle<OEDepict::OEImageBase::DrawCircle>`                  :oe:meth:`DrawPolygon<OEDepict::OEImageBase::DrawPolygon>`                 :oe:meth:`GetHeight<OEDepict::OEImageBase::GetHeight>`
   :oe:meth:`DrawCubicBezier<OEDepict::OEImageBase::DrawCubicBezier>`        :oe:meth:`DrawQuadraticBezier<OEDepict::OEImageBase::DrawQuadraticBezier>` :oe:meth:`GetMinFontSize<OEDepict::OEImageBase::GetMinFontSize>`
   :oe:meth:`DrawLine<OEDepict::OEImageBase::DrawLine>`                      :oe:meth:`DrawRectangle<OEDepict::OEImageBase::DrawRectangle>`             :oe:meth:`GetWidth<OEDepict::OEImageBase::GetWidth>`
   :oe:meth:`DrawPath<OEDepict::OEImageBase::DrawPath>`                      :oe:meth:`DrawText<OEDepict::OEImageBase::DrawText>`                       :oe:meth:`GetSVGClass<OEDepict::OEImageBase::GetSVGClass>`
   :oe:meth:`GetSVGGroup<OEDepict::OEImageBase::GetSVGGroup>`                :oe:meth:`GetSVGGroups<OEDepict::OEImageBase::GetSVGGroups>`               :oe:meth:`NewSVGClass<OEDepict::OEImageBase::NewSVGClass>`
   :oe:meth:`NewSVGGroup<OEDepict::OEImageBase::NewSVGGroup>`                :oe:meth:`PopGroup<OEDepict::OEImageBase::PopGroup>`                       :oe:meth:`PushGroup<OEDepict::OEImageBase::PushGroup>`
   :oe:meth:`SetMinFontSize<OEDepict::OEImageBase::SetMinFontSize>`
   ========================================================================= ========================================================================== =========================================================================

   .. ################################################################
      # Constructors
      ################################################################

   .. oe:method:: Constructors

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

         .. oe:api::

            OEImage(double width, double height,
                    const OESystem::OEColor& bgColor = OESystem::OEWhite)

      .. oe:language:: python

         .. oe:api:: python

            OEImage(width: float, height: float, bgColor: OEColor = OEWhite) -> OEImage

      Default constructor that creates an :ref:`OEImage <OEDepict_OEImage>`
      with the specified width and height.

      *width, height*
        The dimensions of the image, both have to be positive (non-zero)
        numbers.

      *bgColor*
        The color that is used to clear the image  upon construction.
      The default background color is :oe:const:`OEWhite<OESystem::OESystem::OEWhite>`.
        A :file:`.png` image with transparent background can be
        generated by passing the
      :oe:const:`OETransparentColor<OESystem::OESystem::OETransparentColor>`
        as the background color.

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

         .. oe:api::

            OEImage(const OEImage& rhs)

      .. oe:language:: python

         .. oe:api:: python

            OEImage(rhs: OEImage) -> OEImage

      Copy constructor.

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

         .. oe:api::

            OEImage(const OEImage& src, double scale)

      .. oe:language:: python

         .. oe:api:: python

            OEImage(rhs: OEImage, scale: float) -> OEImage

      Copy constructor with scaling.

      *scale*
        The scaling factor is used to create a new image from the given one.
        The scaling factor has to be a positive (non-zero) number.

      The following code snippet shows how to half and double the size of an image.

      .. oe:source:: ImageScale.py
         :language: python
         :noindent:
         :frag:     SNIPPET-IMAGE-SCALE

      .. oe:source:: ImageScale.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-IMAGE-SCALE

      .. oe:source:: ImageScale.java
         :language: java
         :noindent:
         :frag:     SNIPPET-IMAGE-SCALE

      .. oe:source:: ImageScale.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-IMAGE-SCALE

      .. _table_OEImage_scale:

      .. list-table:: **Examples of image scaling**
         :widths: 250 250 250
         :header-rows: 1

         * - original image
           - scale = 0.5
           - scale = 2.0
         * - .. image:: ../images/image.*
           - .. image:: ../images/halfimage.*
           - .. image:: ../images/doubleimage.*



   .. ################################################################
      # Clear
      ################################################################

   .. oe:method:: Clear

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

         .. oe:api::

            void Clear(const OESystem::OEColor& color)

      .. oe:language:: python

         .. oe:api:: python

            Clear(color: OEColor) -> None

      Appends a clear command to the display list of the
      :ref:`OEImage <OEDepict_OEImage>` object.

      .. seealso::

         * :oe:meth:`OEDepict::OEImageBase::Clear` method
         * :ref:`OEColor <OESystem_OEColor>` class


   .. ################################################################
      # DrawArc
      ################################################################

   .. oe:method:: DrawArc

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

         .. oe:api::

            void DrawArc(const OE2DPoint& center, double bgnAngle,
                         double endAngle, double radius, const OEPen& pen)

      .. oe:language:: python

         .. oe:api:: python

            DrawArc(center: OE2DPoint, bgnAngle: float, endAngle: float,
                    radius: float, pen: OEPen) -> None

      Appends an arc drawing command to the display list of the
      :ref:`OEImage <OEDepict_OEImage>` object.
      See example in :ref:`Figure: Example of drawing an arc<figure_OEImage_DrawArc>`.

      .. _figure_OEImage_DrawArc:

      .. figure:: ../images/OEImageBase-DrawArc.*
         :align:  center
         :scale:  100

         **Example of drawing an arc**

      .. seealso::

         * :oe:meth:`OEDepict::OEImageBase::DrawArc` method
         * :ref:`OE2DPoint <OEDepict_OE2DPoint>` class
         * :ref:`OEPen <OEDepict_OEPen>` class


   .. ################################################################
      # DrawCircle
      ################################################################

   .. oe:method:: DrawCircle

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

         .. oe:api::

            void DrawCircle(const OE2DPoint& center, double radius,
                            const OEPen& pen)

      .. oe:language:: python

         .. oe:api:: python

            DrawCircle(center: OE2DPoint, radius: float, pen: OEPen) -> None

      Appends a circle drawing command to the display list of the
      :ref:`OEImage <OEDepict_OEImage>` object.
      See example in :ref:`Figure: Example of drawing a circle<figure_OEImage_DrawCircle>`.

      .. _figure_OEImage_DrawCircle:

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

         **Example of drawing a circle**

      .. seealso::

         * :oe:meth:`OEDepict::OEImageBase::DrawCircle` method
         * :ref:`OE2DPoint <OEDepict_OE2DPoint>` class
         * :ref:`OEPen <OEDepict_OEPen>` class


   .. ################################################################
      # DrawCubicBezier
      ################################################################

   .. oe:method:: DrawCubicBezier

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

         .. oe:api::

            void DrawCubicBezier(const OE2DPoint& bgn, const OE2DPoint& c1,
                                 const OE2DPoint& c2, const OE2DPoint& end,
                                 const OEPen& pen)

      .. oe:language:: python

         .. oe:api:: python

            DrawCubicBezier(bgn: OE2DPoint, c1: OE2DPoint, c2: OE2DPoint,
                            end: OE2DPoint, pen: OEPen) -> None

      Appends a cubic |Bezier| curve drawing command to the display
      list of the :ref:`OEImage <OEDepict_OEImage>` object.
      See example in :ref:`Figure: Example of drawing a cubic Bezier curve<figure_OEImage_DrawCubicBezier>`.

      .. _figure_OEImage_DrawCubicBezier:

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

         **Example of drawing a cubic Bezier curve**

      .. seealso::

         * :oe:meth:`OEDepict::OEImageBase::DrawCubicBezier` method
         * :ref:`OE2DPoint <OEDepict_OE2DPoint>` class
         * :ref:`OEPen <OEDepict_OEPen>` classes


   .. ################################################################
      # DrawLine
      ################################################################

   .. oe:method:: DrawLine

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

         .. oe:api::

            void DrawLine(const OE2DPoint& bgn, const OE2DPoint& end,
                          const OEPen& pen)

      .. oe:language:: python

         .. oe:api:: python

            DrawLine(bgn: OE2DPoint, end: OE2DPoint, pen: OEPen) -> None

      Appends a line drawing command to the display list of the
      :ref:`OEImage <OEDepict_OEImage>` object.
      See example in :ref:`Figure: Example of drawing a line<figure_OEImage_DrawLine>`.

      .. _figure_OEImage_DrawLine:

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

         **Example of drawing a line**

      .. seealso::

         * :oe:meth:`OEDepict::OEImageBase::DrawLine` method
         * :ref:`OE2DPoint <OEDepict_OE2DPoint>` class
         * :ref:`OEPen <OEDepict_OEPen>` class


   .. ################################################################
      # DrawPath
      ################################################################

   .. oe:method:: DrawPath

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

         .. oe:api::

            void DrawPath(const OE2DPath& path, const OEPen& pen)

      .. oe:language:: python

         .. oe:api:: python

            DrawPath(path: OE2DPath, pen: OEPen) -> None

      Appends a path drawing command to the display list of the
      :ref:`OEImage <OEDepict_OEImage>` object.
      See example in :ref:`Figure: Example of drawing a path<figure_OEImage_DrawPath>`.

      .. _figure_OEImage_DrawPath:

      .. figure:: ../images/OEImageBase-DrawPath.*
         :align:  center
         :scale:  100

         **Example of drawing a path**

      .. seealso::

         * :oe:meth:`OEDepict::OEImageBase::DrawPath` method
         * :ref:`OE2DPath <OEDepict_OE2DPath>` class
         * :ref:`OEPen <OEDepict_OEPen>` class


   .. ################################################################
      # DrawPie
      ################################################################

   .. oe:method:: DrawPie

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

         .. oe:api::

            void DrawPie(const OE2DPoint& center, double bgnAngle,
                         double endAngle, double radius, const OEPen& pen)

      .. oe:language:: python

         .. oe:api:: python

            DrawPie(center: OE2DPoint, bgnAngle: float, endAngle: float,
                    radius: float, pen: OEPen) -> None

      Appends a pie drawing command to the display list of the
      :ref:`OEImage <OEDepict_OEImage>` object.
      See example in :ref:`Figure: Example of drawing a pie<figure_OEImage_DrawPie>`.

      .. _figure_OEImage_DrawPie:

      .. figure:: ../images/OEImageBase-DrawPie.*
         :align:  center
         :scale:  100

         **Example of drawing a pie**

      .. seealso::

         * :oe:meth:`OEDepict::OEImageBase::DrawPie` method
         * :ref:`OE2DPoint <OEDepict_OE2DPoint>` class
         * :ref:`OEPen <OEDepict_OEPen>` class


   .. ################################################################
      # DrawPoint
      ################################################################

   .. oe:method:: DrawPoint

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

         .. oe:api::

            void DrawPoint(const OE2DPoint& p, const OESystem::OEColor& color)

      .. oe:language:: python

         .. oe:api:: python

            DrawPoint(p: OE2DPoint, color: OEColor) -> None

      Appends a point drawing command to the display list of the
      :ref:`OEImage <OEDepict_OEImage>` object.
      See example in :ref:`Figure: Example of drawing a point<figure_OEImage_DrawPoint>`.

      .. _figure_OEImage_DrawPoint:

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

         **Example of drawing a point**

      .. seealso::

         * :oe:meth:`OEDepict::OEImageBase::DrawPoint` method
         * :ref:`OE2DPoint <OEDepict_OE2DPoint>` class
         * :ref:`OEColor <OESystem_OEColor>` class


   .. ################################################################
      # DrawPolygon
      ################################################################

   .. oe:method:: DrawPolygon

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

         .. oe:api::

            void DrawPolygon(const std::vector<OE2DPoint>& points,
                             const OEPen& pen)

      .. oe:language:: python

         .. oe:api:: python

            DrawPolygon(points: OE2DPointVector, pen: OEPen) -> None

      Appends a polygon drawing command to the display list of the
      :ref:`OEImage <OEDepict_OEImage>` object.
      See example in :ref:`Figure: Example of drawing a polygon<figure_OEImage_DrawPolygon>`.

      .. _figure_OEImage_DrawPolygon:

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

         **Example of drawing a polygon**

      .. seealso::

         * :oe:meth:`OEDepict::OEImageBase::DrawPolygon` method
         * :ref:`OE2DPoint <OEDepict_OE2DPoint>` class
         * :ref:`OEPen <OEDepict_OEPen>` class


   .. ################################################################
      # DrawQuadraticBezier
      ################################################################

   .. oe:method:: DrawQuadraticBezier

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

         .. oe:api::

            void DrawQuadraticBezier(const OE2DPoint& bgn, const OE2DPoint& c,
                                     const OE2DPoint& end, const OEPen& pen)

      .. oe:language:: python

         .. oe:api:: python

            DrawQuadraticBezier(bgn: OE2DPoint, c1: OE2DPoint, end: OE2DPoint,
                                pen: OEPen) -> None

      Appends a quadratic |Bezier| curve drawing command to the display
      list of the :ref:`OEImage <OEDepict_OEImage>` object.
      See example in :ref:`Figure: Example of drawing a quadratic Bezier curve<figure_OEImage_DrawQuadraticBezier>`.

      .. _figure_OEImage_DrawQuadraticBezier:

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

         **Example of drawing a quadratic Bezier curve**

      .. seealso::

         * :oe:meth:`OEDepict::OEImageBase::DrawQuadraticBezier` method
         * :ref:`OE2DPoint <OEDepict_OE2DPoint>` class
         * :ref:`OEPen <OEDepict_OEPen>` classes


   .. ################################################################
      # DrawRectangle
      ################################################################

   .. oe:method:: DrawRectangle

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

         .. oe:api::

            void DrawRectangle(const OE2DPoint& tl, const OE2DPoint& br,
                               const OEPen& pen)

      .. oe:language:: python

         .. oe:api:: python

            DrawRectangle(tl: OE2DPoint, br: OE2DPoint, pen: OEPen) -> None

      Appends a polygon drawing command to the display list of the
      :ref:`OEImage <OEDepict_OEImage>` object.
      See example in :ref:`Figure: Example of drawing a rectangle<figure_OEImage_DrawRectangle>`.

      .. _figure_OEImage_DrawRectangle:

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

         **Example of drawing a rectangle**

      .. seealso::

         * :oe:meth:`OEDepict::OEImageBase::DrawRectangle` method
         * :ref:`OE2DPoint <OEDepict_OE2DPoint>` class
         * :ref:`OEPen <OEDepict_OEPen>` class


   .. ################################################################
      # DrawText
      ################################################################

   .. oe:method:: DrawText

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

         .. oe:api::

            void DrawText(const OE2DPoint& c, const std::string& text,
                          const OEFont& font, double maxwidth = 0.0)

      .. oe:language:: python

         .. oe:api:: python

            DrawText(c: OE2DPoint, text: str, font: OEFont,
                     maxwidth: float = 0.0) -> None

      Appends a text drawing command to the display list of the
      :ref:`OEImage <OEDepict_OEImage>` object.
      See example in :ref:`Figure: Example of drawing a text<figure_OEImage_DrawText>`.

      .. _figure_OEImage_DrawText:

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

         **Example of drawing a text**

      .. seealso::

         * :oe:meth:`OEDepict::OEImageBase::DrawText` method
         * :ref:`OE2DPoint <OEDepict_OE2DPoint>` class
         * :ref:`OEFont <OEDepict_OEFont>` class


   .. ################################################################
      # DrawTriangle
      ################################################################

   .. oe:method:: DrawTriangle

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

         .. oe:api::

            void DrawTriangle(const OE2DPoint& a, const OE2DPoint& b,
                              const OE2DPoint& c, const OEPen& pen)

      .. oe:language:: python

         .. oe:api:: python

            DrawTriangle(pA: OE2DPoint, pB: OE2DPoint, pC: OE2DPoint,
                         pen: OEPen) -> None

      Appends a triangle drawing command to the display list of the
      :ref:`OEImage <OEDepict_OEImage>` object.
      See example in :ref:`Figure: Example of drawing a triangle<figure_OEImage_DrawTriangle>`.

      .. _figure_OEImage_DrawTriangle:

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

         **Example of drawing a triangle**

      .. seealso::

         * :oe:meth:`OEDepict::OEImageBase::DrawTriangle` method
         * :ref:`OE2DPoint <OEDepict_OE2DPoint>` class
         * :ref:`OEPen <OEDepict_OEPen>` class


   .. ################################################################
      # GetHeight
      ################################################################

   .. oe:method:: GetHeight

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

         .. oe:api::

            double GetHeight() const

      .. oe:language:: python

         .. oe:api:: python

            GetHeight() -> float

      Returns the height of the :ref:`OEImage <OEDepict_OEImage>` object.


   .. ################################################################
      # GetWidth
      ################################################################

   .. oe:method:: GetWidth

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

         .. oe:api::

            double GetWidth() const

      .. oe:language:: python

         .. oe:api:: python

            GetWidth() -> float

      Returns the width of the :ref:`OEImage <OEDepict_OEImage>` object.


   .. ################################################################
      # IsEmpty
      ################################################################

   .. oe:method:: IsEmpty

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

         .. oe:api::

            bool IsEmpty() const

      .. oe:language:: python

         .. oe:api:: python

            IsEmpty() -> bool

      Returns whether or not the display list of the
      :ref:`OEImage <OEDepict_OEImage>` object is empty.


   .. ################################################################
      # Render
      ################################################################

   .. oe:method:: Render

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

         .. oe:api::

            bool Render(OEImageBase& image) const

      .. oe:language:: python

         .. oe:api:: python

            Render(image: OEImageBase) -> bool

      Renders the image stored in the :ref:`OEImage <OEDepict_OEImage>`
      object by executing the stored drawing commands in the order in
      which they were issued.

   .. ################################################################
      # RenderLayer
      ################################################################

   .. oe:method: RenderLayer DO NOT DOCUMENT USED ONLY INTERNALLY

      .. oe:api::

         bool RenderLayer(OEImageBase& image) const
         bool RenderLayer(OEImageBase& image, const OE2DPoint&) const

      Used to transfer push / pop instructions from one image to another.
