Variable Tuning

Edit Variables to customize Operation and Performance

• Variable Editing
• Tuning for Day and Night Settings
• Tuning for Low Light Images
• Image Quality Settings
• Tuning to Reduce Motion Tracking False Positives
• Motion Tracking Versus Motion Detection
• Actions When Motion Detected and Motion Tracking Triggered
  • Motion Camera Full Image Mode
  • Motion Video Mode
  • Motion Time Lapse Sequence Mode
  • Motion Quick Image from Video Stream Mode (minimal delay)
  • Force Image if No Motion for Specified Time Period
  • Video Repeat Dash Cam Mode

Editing Variables

pi-timolo.py variables are stored in the config.py file. Use nano or menubox.sh to edit the variables

cd ~/pi-timolo
nano config.py

press ctrl-x y to save changes.

Two config.py templates are installed.

• config.py is the file that is read by pi-timolo.py. This would be the file you would edit per above

• config.py.default is a backup copy of the original default config.py file. To restore an original configuration you can copy this file over the original config.py file per console commands below

  cd ~/pi-timolo
  cp config.py config.py.bak
  cp config.py.default config.py

Note: use nano to reinstate any customized settings

Tuning for Day Night Settings (motion and Timelapse)

You can specify if you want to suppress taking motion/timelapse images/video during daylight or night time. The default is False for both settings below or take images/video for both day and night.

IMAGE_NO_NIGHT_SHOTS = False     
IMAGE_NO_DAY_SHOTS = False

Set the appropriate or desired setting to True. Note Setting them both to True will suppress taking any/all images/video
Example below will suppress taking mages during twilight/night conditions based on Low Light variable settings.

IMAGE_NO_NIGHT_SHOTS = True     
IMAGE_NO_DAY_SHOTS = False

Tuning for Low Light Images

Low Light conditions can be due to Twilight, Night, overcast, interior lighting changes, Etc Day/Night lighting transitions can be tuned to avoid over bright or over dark images. Most lighting transitions are handled by the camera automatic settings.

Once the camera is below the capability of automatic adjustment the thresholds for twilight, dark and black settings use preset variables below. These variables can be used to tweak image brightness and quality. Verbose logging data using a short duration time lapse mode eg 10 seconds should be used to assist with low light variable changes. The default settings should work OK in most situations and may only need minor adjustments. These settings are not applicable to video or MOTION_TRACK_QUICK_PIC_ON modes.

NIGHT_TWILIGHT_MODE_ON = True # Default= True Outside Lighting  False= Inside with No Twilight Lighting (reduce over exposures)
NIGHT_TWILIGHT_THRESHOLD = 90 # Default= 90 dayPixAve where twilight starts (framerate_range shutter)
NIGHT_DARK_THRESHOLD = 50     # Default= 50 dayPixAve where camera variable shutter long exposure starts
NIGHT_BLACK_THRESHOLD = 4     # Default= 4  dayPixAve where almost no light so Max settings used
NIGHT_SLEEP_SEC = 20          # Default= 30 Sec - Time period to allow camera to calculate low light AWB
NIGHT_MAX_SHUT_SEC = 5.9      # Default= 5.9 Sec Highest V1 Cam shutter for long exposures V2=10 Sec.
NIGHT_MAX_ISO  = 800          # Default= 800 Night ISO setting for Long Exposure below nightThreshold
NIGHT_DARK_ADJUST = 4.7       # Default= 4.7 Factor to fine tune NIGHT_DARK_THRESHOLD brightness (lower is brighter)

Image Quality Settings

The config.py motion track setting uses a stream image since it is much faster. If you want better quality motion images

MOTION_TRACK_QUICK_PIC_ON = True

then set

MOTION_TRACK_QUICK_PIC_ON = False 

This will stop the motion track stream and save a pi-camera image. There will be a several second delay for the pi-camera to switch between stream mode and image mode. This will take a much better image.

Note You can also adjust default jpg image quality using the config.py image setting

IMAGE_JPG_QUAL = 95          # Default= 95 jpg Encoder Quality Values 1(low)-100(high min compression) 0=85

95 is the default camera quality and should be OK.

Please Note: The original pi-timolo.py was converted to use opencv motion tracking instead of motion detection since it greatly reduces false positives and also allows capturing a MOTION_TRACK_QUICK_PIC_ON frame image from the motion track stream.

Tuning to Reduce Motion Tracking False Positives

If pi-timolo is getting triggered regularly by two or more moving objects (eg trees near each other), You may be able to reduce this by tuning several variables.

Adjust config.py Variable motionTrackMinArea

