[docs] Reorganize config file template to match UI

dist/pre_release.py

@@ -113,6 +113,12 @@ def build_docs(use_local_images=True):
         print("Postprocessing docs.")
 
         delete_and_replace = [
+            "assets/app-ffmpeg-settings.jpg",
+            "assets/app-input-settings.jpg",
+            "assets/app-main-window.jpg",
+            "assets/app-motion-settings.jpg",
+            "assets/app-opencv-settings.jpg",
+            "assets/app-scan-window.jpg",
             "assets/bounding-box.gif",
             "assets/dvr-scan-logo.png",
             "assets/dvr-scan.ico",

docs/faq.md

@@ -2,15 +2,7 @@
 # :fontawesome-solid-keyboard:Frequently Asked Questions
 
 
-----------------------------------------------------------
-
-
-### How do I run DVR-Scan?
-
-Currently, DVR-Scan is a command-line program only, and must be launched from a terminal or command prompt (e.g. `cmd.exe` on Windows).
-In the meantime, Windows users can [use these instructions](https://github.com/Breakthrough/DVR-Scan/issues/178) create helpful drag-and-drop shortcuts. These will allow you to run DVR-Scan by dragging and dropping the video(s) you want to scan.
-
-!!! note "A [beta release for the new GUI version of DVR-Scan](https://github.com/Breakthrough/DVR-Scan/releases/tag/v1.7-dev0) is now available for testing on Windows/Linux/OSX!"
+## Command-Line Interface
 
 
 ----------------------------------------------------------

docs/guide.md

@@ -1,101 +1,39 @@
 
 # :fontawesome-solid-circle-info: User Guide
 
-## :fontawesome-solid-terminal:Running DVR-Scan
-
-After installation, the `dvr-scan` command should be available from a terminal or command prompt. Try running `dvr-scan --help`.
-
-!!! info "For portable versions, replace `dvr-scan` with the path to `dvr-scan.exe` in the extracted files on your system."
-
-To extract all motion events from a video, you can start with:
-
-    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 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).
-
-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. Lastly, most program options can be set [using a config file](docs.md#config-file).  DVR-Scan also looks for a `dvr-scan.cfg` file in the following locations:
-
- * Windows: `C:/Users/%USERNAME%/AppData/Local/DVR-Scan/dvr-scan.cfg`
- * Linux: `~/.config/DVR-Scan/dvr-scan.cfg` or `$XDG_CONFIG_HOME/dvr-scan.cfg`
- * OSX: `~/Library/Preferences/DVR-Scan/dvr-scan.cfg`
-
-These settings will be used by default each time you run DVR-Scan, unless you override them.
-
-### Running Without Terminal
-
-A GUI is being developed for DVR-Scan but is not yet available. In the meantime, Windows users can see [Issue #178](https://github.com/Breakthrough/DVR-Scan/issues/178) for instructions on how to create drag-and-drop shortcuts to run DVR-Scan without needing to type commands.
-
-### Multiple Videos
 
-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
-
-Wildcards are also supported:
-
-    dvr-scan -i video*.mp4
-
-Note that this will **concatenate** the videos together *in the order they are specified*.
-
-This can be undesirable for some types of footage being analyzed.  For example, if a folder contains different dashcam footage clips, a significant amount of time can pass between clips (e.g. when the vehicle is shut off).  This can result in DVR-Scan generating false events between videos.
-
-To avoid this, you can run DVR-Scan on each video in a loop. For example, on Windows:
-
-    for /F %i in ('dir *.mp4 /b') do dvr-scan -i %i
-
-Or on Linux/OSX:
-
-    for f in /mnt/videos/*.mp4
-    do
-        dvr-scan -i $f
-    done
-
-Note that multiple inputs also do not support other output modes. You can use `ffmpeg` to [concatenate all input videos](https://trac.ffmpeg.org/wiki/Concatenate) before processing, or use a for-loop as above.
-
-### Output Format
-
-By default, DVR-Scan uses the OpenCV VideoWriter for video output. This usually requires the output files be in .AVI format of some kind.
+## :fontawesome-solid-terminal:Running DVR-Scan
 
-DVR-Scan also supports using `ffmpeg` to extract motion events. This is done by setting `-m`/`--output-mode` to `ffmpeg` (reencode) or `copy` (codec copy mode, may not be frame accurate). For example:
+After installation, you can run DVR-Scan by clicking on the application shortcut, or running `dvr-scan-app` from a terminal. If you downloaded the portable version, run `dvr-scan-app.exe`.
 
-    dvr-scan -i video.mp4 -m ffmpeg
+!!! note "The `dvr-scan` command is the command-line interface for DVR-Scan. To launch the GUI, run `dvr-scan-app`. For help with the command-line interface or config files, see the [Documentation](docs.md) page for details. "
 
-You can customize the options passed to `ffmpeg` using a [config file](docs.md#config-file) (see [the `ffmpeg-input-args` and `ffmpeg-output-args`](docs.md#output)) settings).
+Start by clicking the <b>Add</b> button to add one or more videos:
 
-Setting output mode to `ffmpeg` or `copy` has the following caveats:
+<img alt="[Main App Window]" src="../assets/app-main-window.jpg"/>
 
- - inputs that have a variable framerate (VFR) may not be  extracted reliably
- - input concatenation is not supported
- - overlays are not supported
+To extract and save the motion events from the input, click the <b>Start</b> button. You will be prompted for a location to save the events to, after which scanning will begin:
 
-You can customize the options passed to `ffmpeg` using a [config file](docs.md#config-file) (see [the `ffmpeg-input-args` and `ffmpeg-output-args`](docs.md#options)) settings).
 
-### VFR (Variable Framerate)
+<img alt="[Scan Window]" src="../assets/app-scan-window.jpg"/>
 
-!!! warning "Variable framerate (VFR) video support is still under development and may produce incorrect results."
+Once complete, each event will be saved to the output folder you selected.  To tune motion sensitivity, go to <b>Settings -> Motion</b> and adjust threshold, where lower values are more sensitive to motion, and higher values are less sensitive.  You can also adjust event settings and more:
 
-Variable framerate (VFR) videos are *not well supported*, but basic functionality does work. Motion detection and event extraction should work correctly with default settings. Note however that calculated timestamps may be incorrect, and extracted footage may playback at the wrong speed.
 
-Frame numbers will be accurate, but timestamps will not.  This can yield incorrect results when setting output mode to `ffmpeg` or `copy`, as well as inaccurate timestamps when using overlays. This issue is [tracked on Github](https://github.com/Breakthrough/PySceneDetect/issues/168).  If this workflow is required, you can re-encode the source material into fixed framerate before processing.
+<img alt="[Motion Settings Window]" src="../assets/app-motion-settings.jpg"/>
 
+See [the config option documentation](docs.md#config-file) for a detailed description of each setting.
 
 ## :fontawesome-solid-crop-simple:Region Editor
 
-With the Region Editor, you can limit motion detection to specific areas of the frame.  You can launch the region editor by by adding `-r`/`--region-editor` to the DVR-Scan command:
-
-    dvr-scan -i video.mp4 -r
-
-The region editor will open and display a rectangle over the first frame:
+The Region Editor allows you to limit motion detection to specific areas of the frame. Once you have a video loaded, check "Set Regions" and press the "Region Editor" button:
 
 <img alt="[Region Editor Startup Window]" src="../assets/region-editor-start.jpg"/>
 
 You can use the mouse to add or move points when editing regions. Left click to add a new point, or drag an existing one. Right click can be used to delete a point, and to add/remove shapes.
 
-To begin scanning, click File -> Start Scan. You will be prompted to save the regions you have created before scanning so you can re-use them if required.
+To begin scanning, close the region editor, and click the Start button.  You will be prompted to save the regions you have created before scanning so you can re-use them if required.
 
 ### Regions
 

dvr-scan.cfg

@@ -19,7 +19,6 @@
 
 # * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 #  GENERAL
-#
 # * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 
 # Show region editor window (-r/--region-editor) before scanning.
@@ -34,7 +33,7 @@
 
 
 # * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
-#  INPUT / OUTPUT
+#  INPUT
 # * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 
 # Which mode to use for decoding frames. Possible values are: OPENCV, PYAV,
@@ -45,6 +44,17 @@
 # timestamp accuracy with videos and network streams that may skip frames.
 #use-pts = no
 
+# Integer factor to shrink video before processing. Values <= 1 have no effect.
+#downscale-factor = 0
+
+# Number of frames to skip between processing when looking for motion events.
+#frame-skip = 0
+
+
+# * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+#  OUTPUT
+# * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
 # Directory to output all created files. If unset, files will be created
 # in the current working directory.
 #output-dir = /usr/tmp/somedir
@@ -66,7 +76,7 @@
 
 
 # * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
-#  MOTION EVENTS
+#  MOTION
 # * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 
 # Amount of time which must have motion in each frame to trigger an event.
@@ -78,19 +88,24 @@
 # Amount of time to include after an event.
 #time-post-event = 2.0s
 
+# Threshold representing amount of motion in a frame (or the ROI, if set) for
+# a motion event to be triggered. Lower values require less movement, and are
+# more sensitive to motion. If too high, some movement may not be detected,
+# while too low of a threshold can result in false detection events.
+#threshold = 0.15
+
 
 # * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
-#  DETECTION PARAMETERS
+#  ADVANCED
 # * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 
+
 # Type of background subtraction to use, one of: MOG2, CNT, MOG2_CUDA
 #bg-subtractor = MOG2
 
-# Threshold representing amount of motion in a frame (or the ROI, if set) for
-# a motion event to be triggered. Lower values require less movement, and are
-# more sensitive to motion. If too high, some movement may not be detected,
-# while too low of a threshold can result in false detection events.
-#threshold = 0.15
+# 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
 
 # Scores of this amount or higher are ignored. 255.0 is the maximum score, so
 # values greater than 255.0 will disable the filter.
@@ -107,29 +122,31 @@
 # The threshold is not used by the CNT subtractor.
 #variance-threshold = 16
 
-# 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 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
+# * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+#  BOUNDING BOX OVERLAY
+# * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 
-# Integer factor to shrink video before processing. Values <= 1 have no effect.
-#downscale-factor = 0
+# Enable/disable overlay.
+#bounding-box = yes
 
-# Number of frames to skip between processing when looking for motion events.
-#frame-skip = 0
+# Box edge color in the form (R,G,B) or 0xFFFFFF
+#bounding-box-color = 255, 0, 0
+
+# Thickness of bounding box, relative to largest edge of input video.
+#bounding-box-thickness = 0.0032
+
+# Amount of temporal smoothing to apply.
+#bounding-box-smooth-time = 0.1s
+
+# Minimum side length of bounding box, relative to largest edge of input video.
+#bounding-box-min-size = 0.032
 
 
 # * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
-#  OVERLAYS
+#  TEXT OVERLAYS
 # * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 
-#
-# Text Overlays
-#
-
 # Enable/disable timecode overlay in top-left of video frame.
 #time-code = yes
 
@@ -153,23 +170,3 @@
 
 # Text background color in the form (R,G,B) or 0xFFFFFF
 #text-bg-color = 0, 0, 0
-
-
-#
-# Bounding Box Overlay
-#
-
-# Enable/disable overlay.
-#bounding-box = yes
-
-# Box edge color in the form (R,G,B) or 0xFFFFFF
-#bounding-box-color = 255, 0, 0
-
-# Thickness of bounding box, relative to largest edge of input video.
-#bounding-box-thickness = 0.0032
-
-# Amount of temporal smoothing to apply.
-#bounding-box-smooth-time = 0.1s
-
-# Minimum side length of bounding box, relative to largest edge of input video.
-#bounding-box-min-size = 0.032