Merge branch 'release/0.6.0'

mlange-42 · Apr 17, 2020 · afa7850 · afa7850
2 parents 3ddceeb + f683fa1
commit afa7850
Show file tree

Hide file tree

Showing 14 changed files with 603 additions and 105 deletions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "chrono-photo"
-version = "0.5.0"
+version = "0.6.0"
 authors = ["m-lange <martin_lange_@gmx.net>"]
 edition = "2018"
 

diff --git a/README.md b/README.md
@@ -204,6 +204,10 @@ OPTIONS:
         --sample <sample>           Restricts calculation of median and inter-quartile range to a sub-sample of input
                                     images. Use for large amounts of images to speed up calculations. Optional. Used
                                     with `--mode outlier` only
+        --shake <r1/r2>             Camera shake reduction parameters. Optional, default none. Format: `anchor-
+                                    radius/shake-radius`
+        --shake-anchors <x/y>...    Camera shake reduction anchors. Optional, default none. Format: `x1/y1 [x2/y2
+                                    [...]]`
     -s, --slice <slice>             Controls slicing to temp files (rows|pixels|count)/<number>. Used with `--mode
                                     outlier` only. Optional, default 'rows/4'
     -d, --temp-dir <path>           Temp directory. Used with `--mode outlier` only. Optional, default system temp

