Getting started

The Social Interaction Cloud (SIC) is a native python framework. It can be used via the social-interaction-cloud python package. The framework uses Redis for message brokering. To help you get started you can clone the sic_applications repository. Below you will find the basic instructions for cloning the repository and setting up the Social Interaction Cloud.

General prerequisites

Python >= 3.10, <= 3.12

Latest version of SIC

2.0.20

If you want to upgrade to the latest version, run this command in your venv:

pip install social-interaction-cloud --upgrade

Install

Below you can find the installation instructions for Linux, MacOS, and Windows.

In these instructions we will perform git operations through a basic terminal and use Python's standard venv to create a virtual environment. If you're more familiar with other tools like PyCharm, VisualStudio, or Conda, feel free to use them instead. It is advised not to mix venvs. If you are going to use Python’s standard venv, do not mix it with your conda environment, as it might lead to unexpected behavior.

You can watch this video as well (Windows): Tutorial 1: Getting Started

Instructions

# Install git/redis/system dependencies for pyaudio
sudo apt update
sudo apt install git redis portaudio19-dev python3-pyaudio

# Clone the sic_applications repo
git clone https://github.com/Social-AI-VU/sic_applications.git

# Create and activate virtual environment within the sic_applications folder
cd sic_applications
python -m venv venv_sic
source venv_sic/bin/activate

# Install social-interaction-cloud
pip install social-interaction-cloud

# Recommended on linux & mac: install libturbo-jpeg
sudo apt-get install -y libturbojpeg
pip install -U git+https://github.com/lilohuang/PyTurboJPEG.git

# Install git/redis/system dependencies for pyaudio
brew install git redis portaudio

# Clone the sic_applications repo
git clone https://github.com/Social-AI-VU/sic_applications.git

# Create and activate virtual environment within the sic_applications folder
cd sic_applications
python -m venv venv_sic
source venv_sic/bin/activate

# Install social-interaction-cloud
pip install social-interaction-cloud

# Recommended on linux & mac: install libturbo-jpeg
brew install jpeg-turbo
pip install -U git+https://github.com/lilohuang/PyTurboJPEG.git

For Windows users, the installation is not as as straightforward as for Ubuntu or Mac users, but it’s also fairly simple.

Go to the official Git Download for Windows and download the latest version of the installer. A file named Git-2.xx.xx-64-bit.exe should be downloaded.
Run the downloaded installer. You can keep the default settings by clicking Next through each step, and then click Install at the end.
After installation: open git Bash and run the following commands.

# Clone the sic_applications repo
git clone https://github.com/Social-AI-VU/sic_applications.git

# Create and activate virtual environment within the sic_applications folder
cd sic_applications
python -m venv venv_sic
.\venv_sic\Scripts\activate

# Install social-interaction-cloud
pip install social-interaction-cloud

Optional Install libturbo-jpeg

Download and run installer from https://sourceforge.net/projects/libjpeg-turbo/files/2.1.5.1/libjpeg-turbo-2.1.5.1-gcc64.exe/download
Add the bin folder where you installed libjpeg-turb to the PATH environment variable (see e.g. How to Change the PATH Environment Variable on Windows: 14 Steps for how to do this)
Make sure that the dll is called turbojpeg.dll (e.g. by copying and renaming libturbojpeg.dll)
Pip Install PyTurboJPEG via

If you somehow can’t make git clone work, just go to the repository sic_applications , click the Code button. A drop down menu will appear. In this menu, you will see an option that says Download ZIP. Click on it.

Running your first application

Running any application consists of two (or three) steps:

Start Redis
(Optional) Start a service, such as face detection
Run your program

We will cover two examples: running an application without a service (step 1 and 3) and with a service (step 1, 2, and 3).

Example 1: Running an application without a service

For this example we will show your computer’s camera output on your screen. The code for this example is available in the sic_applications/demos folder and called demo_desktop_camera.py. An equivalent example showing Nao’s camera output can be found here Display an image from the robot

Step 1: starting Redis on your laptop

To enable communication between all your devices, we have to start Redis server. Make sure Redis is always up and running when you run any demos.

Step 3: running an application

To start the camera demo from the terminal, use the following commands.

If all goes well, a display should pop up showing you the camera output from your webcam!

And you should get the following output:

Troubleshoot

Example 2: running an application with a service

In this example we will use the face detection service to draw a bounding box around a face that is detected in your laptop camera feed. It uses the sic_applications/demos demo_desktop_camera_facedetection.py.

The Available services page provides more details about which services are available, how to use them, and how to extend them.

Step 1: starting Redis on your laptop

It is the same as in example 1.

Step 2: run the service

Services might need additional dependencies installed before being able to run them. You can install them with the appropriate service tag. For example,

A service can easily be run by opening a new terminal and calling the run-service command, for example run-face-detectionor run-dialogflow. See the Available services page for more info about the dependencies and run commands for each service.

Note: the --upgrade ensures the new dependencies are installed if you already have previously installed the social interaction cloud.

For our example we will start the face-detection service.

If successful you should get the following output:

Step 3: run the application

Run the demo file demo_desktop_camera_facedetection.py.

If all goes well, a display should pop up showing a bounding box around the detected face! If the image appears upside down, go to line 34 in demo_desktop_camera_facedetection.py and change the flip parameter to -1.

And that's it! 🎉

Go have some fun with robots, see Getting started with the Nao robot | Starting SIC on the Robot (NAOv6) and Getting started with Franka Emika Research 3.