Improve the documentation (open-mmlab#85)

* fix doc generation

* add docs for optical flow

* fix typo

docs/conf.py

@@ -24,7 +24,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'mmcv'
-copyright = '2018, Kai Chen'
+copyright = '2018-2019, Kai Chen'
 author = 'Kai Chen'
 
 # The short X.Y version
@@ -45,6 +45,7 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
+    'recommonmark',
 ]
 
 autodoc_mock_imports = ['cv2', 'torch', 'enum', 'pathlib']
@@ -55,9 +56,10 @@
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-source_suffix = ['.rst', '.md']
-
-source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
 
 # The master toctree document.
 master_doc = 'index'

docs/video.md

@@ -4,9 +4,11 @@ This module provides the following functionalities.
 
 - A `VideoReader` class with friendly apis to read and convert videos.
 - Some methods for editing (cut, concat, resize) videos.
-- Optical flow read/write.
+- Optical flow read/write/warp.
 
 
+### VideoReader
+
 The `VideoReader` class provides sequence like apis to access video frames.
 It will internally cache the frames which have been visited.
 
@@ -42,6 +44,8 @@ video.cvt2frames('out_dir')
 mmcv.frames2video('out_dir', 'test.avi')
 ```
 
+### Editing utils
+
 There are also some methods for editing videos, which wraps the commands of ffmpeg.
 
 ```python
@@ -56,4 +60,59 @@ mmcv.resize_video('test.mp4', 'resized1.mp4', (360, 240))
 
 # resize a video with a scaling ratio of 2
 mmcv.resize_video('test.mp4', 'resized2.mp4', ratio=2)
-```
+```
+
+### Optical flow
+
+`mmcv` provides the following methods to operate on optical flows.
+
+- IO
+- Visualization
+- Flow warpping
+
+We provide two options to dump optical flow files: uncompressed and compressed.
+The uncompressed way just dumps the floating numbers to a binary file. It is
+lossless but the dumped file has a larger size.
+The compressed way quantizes the optical flow to 0-255 and dumps it as a
+jpeg image. The flow of x-dim and y-dim will be concatenated into a single image.
+
+```python
+flow = np.random.rand(800, 600, 2).astype(np.float32)
+# dump the flow to a flo file (~3.7M)
+mmcv.flowwrite(flow, 'uncompressed.flo')
+# dump the flow to a jpeg file (~230K)
+# the shape of the dumped image is (800, 1200)
+mmcv.flowwrite(flow, 'compressed.jpg', quantize=True, concat_axis=1)
+
+# read the flow file, the shape of loaded flow is (800, 600, 2) for both ways
+flow = mmcv.flowread('uncompressed.flo')
+flow = mmcv.flowread('compressed.jpg', quantize=True, concat_axis=1)
+```
+
+It is possible to visualize optical flows with `mmcv.flowshow()`.
+
+```python
+mmcv.flowshow(flow)
+```
+
+![progress](_static/flow_visualization.png)
+
+3. Flow warpping
+
+```python
+img1 = mmcv.imread('img1.jpg')
+flow = mmcv.flowread('flow.flo')
+warpped_img2 = mmcv.flow_warp(img1, flow)
+```
+
+img1 (left) and img2 (right)
+
+![raw images](_static/flow_raw_images.png)
+
+optical flow (img2 -> img1)
+
+![optical flow](_static/flow_img2toimg1.png)
+
+warpped image and difference with ground truth
+
+![warpped image](_static/flow_warp_diff.png)

mmcv/opencv_info.py

@@ -2,7 +2,11 @@
 
 
 def use_opencv2():
-    return cv2.__version__.split('.')[0] == '2'
+    try:
+        major_version = cv2.__version__.split('.')[0]
+    except TypeError:  # solves doc generation issue
+        major_version = 4
+    return major_version == '2'
 
 
 USE_OPENCV2 = use_opencv2()

mmcv/version.py

@@ -1 +1 @@
-__version__ = '0.2.8'
+__version__ = '0.2.9'