######################################################################################################################

#

# JeVois Smart Embedded Machine Vision Toolkit - Copyright (C) 2016 by Laurent Itti, the University of Southern

# California (USC), and iLab at USC. See http://iLab.usc.edu and http://jevois.org for information about this project.

#

# This file is part of the JeVois Smart Embedded Machine Vision Toolkit. This program is free software; you can

# redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software

# Foundation, version 2. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;

# without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public

# License for more details. You should have received a copy of the GNU General Public License along with this program;

# if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

#

# Contact information: Laurent Itti - 3641 Watt Way, HNB-07A - Los Angeles, CA 90089-2520 - USA.

# Tel: +1 213 740 3527 - itti@pollux.usc.edu - http://iLab.usc.edu - http://jevois.org

######################################################################################################################

####################################################################################################

JeVois embedded machine vision framework INSTALL

####################################################################################################

This guide assumes a fresh Ubuntu 16.04 (xenial) install. For more recent versions of Ubuntu, replace 'xenial' below by

the code name of your version (e.g., artful for 17.10, bionic for 18.04, etc)

jevois is a C++17 software framework for real-time machine vision running on smart cameras

See http://jevois.org for full documentation.

See https://github.com/jevois for full source code.

On GitHub, the master branch is for stable releases, minor patch work, or addition of new features that do not break the

current release version. More disruptive development is in devX.Y branches.

JeVois software is organized into five top-level packages:

- jevois: The core C++17 JeVois software.

- jevoisbase: The base collection of 25+ machine vision modules for JeVois.

- samplemodule: A sample standalone module for JeVois written in C++, to use as a template for new modules.

- samplepythonmodule: A sample standalone module for JeVois written in Python, to use as a template for new modules.

- jevois-sdk: The framework that provides a Linux kernel and operating system for a JeVois camera, to be flashed

to a microSD card.

This guide is for developers. If you just want to use a JeVois smart camera, and possibly do some additional machine

vision development in Python only, you should just download a pre-build microSD card image from http://jevois.org/start

as you do not need any of what is described here.

####################################################################################################

Installation using Ubuntu packages (for most people except Linux kernel hackers)

####################################################################################################

JeVois provides Ubuntu packages that will pull in all the dependencies required to run JeVois software and develop for

JeVois.

See http://jevois.usc.edu for the latest instructions as they may be updated more often than this INSTALL file. In

summary:

You need at least 30GB free space in your root partition.

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys DD24C027

sudo add-apt-repository "deb http://jevois.usc.edu/apt xenial main" # replace xenial by artful, bionic, etc if needed

sudo apt update

sudo apt upgrade

- If you want everything to be able to compile C++ modules for JeVois and flash to microSD:

sudo apt install jevois-sdk-dev

Will install:

+ jevois-opencv: OpenCV compiled for your host computer (amd64) and installed in /usr/share/jevois-opencv-x.y.z

so that it will not interfere with any other OpenCV installation you might already have.

+ jevois-host: pre-compiled JeVois core software to run on your host computer.

+ jevois-platform: pre-compiled JeVois core software to flash to microSD and run inside the smart camera.

+ jevoisbase-host: pre-compiled JeVois base suite of machine vision modules to run on your host computer.

+ jevoisbase-platform: pre-compiled JeVois base suite of machine vision modules to flash to microSD and run inside

the smart camera.

+ jevois-sdk: pre-compiled Linux kernel and operating system to be flashed to microSD and run inside the smart camera.

+ jevois-sdk-dev: cross-compilers, libraries, and tools to cross-compile new machine vision modules that will

run inside the smart camera.

+ and all the dependencies required by these packages.

- Or, depending on what you want to do:

If you just want to run JeVois software (jevois-daemon) on your host computer with a standard webcam:

sudo apt install jevois-host jevoisbase-host

Will install:

+ jevois-opencv: OpenCV compiled for your host computer (amd64) and installed in /usr/share/jevois-opencv-x.y.z

so that it will not interfere with any other OpenCV installation you might already have.

+ jevois-host: pre-compiled JeVois core software to run on your host computer.

+ jevoisbase-host: pre-compiled JeVois base suite of machine vision modules to run on your host computer.

+ and all the dependencies required by these packages.

If you want jevois and jevoisbase cross-compiled for the platform hardware:

sudo apt install jevois-platform jevoisbase-platform

Will install:

+ jevois-platform: pre-compiled JeVois core software to flash to microSD and run inside the smart camera.

+ jevoisbase-platform: pre-compiled JeVois base suite of machine vision modules to flash to microSD and run inside

the smart camera.

+ and all the dependencies required by these packages.

