.. _chapter_basic:

********************************************************************************
Basic Drawing Primitives
********************************************************************************

The following example introduces how an image can be created in
**OEDepict TK** to generate a single black line across an image:

#. Create an :ref:`OEImage <OEDepict_OEImage>` object
   with a specific width and height.

#. Specify the two end points of the line with :ref:`OE2DPoint <OEDepict_OE2DPoint>` objects.

#. Draw the line with the
   :oe:meth:`OEDepict::OEImage::DrawLine` method using the :oe:const:`OEDepict::OEDepict::OEBlackPen` to specify the
   graphical properties of the line.

#. Write the image into a file by calling the
   :oe:func:`OEDepict::OEWriteImage` function.

   The :ref:`OEImage <OEDepict_OEImage>` class is implemented as a container of
   drawing commands. When a method such as :oe:meth:`OEDepict::OEImage::DrawLine`
   is called, rather than immediately drawing the line specified by the parameters,
   a line drawing operation is created in the :ref:`OEImage <OEDepict_OEImage>` class
   for later execution.

.. oe:source:: DrawLine.py
   :language: python
   :refnum:   1
   :caption:  Example of line drawing
   :frag:     SNIPPET-DRAW-LINE

.. oe:source:: DrawLine.cpp
   :language: c++
   :refnum:   1
   :caption:  Example of line drawing
   :frag:     SNIPPET-DRAW-LINE

.. oe:source:: DrawLine.java
   :language: java
   :refnum:   1
   :caption:  Example of line drawing
   :frag:     SNIPPET-DRAW-LINE

.. oe:source:: DrawLine.cs
   :language: csharp
   :refnum:   1
   :caption:  Example of line drawing
   :frag:     SNIPPET-DRAW-LINE

The image created by :oe:src:`Listing 1<SNIPPET-DRAW-LINE-DrawLine>` is shown in
:ref:`Figure: Example of line drawing<figure_basic_line_drawing>`.

.. _figure_basic_line_drawing:

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

   **Example of line drawing**

.. seealso::

   * :ref:`OEPen <OEDepict_OEPen>` class
   * :ref:`OEImage <OEDepict_OEImage>` class
   * :oe:func:`OEDepict::OEWriteImage` function

Coordinate System
================================================================================

The coordinate system used in **OEDepict TK** has the origin (x=0.0, y=0.0) at the
top left with the x-axis pointing to the right and the y-axis pointing down.

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

   **2D coordinate system** *(X = horizontal, Y = vertical)*

.. seealso::

   * :ref:`OE2DPoint <OEDepict_OE2DPoint>` class

Basic Shapes
================================================================================

**OEDepict TK** supports drawing the following basic shapes:

   .. list-table::
      :widths: 100 100 100
      :header-rows: 0

      * - :oe:meth:`OEDepict::OEImageBase::DrawArc`
        - :oe:meth:`OEDepict::OEImageBase::DrawCircle`
        - :oe:meth:`OEDepict::OEImageBase::DrawCubicBezier`

      * - .. image:: images/OEImageBase-DrawArc.*
             :align:  center
        - .. image:: images/OEImageBase-DrawCircle.*
             :align:  center
        - .. image:: images/OEImageBase-DrawCubicBezier.*
             :align:  center

      * - :oe:meth:`OEDepict::OEImageBase::DrawLine`
        - :oe:meth:`OEDepict::OEImageBase::DrawPath`
        - :oe:meth:`OEDepict::OEImageBase::DrawPie`

      * - .. image:: images/OEImageBase-DrawLine.*
             :align:  center
        - .. image:: images/OEImageBase-DrawPath.*
             :align:  center
        - .. image:: images/OEImageBase-DrawPie.*
             :align:  center

      * - :oe:meth:`OEDepict::OEImageBase::DrawPoint`
        - :oe:meth:`OEDepict::OEImageBase::DrawPolygon`
        - :oe:meth:`OEDepict::OEImageBase::DrawQuadraticBezier`

      * - .. image:: images/OEImageBase-DrawPoint.*
             :align:  center
        - .. image:: images/OEImageBase-DrawPolygon.*
             :align:  center
        - .. image:: images/OEImageBase-DrawQuadraticBezier.*
             :align:  center

      * - :oe:meth:`OEDepict::OEImageBase::DrawRectangle`
        - :oe:meth:`OEDepict::OEImageBase::DrawText`
        - :oe:meth:`OEDepict::OEImageBase::DrawTriangle`

      * - .. image:: images/OEImageBase-DrawRectangle.*
             :align:  center
        - .. image:: images/OEImageBase-DrawText.*
             :align:  center
        - .. image:: images/OEImageBase-DrawTriangle.*
             :align:  center


Image File Formats
================================================================================

**OEDepict TK** natively supports a variety of graphical file
formats. :oe:func:`OEDepict::OEWriteImage` automatically detects the
desired file format from the file name passed to the function. The
following table lists the file formats natively supported
in **OEDepict TK** and their associated file extensions:

====================================== ===================== ============================
Graphics File Format                   Format Type           File Extension
====================================== ===================== ============================
PNG (Portable Network Graphics)        :term:`raster image`  :file:`.png`
:term:`SVG` (Scalable Vector Graphics) :term:`vector image`  :file:`.svg`
*bare* :term:`SVG` (with no header)    :term:`vector image`  :file:`.bsvg`
Postscript                             :term:`vector image`  :file:`.ps`
Encapsulated PostScript                :term:`vector image`  :file:`.eps`
PDF (Portable Document Format)         :term:`vector image`  :file:`.pdf`
====================================== ===================== ============================

The :oe:func:`OEDepict::OEIsRegisteredImageFile` function can be used
to query whether a given file extension is supported by **OEDepict TK**.
All the supported file formats can be queried using
the :oe:func:`OEDepict::OEGetSupportedImageFileExtensions` function.
