Installation

Caution

The latest version only support Blender version >= 3.4. If for some reason you need to use Blender version 3.0 – 3.2, please check out the source code beautiful-atoms to blender-3.2 branch first.

Requirements

• Blender, please install Blender (version >= 3.4) first.

• ASE

• Scikit-image

Optional:

• spglib

• Pymatgen

• matplotlib

• openbabel

Use Cross-Platform Installation Script

Manually installing dependencies in Blender can be non-trivial. beautiful-atoms provides a cross-platform script install.py to automate the process. We recommend you try it first.

Alternatively, you may use Manual installations or use our Container image.

How it works

The installation script replaces Blender’s bundled python distribution with a conda environment. Before starting, make sure you have a working Anaconda or Miniconda with Python>=3.6, and git on your system.

For all platforms, the installation workflow contains 3 steps:

1. Clone beautiful-atoms to your local machine.

2. Create a new conda environment (e.g. beautiful_atoms) and activate it.

3. Use conda’s default python interpreter to run install.py

The detailed steps are slightly per operation system:

LinuxmacOSWindows

active:

Find out where Blender’s bundled python is located on your system. For example, if you have installed Blender 3.4.0 at ~/apps/Blender, its python bundle is at ~/apps/Blender/3.4.

# Step 1
git clone https://github.com/beautiful-atoms/beautiful-atoms.git && cd beautiful-atoms
# Step 2
conda create -n beautiful_atoms && conda activate beautiful_atoms
# Step 3. The "--use-startup --use-preferences" options are
# suggested for a beginner of Blender. However, if you want to keep
# your own startup and preferences of Blender, please remove these
# options.
$CONDA_PYTHON_EXE install.py ~/apps/Blender/3.4  --use-startup --use-preferences

Change ~/apps/Blender/3.4 in step 3 to the path on your system.

Note

• In step 2, it is important to use a python interpreter outside the activated conda environment, such as $CONDA_PYTHON_EXE.

• In step 3, Blender installed via Flatpak or Snap may have complex directory hierachy. Check their documentations for details or try with a portable Blender distribution.

You can check the usage of install.py by:

python install.py --help

There are several useful options in install.py. For example, if you’re developing the source code for batoms, adding --develop option to the installation process makes a symlink between your local code and the blender plugin folder and keeps the plugin up-to-date. You can also run python install.py –dry-run [options] to get a preview of what steps will the installer perform and which files will be changed.

Uninstallation

install.py allows uninstalling the batoms with its dependencies to revert Blender to its previous state.

Linux and macOSWindows

active:

Remove the batoms plugin and restore Blender’s bundled python.

python install.py --uninstall <path/to/blender/3.x>

(Optional) Remove the conda environment:

conda deactivate
conda remove -n beautiful_atoms

You may omit the path to Blender’s bundled python on macOS and Windows if installed using the same option.

Manual installations

For a basic installation. Please check the OS-specific tutorials below:

• Linux
• Windows
• MacOS

Container image

We also provide a container image ghcr.io/beautiful-atoms/beautiful-atoms (a mirrored image luciusm/beautiful_atoms is hosted at Dockerhub if you cannot access Github’s container registry), for users familiar with Docker or other container platforms. You may find it useful if your workflow does not depend on GUI, such as automatic code unit tests, high-throughput rendering, and working with HPC systems.

To use the container image in Docker (may need to run as admin):

docker pull ghcr.io/beautiful-atoms/beautiful-atoms:latest

The container image should be compatible with Shifter or Singularity on HPC systems, check their manuals for more information.

To run a local python script (e.g. ./render.py) inside the container (may need to run as admin):

docker run --rm \
       -v $(pwd):/workdir \
       ghcr.io/beautiful-atoms/beautiful-atoms:latest \
       blender -b -P render.py

If you encounter issues with write permission to the output image, this is likely because the owner of your current directory has different user id (UID) or group id (GID) than the default value (1000:100). You can find the currently owner of the directory using ls -ln ., the UID & GID will be displayed on the 3rd and 4th columns. For example, if the host directory is owned by 1001:101, the docker command becomes:

docker run --rm \
       -v $(pwd):/workdir \
       -u 1001:101 \
       ghcr.io/beautiful-atoms/beautiful-atoms:latest \
       blender -b -P render.py

You can find the UID & GID of current directory owner by running ls -aln ..

Use GUI with the docker container

It is possible to run Blender GUI within the docker container (only tested on Linux) by X11 forwarding. Please check this tutorial for more details.

Warning

There are several known limitations with Blender docker container, especially on macOS.

1. Cannot be run with macOS with ARM processor (issue)

2. GUI forwarding not working with XQuartz (issue)

3. Blender cannot render using EEVEE without a display. Choose cycles as the renderer if you want to render headlessly.

Other Troubleshooting

Please read Tips page for more setup.