If you want to be able to flash a microSD card using jevois-flash-card:

sudo apt install jevois-sdk

+ jevois-opencv: OpenCV compiled for your host computer (amd64) and installed in /usr/share/jevois-opencv-x.y.z

so that it will not interfere with any other OpenCV installation you might already have.

+ jevois-host: pre-compiled JeVois core software to run on your host computer.

+ jevois-platform: pre-compiled JeVois core software to flash to microSD and run inside the smart camera.

+ jevoisbase-host: pre-compiled JeVois base suite of machine vision modules to run on your host computer.

+ jevoisbase-platform: pre-compiled JeVois base suite of machine vision modules to flash to microSD and run inside

the smart camera.

+ jevois-sdk: pre-compiled Linux kernel and operating system to be flashed to microSD and run inside the smart camera.

+ and all the dependencies required by these packages.

If you want to be able to cross-compile new modules for JeVois platform hardware:

sudo apt install jevois-sdk-dev

(installs everything, see above).

If you want to be able to recompile the platform Linux kernel or change the platform O.S. or add

new buildroot packages to the platform:

You need to install jevois-sdk-dev and then rebuild jevois-sdk from source. Follow the instructions in this

INSTALL file.

If you want to recompile jevois and/or jevoisbase, you will also need to get their source code from GitHub. See

instructions below related to downloading and compiling jevois and jevoisbase.

After you have installed at least jevois-host and jevoisbase-host, just plug in a USB camera and try

jevois-daemon

which should launch JeVois software compiled for the host computer. You should see the saliency demo in a window. You

can interact with the JeVois system by typing commands in the terminal in which you started jevois-daemon. For example,

try:

info

help

listmappings

To start jevois-daemon in a specific mode, find its number in the listmappings list, then type 'quit' to quit

jevois-daemon, and finally:

jevois-daemon --videomapping=19

to start it again in using that new video mapping (here, mapping 19 was for Demo QR-code according

to listmappings).

From there, go to http://jevois.org/doc

Note: If you want to recompile jevois and jevoisbase from the latest source on GitHub, you will first need to get them

from GitHub as well. See the programmer tutorials at http://jevois.org/tutorials for instructions.

####################################################################################################

Full installation from scratch

####################################################################################################

Only do this if you want to:

- re-compile the Linux kernel of JeVois, and/or

- change the operating system of JeVois (e.g., add new libraries or new programs)

Otherwise, see above

Getting JeVois to install from scratch for full developer capability requires several steps, outlined below:

1. Install some needed utilities and other packages on your Linux computer

2. Download the JeVois source code from GitHub.

3. Download and install OpenCV 3.4 specially configured for JeVois.

4. Setup jevois-sdk, cross-compile all the programs that will run on the camera, cross-compile its kernel.

5. Compile jevois and jevoisbase for host computer. You can then run it on your computer using any camera.

6. Cross-compile jevois and jevoisbase for the JeVois platform hardware.

7. Install the kernel, operating system, and cross-compiled jevois and jevoisbase to microSD.

Getting all these steps done will take some time. The most difficult step is to get the entire jevois-sdk, including

Linux kernel, cross-compiled from scratch -- this can easily take 10 hours. For this reason, you may bypass this step by

using the Ubuntu packages described above.

For all the commands below, we recommend that you copy and paste them one line at a time. If you have opened this

INSTALL file in emacs or firefox, you would do:

- triple left click on one line, which entirely selects it

- move mouse to a terminal window and middle-click to paste and run that one line

####################################################################################################

Install necessary packages on your host computer

####################################################################################################

The jevois-opencv Ubuntu package (which is a dependency of jevois-sdk-dev) will pull these. Since you should have

already installed jevois-sdk-dev as explained above, most likely you do not need to follow the instructions in this

section and you can skip to the next section.

For some Ubuntu 16.04LTS (xenial) based distros such as Mint18, you need to add:

deb http://cz.archive.ubuntu.com/ubuntu yakkety main universe

deb http://ppa.launchpad.net/ubuntu-toolchain-r/test

to /etc/apt/sources.list to get the necessary packages (including g++-6). You can remove them when done.

# Open a terminal, then type:

sudo apt-get update

sudo apt install build-essential gcc-6 g++-6 guvcview subversion cmake emacs git mercurial doxygen-gui graphviz

sudo apt install libboost-all-dev libjpeg-turbo8-dev autoconf libeigen3-dev screen lsb lib32stdc++6

sudo apt install gcc-4.7-arm-linux-gnueabi gcc-6-arm-linux-gnueabihf g++-6-arm-linux-gnueabihf gawk u-boot-tools