diff --git a/cmd_examples/shake.bat b/cmd_examples/shake.bat
@@ -0,0 +1,8 @@
+..\target\release\chrono-photo ^
+  --pattern "../test_data/generated/image-*.jpg" ^
+  --output ../test_data/out.jpg ^
+  --temp-dir ../test_data/temp ^
+  --shake 5/5 ^
+  --shake-anchors 992/692 ^
+  --debug
+pause
diff --git a/docs/options.md b/docs/options.md
@@ -9,6 +9,8 @@
 [--background](#--background) &nbsp; [--weights](#--weights) &nbsp; [--fade](#--fade)
 * [Video creation](#video-creation)
   * [--video-in](#--video-in) &nbsp; [--video-out](#--video-out)
+* [Camera shake reduction](#camera-shake-reduction)
+  * [--shake](#--shake) &nbsp; [--shake-anchors](#--shake-anchors)
 * [Performance](#performance)
   * [--threads](#--threads) &nbsp; [--video-threads](#--video-threads) &nbsp; [--sample](#--sample) &nbsp; [--compression](#--compression) &nbsp; [--slice](#--slice)
 
@@ -225,6 +227,43 @@ Everything here refer to the frames left _after_ selection through option [`--fr
 
 _Default:_ No video output, or `././.` if `--video-in` is specified.
 
+## Camera shake reduction
+
+To enable camera shake reduction, both of the following options must be supplied.
+By default, no camera shake reduction is applied.
+
+If camera shake is detected, images are cropped by the amount of shake for correction.
+Thus, the output image will be slightly smaller than the input images.
+
+#### `--shake`
+
+_Optional._ Shake anchor radius and search radius in format `anchor-radius/search-radius`.
+
+Example:
+```
+--shake 10/5
+```
+_Default:_ No camera shake reduction.
+
+#### `--shake-anchors`
+
+_Optional._ Pixel coordinates of shake detection anchors in the _first_ image. 
+Format `x1/y1 [x2/y2 ...]`.
+
+Anchors are optimally placed at positions with high contrast in both directions (x, y),
+like a dark corner on light background.
+Also, anchors should not be occluded by a moving object in any image of the sequence.
+
+Use an image editing software to get the exact pixel coordinates.
+Origin is the top-left corner of the image.
+
+Example:
+```
+--shake-anchors 1234/789 2345/890
+```
+
+_Default:_ No camera shake reduction.
+
 ## Performance
 
 #### `--threads`

diff --git a/docs/tutorial_photos.md b/docs/tutorial_photos.md
@@ -13,13 +13,15 @@ We assume that you have such an image sequence ready, e.g. obtained by following
 File extensions are for Windows. On Linux or Mac OSX, they need to be adapted accordingly.
 Particularly Windows batch files (`.bat`) need to be replaces by Unix shell scripts (`.sh`). 
 
-For detailed explanation of all available options, see the [Command line options](options.md) documentation file.
+See the **[Command line options](options.md)** documentation file for detailed explanation of all available options.
 
 **Content**
 * [Working directory](#working-directory)
+* [Printing help message](#printing-help-message)
 * [Most simple command](#most-simple-command)
 * [Fast algorithm for large projects](#fast-algorithm-for-large-projects)
 * [Tweaking algorithm parameters](#tweaking-algorithm-parameters)
+* [Camera shake reduction](#camera-shake-reduction)
 * [Summary](#summary)
 
 ## Working directory
@@ -40,6 +42,17 @@ No further files from the installation directory are required.
 The above structure is not required, we assume it just for convenient command line usage.
 E.g., input images and output folder can be in completely different locations.
 
+## Printing help message
+
+To print help for `chrono-photo`, run
+```
+chrono-photo -h
+```
+or, for more comprehensive help texts
+```
+chrono-photo --help
+```
+
 ## Most simple command
 
 We start by processing the images using standard parameters. 
@@ -105,6 +118,10 @@ We want to use the outlier algorithm, with an "absolute" threshold range
 Selection between background pixels will be done randomly,
 while the most extreme outlier is selected in case outliers are found.
 
+## Camera shake reduction
+
+[TODO]
+
 ## Summary
 
 [TODO]

diff --git a/docs/tutorial_recording.md b/docs/tutorial_recording.md
@@ -46,6 +46,10 @@ a still background and steady camera.
 The long time span covered as well as the higher resolution compared to video take their toll here.
 Additionally, some manual corrections may be required afterwards.
 
+As a fallback, `chrono-photo` provides optional camera shake reduction. 
+For details, see section [Camera shake reduction](options.md#camera-shake-reduction)
+in the options' documentation.
+
 The following points apply no matter whether photos or videos are recorded,
 but the focus is primarily on video.
 

diff --git a/src/cli.rs b/src/cli.rs
@@ -1,6 +1,7 @@
 //! Command-line interface for chrono-photo.
 use crate::flist::FrameRange;
 use crate::options::{BackgroundMode, Fade, OutlierSelectionMode, SelectionMode, Threshold};
+use crate::shake::{ShakeAnchor, ShakeParams, ShakeReduction};
 use crate::slicer::SliceLength;
 use crate::streams::Compression;
 use core::fmt;
@@ -110,6 +111,15 @@ pub struct Cli {
     #[structopt(long, name = "video-threads", value_name = "num")]
     video_threads: Option<usize>,
 
+    /// Camera shake reduction parameters. Optional, default none.
+    /// Format: `anchor-radius/shake-radius`
+    #[structopt(long, value_name = "r1/r2")]
+    shake: Option<ShakeParams>,
+
+    /// Camera shake reduction anchors. Optional, default none. Format: `x1/y1 [x2/y2 [...]]`
+    #[structopt(long, name = "shake-anchors", value_name = "x/y")]
+    shake_anchors: Option<Vec<ShakeAnchor>>,
+
     /// Print debug information (i.e. parsed cmd parameters).
     #[structopt(long)]
     debug: bool,
@@ -145,13 +155,21 @@ impl Cli {
                 warings.push("--compression".to_string());
             }
         }
+        if self.shake.is_some() != self.shake_anchors.is_some() {
+            return Err(ParseCliError(
+                "Provide both options or none: `--shake` and `--shake-anchors`".to_string(),
+            ));
+        }
 
         let mut weights = [1.0; 4];
         if let Some(w) = &self.weights {
             for (i, v) in w.iter().enumerate() {
                 weights[i] = *v;
             }
         }
+
+        let shake_params = self.shake;
+        let shake_anchors = self.shake_anchors;
         let out = CliParsed {
             pattern: self.pattern,
             // is_16bit: self.is_16bit,
@@ -188,6 +206,15 @@ impl Cli {
             fade: self.fade.unwrap_or(Fade::none()),
             threads: self.threads,
             video_threads: self.video_threads,
+            shake_reduction: shake_params.and_then(|shake| {
+                shake_anchors.and_then(|anchors| {
+                    Some(ShakeReduction::new(
+                        anchors.iter().map(|a| a.anchor()).collect(),
+                        shake.anchor_radius(),
+                        shake.search_radius(),
+                    ))
+                })
+            }),
             debug: self.debug,
         };
 
@@ -248,6 +275,8 @@ pub struct CliParsed {
     pub threads: Option<usize>,
     /// Number of threads for parallel video frame output. Optional, default equal to number of processors.
     pub video_threads: Option<usize>,
+    /// Shake reduction
+    pub shake_reduction: Option<ShakeReduction>,
     /// Print debug information (i.e. parsed cmd parameters).
     pub debug: bool,
 }

diff --git a/src/lib.rs b/src/lib.rs
@@ -3,6 +3,7 @@ pub mod cli;
 pub mod color;
 pub mod flist;
 pub mod options;
+pub mod shake;
 pub mod simple;
 pub mod slicer;
 pub mod streams;