.. include:: ../substitutions .. TODO: Replace |pyddg-gitlab| with the package name once the library is on PyPI. .. |pyddg-gitlab| replace:: git+https://gitlab.discretization.de/python/pyddg@\ |tag| .. |pyddg-gitlab-different| replace:: git+https://gitlab.discretization.de/python/pyddg@\ |different_tag| .. _blender_pyddg_installation: pyddg and Blender Installation ------------------------------- .. contents:: :local: :backlinks: none .. _blender_linux_installation: Linux and WSL ^^^^^^^^^^^^^ .. warning:: Don't install Blender using other methods unless you know what you are doing. Install Blender |major_minor|.\ |point| to a directory of your choice, e.g. ``~/blender``, with the following command: .. TODO: Replace this with sh <(curl https://gitlab.discretization.de/python/pyddg/-/raw/develop/scripts/setup_blender) ~/blender |major| |minor| |point| once the repository is public. .. parsed-literal:: sh <(curl https://gitlab.discretization.de/pyddg/pyddg/-/raw/develop/scripts/setup_blender) ~/blender |major| |minor| |point| We don't support newer versions of Blender right now, though they are likely to work. Create a directory for your project and enter it. Create a virtual environment with .. parsed-literal:: ~/blender/\ |blender_major_minor|\ /\ |major_minor|\ /_python/bin/python3.\ |python_minor|\ -m venv venv The following commands need to be run every time you want to work with the library: .. parsed-literal:: export PATH="$HOME/blender/\ |blender_major_minor|\ :$PATH" export PYTHONPATH="venv/lib/python3.\ |python_minor|\ /site-packages/" source venv/bin/activate .. warning:: Blender won't work until you enter the virtual environment and set these environment variables. Install a specific version of the library with .. parsed-literal:: pip install |pyddg-gitlab| Verify that Blender finds the library with .. code-block:: doscon blender --background --python-expr 'import ddg; print("Successfully imported ddg!")' Start Blender with .. code-block:: doscon blender If you now want to learn how to start scripting in Blender continue reading :ref:`here `. Deactivate the virtual environment with .. code-block:: doscon deactivate .. TODO warning that environment vars need to be set MacOS ^^^^^ .. warning:: Don't install Blender using other methods unless you know what you are doing. Install Blender |major_minor|.\ |point| for Apple Silicon to ``Applications`` with the following command. If you're running Intel, pass ``x64`` instead of ``arm64``. Note that it requires root privileges! .. parsed-literal:: sh <(curl https://gitlab.discretization.de/pyddg/pyddg/-/raw/develop/scripts/setup_blender_macos) arm64 |major| |minor| |point| Create a directory for your project and enter it. Create a virtual environment with .. parsed-literal:: /Applications/Blender-\ |major_minor|.\ |point|\-pyddg.app/Contents/Resources/\ |major_minor|\ /_python/bin/python3.\ |python_minor|\ -m venv venv The following commands need to be run every time you want to work with the library: .. 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 .. warning:: Blender won't work until you enter the virtual environment and set these environment variables. Install the library with .. parsed-literal:: pip install |pyddg-gitlab| Verify that Blender finds the library with .. code-block:: doscon Blender --background --python-expr 'import ddg; print("Successfully imported ddg!")' Start Blender with .. code-block:: doscon Blender Remember that you have to start it inside the virtual environment and that you have exported the `PATH` and `PYTHONPATH` before. If you now want to learn how to start scripting in Blender continue reading :ref:`here `. Deactivate the virtual environment with .. code-block:: bash deactivate Windows ^^^^^^^ .. COMMENT for the maintainer: If the value of |major_minor| changes, make sure to adjust the version in the link to the installation .. note:: If you prefer to work in a GNU/Linux environment directly on Windows, you can install `WSL `_. You can then follow the instruction for :ref:`blender_linux_installation`. For instructions on how to use the Blender GUI on WSL, see :ref:`blender_display_on_WSL` Install Blender |major_minor| using the `official installer `_. You can install it to a custom directory, but from now on we will assume the default directory. Using an elevated terminal (i.e. "Run as administrator" in cmd.exe) .. image:: windows01.png :width: 500 Install a specific version of the library inside Blender with .. parsed-literal:: "C:\\Program Files\\Blender Foundation\\Blender \ |major_minor|\ \\\ |major_minor|\ \\python\\bin\\python.exe" -m ^ ensurepip .. parsed-literal:: "C:\\Program Files\\Blender Foundation\\Blender \ |major_minor|\ \\\ |major_minor|\ \\python\\bin\\python.exe" -m ^ pip install --target "C:\\Program Files\\Blender Foundation\\Blender \ |major_minor|\ \\\ |major_minor|\ \\python\\lib\\site-packages" ^ |pyddg-gitlab| The ``--target`` flag ensures that the library gets installed into Blender's Python. .. note:: You need to have `git installed `_ and may have to manually `add it to your PATH `_. In the guide on how to add git to your PATH you may need to choose "edit the **system** environment variables" instead of "edit environment variables for **your account**" to have the rights to edit the PATH. .. warning:: This modifies your Blender installation. Updating or installing another Blender version may result in problems. Verify that Blender finds the library with .. parsed-literal:: "C:\\Program Files\\Blender Foundation\\Blender \ |major_minor|\ \\blender.exe" --background --python-expr "import ddg; print('Successfully imported ddg!')" You can start Blender with .. parsed-literal:: "C:\\Program Files\\Blender Foundation\\Blender \ |major_minor|\ \\blender.exe" or by double-clicking on the Blender icon on your Desktop. If you now want to learn how to start scripting in Blender continue reading :ref:`here `. Updating and switching versions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Choose a different version, e.g. |different_tag|. Inside the virtual environment, run .. parsed-literal:: pip install |pyddg-gitlab-different| If you are on Windows, you need to upgrade your Blender's ``pyddg``. .. parsed-literal:: "C:\\Program Files\\Blender Foundation\\Blender \ |major_minor|\ \\\ |major_minor|\ \\python\\bin\\python.exe" -m ^ pip install --target "C:\\Program Files\\Blender Foundation\\Blender \ |major_minor|\ \\\ |major_minor|\ \\python\\lib\\site-packages" |pyddg-gitlab-different| .. warning:: Updating the version is likely to fail if the library was moved after installation. This is due to the setup of `virtual environments `_: "[...] environments are inherently non-portable, in the general case." .. _blender_display_on_WSL: Setting up display for interactive Blender on WSL ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ While `WSL supports Linux GUI apps on Windows 11 `_, the same cannot be said for Windows 10. In this case, you need to set up an X Server to display graphical outputs of interactive Blender. `VcXsrv `_ is an open-source tool that can set up a Windows X Server. After installing VcXsrv, an X Server can be set up by running xlaunch.exe. In Display settings, choose "Multiple windows", Display number 0. .. image:: xlaunch_01.png :width: 400 Choose "Start no client" for client startup option. .. image:: xlaunch_02.png :width: 400 In Extra settings, tick "Disable access control" to enable access from clients in WSL. .. image:: xlaunch_03.png :width: 400 Finally, do not forget to save the configuration and finish. Next time you need to start an X Server, start the saved .xlaunch file to avoid setting it up all over again. You will know that VcXsrv is running when the XLaunch icon appears in the taskbar. .. image:: xlaunch_04.png :width: 200 The next thing to do is to set the environment variable ``DISPLAY`` for our WSL instance. This can be done dynamically with: .. code-block:: bash export DISPLAY="`sed -n 's/nameserver //p' /etc/resolv.conf`:0" If you already added Blender to the ``$PATH`` in WSL, simply running ``blender`` will launch interactive Blender. .. image:: blender_gui_01.png :width: 600