If you know the appoximate contour size you are interested in, like really big things, then you can just set the motionTrackMinArea to a sqpx size just below the object size you are interested in. Use verbose mode and log to file to allow viewing events. By default value is pretty small

MOTION_TRACK_MIN_AREA = 100    # Default= 100 sq px  Minimum Area required to start tracking

Increasing this value would eliminate any smaller sqpx contours that may be triggering a motion event. I would try increasing this slowly until you see an improvement. I set this low because I wanted to catch people farther away (smaller)

Adjust config.py Variable motionTrackTrigLen

The config.py motionTrackTrigLen variable is the total distance in pixels a moving objects must travel in order to trigger a motion event. It has to be short enough to capture far away objects (if that is what you want) or increase length to trigger only when an object moves a longer pixel length.
One object moving (above the motionTrackMinArea) back and forth below this trig len value will not trigger motion but will start the track and then time out. Unfortunately there can be two unrelated moving objects at the right distance away that can cause a false positive.
Try adjusting value up or down incrementally to see if this reduces false positives. Smaller can often improve the situation if the two moving objects are relatively far away from each other.

Change pi-timolo.py Algorithm for TRACK_TRIG_LEN_MAX

This is an internal pi-timolo.py variable. This variable is currently set for 1/2 screen height. This variable formula can be found at approx line 117 in the pi-timolo.py file. It is a pixel length that is half the camera height (an arbitrary setting on my part) per formula.

TRACK_TRIG_LEN_MAX = int(CAMERA_HEIGHT / 2) # Set max over triglen allowed half cam height

This will filter out objects moving in two location of the screen that are greater than this value. I may change this to be Trigger length + 1/2 or 1/3 trigger length. All this is saying is that if the object moved greater than the trigger length to report motion, It cannot also be more the TRACK_TRIG_LEN-MAX value above the trigger length. in the original case it would be half the stream height which is quit a bit. 720/2 = 360 pixels

You could try changing this formula to something like

TRACK_TRIG_LEN_MAX = int(MOTION_TRACK_TRIG_LEN + (MOTION_TRACK_TRIG_LEN/2)) 

or some other calculated value. The problem with this formula would be that you could exceed the screen size if the motionTrackTrigLen was a larger value. That is why I set the value to half the screen height to avoid that situation.

I would avoid hard coding this variable to a set value unless it is added to config.py where it is more visible.

Change pi-timolo.py Variable Formula for TRACK_TRIG_LEN_MIN

This variable is used to verify the object has moved by at least a quarter of the trigger length. This starts a timeout timer. This variable is set at approx line 118 in pi-timolo.py at 1/4 the motionTrackTrigLen per formula below. You could try changing the divisor up or down slightly. It is not recommended you hard code this variable.

TRACK_TRIG_LEN_MIN = int(MOTION_TRACK_TRIG_LEN / 6)

Adjust config.py Variable MOTION_TRACK_TIMEOUT_SEC

This variable sets a limit for how long motion will be tracked before giving up. Just in case the object moves then stops and never achieves the full trigger length within the timeout period. The default value of 1 second should be OK and should catch most reasonably slow objects but you can increase the timeout in case very slow moving objects are not getting caught by original default. I had set the original value to 3 seconds but this was too long for most moving objects unless motion was verry slow. In most cases it is better to just change the motionTrackTrigLen in config.py that is the same as TRACK_TRIG_LEN_MIN. I guess it was not necessary to have two variables for the same thing (note to self).

Conclusion

These are the best settings that can be adjusted to reduce false positive motions. Otherwise the logic would have to track each individual event and make sure motion event was close enough to the previous event but within a timeout period.

Motion Detection Versus Motion Tracking

• Motion Tracking reduces false positives by detecting if a series of motion events has moved a set distance of pixels away from the initial movement location in a specified time period.

• Motion (non tracking) is simply triggered when there is a difference between two frames. This can be generated by moving object(s), lighting changes or random motion like a bush moving back and forth. That is why I set motion tracking as the default since it can eliminate most false positive motion situations.

Example for enabling Motion Tracking. Note videoRepeatOn has to be disabled since if overrides all other modes if True

MOTION_TRACK_ON = True        # default= True True=Turns Motion Detect On, False=Off
VIDEO_REPEAT_ON = False       # default = False True=Turns on dash cam video mode (not timelapse or motion detection)

Actions When Motion Detected or Motion Tracking Triggered

When motion or motion tracking is detected (triggered) you Can

• Take a single Pi Camera Still Image per image size, format and quality settings
• Take a single Pi Camera h264 Video for specified Duration and image settings. Will be converted to MP4 by convid.sh
• Take a Quick Image Frame from Video Stream per Stream image size (normally low resolution)
• Take a Time Lapse Image Series with a specified Duration and Interval between images per image settings
• Take Forced image if No Motion Detected for a Specified Time Period (default 3600 seconds or 1 hour)

