This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Installation

1: Ubuntu
2: Linux using docker
3: Raspberry Pi 4
4: Windows 10

1 - Ubuntu

Dependencies

Install the following packages in your system if they not available yet:

1
2
3
sudo apt install \
    build-essential \
    clang

Bazel:

1
2
3
4
curl https://bazel.build/bazel-release.pub.gpg | sudo apt-key add -
echo "deb [arch=amd64] https://storage.googleapis.com/bazel-apt stable jdk1.8" | sudo tee /etc/apt/sources.list.d/bazel.list
sudo apt update
sudo apt install bazel

LunarG Vulkan SDK:

1
2
3
4
wget -qO - https://packages.lunarg.com/lunarg-signing-key-pub.asc | sudo apt-key add -
sudo wget -qO /etc/apt/sources.list.d/lunarg-vulkan-1.3.211-focal.list https://packages.lunarg.com/vulkan/1.3.211/lunarg-vulkan-1.3.211-focal.list
sudo apt update
sudo apt install vulkan-sdk

Verify that the SDK was successfully installed by running:

1
vulkaninfo

Python3 dependencies
1
sudo apt install python3-pip

Build C++ Libraries

Clone and compile Lluvia’s C++ libraries:

1
2
3
4
5
6
7
git clone https://github.com/jadarve/lluvia.git
cd lluvia

# install requirements listed in lluvia's root folder
sudo python3 -m pip install -r requirements.txt

bazel build //lluvia/cpp/...

Run the tests to verify that your compilation runs properly:

1
bazel test //lluvia/cpp/...

Python3 package

To build the Python3 package, execute the commands below from the repository’s top-level directory. You can create a virtual environment to isolate the installation:

1
2
bazel build //lluvia/python:lluvia_wheel
pip3 install bazel-bin/lluvia/python/lluvia-0.0.1-py3-none-any.whl

Open a Python3 interpreter and import lluvia:

1
2
3
import lluvia as ll

session = ll.createSession()

If the import completes successfully, lluvia is ready to use.

2 - Linux using docker

Install docker following the official documentation and the post installation guide.

Clone lluvia and build the container

1
2
3
4
git clone https://github.com/jadarve/lluvia.git
cd lluvia

docker build ci/ --tag="lluvia:local"

Run the container, mounting lluvia’s repository at /lluvia:

1
2
3
docker run \
    --mount type=bind,source="$(pwd)",target=/lluvia \
    -it --rm "lluvia:local" /bin/bash

Inside the container, build and test all of lluvia package:

1
2
3
cd lluvia
bazel build //...
bazel test --test_output=errors //...

3 - Raspberry Pi 4

Raspberry Pi config

OS Installation

On the desktop machine, download the Raspberry Pi Imager and install a fresh version of the operating system in a micro SD card.

1
sudo apt install rpi-imager

Go to extra settings and enable SSH access, configure the WiFi, if needed. Click in write and wait for the process to complete.

Insert the micro SD card in the RPi and next, update and upgrade the operating system:

1
2
3
4
sudo apt update
sudo apt upgrade

sudo reboot

Expand storage

1
sudo raspi-config

1
sudo reboot

Increase swap memory

Some of the instructions bellow require more memory than the one available in the RPi4. For this, it is recommended to increase the SWAP memory available to the system so that compilation does not fail unexpectedly. Open the /sbin/dphys-swapfile and /etc/dphys-swapfile, and edit the line CONF_MAXSWAP=<some_value> to 4096. After it, reboot the RPi.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# unmount the swap
sudo dphys-swapfile swapoff

# edit the swap configuration to:
# CONF_SWAPSIZE=2048 
# CONF_MAXSWAP=4096
sudo nano /sbin/dphys-swapfile
sudo nano /etc/dphys-swapfile

# configure with new values
sudo dphys-swapfile setup

# start swap
sudo dphys-swapfile swapon

Camera module

If you have a camera module available, you can enable it by following the official guide

1
sudo raspi-config

1
sudo reboot

Vulkan SDK

Installation guide

The official installation instructions are available in the LunarG website.

