[cli] More work on region editor and docs.

docs/docs.md

@@ -153,9 +153,36 @@ Detection can be limited to specific regions of the frame. This can be done inte
 
 Regions are specified as a list of points (X, Y) forming a closed polygon (shape with at least 3 points). For example, a triangle is defined as `0 0 100 0 50 50`. Multiple regions can be combined, and the result can also be saved to a file using `-s/--save-region`.
 
-!!! tip "Setting a region of interest improves scanning performance."
+!!! tip "Setting a smaller region of interest can improve scanning performance."
+
+ * <b><pre>-r, --region-editor</pre></b> Display region editor before processing. Press `H` to show controls in your terminal. See [the user guide](guide.md#region-editor) for more details.
+<span class="dvr-scan-example">
+```
+dvr-scan -i video.mp4 -r
+```
+</span>
+
+ * <b><pre>-a, --add-region</pre></b>Add a region to the scan. Regions are defined by a list of points (min. 3) that enclose the scanning region.
+<span class="dvr-scan-example">
+```
+dvr-scan -i video.mp4 -a 50 50 100 50 75 75
+```
+</span>
+
+ * <b><pre>-s, --save-region</pre></b>Save region data for this scan. Include all regions added or loaded via command line, and any edits made with the region editor if launched.
+<span class="dvr-scan-example">
+```
+dvr-scan -i video.mp4 -r -s regions.txt
+```
+</span>
+
+ * <b><pre>-R, --load-region</pre></b>Load region data an existing file.
+<span class="dvr-scan-example">
+```
+dvr-scan -i video.mp4 -R regions.txt
+```
+</span>
 
-TODO - This feature is under development in v1.6. More to come here.
 
 ------------------------------------------------
 

docs/guide.md

@@ -59,18 +59,60 @@ This should show a window that appears similar to:
 
 Press `H` to print a list of all controls.  Press `S` to save the current regions to a file, or `O` to load existing ones.  Regions can also be set, saved, and loaded [from the command line](docs.md#regions). Regions from the command line also appear in the the region editor, and any edits will be applied before processing.
 
-When you are satisfied with the region, press space bar or enter/return to start processing the video.  Hit escape at any time to quit the program.
+When you are satisfied with the region, press **space bar or enter to start processing** the video.  You can press **escape to quit** the program without saving.
 
 ### Regions
 
-You can use the left mouse button to add a new point to the current region, or drag existing points.  Points can be deleted by middle clicking (or right-click on Windows).  This allows you to create complex shapes, such as:
+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:
 
 <img alt="example of non-rectangular region" src="../assets/region-editor-region.jpg"/>
 
-You can hit `M` to view a cutout of the active mask:
+Regions can be created by pressing `Shift + A` and deleted by pressing `Shift + X`.
+or to click-and-drag an existing point.
 
-<img alt="example of region mask" src="../assets/region-editor-mask.jpg"/>
+<img alt="example of region mask" src="../assets/region-editor-multiple.jpg"/>
 
-A new region can be created by pressing `A`, and the selected region can be deleted by pressing `X`.  Regions can be selected using the number keys `1`-`9`, or by pressing `k`/`l` to select the previous/next region. Note that only one region can be active at a time (you must select an existing shape to modify it).
+Regions can be selected using the number keys `1`-`9`, or by pressing `k`/`l` to select the previous/next region. Note that only one region can be active at a time (you must select an existing shape to modify it).
 
-<img alt="example of region mask" src="../assets/region-editor-multiple.jpg"/>
+Lastly, you can hit `M` to view a cutout of the active mask:
+
+<img alt="example of region mask" src="../assets/region-editor-mask.jpg"/>
+
+### Controls
+
+#### Editor
+
+| Command | Keyboard | Alt |
+|--|--|--|
+| Mask On/Off | `M` | |
+| Start Scan | Space,<br/>Enter | |
+| Quit | Escape | |
+| Save | `S` | |
+| Load | `O` | |
+| Undo | `Z` | :fontawesome-brands-windows:`Ctrl + Z`|
+| Redo | `Y` | :fontawesome-brands-windows:`Ctrl + Y`|
+| Print Points | `C` | |
+
+#### Regions
+
+| Command | Keyboard | Mouse |
+|--|--|--|
+| Add Point | `A` | Left |
+| Delete Point | `X` | :fontawesome-brands-windows:Right<br/>:fontawesome-brands-linux:Middle |
+| Add Region | `Shift + A` | |
+| Delete Region | `Shift + X` | |
+| Select Region | `1` - `9` | |
+| Next Region | `L` | |
+| Previous Region | `K` | |
+
+#### Display
+
+| Command | Keyboard | Mouse |
+|--|--|--|
+| Downscale Increase | `W` | |
+| Downscale Decrease | `E` | |
+| Antialiasing | `Q` | |
+| Window Mode | `R` | |
+| Display Menu | | :fontawesome-brands-linux:Right |

docs/index.md

@@ -13,30 +13,34 @@ hide:
 
 !!! success "Latest Version: 1.5.1 (August 15, 2022)"
 
-    <div class="buttongrid">[:fontawesome-solid-download: &nbsp; Download](download.md){ .md-button #download-button }[:fontawesome-solid-book: User Guide](user_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>
+    <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 is a command-line application that **automatically detects motion events in video files** (e.g. security camera footage).  DVR-Scan looks for areas in footage containing motion, and saves each event to a separate video clip.  DVR-Scan is free and open-source software, and works on Windows, Linux, and Mac.
 
 ## :fontawesome-solid-person-running:Quickstart
 
-<img alt="overlay example" src="assets/bounding-box.gif"/>
-
 Scan `video.mp4` (separate clips for each event):
 
     dvr-scan -i video.mp4
 
-Only scan a region of interest (select with mouse):
+Only scan a region of interest ([see user guide](guide.md#region-editor) or hit `H` for controls):
+
+    dvr-scan -i video.mp4 -r
 
-    dvr-scan -i video.mp4 -roi
+<img alt="overlay example" src="assets/region-editor-multiple.jpg" width="480"/>
 
 Draw boxes around motion:
 
     dvr-scan -i video.mp4 -bb
 
+<img alt="overlay example" src="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).
+Once installed, see [the user guide](guide.md) to get started, try one of the examples above, or type `dvr-scan --help`. Press `Ctrl + C` to stop processing at any time.
+
+See the [documentation](docs.md) for a complete description of all [command-line](docs.md#dvr-scan-options) and [config file](docs.md#config-file) settings.

dvr-scan.cfg

@@ -75,7 +75,7 @@
 # * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 
 # Type of background subtraction to use, one of: MOG2, CNT, MOG2_CUDA
-# bg-subtractor = MOG2
+#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
@@ -87,6 +87,10 @@
 # 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
+
 # Integer factor to shrink video before processing. Values <= 1 have no effect.
 #downscale-factor = 0
 

dvr_scan/__main__.py

@@ -26,6 +26,7 @@
 EXIT_SUCCESS: int = 0
 EXIT_ERROR: int = 1
 
+
 def main():
     """Main entry-point for DVR-Scan."""
     settings = parse_settings()

dvr_scan/cli/__init__.py

@@ -353,6 +353,8 @@ def __call__(self, parser, namespace, values: List[str], option_string=None):
                 self, message if message else RegionAction.DEFAULT_ERROR_MESSAGE)) from ex
 
         # Append this ROI to any existing ones, if any.
+        # TODO(v1.7): Audit uses of the 'regions' constant for -a/--add-region, replace with a named
+        # constant where possible.
         items = getattr(namespace, 'regions', [])
         items += [region.value]
         setattr(namespace, 'regions', items)

dvr_scan/cli/controller.py

@@ -41,22 +41,26 @@ def __init__(self, args: argparse.Namespace, config: ConfigRegistry):
         self._args = args
         self._config = config
 
+    @property
+    def config(self) -> ConfigRegistry:
+        return self._config
+
     def get_arg(self, arg: str) -> ty.Optional[ty.Any]:
         """Get setting specified via command line argument, if any."""
         arg_name = arg.replace('-', '_')
         return getattr(self._args, arg_name) if hasattr(self._args, arg_name) else None
 
-    def get(self, option: str, arg: ty.Optional[str] = None) -> ty.Union[str, int, float, bool]:
+    def get(self, option: str) -> ty.Union[str, int, float, bool]:
         """Get setting based on following resolution order:
             1. Argument specified via command line.
             2. Option set in the active config file (either explicit with -c/--config, or
                the dvr-scan.cfg file in the user's settings folder).
             3. Default value specified in the config map (`dvr_scan.cli.config.CONFIG_MAP`).
         """
-        arg_val = self.get_arg(option if arg is None else arg)
+        arg_val = self.get_arg(option)
         if arg_val is not None:
             return arg_val
-        return self._config.get_value(option)
+        return self.config.get_value(option)
 
 
 def _preprocess_args(args):
@@ -269,11 +273,18 @@ def run_dvr_scan(settings: ProgramSettings) -> ty.List[ty.Tuple[FrameTimecode, F
         duration=settings.get_arg('duration'),
     )
 
-    # TODO(v1.7): Ensure ROI window respects start time if set.
+    # If the user specified some regions on the command line, ignore the load-regions setting in the
+    # config file.
+    load_region = settings.get_arg('load-region')
+    if load_region is None:
+        load_region = settings.config.get_value('load-region', ignore_default=True)
+        if not settings.get_arg('regions') is None:
+            load_region = None
+
     scanner.set_regions(
-        region_editor=settings.get('region-editor'),
+        region_editor=settings.get_arg('region-editor'),
         regions=settings.get_arg('regions'),
-        load_region=settings.get('load-region'),
+        load_region=load_region,
         save_region=settings.get_arg('save-region'),
     )