Below are several example settings for what to do if motion or motion tracking is detected or triggered.

Motion Camera Full Image Mode

Takes a single pi-camera image rather than a video per the image size, quality, format settings

MOTION_VIDEO_ON = False      # Default= False  True=Take a video clip rather than image
MOTION_TRACK_MINI_TL_ON = False     # Default= False  True=Take a quick time lapse sequence rather than a single image (overrides MOTION_VIDEO_ON)
MOTION_TRACK_QUICK_PIC_ON = False   # Default= False True= Grab stream frame rather than stopping stream to take full size image
VIDEO_REPEAT_ON = False      # Turn on Video Repeat Mode IMPORTANT Overrides timelapse and motion

The image taken will be a normal pi-camera image that needs a second or so to switch from video motion tracking streaming mode to normal camera operation. This can often miss quick moving motion.

Motion Video Mode

Take a Video for a specified time period eg 10 seconds per example below using image size settings.

MOTION_VIDEO_ON = tRUE      # Default= False  True=Take a video clip rather than image      
MOTION_VIDEO_TIMER_SEC = 10  # Default= 10 seconds of video clip to take if Motion Detected  
VIDEO_REPEAT_ON = False

Motion Time Lapse Sequence Mode

Take a series of timelapse images per image size, quality and format settings, for a specific time period eg 60 seconds and interval time between images eg 5 seconds see example settings below thus you will get 12 images after motion spaced 5 seconds apart. This is more likely to capture a high quality image of moving object for a period of time

MOTION_VIDEO_ON = False      # Default= False  True=Take a video clip rather than image
MOTION_TRACK_MINI_TL_ON = True     # Default= False  True=Take a quick time lapse sequence rather than a single image (overrides MOTION_VIDEO_ON)
MOTION_TRACK_MINI_TL_SEQ_SEC = 30   # Default= 30 Duration in seconds of quick time lapse sequence after initial motion detected
MOTION_TRACK_MINI_TL_TIMER_SEC = 5  # Default= 5 seconds between each Quick time lapse image. 0 is fast as possible

MOTION_TRACK_QUICK_PIC_ON = False   # Default= False True= Grab stream frame rather than stopping stream to take full size image
VIDEO_REPEAT_ON = False      # Turn on Video Repeat Mode IMPORTANT Overrides timelapse and motion

Motion Quick Image from Video Stream Mode (minimal delay)

If motionTrackQuickPic is set to True a video frame image is saved. Note motionTrackQuickPic is automatically disabled if motionTrackOn = False. The QuickPic image resolution will normally be lower and may be blurred since it is taken directly from the video stream. This mode captures an image of the movement immediately and can catch quick moving motion. Use the following setting

MOTION_VIDEO_ON = False      # Default= False  True=Take a video clip rather than image

MOTION_TRACK_ON = True         # Default= True True=Turns Motion Detect On, False=Off
MOTION_TRACK_QUICK_PIC_ON = False   # Default= False True= Grab stream frame rather than stopping stream to take full size image
VIDEO_REPEAT_ON = False      # Turn on Video Repeat Mode IMPORTANT Overrides timelapse and motion

Otherwise you can just take a normal Motion Camera Full Image after a few seconds delay to switch from video stream to camera still mode. Delay will be longer for low light conditions.

Force Image if No Motion for Specified Time Period

You can also specify what to do if there is No motion for a specified period of time eg take a picture anyway if there has been no motion for an hour or specified number of seconds. Zero will disable this feature (pi-timolo ver 7.9 or greater).

MOTION_FORCE_SEC = 3600      # Default= 3600 seconds (1 hr) OFF=0  Force an image if no Motion Detected in specified seconds.

Sometimes I set my camera with a motionForce = 300 so it forces an image every 5 minutes that can act as an easy way to get regular updates when in motion mode only. This will take an image immediately if motion tracking is activated, at which time the 300 second motionForce wait will restart.

Video Repeat Dash Cam Mode

You can put the camera into a Dash Cam video Repeat mode where video is taken continuously. You can specify the duration of each video segment. When video Repeat mode is enabled, it will suppress Motion and/or Time lapse modes

VIDEO_REPEAT_ON = True      # Turn on Video Repeat Mode IMPORTANT Overrides timelapse and motion

To re enable motion and/or timelapse modes set

VIDEO_REPEAT_ON = False      # Turn on Video Repeat Mode IMPORTANT Overrides timelapse and motion

There are many other combinations possible. Sometimes I will set both timelapse and motion on These variable settings can be found in the config.py file.