sudo apt install libgtk2.0-dev pkg-config python-dev python-numpy python-pip libdc1394-22 libdc1394-22-dev libjpeg-dev

sudo apt install libpng-dev libtiff5-dev libavcodec-dev libavformat-dev libswscale-dev libxine2-dev

sudo apt install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libv4l-dev libtbb2 libtbb-dev libqt4-dev

sudo apt install libfaac-dev libmp3lame-dev libopencore-amrnb-dev libopencore-amrwb-dev libtheora-dev libvorbis-dev

sudo apt install libxvidcore-dev x264 v4l-utils unzip qt5-default python3-dev python3-numpy python3-pip libgtk-3-dev

sudo apt install libatlas-base-dev gfortran libturbojpeg libgles2-mesa libgles2-mesa-dev

sudo ln -s /usr/bin/arm-linux-gnueabi-gcc-4.7 /usr/bin/arm-linux-gnueabi-gcc

sudo ln -s /usr/lib/x86_64-linux-gnu/libturbojpeg.so.0.?.0 /usr/lib/x86_64-linux-gnu/libturbojpeg.so

# to prevent nautilus from opening 3 windows each time you insert a JeVois microSD card:

gsettings set org.gnome.desktop.media-handling automount-open false

####################################################################################################

Download JeVois source code

####################################################################################################

cd

git clone https://github.com/jevois/jevois.git

git clone https://github.com/jevois/jevoisbase.git

git clone https://github.com/jevois/jevois-sdk.git

git clone https://github.com/jevois/samplemodule.git

git clone https://github.com/jevois/samplepythonmodule.git

git clone https://github.com/jevois/jevois-tutorials.git

# Set the following environment variables in your ~/.bashrc

# JEVOIS_ROOT is where we install machine vision modules for JeVois

# JEVOIS_SDK_ROOT is where you setup the jevois development kit that is used to build the linux kernel,

# libraries and packages cross-compiled for JeVois platform, etc

export JEVOIS_SDK_ROOT=${HOME}/jevois-sdk

export JEVOIS_ROOT=/jevois

# and close all terminals and open a new terminal to make sure the environment is refreshed.

####################################################################################################

ADVANCED: Installing OpenCV 3.4.0 on a Linux host system:

####################################################################################################

SHORTCUT: sudo apt install jevois-opencv

FROM SOURCE:

sudo apt install build-essential gcc-6 g++-6 gfortran-6 cmake libboost-all-dev autoconf libeigen3-dev libgtk2.0-dev

sudo apt install libdc1394-22 libdc1394-22-dev libjpeg-dev libpng-dev libtiff5-dev libavcodec-dev libavformat-dev

sudo apt install libswscale-dev libxine2-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libv4l-dev

sudo apt install libtbb-dev libqt4-dev libfaac-dev libmp3lame-dev libopencore-amrnb-dev libopencore-amrwb-dev

sudo apt install libtheora-dev libvorbis-dev libxvidcore-dev x264 v4l-utils unzip qt5-default python3.5-dev

sudo apt install python3-numpy python3-pip libgtk-3-dev libatlas-base-dev libturbojpeg

sudo apt install protobuf-compiler libprotobuf-dev

mkdir opencv

cd opencv

export ver="3.4.0"

export pyver="3.5" # or use 3.6 on Ubuntu 17.10 and later

wget https://github.com/opencv/opencv/archive/${ver}.tar.gz

tar zxvf ${ver}.tar.gz

rm -f ${ver}.tar.gz

wget https://github.com/opencv/opencv_contrib/archive/${ver}.tar.gz

tar zxvf ${ver}.tar.gz

rm -f ${ver}.tar.gz

cd opencv-${ver}

export opencvroot=`pwd`

mkdir build

cd build

cmake \

-DCMAKE_BUILD_TYPE=RELEASE \

-DCMAKE_INSTALL_PREFIX=/usr/share/jevois-opencv-${ver} \

-DCPACK_SET_DESTDIR=ON \

-DPYTHON_DEFAULT_EXECUTABLE=/usr/bin/python${pyver} -DPYTHON_EXECUTABLE=/usr/bin/python${pyver} \

-DWITH_TBB=ON -DWITH_V4L=ON -DWITH_QT=OFF -DWITH_OPENGL=OFF -DWITH_OPENCL=OFF -DWITH_VTK=OFF -DWITH_CUDA=OFF \

-DWITH_EIGEN=ON -DBUILD_opencv_python2=OFF -DENABLE_FAST_MATH=1 -DWITH_OPENMP=ON -DENABLE_CXX11=ON \

