Setting Up the Dev Environment

Note

This is NOT for the console computer but your personal laptop or PC

Setup of MRI4ALL development environment

By going through these instructions, you will create a development environment for the MRI4ALL console software. It will create a new virtual machine (using VirtualBox), install all required dependencies, and checkout the latest version from the console repository. Programming work is best done using Visual Studio Code running on the host computer and connecting into the virtual machine via the "Remote SSH Extension".

NOTE: These instructions have been written for systems with Intel/AMD CPUs (e.g., running Windows or Linux). Newer Apple Macintosh systems with M1 or M2 systems are not able to run regular virtual machines. For setting up a dev environment on those machines, Python and the needed packages need to be installed natively (without VM). Look inside the installation script install.sh to see the required packages. It is recommended to setup a separate virtual environment (venv) for Python before installing the packages.

General installation

The virtual machine runs under VirtualBox and is provisioned using the open-source tool Vagrant. Both tools first need to be installed on your host computer.

• Install VirtualBox from https://www.virtualbox.org (7.0.10 or later)

• Install Vagrant from https://www.vagrantup.com (2.3.7 or later)

• Create folder for MRI4ALL VM, e.g. C:\mri4all

• Download the files "Vagrantfile" and "install.sh" from the MRI4ALL console repository (https://github.com/mri4all/console/tree/main/installation) and copy them into folder (Note:: Make sure that the browser does not add any extension to the file "Vagrantfile")

• Open a command shell and go to the folder (e.g., cd C:\mri4all)

• Create the virtual machine by calling “vagrant up”. This process will take several minutes (~ 5 minutes). You will see the output from the installation process in the command shell. When done, you will see "Installation complete.".

• You can stop the virtual machine with "vagrant halt", restart it with "vagrant up", and get an SSH shell with "vagrant ssh". The VM can be deleted with "vagrant destroy".

Setup of Visual Studio Code

• Install Visual Studio Code on your host computer (https://code.visualstudio.com)

• Open Visual Studio Code and install the following VS Code extensions (via the tool bar on the left): “Remote – SSH”, “Remote – SSH: Editing Configuration Files”, “Remote Explorer”

• Other (optional) recommended extensions: “Python”, “Pylance”, “Git Graph”, “Code Spell Checker”, "Pretty_imports", "GitHub copilot" or "Intellicode", "GitHub Actions", "Link GitHub Issues"

• When the VM is running, click on the bottom left icon in VS Code (“Open a Remote Window”) and select “Connect to Host”. Then click “Configure SSH Hosts…”. Add the following section to the configuration file (assuming the VM has been created in C:\mri4all) and save the configuration:

Host mri4all
  HostName 127.0.0.1
  User vagrant
  Port 2222
  UserKnownHostsFile /dev/null
  StrictHostKeyChecking no
  PasswordAuthentication no
  IdentityFile C:/mri4all/.vagrant/machines/default/virtualbox/private_key
  IdentitiesOnly yes
  LogLevel FATAL  

• Now, click on “Connect to Host” again and select mri4all from the list. During the first run, select “Linux” as Operating system. VS Code will now install the server application inside the VM. Afterwards, click on "Open Folder". The mri4all installation folder is at “/opt/mri4all/console”.

Git Setup

Since VS Code is running on your host computer, it will use the GitHub credentials stored on your host computer for authenticating commits to the MRI4ALL repositories such as console. Thus, you don't need to enter any credentials within the VM. However, you need to let Git in the VM know your identity. Do do this, open a VM Terminal from within VS Code (using Terminal -> New Terminal). Then, type the following two commands:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Code pulls and commits can now be done using the "Source Control" tab on the left side of VS Code (third icon from top).

Starting MRI4ALL applications

To start and test the MRI4ALL services, open a terminal in VS Code. Activate the Python virtual environment with the following command:

source /opt/mri4all/env/bin/activate

Now you can start any of the Python programs in the folder /opt/mri4all/console (e.g., "python run_acq.py" for the acquisition service). Running the UI services requires the graphical frontend (X11). To start and open the X11 UI, go to the VirtualBox VM window that appeared when you started the VM. It should show a text based login screen. Login with the username "vagrant" (password "vagrant"). On the command shell type:

startx

This should now start the XFCE window manager. Open a terminal shell ("Terminal Emulator" in the top-left menu), activate the Python virtual environment, and start the UI service with:

source /opt/mri4all/env/bin/activate
cd /opt/mri4all/console
python run_ui.py

Forms for the UI (.ui files) can be created/modified with the "Qt Creator" which provides a graphical form editor. Qt Creator can be started with:

qtcreator

Advanced VM settings

After shutting down the VM ("vagrant halt"), the configuration of the VM can be modified via the VirtualBox GUI. Select the VM in the list and click on "Settings". To make the graphics display faster, click on "Display" and select "Graphics Controller: VMSVGA" and "Enable 3D Acceleration". Depending on your computer's configuration, you can assign more memory and CPU cores to the VM on the "System" page.

Tweaks

Adding venv to Bash script

If you plan to only use the main development location for the MRI4ALL console software, consider adding the following line to the .bashrc file in your home folder. This way, the virtual Python environment is automatically selected when open a shell. You can edit the .bashrc file with the "nano" command:

cd ~
nano .bashrc

Insert the following line at the end of the file and save:

source /opt/mri4all/env/bin/activate

Selecting correct Python environment in Visual Studio Code

By default, VS Code does not know which Python virtual environment to use for checking (lynting) the MRI4ALL code and will use the default Python version. Because PyQt gets installed in the virtual environment, it cannot resolve the Qt references (Qt references are underlined in yellow). This can be solved by selecting the correct Python interpreter in Visual Studio Code.

• Press CTRL-SHIT-P to open the VS Code Commandshell.
• Type in "Python: Select Interpreter".
• Select "Enter interpreter path..."
• Select "/opt/mri4all/env/bin/python"

Afterwards, the yellow underlining of Qt references should be gone.

Getting files in/out of the Dev Environment

If you want to copy files into the Dev Environment (e.g., image files that should be added to the repository), copy them to the Vagrant folder on your host computer (where you had placed the Vagrantfile and install.sh files). This folder is automatically mounted into the VM under the path /vagrant, so that you can then access the files from within the VM (e.g., in a VS Code Terminal or in the X11 window). Using this mechanism, you can also get files out of the VM.

If you want to add small text files (e.g., a source code file that you want to add to the repo), you can also drag-and-drop it to the left "Explorer" bar of Visual Studio Code.

Restarting the X11 environment

If there should be problems with the X11 window (this sometimes happens when Bidirectional Drag-and-Drop is enabled in VirtualBox -- so it's better to keep that option off), you can restart the XFCE4 window manager by pressing Alt-F4 and selecting "Logout". Afterwards, you can restart the window manager with "startx" again.