.. include:: ../../../substitutions
.. _blender_getting_started:

Scripting in Blender
====================

In the following, it is explained how to get started with scripting and using pyddg in the Blender GUI with Blender |major_minor|.


.. note::
    The Blender docs provide a detailed overview of the **Blender GUI** under `Blenders User Interface`_.   
    You can find detailed information on Blenders **python API** in `Blenders Python API docs`_.

Launching Blender
-----------------

Start Blender according to your OS:

**Linux and WSL**

.. parsed-literal::

    export PATH="$HOME/blender/\ |blender_major_minor|\ :$PATH"
    export PYTHONPATH="venv/lib/python3.\ |python_minor|\ /site-packages/"
    source venv/bin/activate
    blender

**MacOS**

.. parsed-literal::

    export PATH="/Applications/Blender-\ |major_minor|.\ |point|\-pyddg.app/Contents/MacOS/:$PATH"
    export PYTHONPATH="venv/lib/python3.\ |python_minor|\ /site-packages/"
    source venv/bin/activate
    Blender

**Windows**

.. parsed-literal::

    "C:\\Program Files\\Blender Foundation\\Blender \ |major_minor|\ \\blender.exe"

or by double-clicking on blender.exe or the Blender icon on your Desktop.

.. warning::

    If you close the terminal from which you started Blender, it will **kill Blender instantly**
    without saving!


.. note::

    For MacOS, Linux and WSL you need to `cd` into the directory where
    you have created your virtual environment.
    You may need to change the path to Blender, if you have installed it in a different
    location or a different version.

Output and Error Messages
-------------------------

The outputs and error messages of scripts executed within Blender are printed in the **terminal** you started Blender with.
Error messages also appear in Blender's info editor (see below), which is not the case for outputs of print statements. 

On Windows you can activate a console using the Menu: ``Window > Toggle System Console``.

Workspaces
----------

The Blender window is subdivided into different sections, called **areas**. Each area is of a specific **editor** type. A **workspace** is a selection of editors in the Blender window.

In the top bar, you can choose from different presets. The **scripting workspace** provides a useful setup for scripting in Blender. The corresponding editors will be explained below. 

.. image:: getting_started01.png

You can also **customize the workspace** and select editors manually as follows.  
To create a **new area**, split up an area into two. To do this, hover the mouse cursor over one of the corners until you see a cross. Then, drag the cross to create the new area. To **delete an area**, drag it into a neighboring area in the same way.

|custom_workspace1| |custom_workspace2| 

In the top left corner of each area, you can now **select an editor type**.

|custom_workspace3| 

For further  information, see the Blender docs under `Areas`_ and `Editors`_.

.. |custom_workspace1| image:: custom_workspace1.png
   :width: 45%

.. |custom_workspace2| image:: custom_workspace2.png
   :width: 45%

.. |custom_workspace3| image:: custom_workspace3.png
   :width: 45%

Scripting Workspace
^^^^^^^^^^^^^^^^^^^

In the top bar of the Blender window, click on "Scripting", to choose the **Scripting workspace**. 

Now, the window is subdivided into different areas. Next to the "Outliner" and the "Properies" editors on the right, there are 4 areas with editor types "Viewport", "Python Console", "Text Editor" and "Info", which are explained below. 


Python Console
^^^^^^^^^^^^^^

The **Python Console** is usually used for testing short code snippets. Import pyddg with 

.. code-block:: shell

    import ddg


.. image:: getting_started02.png

Text Editor
^^^^^^^^^^^

With the **Text Editor** you can edit and execute existing python scripts or write new ones. To create a new python script, click "New".

.. image:: getting_started03.png

A script starts with importing ddg, possibly bpy (Blenders Python API),
and all other packages and modules that are needed. This could be for example:

.. doctest::

    >>> import ddg
    >>> import bpy
    >>> from ddg.datastructures.halfedge.surface_generator import cube

Execute the script with ``Alt+P`` or by clicking the play button. 

.. image:: getting_started04.png

In the script you can implement your geometric constructions and visualize them in
Blender:

.. doctest::

    >>> cube1 = cube()
    >>> blender_object = ddg.to_blender_object(cube1)

When getting started you should first learn about
:ref:`The functions to_blender_object and to_blender_object_helper <to_blender_object_and_helper>`
and then follow the links within for more information on visualizing the
different types of ddg objects.

When executing a script multiple times it immediately becomes clear that objects
are not removed and will be stacked (also there is the default Blender cube in a new
document that we usually don't want). Therefore
:ref:`clearing objects <blender_utils_clear>` is an essential part when using the
library in Blender.

A minimal example of a script would look like this:

.. doctest::

    >>> import ddg
    >>> from ddg.datastructures.halfedge.surface_generator import cube
    >>> from ddg.visualization.blender.scene import clear

    >>> clear()
    >>> cube1 = cube()
    >>> blender_object = ddg.to_blender_object(cube1)


Info Editor
^^^^^^^^^^^
The **Info** editor lists executed operators, warnings and errors in Blender.
Here you can check if the script was properly executed or failed.

.. image:: getting_started05.png