CVWorkspace is a collection of scripts, which simplify the process of simultaneous installation of various computer vision frameworks.

Please note, that this work targets computer vision developers with experience in different deep learning and computer vision frameworks, various build tools and so on. If you are a beginner, it is recommended to use official installation instructions.

Different deep learning frameworks provide different functionality for computer vision tasks, be it research or production. Having experience with many of open source tools, we know their advantages and drawbacks and that one computer vision tool is nearly never enough to fully solve challenging real world task.

Most of the frameworks come with their own pre-built packages or dockerfiles which are supposed to be built separately. While being natural, such situation obstructs use of all the strong sides of different frameworks at once.

This work aims to be a small step towards placing the great open source tools together.

This section presents a list of core design concepts with their rationale and introduces the scripts' organisation structure.

The collection of scripts is organised as follows

1. Top level scripts
   
   config.sh – configuration script
   install.sh – the main installation script
   versions.sh – specifies versions of libraries to be installed
   

2. Folders
   
   base deps – contains scripts which install base dependencies of the frameworks to be built
   frameworks – contains scripts which target deep learning frameworks and their computer vision ecosystems
   additional – provides various additional installation scripts for tools, which are not necessary for deep learning frameworks, but are of common usage in computer vision community
   production – provides production specific installation scripts.

config.sh has the core variable WORKSPACE_BASE which specifies the installation folder for your frameworks and their dependencies.
The other important variable in config.sh to note is SOURCE_SETUP_SCRIPT_IN_BASHRC. Export it to 1, if you want the CVWorkspace environment to be immediately initialised on every new bash terminal.

The usage of CVWorkspace consists of four installation steps:

1. CUDA
2. Base dependencies
3. Frameworks with their computer vision ecosystems
4. Additional and production components.

Suppose, you have clear Ubuntu 18.04 or Ubuntu 20.04.
The following sections separately describe each of the steps.

CUDA is being installed separately from the main script install.sh.
cd to CVWorkspace/additional/cuda and run

sudo bash -i install_cuda.sh

It will install CUDA 11.2 and appropriate nvidia driver at the same time.
Please, restart your computer afterwards for the changes to take effect.

Installing cuDNN is perhaps the most inconvinient job for the CVWorksapce user.
Please, download the latest cudnn archive compatible with CUDA 11.2 from official NVIDIA web site. NVIDIA wants users to be logged in before accessing it.

Once cuDNN archive has been downloaded, please modify install_cudnn.sh, so that the variable CUDNN_ARCHIVE referes to your cuDNN archive. Afterwards the installation is performed with the command

sudo bash -i install_cudnn.sh

To install base dependencies export WITH_BASE_DEPS with value 1

export WITH_BASE_DEPS=1

Installing base dependencies is performed with running the command

bash -i install.sh

To install a deep learning framework, say Pytorch, export its option variable with value 1

export WITH_PYTORCH=1

and run

bash -i install.sh

The same applies for the framework-specific computer vision ecosystems, say Detectron2. First the appropriate variables are set

export WITH_TORCHVISION=1
export WITH_FVCORE=1
export WITH_DETECTRON2=1

and then install.sh is called

bash -i install.sh

The following table summarises frameworks and the appropriate switches

The following table summarises computer vision environments on top of deep learning frameworks and the appropriate switches

The additional and production components target specific use cases, which are common in computer vision research and industry.

Installation of additional and production components is performed in the same fashion, as frameworks. Say, to install FFmpeg, first the option has to be set

export WITH_FFMPEG=1

and then install.sh ran

bash -i install.sh

The additional components include

1. Dataset Converters – a conversion toolset between different object detection and instance segmentation dataset formats
2. FFmpeg – vast software and library suite to handle, in particular, video streams
3. OpenVINO – a toolset to deploy trained models on Intel devices (CPU, HD Graphics, Myriad X based).

The following table summarises additional components and their switch options

Note. ffmpeg executable is being searched by torchvision's setup script. If you have FFmpeg installed before torchvision, you may face torchvision build issues.

Note. It is recommended to use official OpenVINO installers, provided by Intel. One cannot reproduce them from source, because of lack of special tools. OpenVINO build is workable only on Ubuntu 18.04.

The production components include

CryptoPP – a C++ library to encrypt your trained models, when deploying them in production

The following table summarises production components and their switch options

To activate built workspace, source LIBS_BASE/setup.sh script, by default located in WORKSPACE_BASE/libs

source $LIBS_BASE/setup.sh

The base components are

1. Git, Wget, GNU build essentials
2. CMake and Bazel build systems
3. Python with framework dependency packages
4. Various C++ libs required for framework build.

Git, Wget, GNU build essentials (gcc, g++, gfortran), as well as Python are installed globally at root level.

Python version installed is 3.7.

The Python packages are being installed in WORKSPACE_BASE folder as a virtual environment via pipenv. All the C++ deps, as well as CMake and Bazel are locally installed in WORKSPACE_BASE.

Such separation of environment allows user to choose different python packages, C++ libraries and build tools between different installations of CVWorkspace.

For more advanced understanding of the installed CVWorkspace structure, please refer to file LIBS_BASE/setup.sh.

Note. The options in the files described here are for advanced research development and not recommended to change if you feel unconfident with their meaning.

Deep learning frameworks are often changed by the user in projects, where some new techniques are invented. If you are doing serious research or production development, you know, that reproducibility of results is a must. That includes reproducibility of the environment, where the result were achieved. Given how much changes are often done and in different tools this environment reproducibility task is often not trivial.

To solve it, the advanced configuration files are presented in the folder

frameworks/advanced_config

set_checkout_targets.sh – allows to checkout concrete branch and even commit by its hash
set_patches.sh – allows to systematize your patches done to the framework during development on top of the branch/commit hash
set_urls.sh – allows to use your private forks as a base framework url in case of serious changes.

To reproduce concrete python environment, it can be specified with Pipfile, which is passed to CVWorkspace with WITH_PIPFILE option.

To specify concrete CVWorkspace revision, which was used to generate the experiment environment, please export CVWORKSPACE_CHECKOUT_TARGET variable.

Sometimes CVWorkspace can be useful for the experiment environment specification, but lacks some functionality. One can pass needed modifications as a patch on top of CVWORKSPACE_CHECKOUT_TARGET by exporting CVWORKSPACE_PATCH variable.

Note. Additionally frameworks/advanced_config contains set_build_types.sh. It defines variables to build frameworks and some ecosystems with debugging symbols to simplify understanding and debugging of complicated implementation details.

CVWorkspace is intended to be non-commercial work with open source spirit and contributions are highly welcome.

The expected contribution conditions are

• you agree, that your contributions are MIT-licensed
• contributed code is written from scratch and does not have parts copied from other repositories.