OpenCCTVPlatformInstallationManual

SystemdiagramofOpenCCTVsystem

The OpenCCTV platform is developed on Ubuntu operating system. A web application is

developed using Ruby on Rails architecture. The backend system is developed using C/C++.
Ubuntu 14.04 is required for the OpenCCTV deployment. User can download Ubuntu ISO
image from
http://www.ubuntu.com/download/desktop
. After user finishes Ubuntu installation,
usercanfollowthefollowingstepstodeployOpenCCTVplatform.

Step1:CloneOpenCCTVPlatformrepository

The OpenCCTV platform is an open source project. Source code is available on Github:
https://github.com/aitvgl/OpenCCTV
. The first step of installation is cloning a repository to
users computer. User first needs to open a Terminal window, which isacommandprompttool
inUbuntu,byclickingattheicononthetopoftoolbarontheleftsideofdesktopscreen.

Then, user has to type awordTerminalinatextfieldasshownin figurebelow.After that,user

hastoclickonaniconTerminal.

A terminal window will be popup and waitsforacommand linefromuser.Adefaultdirectoryof

terminalwindowis/home/your_username.

Atthisstep,userhastoclonetheOpenCCTVrepositorytouserscomputerbyexecutingthe
followingcommand:

gitclone
https://github.com/aitvgl/OpenCCTV.git

Aresultfromexecutingthiscommandisshowninfigurebelow.

Atthisstep,userwillgetafoldernamedOpenCCTV.Tochangedirectory,userhastotypein
acommandcdOpenCCTVandpressanenterbutton.

NowyourcurrentdirectoryischangedtoOpenCCTVdirectory.AnOpenCCTVfolderconsistsof
13subfolderswhichare
AnalyticRunner
isamodulewhichworkswithAnalyticStartertostart/stopanalytic
module.
AnalyticStarter
FaceDetectAnalyticResults
isasimpleRubyonRailswebapplicationfordisplaying
theoutputresultfromFaceDetectionAnalytic.
FaceDetectionAnalytic
isasimplefacedetectionsoftware.Theoutputofthesoftware
isstoredinthedatabaseusedbyFaceDetectAnalyticResults.
FakeVmsConnectorPlugin
isanexampleofVMSconnector.
HikVisionConnector
isaconnectorforgettingavideostreamfromHikVisionNVR.
MilestoneVmsConnectorPlugin
isaconnectorforgettingavideostreamfrom
MilestoneVMS.
MockAnalyticPlugin
isanexampleofanalyticmodule.Ifuserwouldliketouseyour
ownanalytic,userhastofollowtheAPIsinthisexample.Useralsocanlookintothe
FaceDetectionAnalyticasanexampletoo.
opencctvdependencies
containslibrariesrequiredforOpenCCTVplatform.
OpenCCTVServer
isamodulewhichworkswithOpenCCTVServer_Starter.This
moduleisusedtostart/stopserver.
OpenCCTVServer_Starter

OpenCCTVWeb
isamainRubyonRailswebapplicationsourcecode.
ZoneMinderConnectorPlugin
isaconnectorusedforgettingavideostreamfrom
ZoneMinderVMS.

Step2:RubyonRailsinstallation
Reference:
https://cis.ait.asia/course_offerings/224/railscompanion

To set up OpenCCTV Web application, user has to install Ruby on Rails framework. The
instruction about Ruby on Rails installation was written by Dr.MatthewN.Dailey.Usercanvisit
https://cis.ait.asia/course_offerings/224/railscompanion andfollowtheinstuctionstepbystep.If
user can not access the reference link, user can follow the instruction below, which is copied
fromthereferencelink.

These instructions are oriented towards the

Ubuntu 14.04 (Trusty Tahr) desktop installation.
ForotherLinuxdistros,theinstructionscanvary.
Please note that this document provides quickstart information only. If youneedmoredetailed
information,lookthroughthereferencesectionorsearchtheWeb.

PostgreSQLInstallation
InstallPostgreSQLbeforeyoucreateyourRailsprojects.ThisissimplewithUbuntu:14.04:
$sudoaptgetinstallpostgresqlpostgresqldoc

RailsInstallation
You can install Ruby, Ruby Gems, and other Rubyrelated packages using aptget or from
source packages. But these approaches are outdated and lead to major headaches when you
needtoupdatetonewversionorworkwitholderversions.
We will be using rbenv (anewlightweight Rubyversionmanagement tool)toinstallRuby,Ruby
Gems, Rails, and other Rubyrelated packages. rbenv is a commandline tool allowing you to
easily install,manage,and workwith multipleRubyenvironmentsincludinginterpretersandsets
ofRubygems.
Ruby Gems is a package manager for the Ruby programming language that provides a
standard way of distributing Ruby programs and libraries (in a selfcontained format called a
"gem"), a tool designed to easily manage the installation of gems, and a server for distributing
them.
Housekeeping
Firstofall,run
$sudoaptgetupdate

sothatwehavethelatestsourcesandupdateonourmachine.
Next, we're going to install gitcore and curl which are both required to install and use rbenv,
andbuildessentialwhichisrequiredtocompileRubyandsomeoftheRubygems.
$ sudo aptget install gitcore curl zlib1gdev buildessential libssldev libreadlinedev
libyamldevlibsqlite3devsqlite3libxml2devlibxsltdevlibpqdev


Installingrbenv
Installing with rbenv is a simple two step process. First you install rbenv, then you install the
rubybuildpluginforrbenv.
Firstinstallthelatestversionofrbenv:
$cd

$gitclonegit://github.com/sstephenson/rbenv.git.rbenv


$echo'exportPATH="$HOME/.rbenv/bin:$PATH"'>>~/.bashrc

$echo'eval"$(rbenvinit)"'>>~/.bashrc

$exec$SHELL

Nextinstalltherubybuildpluginforrbenv:
$gitclonegit://github.com/sstephenson/rubybuild.git~/.rbenv/plugins/rubybuild

$echo'exportPATH="$HOME/.rbenv/plugins/rubybuild/bin:$PATH"'>>~/.bashrc

$exec$SHELL

InstallingRuby
Now we can install any version of Ruby we like. To check whatreleasesofRubyareavailable,
youcouldrun
$rbenvinstalllist

andseethat(atthetimeI'mwriting)thelatestreleaseis2.1.2p95.Installit:
$rbenvinstall2.1.2
$rbenvglobal2.1.2
$rubyv

Youshouldseeoutputsimilartothis:
ruby2.1.2p95(20140508revision45877)[x86_64linux]

NOTE: On 8 September 2015, the latest release is 2.2.3. User can install the latest release by
executingthefollowingcommands:
$rbenvinstall2.2.3

NOTE:Thisstepmaytakesometime.

$rbenvglobal2.2.3
$rubyv
Youshouldseethisoutput:

RubyGems
The following step is to tell Rubygemsnottoinstallthedocumentationforeachpackagelocally.
youcansimplyupdateyour~/.gemrcfile.
$echo"gem:norinordoc">~/.gemrc

Next,checkyourRubyGemsversion:
$gemv

Itshouldreportversion2.2.2.Runthefollowingcommandtoupdatetothelatestversion:

$gemupdatesystem

$gemv

InstallingRails
Nextlet'sinstallthelatestversionofRails(4.1.5atthetimeofwriting).Toinstall:
ToinstallNodeJS,youcanadditusingaPPArepository:
$sudoaddaptrepositoryppa:chrislea/node.js

Pressanenterbuttontoproceedtonextstep

$sudoaptgetupdate

$sudoaptgetinstallnodejs

$geminstallrails


You'llneedtorunthefollowingcommandtomaketherailsexecutableavailable:
$rbenvrehash

Nowthatyou'veinstalledRails.Youcanchecktheversionasfollows:
$railsv

Step3:OpenCCTVWebapplicationconfigurations

Userhastoexecutethefollowingcommands:
1) cdOpenCCTVWeb/
2) bundleinstall

3) IfyourcomputerdoesnthaveMySQL,youhavetoinstallMySQL

sudoaptgetinstallmysqlserver

While installing MySQL, you will be asked to set username and password for
administrator(root).
Then, you have to create MySQL account for usingwithRubyOnRailsWebapplication
bythefollowingcommands:

mysqlurootp

