Merge branch 'main' into develop

.github/workflows/build-windows.yml

@@ -1,5 +1,4 @@
 # Build Portable Windows EXE (x64) Distribution for DVR-Scan
-
 name: Windows Distribution
 
 on:

.github/workflows/build.yml

@@ -1,7 +1,20 @@
-
+# Build Python Source/Wheel Distributions of DVR-Scan
 name: Python Distribution
 
-on: [pull_request, push]
+on:
+  pull_request:
+    paths:
+      - dist/**
+      - dvr_scan/**
+      - tests/**
+  push:
+    paths:
+      - dist/**
+      - dvr_scan/**
+      - tests/**
+    tags:
+      - v*-release
+  workflow_dispatch:
 
 jobs:
   build:

.github/workflows/check-code-format.yml

@@ -1,17 +1,18 @@
-# Use YAPF to format DVR-Scan.
+# Use YAPF to check DVR-Scan formatting (run `yapf -i -r dvr_scan tests` locally to fix)
 name: Check Code Format
 
 on:
   pull_request:
     paths:
+      - .style.yapf
       - dvr_scan/**
       - tests/**
   push:
     paths:
+      - .style.yapf
       - dvr_scan/**
       - tests/**
 
-
 jobs:
   build:
 

.github/workflows/update-site.yml

@@ -1,11 +1,12 @@
-
+# Update www.dvr-scan.com
 name: Update Website
 
 on:
   push:
     branches:
       - main
     paths:
+      - 'docs/**'
       - 'website/**'
   workflow_dispatch:
 

.gitignore

@@ -2,7 +2,9 @@
 *.pyo
 site/
 build/
-dist/
+dist/dvr-scan/*
+dist/dvr-scan*
+dist/dvr_scan*
 *.egg-info/
 /tutorial-env/*
 .DS_Store

README.md

@@ -4,10 +4,12 @@
 
 ------------------------------------------------
 
-### Latest Release: v1.5.1 (August 15, 2022)
+### Latest Release: v1.6 (October 15, 2023)
 
 **Website**: [dvr-scan.com](https://www.dvr-scan.com)
 
+**User Guide**: [dvr-scan.com/guide](https://www.dvr-scan.com/guide/)
+
 **Documentation**: [dvr-scan.com/docs](https://www.dvr-scan.com/docs/)
 
 ------------------------------------------------------
@@ -26,23 +28,27 @@ Scan `video.mp4` (separate clips for each event):
 
     dvr-scan -i video.mp4
 
-Only scan a region of interest ([see user guide](https://dvr-scan.readthedocs.io/en/develop/guide/) or hit `H` for controls):
+Select a region to scan using [the region editor](https://www.dvr-scan.com/guide/):
+
+    dvr-scan -i video.mp4 -r
+
+<img alt="example of region editor" src="https://raw.githubusercontent.com/Breakthrough/DVR-Scan/releases/1.6/docs/assets/region-editor-mask.jpg" width="480"/>
 
-    dvr-scan -i video.mp4 -roi
+Select a region to scan using command line (list of points as X Y):
 
-<img alt="example of region editor" src="https://raw.githubusercontent.com/Breakthrough/DVR-Scan/develop/docs/assets/region-editor-multiple.jpg" width="480"/>
+    dvr-scan -i video.mp4 -a 50 50 100 50 100 100 100 50
 
 Draw boxes around motion:
 
     dvr-scan -i video.mp4 -bb
 
-<img alt="example of bounding boxes" src="https://raw.githubusercontent.com/Breakthrough/DVR-Scan/develop/docs/assets/bounding-box.gif" width="480"/>
+<img alt="example of bounding boxes" src="https://raw.githubusercontent.com/Breakthrough/DVR-Scan/releases/1.6/docs/assets/bounding-box.gif" width="480"/>
 
 Use `ffmpeg` to extract events:
 
     dvr-scan -i video.mp4 -m ffmpeg
 
-See [the documentation](docs.md) for a complete list of all command-line and configuration file options which can be set. You can also type `dvr-scan --help` for an overview of command line options. Some program options can also be set [using a config file](docs.md#config-file).
+See [the documentation](https://www.dvr-scan.com/docs) for a complete list of all command-line and configuration file options which can be set. You can also type `dvr-scan --help` for an overview of command line options. Some program options can also be set [using a config file](https://www.dvr-scan.com/docs/#config-file).
 
 ------------------------------------------------
 

dist/.version_info

@@ -6,8 +6,8 @@ VSVersionInfo(
   ffi=FixedFileInfo(
 # filevers and prodvers should be always a tuple with four items: (1, 2, 3, 4)
 # Set not needed items to zero 0.
-filevers=(0, 1, 6, 999),
-prodvers=(0, 1, 6, 999),
+filevers=(0, 1, 6, 0),
+prodvers=(0, 1, 6, 0),
 # Contains a bitmask that specifies the valid bits 'flags'r
 mask=0x3f,
 # Contains a bitmask that specifies the Boolean attributes of the file.
@@ -31,12 +31,12 @@ StringFileInfo(
     u'040904B0',
     [StringStruct(u'CompanyName', u'github.com/Breakthrough'),
     StringStruct(u'FileDescription', u'dvr-scan.readthedocs.io'),
-    StringStruct(u'FileVersion', u'v1.6-dev0'),
+    StringStruct(u'FileVersion', u'1.6'),
     StringStruct(u'InternalName', u'DVR-Scan'),
     StringStruct(u'LegalCopyright', u'Copyright © 2023 Brandon Castellano'),
     StringStruct(u'OriginalFilename', u'dvr-scan.exe'),
     StringStruct(u'ProductName', u'DVR-Scan'),
-    StringStruct(u'ProductVersion', u'v1.6-dev0')])
+    StringStruct(u'ProductVersion', u'1.6')])
   ]),
 VarFileInfo([VarStruct(u'Translation', [1033, 1200])])
   ]

dist/package-info.rst

@@ -1,10 +1,27 @@
-====================================================================
+
 DVR-Scan
-====================================================================
+==========================================================
 
 Video Motion Event Detection and Extraction Tool
 ----------------------------------------------------------
 
+.. image:: https://img.shields.io/github/actions/workflow/status/Breakthrough/DVR-Scan/build.yml
+   :target: https://github.com/Breakthrough/DVR-Scan/actions
+
+.. image:: https://img.shields.io/github/release/Breakthrough/DVR-Scan.svg
+   :target: https://github.com/Breakthrough/DVR-Scan
+
+.. image:: https://img.shields.io/pypi/status/dvr-scan.svg
+   :target: https://github.com/Breakthrough/DVR-Scan
+
+.. image:: https://raster.shields.io/pypi/l/dvr-scan.png
+   :target: http://pyscenedetect.readthedocs.org/en/latest/copyright/
+
+.. image:: https://img.shields.io/github/stars/Breakthrough/DVR-Scan.svg?style=social&label=View%20on%20Github
+   :target: https://github.com/Breakthrough/DVR-Scan
+
+----------------------------------------------------------
+
 Website: http://www.dvr-scan.com/
 
 Documentation: http://dvr-scan.readthedocs.org/
@@ -17,6 +34,10 @@ DVR-Scan is a command-line application that **automatically detects motion event
 Quickstart
 ----------------------------------------------------------
 
+Install using ``pip``:
+
+   pip install --upgrade dvr-scan[opencv]
+
 Scan ``video.mp4`` (separate clips for each event)::
 
     dvr-scan -i video.mp4
@@ -25,22 +46,25 @@ Only scan a region of interest (`see user guide <http://www.dvr-scan.com/guide/>
 
     dvr-scan -i video.mp4 -r
 
-.. image:: assets/region-editor-multiple.jpg
+.. image:: https://raw.githubusercontent.com/Breakthrough/DVR-Scan/releases/1.6/docs/assets/region-editor-mask.jpg
   :width: 480
   :alt: overlay example
+
 Draw boxes around motion::
 
     dvr-scan -i video.mp4 -bb
 
-.. image:: assets/bounding-box.gif
+.. image:: https://raw.githubusercontent.com/Breakthrough/DVR-Scan/releases/1.6/docs/assets/bounding-box.gif
   :width: 480
   :alt: overlay example
 
 Use ``ffmpeg`` to extract events::
 
     dvr-scan -i video.mp4 -m ffmpeg
 
-For help or other issues, feel free to submit any bugs or feature requests to Github: https://github.com/Breakthrough/DVR-Scan/issues
+For help or other issues, feel free to submit any bugs or feature requests to Github:
+
+https://github.com/Breakthrough/DVR-Scan/issues
 
 ----------------------------------------------------------
 
@@ -49,5 +73,3 @@ Licensed under BSD 2-Clause (see the ``LICENSE`` file for details).
 Copyright (C) 2016-2023 Brandon Castellano.
 All rights reserved.
 
-
-In my readme on GitHub I have several images that are present there in my project's source tree which I reference successfully with directives like

docs/changelog.md

@@ -5,19 +5,22 @@
 
 ## DVR-Scan 1.6
 
-### 1.6 (In Development)
+### 1.6 (October 15, 2023)
 
 #### Release Notes
 
-This version of DVR-Scan includes a much requested feature: multiple regions of interest.  Not only can you select multiple regions, but they can be any shape or complexity (see [user guide](https://dvr-scan.readthedocs.io/en/develop/guide/#region-editor)):
+DVR-Scan greatly improves masking capabilities with the new region editor ([user guide](https://www.dvr-scan.com/guide/#region-editor)):
 
-<img alt="example of region editor" src="https://raw.githubusercontent.com/Breakthrough/DVR-Scan/develop/docs/assets/region-editor-multiple.jpg" width="480"/>
+<img alt="example of region editor" src="https://raw.githubusercontent.com/Breakthrough/DVR-Scan/releases/1.6/docs/assets/region-editor-multiple.jpg" width="480"/>
+<img alt="example of region editor" src="https://raw.githubusercontent.com/Breakthrough/DVR-Scan/releases/1.6/docs/assets/region-editor-mask.jpg" width="480"/>
+
+Multiple regions can now be defined with any shape, size, and complexity. Region data can be saved to a file and loaded again. Regions can also be specified by command line.
 
 There are also several other bugfixes and improvements, such as improved seeking performance.
 
 #### Changelog
 
- - [feature] [New region editor](https://dvr-scan.readthedocs.io/en/develop/guide/#region-editor) `-r`/`--region-editor` allows creation of multiple regions without shape restrictions, replaces `-roi`/`--region-of-interest`
+ - [feature] [New region editor](https://www.dvr-scan.com/guide/#region-editor) `-r`/`--region-editor` allows creation of multiple regions without shape restrictions, replaces `-roi`/`--region-of-interest`
  - [feature] Multiple regions of interest (rectangular or polygonal) can now be created:
     - Using the new region editor by adding the `-r`/`--region-editor` flag: `dvr-scan -i video.mp4 -r`
     - New `-a`/`--add-region` replaces `-roi`/`--region-of-interest` option: `dvr-scan -i video.mp4 -a 5 5 20 5 20 20 5 20`
@@ -32,7 +35,7 @@ There are also several other bugfixes and improvements, such as improved seeking
  -detection-parameters)
  - [general] Noise reduction kernel can now be disabled by setting `-k`/`--kernel-size` to `0` ([#123](https://github.com/Breakthrough/DVR-Scan/issues/123))
  - [general] Include stack traces in logfiles when setting `--verbosity debug`
- - [bugfix] Fix CNT mode always treating first few frame as having motion [#119](https://github.com/Breakthrough/DVR-Scan/issues/119)
+ - [bugfix] Add `max-score` option to config file to fix CNT mode always treating first few frame as motion, default is 255.0 [#119](https://github.com/Breakthrough/DVR-Scan/issues/119)
  - [bugfix] Fix timecode format `HH:MM:SS[.nnn]` being rejected for start/end time ([#141](https://github.com/Breakthrough/DVR-Scan/issues/141))
  - [bugfix] Fix incorrect RGB mapping for config file (values were treated as BGR instead)
  - [other] Config option `timecode` has been renamed to `time-code` to match the command-line option
@@ -43,6 +46,9 @@ There are also several other bugfixes and improvements, such as improved seeking
     - `time-code-font-color` is now `text-font-color`
     - `time-code-bg-color` is now `text-bg-color`
 
+#### Known Issues
+
+ - Some prebuilt archives include documentation which references the `load-region` config option with the incorrect name (`region-file`) [#153](https://github.com/Breakthrough/DVR-Scan/issues/153)
 
 ----------------------------------------------------------
 

docs/docs.md

@@ -358,6 +358,14 @@ The following options control motion detection.  A more comprehensive descriptio
     ```
     </span>
 
+ * <b><pre>max-threshold</pre></b>
+     Scores of this amount or higher are ignored. 255.0 is the maximum score, so values greater than 255.0 will disable the filter.
+    <span class="dvr-scan-default">
+    ```
+    max-threshold = 255.0
+    ```
+    </span>
+
  * <b><pre>kernel-size</pre></b>
     Size (in pixels) of the noise reduction kernel. Size must be an odd number starting from 3, 0 to disable, or -1 to auto-set based on video resolution.
     <span class="dvr-scan-default">

docs/download.md

@@ -10,15 +10,15 @@ hide:
 
 ## Python <span class="dvr-scan-download-icons">:fontawesome-brands-windows::fontawesome-brands-apple::fontawesome-brands-linux:</span>
 
-!!! python-download "**1.5.1**<span class="dvr-scan-release-date">August 15, 2022</span>"
+!!! python-download "**1.6**<span class="dvr-scan-release-date">October 15, 2023</span>"
 
     <h3>Regular Install:</h3>
 
-        pip install dvr-scan[opencv]==1.5.1
+        pip install dvr-scan[opencv]==1.6
 
     <h3>Headless (Servers):</h3>
 
-        pip install dvr-scan[opencv-headless]==1.5.1
+        pip install dvr-scan[opencv-headless]==1.6
 
 DVR-Scan is [available on PyPI](https://pypi.org/project/dvr-scan/) can be installed using `pip install dvr-scan[opencv]`. DVR-Scan works on Windows, Linux, and OSX, and requires Python 3.7 or higher.
 
@@ -29,9 +29,9 @@ If want to use an existing OpenCV installation or require a non-PyPI version, yo
 
 ## Windows Distribution<span class="dvr-scan-download-icons">:fontawesome-brands-windows:</span>
 
-!!! windows-download "**1.5.1**<span class="dvr-scan-release-date">August 15, 2022</span>"
+!!! windows-download "**1.6**<span class="dvr-scan-release-date">October 15, 2023</span>"
 
-    <div class="buttongrid buttongrid-download">[:fontawesome-solid-download: &nbsp; Installer `.msi`](download.md){ .md-button #download-button }[:fontawesome-solid-file-zipper: &nbsp; Portable `.zip`](changelog.md){ .md-button #changelog-button }</div>
+    <div class="buttongrid buttongrid-download">[:fontawesome-solid-download: &nbsp; Installer `.msi`](https://github.com/Breakthrough/DVR-Scan/releases/download/v1.6-release/dvr-scan-1.6-win64.msi){ .md-button #download-button }[:fontawesome-solid-file-zipper: &nbsp; Portable `.zip`](https://github.com/Breakthrough/DVR-Scan/releases/download/v1.6-release/dvr-scan-1.6-win64.zip){ .md-button #changelog-button }</div>
 
 
 The installer is recommended for most users.  Windows builds include all required dependencies to run DVR-Scan.  Only 64-bit builds are available.
@@ -44,9 +44,9 @@ The installer is recommended for most users.  Windows builds include all require
 
 Nvidia CUDA® builds are available, but still early in development. This version may not be the latest, and should be considered experimental. Not all GPU versions may be supported.
 
-!!! cuda-download "**1.5.1**<span class="dvr-scan-release-date">:fontawesome-solid-triangle-exclamation:</span>"
+!!! cuda-download "**1.5.1 (Not Latest)**<span class="dvr-scan-release-date">:fontawesome-solid-triangle-exclamation:</span>"
 
-    <div class="buttongrid buttongrid-download">[:fontawesome-solid-flask: &nbsp; CUDA® Build `.zip`](docs.md){ .md-button #changelog-button }</div>
+    <div class="buttongrid buttongrid-download">[:fontawesome-solid-flask: &nbsp; CUDA® Build `.zip`](https://github.com/Breakthrough/DVR-Scan/releases/download/v1.5.1-release/dvr-scan-1.5.1-win64-cuda.zip){ .md-button #changelog-button }</div>
 
 Make sure to set `-b MOG2_CUDA` when running DVR-Scan (e.g. `dvr-scan -i video.mp4 -b MOG2_CUDA`). CUDA builds are done infrequently and may not be up to date.  The Python version of DVR-Scan is compatible with any CUDA® enabled version of the `opencv-python` module.  You can get better performance or use DVR-Scan on a wider variety of GPUs if you build the module on your system. with the latest SDK version.
 

docs/guide.md

@@ -9,11 +9,11 @@ After [downloading](download.md), you should have the `dvr-scan` command availab
 
 To extract all motion events from a video, you can start with:
 
-    dvr_scan -i video.mp4
+    dvr-scan -i video.mp4
 
 This will produce output events in your working directory starting with the prefix `video.DSME_` (e.g. `video.DSME_0001.avi`). If you want to limit scanning to a particular part of the video frame, you can use the [region editor](#region-editor):
 
-    dvr_scan -i video.mp4 -r
+    dvr-scan -i video.mp4 -r
 
 DVR-Scan should provide good results for most use cases, but can be fine tuned for specific use cases. There are two main categories of these settings: [detection and sensitivity](docs.md#detection), and [event parameters](docs.md#events).
 
@@ -29,11 +29,11 @@ These settings will be used by default each time you run DVR-Scan, unless you ov
 
 You can specify multiple input videos as long as they have the same resolution and framerate:
 
-    dvr_scan -i video1.mp4 video2.mp4 video*.mp4
+    dvr-scan -i video1.mp4 video2.mp4 video*.mp4
 
 Wildcards are also supported:
 
-    dvr_scan -i video*.mp4
+    dvr-scan -i video*.mp4
 
 Note that this will **concatenate** the videos together *in the order they are specified*.
 
@@ -97,12 +97,11 @@ Press `S` to save the current regions to a file, or `O` to load existing ones.
 
 Regions are a set of points creating a closed shape. A rectangle will be created by default for you to modify.
 
-You can use the left mouse button to add a new point (keyboard: `A`) and right/middle mouse button (keyboard `X`) to delete a point. This allows you to create complex shapes, such as:
+You can use the left mouse button to add a new point (keyboard: `A`) and right/middle mouse button (keyboard `X`) to delete a point. You can left click to drag existing points. This allows creating complex shapes, such as:
 
 <img alt="example of non-rectangular region" src="../assets/region-editor-region.jpg"/>
 
 Regions can be created by pressing `T` and deleted by pressing `G`.
-or to click-and-drag an existing point.
 
 <img alt="example of region mask" src="../assets/region-editor-multiple.jpg"/>
 

docs/index.md

@@ -11,7 +11,7 @@ hide:
 
 ------------------------------------------------------
 
-!!! success "Latest Version: 1.5.1 (August 15, 2022)"
+!!! success "Latest Version: 1.6 (October 15, 2023)"
 
     <div class="buttongrid">[:fontawesome-solid-download: &nbsp; Download](download.md){ .md-button #download-button }[:fontawesome-solid-book: User Guide](guide.md){ .md-button #changelog-button }[:fontawesome-solid-bars: &nbsp; Documentation](docs.md){ .md-button #documentation-button }[:fontawesome-solid-gear: &nbsp; Resources](changelog.md){ .md-button #quickstart-button }</div>
 

dvr-scan.cfg

@@ -83,13 +83,17 @@
 # while too low of a threshold can result in false detection events.
 #threshold = 0.15
 
+# Scores of this amount or higher are ignored. 255.0 is the maximum score, so
+# values greater than 255.0 will disable the filter.
+#max-threshold = 255.0
+
 # Size (in pixels) of the noise reduction kernel. Can be odd integer starting
 # from 3, 0 to disable, or -1 to auto-set using video resolution.
 #kernel-size = -1
 
-# Region file to limit detection area. Region files can be created using the
-# -r/--region-editor or -s/--save-region flags.
-#region-file = roi.txt
+# Region file to limit detection areas. Can be created with the -r / --region-editor
+# See < http://www.dvr-scan.com/guide/#region-editor > for an overview of the editor.
+#load-region = roi.txt
 
 # Integer factor to shrink video before processing. Values <= 1 have no effect.
 #downscale-factor = 0