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.
```

### 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 v1.0
#
# 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 if it contains motion.
#
detection_stream = rtsp://1.2.3.4:554/h264cif
# this is the low resolution secondary stream url of the IP camera the
# will be used to detect motion. it is never recorded. note: consider
# matching the fps of both streams for best results.
#
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 date codes. it creates
# a sub-folder for the date if it needs to and then stores the video file
# using the time.
#
diff_verbose = N
# this is a boolean Y or N option that turns on/off the option to output
# the pixel diff values that the application is reading from the camera in
# real time out into stdout. this is useful for determining the best value
# to use in pix_threshold, color_threshold or consec_threshold.
#
pix_threshold = 8
# this application detects motion by loading back to back frames from the
# detection stream and then compares the color spectrum levels of each
# pixel of those frames. if the levels are significantly different, that
# will maybe considered motion. this threshold indicates how many pixels
# in the image needs to be different before triggering a potential motion
# event.
#
color_threshold = 190
# the color levels in each pixel of the detection stream can range from
# 0-255. in an ideal world the color differences in between frames should
# be 0 if there is no motion but must cameras can't do this. the threshold
# value here is used to filter if the pixels are truly different or if its
# seeing color differences of small objects that are of no interest.
#
consec_threshold = 10
# this setting is used to tell the application how many consecutive frames
# need to have pixel differences over the pix_threshold before triggering
# a motion event and then record to storage.
#
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 can be 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 can be
# delayed if motion was detected.
#
detect_fps = 20
# this is how many frames to read from the detection stream per second.
# setting this any higher the camera's actual fps will just waste cpu
# cycles but setting it too low makes detecting motion inaccurate.
#
secs_post_motion = 10
# this is the minimum amount of seconds to capture after motion was
# detected.
#
```

### Build Setup ###

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

[opencv](https://docs.opencv.org/4.x/df/d65/tutorial_table_of_content_introduction.html).
```
cd /path/to/Motion/Watch/source
mkdir ./build
cd ./build
cmake ..
make
sudo cp ./mow /usr/bin/mow
```