Dependencies

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
sudo apt install -y \
  bison \
  cmake \
  g++ \
  gcc \
  git \
  libglm-dev \
  liblz4-dev \
  libmirclient-dev \
  libpciaccess0 \
  libpng-dev \
  libwayland-dev \
  libx11-dev \
  libx11-xcb-dev \
  libxcb-dri3-0 \
  libxcb-dri3-dev \
  libxcb-ewmh-dev \
  libxcb-keysyms1-dev \
  libxcb-present0 \
  libxcb-randr0-dev \
  libxml2-dev \
  libxrandr-dev \
  libzstd-dev \
  mesa-vulkan-drivers \
  ninja-build \
  ocaml-core \
  pkg-config \
  python \
  python3 \
  python3-distutils \
  qt5-qmake \
  qtbase5-dev \
  qtbase5-dev-tools \
  qtcreator \
  vulkan-tools
  wayland-protocols

Build and install

Download and build the Vulkan SDK

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
mkdir -p ~/local/vulkan
cd ~/local/vulkan

wget -O vulkansdk.tar.gz \
  https://sdk.lunarg.com/sdk/download/1.3.231.2/linux/vulkansdk-linux-x86_64-1.3.231.2.tar.gz

tar -xvf vulkansdk.tar.gz

# remove archive to save space
rm vulkansdk.tar.gz

cd 1.3.231.2

# remove prebuilt x86_64 libraries are not needed in the RPi
rm -rf x86_64

# build the SDK

./vulkansdk -j 4 glslang
./vulkansdk -j 4 vulkan-headers
./vulkansdk -j 4 vulkan-loader
./vulkansdk -j 2 vulkan-validationlayers  # this one consumes all the RAM and uses SWAP memory
./vulkansdk -j 4 vulkan-tools
./vulkansdk -j 4 vulkantools
./vulkansdk -j 4 shaderc
./vulkansdk -j 4 spirv-headers
./vulkansdk -j 4 spirv-tools
./vulkansdk -j 4 spirv-cross
./vulkansdk -j 4 gfxreconstruct
./vulkansdk -j 4 spirv-reflect
./vulkansdk -j 4 vulkan-extensionlayer
./vulkansdk -j 4 vulkan-profiles
./vulkansdk -j 4 DirectXShaderCompiler
./vulkansdk -j 4 volk
./vulkansdk -j 4 VulkanMemoryAllocator
./vulkansdk -j 4 VulkanCapsViewer

Configure the VULKAN_SDK environment variable permanently in the system:

1
2
3
4
5
6
# edit .bashrc or .zshrc accordingly
nano .bashrc

# include the following environment variables at the end of the file
export VULKAN_SDK=~/local/vulkan/1.3.231.2/aarch64                                          
export PATH=$VULKAN_SDK/bin:$PATH

Reload the profile:

1
2
cd
source .bashrc

Install the SDK in the system:

1
2
3
4
5
6
7
sudo cp -r $VULKAN_SDK/include/vulkan/ /usr/local/include/
sudo cp -P $VULKAN_SDK/lib/libvulkan.so* /usr/local/lib/
sudo cp $VULKAN_SDK/lib/libVkLayer_*.so /usr/local/lib/
sudo mkdir -p /usr/local/share/vulkan/explicit_layer.d
sudo cp $VULKAN_SDK/etc/vulkan/explicit_layer.d/VkLayer_*.json /usr/local/share/vulkan/explicit_layer.d

sudo ldconfig

System installation

It is important to install the vulkan libraries as part of the operating system. When Bazel runs the Lluvia tests, is not able to find the layer libraries from the VULKAN_SDK environment variable.

OpenCV

Installation guide

The instructions below are extracted from:

Dependencies

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
sudo apt install -y \
    build-essential \
    cmake \
    gfortran \
    gstreamer1.0-gl \
    gstreamer1.0-gtk3 \
    libatlas-base-dev \
    libavcodec-dev \
    libavformat-dev \
    libblas-dev \
    libcanberra-gtk* \
    libdc1394-22-dev \
    libgif-dev
    libgstreamer-plugins-base1.0-dev \
    libgstreamer1.0-dev \
    libgtk-3-dev \
    libgtk2.0-dev \
    libhdf5-dev \
    libjasper-dev \
    libjpeg-dev \
    liblapack-dev \
    libopenblas-dev \
    libpng-dev \
    libswscale-dev \
    libtbb-dev \
    libtbb2 \
    libtiff-dev \
    libv4l-dev \
    libx264-dev \
    libxvidcore-dev \
    pkg-config \
    protobuf-compiler \
    python3-dev \
    python3-numpy \
    unzip

Build

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
mkdir -p ~/local/opencv && cd ~/local/opencv

# Download and unpack sources
wget -O opencv_contrib.zip https://github.com/opencv/opencv_contrib/archive/4.5.2.zip
wget -O opencv.zip https://github.com/opencv/opencv/archive/4.5.2.zip

