Merge branch 'demmeln/optical-flow-comments' into 'master'

High-level comments for optical flow classes

See merge request basalt/basalt!52

include/basalt/optical_flow/frame_to_frame_optical_flow.h

@@ -51,6 +51,10 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 namespace basalt {
 
+/// Unlike PatchOpticalFlow, FrameToFrameOpticalFlow always tracks patches
+/// against the previous frame, not the initial frame where a track was created.
+/// While it might cause more drift of the patch location, it leads to longer
+/// tracks in practice.
 template <typename Scalar, template <typename> typename Pattern>
 class FrameToFrameOpticalFlow : public OpticalFlowBase {
  public:

include/basalt/optical_flow/multiscale_frame_to_frame_optical_flow.h

@@ -54,6 +54,9 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 namespace basalt {
 
+/// MultiscaleFrameToFrameOpticalFlow is the same as FrameToFrameOpticalFlow,
+/// but patches can be created at all pyramid levels, not just the lowest
+/// pyramid.
 template <typename Scalar, template <typename> typename Pattern>
 class MultiscaleFrameToFrameOpticalFlow : public OpticalFlowBase {
  public:

include/basalt/optical_flow/patch_optical_flow.h

@@ -50,6 +50,15 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 namespace basalt {
 
+// TODO: patches are currently never erased, so over time memory consumption
+// increases
+// TODO: some changes from FrameToFrameOpticalFlow could be back-ported
+// (adjustments to Scalar=float, tbb parallelization, ...).
+
+/// PatchOpticalFlow keeps reference patches from the frame where the point was
+/// initially created. Should result in more consistent tracks (less drift over
+/// time) than frame-to-frame tracking, but it results in shorter tracks in
+/// practice.
 template <typename Scalar, template <typename> typename Pattern>
 class PatchOpticalFlow : public OpticalFlowBase {
  public: