JustMotion/README.md

# Motion Watch #

Motion Watch is a video surveillance application that monitors the video feeds
of an IP camera and records only footage that contains motion. The main
advantage of this is reduced storage requirements as opposed to continuous
recording because only video footage of interest is recorded to storage.
The entire app is designed to operate on just one camera but multiple instances
of this app can be used to operate multiple cameras.

### Usage ###

```
Usage: mow <argument>

 -h : display usage information about this application.
 -c : path to the config file.
 -v : display the current version.
```

### Config File ###

The config file is a simple text file that contain parameters that dictate the
behavior of the application. Below is an example of a config file with all
parameters supported and descriptions of each parameter.
```
# Motion Watch config file
#
# note all lines in this config file that starts with a '#' are ignored.
# also note to avoid using empty lines. if you're going to need an empty
# line, start it with a '#'
#
recording_stream = rtsp://1.2.3.4:554/h264
# this is the url to the main stream of the IP camera that will be used
# to record footage.
#
output_dir = /path/to/footage/directory
# this is the output directory that will be used to store recorded footage
# from the camera. the file naming convention uses the current date for
# playlist files which points to hidden video clips taken from the camera.
#
buff_dir = /tmp/ramdisk/cam_name
# this application records small clips of the footage from the camera and
# then stores them into this directory. any clips with motion detected in
# them are moved to output_dir, if no motion they are deleted. highly
# recommend to use a ramdisk tempfs for this since this directory is used
# for lots of writes.
#
consec_threshold = 512
# motion is detected by comparing each frame in the camera feed for
# differences in the pixels. this value determine how many consecutive
# pixels need to different or how large the suspect object in motion
# needs to be.
#
block_threshold = 1024
# this value tells the application how many "lines" of pixels need to
# exceed consec_threshold before being considered motion.
#
block_x = 64
# this is the x coordinate size or horizontal size of a block of pixels
# that the application will use to detect the presents of motion.
#
block_y = 60
# this is the y coordinate size or vertical size of a block of pixels
# that the application will use to detect the presents of motion.
#
duration = 60
# this sets the internal timer used to reset to the detection loop and
# then call post_cmd if it is defined. note: this time is extended if
# motion was detected. this will also reload the config file so changes
# to the settings will be applied without restarting the application.
#
post_cmd = move_the_ptz_camera.py
# this an optional command to run after the internal timer duration has
# elapsed. one great use for this is to move a ptz camera to the next
# position of it's patrol pattern. note: the call to this command will be
# delayed if motion was detected.
#
max_days = 15
# this defines the maximum amount of days worth of video clips that is
# allowed to be stored in the output_dir. whenever this limit is met,
# the oldest day is deleted.
#
vid_container = mp4
# this is the video file format to use from recording footage from the
# camera. the format support depends entirely on the under laying ffmpeg
# installation.
```

### Setup/Build/Install ###

This application is currently only compatible with a Linux based operating
systems that are capable of building and installing the opencv API from source.

The following 3 scripts make this convenient by downloading, compiling and then
installing the opencv API for you directly from opencv's git repository. This
also makes sure FFMPEG and all of it's dependencies are installed because this
application needs it to work properly.

```
note 1: be sure to run setup.sh and install.sh as root (or use sudo).
note 2: if building from scratch the following scripts will need to
        be run in this order - setup.sh -> build.sh -> install.sh.
```

```
sh ./setup.sh <--- only need to run this once if compiling for the first
sh ./build.sh      time or if upgrading from the ground up.
sh ./install.sh
```