Installation Instructions

Installation

These are the instructions that should be followed to get you started with Elements.

⚠️ We strongly recommend using Anaconda for your python environment, as well as Visual Studio Code as your IDE.

OS requirements

The Elements framework has been tested on the following operating systems:

1. Windows 11
2. Max OS Monterey-Tahoe
3. Ubuntu 22

Clone the repository

Clone the Elements repository from HERE

Checkout to the feature/develop branch:

Visual studio code preparation

Download the python extension in your visual studio code

Open the Elements folder with the visual studio code

Installing Anaconda for python environment handling

We suggest to download the Anaconda package management system to keep your system clean (optional step)

Download the proper Anaconda python distribution based on your system.

For Windows users, make sure you add Anaconda to the PATH environmental variable.

Creating a new python 3.9 environment

Open a new command prompt (Ctrl + Shift + `) in visual studio code:

Create a new elements conda environment with the command:

conda create -n elements python=3.9

This creates a new environment, named elements, with a python version 3.9, which is the proper version to run Elements.

You may now activate the environment by running:

`conda activate elements`

⚠️ For linux users do the following, you need to setup the variable PYOPENGL_PLATFORM to x11:

1. In terminal, run `nano ~/.bashrc`
2. Add the command ‘export PYOPENGL_PLATFORM=x11’ at the end of the file.
3. Save and quit.
4. Run ‘source ~/.bashrc’ for the changes to take effect.

Select the python Interpreter

⚠️ You need to select the proper python interpreter before running any example or test.

Click the python version button on the bottom right and select the elements environment we created.

If the elements interpreter is not shown, click refresh to update the list.

Sometimes, you may need to restart VSCode to refresh the list of environments!

Installing Elements on your environment

Install the needed packages to your elements environment with the following command:

pip install -e .

Your Elements project is now ready!

Run the unit Tests

Running the included unit tests assures that your installation is proper and complete.

Click the unit test icon on the left side panel. You may run a test by clicking the run test button.

Make sure that all the tests run properly.

If the unit tests are not visible like the image above do the following

1. Make sure you have selected the correct interpreter: Click View>Command Palette, select Python: Select Interpeter and choose Elements (the 3.9.x environment you have previously created).

2. Configure the tests properly: Click View>Command Palette again, select: Python: Configure Tests, select unittest, select the . Root directory option, and finally select the test_*.py option.

The unit tests should appear in the list on the left panel!

Run the examples

Now let's run some Elements examples.

Navigate, e.g., to the examples/B.Introductory folder and click the example_B5_cube_free_fly example.

Then, press small play button on the top right of the file (or usually the F5 button) to run the example.

Contributing to the Elements project

In order to contribute to contribute to the Elements package:

1. Fork the develop branch.

2. Clone your forked repo to your computer.

3. Install it in editable mode by running:

   pip3 install -e .

at the directory where the setup.py file is located.

4. Create a feature branch from the develop branch, and work on it.
5. Push your feature branch to your github repo.
6. Open a Pull Request to the original develop branch.