unzip opencv.zip
unzip opencv_contrib.zip

mv opencv-4.5.2 opencv
mv opencv_contrib-4.5.2 opencv_contrib

# remove archives
rm opencv.zip
rm opencv_contrib.zip

# Create build directory and switch into it
mkdir -p opencv/build && cd opencv/build

# Configure
cmake -D CMAKE_BUILD_TYPE=RELEASE \
-D CMAKE_INSTALL_PREFIX=/usr/local \
-D OPENCV_EXTRA_MODULES_PATH=~/local/opencv/opencv_contrib/modules \
-D ENABLE_NEON=ON \
-D WITH_OPENMP=ON \
-D WITH_OPENCL=OFF \
-D BUILD_ZLIB=ON \
-D BUILD_TIFF=ON \
-D WITH_FFMPEG=ON \
-D WITH_TBB=ON \
-D BUILD_TBB=ON \
-D BUILD_TESTS=OFF \
-D WITH_EIGEN=OFF \
-D WITH_GSTREAMER=ON \
-D WITH_V4L=ON \
-D WITH_LIBV4L=ON \
-D WITH_VTK=OFF \
-D WITH_QT=OFF \
-D OPENCV_ENABLE_NONFREE=ON \
-D INSTALL_C_EXAMPLES=OFF \
-D INSTALL_PYTHON_EXAMPLES=OFF \
-D BUILD_opencv_python3=TRUE \
-D OPENCV_GENERATE_PKGCONFIG=ON \
-D BUILD_EXAMPLES=OFF ..

# Build
make -j 4

# Install
sudo make install

Lluvia

Bazel

1
2
3
4
wget -O bazel https://github.com/bazelbuild/bazel/releases/download/5.3.2/bazel-5.3.2-linux-arm64

chmod +x bazel
sudo mv bazel /usr/local/bin

Build and install C++ and Python packages

Install clang compiler

1
sudo apt install -y clang

Clone and build Lluvia

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
git clone https://github.com/jadarve/lluvia.git
cd lluvia

# install requirements listed in lluvia's root folder
sudo python3 -m pip install -r requirements.txt

bazel build //lluvia/cpp/...

# Run the tests to verify runtime is configured propertly
bazel test //lluvia/cpp/...

# Build and install the python wheel
bazel build //lluvia/python:lluvia_wheel
python3 -m pip install bazel-bin/lluvia/python/lluvia-0.0.1-py3-none-any.whl

Examples

With the Raspberry Pi camera module installed, it is possible to run the webcam demo located at samples/webcam/webcam.py. The command below configures the camera to output images at 320x240 resolution and fed to the webcam/HornSchunck container node, defined in the horn_schunck.lua script:

1
2
./samples/webcam/webcam.py --width=320 --height=240 \
  ./samples/webcam/scripts/horn_schunck.lua webcam/HornSchunck

The resulting color-encoded optical flow is displayed in a second window.

4 - Windows 10

Dependencies

Python2. This is needed for Bazel to be able to run Python binaries
1 2 3
choco install python2 python -m pip install jinja2

Python3 dependencies

1
pip3 install cython numpy pytest jinja2 markupsafe

Vulkan SDK: follow the official installation instructions from LunarG.
Bazel: follow the official installation guide from bazel.build.

Clone and configure the repository

Clone the Lluvia repository from Github:

1
2
git clone https://github.com/jadarve/lluvia.git
cd lluvia

Open platform/values.bzl and change the paths to Python2 and Python3 according to your installation. Initially the file looks like this:

1
2
3
4
5
6
7
8
9
# Linux
python2_path_linux = "/usr/bin/python2"
python3_path_linux = "/usr/bin/python3"

# Windows
python2_path_windows = "C:/Python27/python.exe"

# get this value by running where.exe python3
python3_path_windows = "C:/hostedtoolcache/windows/Python/3.7.9/x64/python3.exe"

Build the C++ libraries

1
bazel build //lluvia/cpp/...

Run the tests to verify that your compilation runs properly:

1
bazel test //lluvia/cpp/...

Python3 package

To build the Python3 package, execute the commands below from the repository’s top-level directory.

1
2
bazel build //lluvia/python:lluvia_wheel
pip3 install bazel-bin/lluvia/python/lluvia-0.0.1-py3-none-any.whl

Open a Python3 interpreter and import lluvia package

1
2
3
import lluvia as ll

session = ll.createSession()

If the import completes successfully, lluvia is ready to use.