After executingthiscommand,you willbeaskedto enterapassword.Youhavetofillthe

same password which is set during MySQL installation. Next, you have to enter the
followingcommandsforcreatinganewusernameandpassword,andsettingprivileges.

CREATEUSERusername@localhostIDENTIFIEDBYpassword

GRANTALLPRIVILEGESON*.*TOusername@localhost

FLUSHPRIVILEGES

NOTE: Please do not copy these commands and paste into terminal because a
single quote character ()willcreateaproblem.Youhavetotypeinacommandby
yourself.

If youcanexecuteallthreecommandswithouterrormessages,youhavetopressCtrl+d
(hold a Ctrl button and press d button) to exit mysql command line. In this example, a
new user called username is created for localhost. A
username
s password is
password.Afterthat,youhavetorestartmysqlservicebyexecutingthiscommand:

sudoservicemysqlrestart

Beforemakingchangesindatabase.yml,youneedtorunacommand

geminstallmysql2

atopencctvfolder.

At this step, user needs to understand database configuration. If user opens a

database.yml file inOpenCCTV/OpenCCTVWeb/config,thefollowinglineswillbeshown
up:

#MySQL.Versions5.0+arerecommended.
#
#InstalltheMYSQLdriver
#geminstallmysql2
#
#EnsuretheMySQLgemisdefinedinyourGemfile

#gem'mysql2'
#
#Andbesuretousenewstylepasswordhashing:
#
http://dev.mysql.com/doc/refman/5.0/en/oldclient.html
#
default:&default
adapter:mysql2
encoding:utf8
pool:5
username:username
password:password
host:host
socket:/var/run/mysqld/mysqld.sock

Since a user calledusername iscreatedforlocalhost,youhavetochange hostname

from host to localhost. If you would like to change Web application configurations,
please make sure that you create a new username and password, and assign to the
samehostnameusedindatabase.yml.

If everything is fine and there is no error message, we are now ready for creating a
database which will be used by Ruby on Rails Web application. To create a database
forRubyonRails,atopencctvfolder,youhavetoexecuteacommand

rakedb:create

Afterexecutingthiscommand,youshouldgetdatabaseasshowninfigurebelow.

NOTE:ThisWebGUIisPHPMyAdmin.Usercaninstallitbyexecutinga

command:sudoaptgetinstallphpmyadmin

The rake db:create will just create only a database named opencctv and two tables:
opencctv_development,opencctv_test.

Next,userhastorunacommand

rakedb:migrate

tocreatealltablesrequiredforRubyonRailsWebapplicationasshownbelow.

Step4:OpenCCTVinstallation

WearealmostreadyforOpenCCTVinstallation.Pleasemakesurethatyouhaveinstalledthe
requiredlibrariesasfollows:
BoostC++Libraries
InstallationguidetoBoost:
http://particlephysicsandcode.com/2013/03/11/installingboost152ubuntu1204
fedora/
OpenCV
InstallationguidetoOpenCV:
http://docs.opencv.org/trunk/doc/tutorials/introduction/linux_install/linux_install.ht
ml
libVLC
sudoaptgetinstallx264libvlccoredevlibvlcdev
libsodium
Downloadlibsodiumsourcecodefrom
https://download.libsodium.org/libsodium/releases/
Extracttarballfile
Executethefollowingcommand
./configure
make
sudomakeinstall
GoogleProtocolBuffer
https://developers.google.com/protocolbuffers/?hl=en
libzmq
Downloadlibzeromqsourcecodefrom
http://zeromq.org/area:download
Extracttarballfile
Executethefollowingcommand
./configure
make
sudomakeinstall

zmqheaderfile
Downloadzmq.hppfrom
https://github.com/zeromq/cppzmq
Copyzmq.hppto/usr/local/include/

libmysqlconndev
sudoaptgetinstalllibmysqlcppconndev

Updaterecentlyinstalledlibrariesbyexecutingacommand
sudoldconfig

NOTE:Usercancheckaboutcommandsforinstallingrequiredlibrariesin
opencctvdependenciesfolder.

ThereisonemorestepbeforewecancompilethesourcecodeandinstalltheOpenCCTV.User
has to compile two .proto files (image.proto and analytic_result.proto) by using the command
below.

protocI=/home/jednipat/works/OpenCCTV/OpenCCTVServer/src/opencctv/util/serialization/gpb
cpp_out=/home/jednipat/works/OpenCCTV/OpenCCTVServer/src/opencctv/util/serialization/gpb
/home/jednipat/works/OpenCCTV/OpenCCTVServer/src/opencctv/util/serialization/gpb/image.proto

and

protocI=/home/jednipat/works/OpenCCTV/OpenCCTVServer/src/opencctv/util/serialization/gpb
cpp_out=/home/jednipat/works/OpenCCTV/OpenCCTVServer/src/opencctv/util/serialization/gpb
/home/jednipat/works/OpenCCTV/OpenCCTVServer/src/opencctv/util/serialization/gpb/analytic_result.pro
to

Userhastochangeapathtofolderandfiletomatchwithyoursystemenvironment.
If
thereisnoerror,wecannowproceedtofinalstepofinstallation.

ToinstalltheOpenCCTV,userhastoexecuteacommand

shinstall_all.sh

Executing this shell script will ask you to enter roots password.Afterthat,youhavetoreadthe
messages in the terminal carefully to make sure that all modules are compiled successfully
withoutanyerrormessages.

Iftheinstallationiscompleted,youwillseeafoldernamedopencctvin/usr/localdirectory.

Theopencctvin/usr/localcontainsthefollowingsubfolders.

Step5:StartOpenCCTVservices

Oncetheinstallationiscompleted,userwillgetopencctvfolderin/usr/local.Weneedtostart
threeserviceswhichare
1) OpenCCTVWeb
Asweexplainearlier,theOpenCCTVWebisamainwebapplicationwhichisusedfor
controllingthewholesystem.Tostartthismodule,wehavetoexecutethefollowing
command:
railss

User
cannot
close this terminal window or
kill this process. Otherwise, the web
application will stop working. If you want to stop web application, youcanholda control
button and press c button on your keyboard (Ctrl+C). This is a shortcut key to kill
processviaterminalinUbuntuOS.

2) AnalyticStarter
AnalyticStarter is a module to handle analytic plugin for retrieving video stream from
OpenCCTV server and passing a video frame to analytic module. To open a new
terminal window without stopping the running process, user can press a hold ctrl and
shift button, and the press t button on your keyboard (Ctrl+Shift+T). This shortcut key
will open a new tab of terminal window within the same window. Youwillseeaterminal
windowlikethis.


Onceweopenanewterminalunderthesamewindow,wehavetochangeourcurrent
directorytoAnalyticStarterdirectory.

cd../AnalyticStarter
Then,userhastoexecutetheAnalyticStarterusingacommand

./AnalyticStarter

As previously mentioned in OpenCCTVWeb, we

cannot close this terminal or
kill this
process.

3) OpenCCTVServerStarter
OpenCCTVServerStarterisusedtostart/stopOpenCCTVServer.Tostartthisservice,
wewilldothesameprocessaswedidforAnalyticStarter.Userhastoopenanew
terminal,gotoOpenCCTVServerStarterdirectory,andthenexecutethefollowing
command:

./OpenCCTVServer_Starter

As previously mentioned in OpenCCTVWeb, we

cannot close this terminal or
kill this
process.

Now,wecancheckourwebapplicationonwebbrowser.Userhastoenter
http://localhost:3000
inwebbrowserandyoushouldseethemainwebpageofOpenCCTV.

Ifyouseethismainwebpage,itmeansthatyourOpenCCTVisready.


OpenCCTVPlatformUserManual

1.UploadVMSConnector

1.1)ClickatVMSConnectors>UploadanewVMSConnector

1.2)Fillaconnectornameanddescription

1.3)CompileanduploadMilestoneVMSconnector
1.3.1)CompileMilestoneVMSconnector
TocompileMilestoneVMSconnector,userhastogotoafolderwhichiscloned
fromOpenCCTVGithubrepositoryandfollowthestepsbelow:

cdpath_to_your_OpenCCTV
cdMilestoneVmsConnectorPlugin
cdRelease
makeall

