.. _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``.

Executing Python Scripts via Command Line
-----------------------------------------
Blender is usually (and best) started from a console,
see :ref:`blender_getting_started`.
Executing a python script in Blenders GUI over and over again may
lead to unwanted leakage, caching and unintentionally influencing Blender's state.
Therefore it is recommended to always execute a python script with a new
instance of Blender. This can be done by using the `--pyhton` flag.

.. code-block:: bash

    blender --python /path-to-python-file/file.py

For Windows and Mac change the `blender` call to the corresponding call listed
in :ref:`blender_getting_started`.


Executing Blender in the background
-----------------------------------

If you don't need Blender's GUI, for example when directly rendering from a
Python script, you may want to run Blender in the background to save extra memory.

.. code-block:: bash

    blender --background --python /path-to-python-file/file.py

For Windows and Mac change the `blender` call to the corresponding call listed
in :ref:`blender_getting_started`.


Reducing the number of Blender objects
--------------------------------------
In our experience Blender is better at handling fewer objects with dense meshes
compared to many objects with coarse meshes. Therefore it might make sense
to join multiple objects into one object. Nets can be joined in
:py:class:`~ddg.nets.NetCollection` s. Halfedge objects can be joined by using the
function :py:func:`~ddg.halfedge.copy.union`.
You can manually join objects in Blender by selecting them and pressing `Ctrl + J`.
Alternatively you do this via script using the function :py:func:`~ddg.blender.mesh.join`
that joins meshes or objects with mesh data.

.. _preventing_animations_from_crashing_rendering:

Preventing Animations to Crash during Rendering
-----------------------------------------------
In addition to the tips and tricks above you can find more hints
for more stable rendering of animations in the
:ref:`blender_rendering` guide under **Animation**.


Debugging when Blender crashed
------------------------------
If Blender still crashes, Blender's command line tool offers a lot of options for debugging and getting
more informative debugging messages. Run

.. code-block:: bash

    blender --help

to get an overview.
For Windows and Mac change the `blender` call to the corresponding call listed
in :ref:`blender_getting_started`. Also see `Blender Gotchas <https://docs.blender.org/api/3.4/info_gotcha.html>`_.