Getting started

Installation

Blender offers the possibility to control things using python. However, it has its own python interpreter and it’s not easy to install new packages in it. If we want to use sisl within it, our best bet is to create a virtual environment and then let blender use that python interpreter. The environment that we create, though, MUST have exactly the same python version as the one shipped with blender.

Following, you have a step by step guide to get blender ready for plotting with sisl:

1. Install blender. You can install by downloading it directly from their official webpage, or in any other way. Check their installation documentation

In ubuntu we can install it with:

snap install blender

2. Find out blender’s python version. You should check what is the version that blender is shipped with. Being blender the name of the executable, you can run:

blender -b --python-expr "import sys; print(f'PYTHON VERSION: {sys.version}')"

In blender 3.6 it gives an output that looks like this:

Blender 3.6.3 (hash d3e6b08276ba built 2023-09-21 06:13:29)
PYTHON VERSION: 3.10.12 (main, Aug 14 2023, 22:14:01) [GCC 11.2.1 20220127 (Red Hat 11.2.1-9)]

Blender quit

Therefore, we know that blender 3.6.3 uses python 3.10.12.

3. Create an environment with that python version and install sisl (skip if you have it already). In this case, we will use conda as the environment manager, since it lets us very easily select the python version. You probably don’t need the exact micro version. In our case asking for 3.10 is enough:

conda create -n blender-python python=3.10

Then install all the packages you want to use in blender:

conda activate blender-python
python -m pip install sisl[viz]

4. Find the path to the python libraries of your environment. There are many ways to get this. In conda, this path is in the CONDA_PREFIX environment variable. So you can just:

$> echo $CONDA_PREFIX
/home/miniconda3/envs/blender-python

5. Tell blender to use the libraries in your environment. This is done with the BLENDER_SYSTEM_PYTHON variable, so you need to define it somehow for the blender process. You can specify it every time you use blender:

BLENDER_SYSTEM_PYTHON=/home/miniconda3/envs/blender-python blender

or set it in your initialization files (recommended). E.g. in linux you just include this line in ~/.bashrc:

export BLENDER_SYSTEM_PYTHON=/home/miniconda3/envs/blender-python

If everything went right, you should now be able to:

blender -b --python-expr "import sisl"

and it shouldn’t raise any error. Congratulations, you are ready to use sisl with blender!

First steps

Now that you have everything set up, let’s open blender.

At first, blender might look intimidating because of all the options that it has, but we’ll keep it very simple. Our aim is just to show you how to use sisl, the rest is in your hands. What you see in the center of the screen is the default cube, you can just delete it. If its selected, just press Supr.

Currently, you are now in the Layout tab. The easiest way to start programming is to go to the Scripting tab. It is the last tab at the right of the tool bar.

You should see an interactive console and a text editor to write our scripts. Let’s make our first plot using the console!

We want to plot graphene, so the simplest way is

import sisl
geom_plot = sisl.geom.graphene().plot(backend="blender", bonds_scale=0.01)
geom_plot.show()

If we write these lines on the console, we should get the graphene structure in the viewport.

This is the 3D model. To get an image, we need to render. Rendering is a process that generates an image from a camera (in our case the camera is the black wireframe that we see in the viewport) and the 3D model (objects, materials, lighting…). We can trigger our first render by pressing F12 or Render > Render image.

There are infinite things that you can tweak in blender, but one important thing to know about is the rendering engine. For this image, you have used Eeve which is the default engine. It is very fast, which makes it suitable for real-time rendering applications. For single images that you want to publish, it is usually worth it to use the Cycles engine. This engine does more complex calculations (following light rays as they travel through the scene). You can change it in the right hand side of the window, by clicking the tab with the microwave icon (Render properties). This should give you more realistic looking results.

Now you know how to use sisl inside blender play with all the settings of the GeometryPlot, move the camera, change the lighting, the background, etc… to get amazing images for your talks or publications!

Notice that not only GeometryPlot has support for blender, GridPlot and GeometryPlot also support it. Try to plot a grid and let’s see how it looks!