Ifthesourcecodeiscompiledsuccessfully,userwillget
libMilestoneVmsConnectorPlugin.so
file.

1.3.2)CreateazipfileofVMSconnector
OncewegetlibMilestoneVmsConnectorPlugin.so,userhastocreateazipfileof
thisfileforuploading.

1.3.3)Selectafileforuploading


1.3.4)UploadandsaveVMSconnectortoserver

Afteruploading,usershouldseeaverificationreport.IfaVMSconnectorisimplemented
correctly,thesystemwillshowastatusVerified.ThismeansthattheuploadedVMSconnector
isreadyforusing.

2.RegisteraVMS

2.1)ClickatVMSes>RegisteranewVMS

2.2)RegisteranewVMS
Beforestartingthisprocess,pleasemakesurethatyouhaveinformationaboutyour
VMS.Inthisexample,wewilluseMilestoneVMSasanexamplebecausewejustuploadedthe
MilestoneVMSconnectorintheprevioussection.

2.3)ChecktheVMSconnectorinformation

As shown in the figure above, after user registered a new VMS,thesystemwillshowthe result
of VMS connection and all registered cameras on the VMS. In this example, we connect only
one IP camera to the Milestone VMS. Therefore, there is only one camera in the registered
cameraslist.UsercanclickatShowstreamstoviewtheimagefromthecamera.

If the video stream is accessible from OpenCCTV, when user clicks at Show button in All
registered Streams, user should see a single frame from the video stream as shown in figure
below.

Ifyoucanseeasingleframeinstreaminformation,youcanproceedtonextstep.

3)UploadAnalyticplugin

3.1)ClickatAnalyticPlugins>UploadanewAnalyticplugin

3.2)Compileanduploadanalyticplugin
3.2.1)Compileanalyticplugin
Inthisexample,wewilluseafacedetectionanalyticasanexample.Userhasto
gotoafolderwhichisclonedfromOpenCCTVGithubrepositoryandfollowthesteps
below:
cdpath_to_your_face_detection_analytic_plugin
cdRelease
makeall

Aftercompilingfacedetectionanalyticplugin,youwillgetlibFaceDetectionAnalytic.so.


3.2.2)CreateazipfileoflibFaceDetectionAnalytic.soanduploadtoserver
To create a zip file for face detection analytic, we have toincludeanalytic.config
into the zip file too. This analytic.config contains configuration data of the face detection.
Therefore, we have to select analytic.config and libFaceDetectionAnalytic.so for creating a zip
file.

ThelibFaceDetectionAnalytic.zipwillbeusedforuploadingtotheserver.


3.3)Checkthestatusofanalyticplugin

Iftheverificationreportstatusisverified,youranalyticpluginisreadytouse.Usercan
proceedtonextstep.

4)Createanewanalyticinstance

Intheprevioussteps,weuploadedaMilestoneVMSconnectorandasimpleface
detectionanalyticplugin.Now,wewillcreateanewanalyticinstance.

4.1)ClickatAnalyticsInstances>CreateanewAnalyticinstance

4.2)Selectanalyticpluginandcreateananalyticinstance

4.3)AddinputstreamforanewanalyticinstancebyclickingatAddInputStream


Userhastoselectanalyticinputstreamandinputstream,thenclickatCreateAnalytic
instancestreambutton.

Ifyouseethefigurebelow,itmeansthatwecancreateanewanalyticinstanceandbind
ittothespecifiedvideostreamalready.Youcanproceedtonextstep.

5)CreateOpenCCTVServer

5.1)ClickatOpenCCTVServers>OpenCCTVserverConnection

5.2)ClickatRegisteraConnectiontoOpenCCTVServer

5.3)Filltheinformationaboutconnection
Usercanusedefaultvalueforcreatingthisserverconnection,andthenclickatSave
ConnectionDetails.

5.4)StartOpenCCTVserverbyclickingatStartServer.

Once user clicks on a Start Server button, user should see one window showing a
video stream from camera. This video stream window is displayed from our face detection
analytic. In a real deployment, we can disable this video stream window. This video stream is
fetched from Milestone VMSandthenouranalyticperforms facedetectiononthisvideostream.
The result (output) is written to the database. User may need another web application for
displayingtheoutput.