-DINSTALL_PYTHON_EXAMPLES=ON -DBUILD_EXAMPLES=ON -DINSTALL_C_EXAMPLES=OFF \

-DOPENCV_EXTRA_MODULES_PATH=${opencvroot}/opencv_contrib-${ver}/modules -DBUILD_opencv_hdf=OFF \

-DENABLE_PRECOMPILED_HEADERS=OFF \

..

make -j 50 # replace 50 by your number of CPU cores

suto make install

# This installs into /usr/share/jevois-opencv-3.4.0

# The sample programs are in /usr/share/jevois-opencv-3.4.0/share/OpenCV/samples/

####################################################################################################

Compiling JeVois library and base apps

####################################################################################################

You can compile the JeVois software to run on almost any Linux computer. You can use a standard USB webcam to develop

and test your algorithms rapidly. Once ready, you can cross-compile the exact same code for execution on the hardware

platform. Both host and platform compilation is possible at the same time.

JeVois uses CMake, which simplifies the dual compilation for host hardware (typically, Intel x86_64 CPU) and platform

hardware (ARM CPU). CMake compiles everything in a directory you create, thus we can create two directories, one for

native compilation on the host computer, and one for cross-compilation for the platform hardware.

In the instructions below, we use:

hbuild directory for the files compiled for the HOST

pbuild directory for the files compiled for the PLATFORM

####################################################################################################

Compiling JeVois library and base apps for host computer

####################################################################################################

cd ~/jevois

./rebuild-host.sh

cd hbuild

make doc

cd ..

cd ~/jevoisbase

cd Contrib

./reinstall.sh # do this only once, will download some contributed packages and patch them

cd ..

./rebuild-host.sh

# Plug in any USB webcam and try it:

jevois-daemon

# you can use the JeVois command-line interface in the shell where you started jevois-daemon

# for example, try "help" or "listmappings"

# to start with a specific mapping:

jevois-daemon --videomapping=19

# just issue a 'quit' in the terminal where you started jevois-daemon to quit.

####################################################################################################

Compiling the jevois-sdk from scratch

####################################################################################################

SHORTCUT: sudo apt install jevois-sdk-dev

The shortcut will allow you to cross-compile JeVois software and new modules, and to flash microSD cards. It will not

allow you to change the Linux kernel or operating system of JeVois. You need to follow the FROM SOURCE instructions here

for that.

FROM SOURCE: This will take several hours.

cd

git clone https://github.com/jevois/jevois-sdk.git # if not already done above

cd jevois-sdk

rm -rf out

# Configure buildroot:

cd buildroot

make distclean

cp configs/sun8i_defconfig .config

make xconfig # OPTIONAL: do not mess with these settings unless you know what you are doing

cp .config configs/sun8i_defconfig # OPTIONAL: if you modified some configs

cd ..

# Configure kernel

cd linux-3.4

make distclean

cp config-jevois .config

make xconfig # OPTIONAL: do not mess with these settings unless you know what you are doing

cp .config config-jevois # OPTIONAL: if you modified some configs

cd ..

# configure sunxi build system: choose sun8iw5p1, linux, kernel 3.4, jevois-a33

./build.sh config

# build it

./build.sh

# install everything into staging areas for a new microSD card:

./jevois-build.sh

# flash a microsd:

./jevois-build/jevois-flash-card

####################################################################################################

Compiling JeVois library and base apps for hardware platform

####################################################################################################

This requires that the jevois-sdk-dev be installed (either from a Ubuntu package or from source in the previous step, as

it provides the operating system, Linux kernel 3.4, cross-compiled libraries, and cross-compilers needed to

cross-compile jevois software for platform:

cd ~/jevois

./rebuild-platform.sh

cd ~/jevoisbase

./rebuild-platform.sh --staging

See http://jevois.org/doc/CompilingJeVois.html and http://jevois.org/doc/CompilingJeVoisBase.html for more info.

####################################################################################################

Flashing it all to microSD

####################################################################################################

# rebuild-platform.sh installs the cross-compiled files a staging area that is composed of two directories:

# - /var/lib/jevois-build - for operating system, boot files, and core JeVois software

# - /var/lib/jevois-microsd - for machine vision modules

# See http://jevois.org/doc/ProgrammerOrganization.html for details.

# Now you are ready to burn everything to microSD:

jevois-flash-card

# once you know what you are doing, you can instruct jevois-build.sh to not ask any questions. Just be absolutely

# certain that you are using the right device for your SD card, so that you do not destroy your main hard drive because

# of a small typo:

jevois-flash-card -y /dev/sdX

####################################################################################################

For more information

####################################################################################################

http://jevois.org/doc/Programmer.html