Merge pull request #56 from gift-surg/18-extend-api-to-support-stereo…

…-streams

3D capture on Blackmagic DeckLink 4K Extreme 12G

.gitignore

@@ -18,3 +18,5 @@ src/*.egg-info
 *.swp
 src/tests/pipeline/mtr-build
 gg-iss-16
+gg-iss-5
+bm3d-build

.gitlab-ci.yml

@@ -133,7 +133,6 @@ pypi:
     - cd $GiftGrab_venv
     - source bin/activate
     - pip install pytest
-    - pip install pyyaml
     - ls -alh ./*
     - PyPI_INSTALLER="../$GiftGrab_PyPI_DIST_DIR/$(ls ../$GiftGrab_PyPI_DIST_DIR | grep tar.gz)"
     - if [ -z "$PyPI_INSTALLER" ]; then exit 1; fi
@@ -173,6 +172,10 @@ pypi:
     - pip install numpy
     - $TEST_LAUNCHER numpy bgra; exit_on_fail
     - $TEST_LAUNCHER numpy i420; exit_on_fail
+    # Runt stereo frame tests
+    - $TEST_LAUNCHER stereo bgra; exit_on_fail
+    - $TEST_LAUNCHER stereo i420; exit_on_fail
+    - $TEST_LAUNCHER stereo uyvy; exit_on_fail
     # test support for video files
     - pip install -vvv --install-option="--hevc" --install-option="--enable-nonfree" --install-option="--nvenc" --install-option="--xvid" --install-option="--vp9" --install-option="--numpy" --install-option="--files" --upgrade "$PyPI_INSTALLER"
     - $TEST_LAUNCHER decode hevc bgra; exit_on_fail
@@ -430,8 +433,9 @@ pypi-blackmagic-decklink-sdi-4k:
     - PyPI_INSTALLER="../$GiftGrab_PyPI_DIST_DIR/$(ls ../$GiftGrab_PyPI_DIST_DIR | grep tar.gz)"
     - if [ -z "$PyPI_INSTALLER" ]; then exit 1; fi
     # because pip seems to be getting confused about install options sometimes:
-    - pip install PyYAML
     - pip install pytest
+    - pip install numpy
+    - pip install scipy
     - pip install -vvv --install-option="--blackmagic-decklink-sdi-4k" --install-option="--enable-nonfree" --upgrade "$PyPI_INSTALLER"
     # run tests
     - $TEST_LAUNCHER blackmagic-decklinksdi4k uyvy; exit_on_fail
@@ -444,6 +448,9 @@ pypi-blackmagic-decklink-sdi-4k:
     - 23-support-for-blackmagic-decklink-4k-extreme-12g
     - 20-support-for-capturing-bgra-frames-with-blackmagic-devices
     - 14-unable-to-free-blackmagic-video-source
+    - 5-support-for-3d-capture-on-blackmagic-cards
+    - 18-extend-api-to-support-stereo-streams
+    - 30-12-bit-rgb-to-bgra-converter-for-decklink
 
 blackmagic-decklink-sdi-4k:
   stage: test_cmake
@@ -466,6 +473,9 @@ blackmagic-decklink-sdi-4k:
     - 23-support-for-blackmagic-decklink-4k-extreme-12g
     - 20-support-for-capturing-bgra-frames-with-blackmagic-devices
     - 14-unable-to-free-blackmagic-video-source
+    - 5-support-for-3d-capture-on-blackmagic-cards
+    - 18-extend-api-to-support-stereo-streams
+    - 30-12-bit-rgb-to-bgra-converter-for-decklink
 
 ################## Device: Blackmagic DeckLink 4K Extreme 12G ##################
 pypi-blackmagic-decklink-4k-extreme-12g:
@@ -494,9 +504,10 @@ pypi-blackmagic-decklink-4k-extreme-12g:
     - PyPI_INSTALLER="../$GiftGrab_PyPI_DIST_DIR/$(ls ../$GiftGrab_PyPI_DIST_DIR | grep tar.gz)"
     - if [ -z "$PyPI_INSTALLER" ]; then exit 1; fi
     # because pip seems to be getting confused about install options sometimes:
-    - pip install PyYAML
     - pip install pytest
-    - pip install -vvv --install-option="--blackmagic-decklink-4k-extreme-12g" --install-option="--enable-nonfree" --upgrade "$PyPI_INSTALLER"
+    - pip install numpy
+    - pip install scipy
+    - pip install -vvv --install-option="--blackmagic-decklink-4k-extreme-12g" --install-option="--enable-nonfree" --install-option="--numpy" --upgrade "$PyPI_INSTALLER"
     # run tests
     - $TEST_LAUNCHER blackmagic-decklink4kextreme12g uyvy; exit_on_fail
     - $TEST_LAUNCHER blackmagic-decklink4kextreme12g bgra; exit_on_fail
@@ -510,6 +521,9 @@ pypi-blackmagic-decklink-4k-extreme-12g:
     - 20-support-for-capturing-bgra-frames-with-blackmagic-devices
     - 32-videosourcefactory-destructor-does-not-free-all-devices
     - 14-unable-to-free-blackmagic-video-source
+    - 5-support-for-3d-capture-on-blackmagic-cards
+    - 18-extend-api-to-support-stereo-streams
+    - 30-12-bit-rgb-to-bgra-converter-for-decklink
 
 blackmagic-decklink-4k-extreme-12g:
   stage: test_cmake
@@ -520,7 +534,7 @@ blackmagic-decklink-4k-extreme-12g:
     - rm -rf "$GiftGrab_BUILD_DIR"
     - mkdir -p "$GiftGrab_BUILD_DIR"
     - cd "$GiftGrab_BUILD_DIR"
-    - cmake -D BUILD_PYTHON=ON -D BUILD_TESTS=ON -D USE_BLACKMAGIC_DECKLINK_4K_EXTREME_12G=ON -D ENABLE_NONFREE=ON "$GiftGrab_SOURCE_DIR"
+    - cmake -D BUILD_PYTHON=ON -D USE_NUMPY=ON -D BUILD_TESTS=ON -D USE_BLACKMAGIC_DECKLINK_4K_EXTREME_12G=ON -D ENABLE_NONFREE=ON "$GiftGrab_SOURCE_DIR"
     - make -j; exit_on_fail
     - ctest; exit_on_fail
   tags:
@@ -531,3 +545,6 @@ blackmagic-decklink-4k-extreme-12g:
     - 20-support-for-capturing-bgra-frames-with-blackmagic-devices
     - 32-videosourcefactory-destructor-does-not-free-all-devices
     - 14-unable-to-free-blackmagic-video-source
+    - 5-support-for-3d-capture-on-blackmagic-cards
+    - 18-extend-api-to-support-stereo-streams
+    - 30-12-bit-rgb-to-bgra-converter-for-decklink

doc/requirements.md

@@ -52,7 +52,7 @@ The parantheses in the version column mean that the listed version has been test
 | [libvpx](https://www.webmproject.org/code/) | 1.3.0 | |
 | [libVLC (VLC SDK)](https://wiki.videolan.org/LibVLC/) | 3.0.0 release candidate: [nighly build ID: 20160913-0237](http://nightlies.videolan.org/build/source/?C=M;O=D) | Please see the note in the [libVLC installation instructions](tips.md#libvlc) about using libVLC for capturing network streams. |
 | [Epiphan Video Grabber SDK](https://www.epiphan.com/support/) | 3.30.3.0007 | Epiphan Video Grabber SDK has a proprietary licence: enabling Epiphan Video Grabber SDK makes GIFT-Grab undistributable. |
-| [Blackmagic Desktop Video SDK](https://www.blackmagicdesign.com/support) | 10.4 | Blackmagic Desktop Video SDK has a proprietary licence: enabling support for Blackmagic cards makes GIFT-Grab undistributable. |
+| [Blackmagic Desktop Video SDK](https://www.blackmagicdesign.com/support) | 10.11 | Blackmagic Desktop Video SDK has a proprietary licence: enabling support for Blackmagic cards makes GIFT-Grab undistributable. |
 | [Python](https://www.python.org/) | 2.7 | |
 | [Boost.Python](http://www.boost.org/doc/libs/release/libs/python/) | 1.54.0, and 1.63.0 beta 1 for NumPy support | |
 | [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/) | | |

doc/source/index.rst

@@ -52,6 +52,7 @@ Examples
    scipy
    encoding
    complex
+   stereo
 
 Citing GIFT-Grab
 ^^^^^^^^^^^^^^^^

doc/source/stereo.rst

@@ -0,0 +1,25 @@
+.. _Stereo:
+
+Capturing stereo video
+======================
+
+GIFT-Grab allows for capturing stereo video streams from frame grabbers supporting this
+feature.
+The example below demonstrates how stereo frames can be acquired and saved to individual
+image files.
+Running this example requires GIFT-Grab built/installed with support for
+`Blackmagic DeckLink 4K Extreme 12G`_ and NumPy_.
+The example uses OpenCV_ to save video frames to disk.
+
+.. _`Blackmagic DeckLink 4K Extreme 12G`: https://github.com/gift-surg/GIFT-Grab/blob/master/doc/pypi.md#blackmagic-decklink-4k-extreme-12g
+.. _NumPy: https://github.com/gift-surg/GIFT-Grab/blob/master/doc/pypi.md#numpy
+.. _OpenCV: http://www.opencv.org/
+
+The full source code of the example is below.
+Please follow the comments and the flow of code.
+This example is also available on GitHub_:
+
+.. literalinclude:: ../../src/tests/blackmagic/stereo_capture.py
+    :language: python
+
+.. _GitHub: https://github.com/gift-surg/GIFT-Grab/blob/master/src/tests/blackmagic/stereo_capture.py

doc/tips.md

@@ -17,6 +17,9 @@ If you encounter problems installing any dependency, please have a look at the [
 
 ## Epiphan Video Grabbing SDK
 
+These instructions are provided for convenience only.
+Always check the manufacturer's manuals before proceeding.
+
 1. Download Epiphan video grabbing SDK from [Epiphan support](https://www.epiphan.com/support/) and unpack it, e.g. `wget https://www.epiphan.com/downloads/products/epiphan_sdk-3.30.3.0007.zip; unzip epiphan_sdk-3.30.3.0007.zip`.
 1. Change into the sub-folder `epiphan/samples/v2u` and run `make`. This should create a `build` folder here.
 1. (Optional) Move the top folder (i.e. the one resulting from unpacking the archive) to a system folder, e.g. `/opt`, for easy access by all users.
@@ -25,14 +28,25 @@ If you encounter problems installing any dependency, please have a look at the [
 
 ## Blackmagic Drivers and Blackmagic Desktop Video SDK
 
-1. Download and unpack [Blackmagic Desktop Video SDK](https://www.blackmagicdesign.com/support).
-1. If the resulting folder name has spaces e.g. `Blackmagic DeckLink SDK 10.4`, replace spaces with an underscore, e.g. `Blackmagic_DeckLink_SDK_10.4`.
-1. (Optional) Move the resulting folder to a system folder, e.g. `/opt`, for easy access by all users.
-1. Specify the **absolute** path of the `SDK` sub-folder of this folder as the `BlackmagicSDK_DIR` environment variable, e.g. `export BlackmagicSDK_DIR="/opt/Blackmagic DeckLink SDK 10.4/SDK"`.
-1. Install the driver package appropriate for your system (e.g. `/opt/Blackmagic DeckLink SDK 10.4/deb/amd64/desktopvideo_10.8.4a4_amd64.deb` for a 64-bit Ubuntu Linux).
-1. (Optional) Install the MediaExpress application using the package appropriate for your system (e.g. `/opt/Blackmagic DeckLink SDK 10.4/deb/amd64/mediaexpress_3.5.3a1_amd64.deb` for a 64-bit Ubuntu Linux).
-1. Check your Blackmagic card's firmware status, and update it if necessary.
+These instructions are provided for convenience only.
+Always check the manufacturer's manuals before proceeding.
 
+1. Download and unpack [Blackmagic Desktop Video SDK][blackmagic-support].
+1. If the resulting folder name has spaces e.g. `Blackmagic DeckLink SDK 10.11.1`, replace spaces with an underscore,
+e.g. `Blackmagic_DeckLink_SDK_10.11.1`.
+1. (Optional) Move the resulting folder to a system folder, e.g. `/opt`, for easy access by all users.
+1. Specify the **absolute** path of this folder as the `BlackmagicSDK_DIR` environment variable, e.g.
+`export BlackmagicSDK_DIR="/opt/Blackmagic_DeckLink_SDK_10.11.1"`.
+1. Download and unpack [Blackmagic Desktop Video][blackmagic-support].
+1. Install the driver package appropriate for your system, e.g.
+`dpkg -i Blackmagic_Desktop_Video_Linux_10.11.1/deb/x86_64/desktopvideo_10.11.1a4_amd64.deb`
+1. (Optional) Install the GUI components, e.g.
+`dpkg -i Blackmagic_Desktop_Video_Linux_10.11.1/deb/x86_64/desktopvideo-gui_10.11.1a4_amd64.deb` and
+`dpkg -i Blackmagic_Desktop_Video_Linux_10.11.1/deb/x86_64/mediaexpress_3.5.6a2_amd64.deb`
+1. Check your Blackmagic card's firmware status: `BlackmagicFirmwareUpdater status`, and update if necessary, e.g.
+`BlackmagicFirmwareUpdater update 0`
+
+[blackmagic-support]: https://www.blackmagicdesign.com/support
 
 ## OpenCV
 

src/CMakeLists.txt

@@ -279,6 +279,8 @@ if(USE_BLACKMAGICSDK)
     LIST(APPEND SOURCES blackmagicsdk/blackmagicsdk_video_source.cpp)
     LIST(APPEND HEADERS blackmagicsdk/deck_link_display_mode_detector.h)
     LIST(APPEND SOURCES blackmagicsdk/deck_link_display_mode_detector.cpp)
+    LIST(APPEND HEADERS blackmagicsdk/deck_link_bgra_video_frame.h)
+    LIST(APPEND SOURCES blackmagicsdk/deck_link_bgra_video_frame.cpp)
 endif(USE_BLACKMAGICSDK)
 
 # Performance benchmarking

src/api/videoframe.cpp

@@ -10,22 +10,26 @@ VideoFrame::VideoFrame()
 }
 
 VideoFrame::VideoFrame(enum ColourSpace colour, bool manage_data)
-  : _colour(colour),
-    _manage_data(manage_data),
-    _data(nullptr),
-    _data_length(0)
+    : _colour(colour)
+    , _manage_data(manage_data)
+    , _data(nullptr)
+    , _data_length(0)
+    , _stereo_count(1)
 {
     set_dimensions(0, 0);
 }
 
-VideoFrame::VideoFrame(ColourSpace colour, size_t cols, size_t rows)
+VideoFrame::VideoFrame(ColourSpace colour, size_t cols, size_t rows,
+                       size_t stereo_count)
     : _colour(colour)
     , _manage_data(true)
     , _data(nullptr)
     , _data_length(0)
+    , _stereo_count(stereo_count)
 {
     set_dimensions(cols, rows);
     size_t data_length = required_data_length(_colour, _cols, _rows);
+    data_length *= _stereo_count;
     allocate_memory(data_length);
     set_pixels_black();
 }
@@ -35,6 +39,7 @@ VideoFrame::VideoFrame(const VideoFrame & rhs)
     , _manage_data(true)
     , _data(nullptr)
     , _data_length(0)
+    , _stereo_count(1)
 {
     clone(rhs);
 }
@@ -145,8 +150,10 @@ void VideoFrame::operator=(const VideoFrame & rhs)
 }
 
 void VideoFrame::init_from_specs(unsigned char * data, size_t data_length,
-                                 size_t cols, size_t rows)
+                                 size_t cols, size_t rows, size_t stereo_count)
 {
+    _stereo_count = stereo_count;
+
     if (_manage_data)
     {
         allocate_memory(data_length);
@@ -161,6 +168,20 @@ void VideoFrame::init_from_specs(unsigned char * data, size_t data_length,
     set_dimensions(cols, rows);
 }
 
+const size_t VideoFrame::data_length(size_t stereo_index) const
+{
+    validate_stereo_index(stereo_index);
+    return _data_length / _stereo_count;
+}
+
+unsigned char * const VideoFrame::data(size_t stereo_index) const
+{
+    validate_stereo_index(stereo_index);
+    if (_data == nullptr)
+        return nullptr;
+    return &_data[stereo_index * (_data_length / _stereo_count)];
+}
+
 void VideoFrame::clone(const VideoFrame & rhs)
 {
     if (not _manage_data)
@@ -172,7 +193,7 @@ void VideoFrame::clone(const VideoFrame & rhs)
     _manage_data = true;
     _colour = rhs._colour;
     init_from_specs(rhs._data, rhs._data_length,
-                    rhs._cols, rhs._rows);
+                    rhs._cols, rhs._rows, rhs._stereo_count);
 }
 
 void VideoFrame::set_dimensions(size_t cols, size_t rows)
@@ -213,6 +234,7 @@ void VideoFrame::free_memory()
         _data = nullptr;
         _data_length = 0;
         set_dimensions(0, 0);
+        _stereo_count = 0;
     }
 }