Permalink
Find file Copy path
440 lines (312 sloc) 20.6 KB
######################################################################################################################
#
# 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