build: Don't link libOpenImageIO against OpenCV (#4363)

Fully linking OpenCV against libOpenImageIO is burdensome for people
downstream, especially those who want a static version of
libOpenImageIO.

There were only three IBA functions that use OpenCV: to_OpenCV(),
from_OpenCV(), and capture_image(), and all three are fairly short. Move
them to a separate header, imagebufalgo_opencv.h, make them fully INLINE
(so they don't actually produce object code in libOpenImageIO, which
therefore does not need to link against OpenCV).

Applications wanting these three functions should include this header
and will be responsible themselves for ensuring that the include paths
and linkage of their application makes provisions for finding and using
OpenCV. All other applications don't need to deal with OpenCV dependency
at all.

Our own oiiotool (for --capture) and our python bindings still link
against OpenCV to support this functionality (again, still as an
optional dependency, enabled only if OpenCV is found at build time). But
downstream apps using libOpenImageIO and who do not themselves need our
OpenCV functioality now no longer need to link against OpenCV.

We have removed capture_image() from the Python bindings -- Python
scripts that need to capture live camera images can use OpenCV or any
other capture API of their choice without going through OIIO.

Signed-off-by: Larry Gritz <[email protected]>

docs/Deprecations-3.0.md

@@ -86,6 +86,14 @@ about being deprecated will be removed in the final 3.0 release.
   deprecated since OIIO 1.5, now has deprecation warnings. Use
   `interppixel_NDC()` instead.
 
+## imageio.h
+
+* The global OIIO::attribute query "opencv_version" has been removed. The
+  libOpenImageIO library itself no longer has OpenCV as a dependency or links
+  against it. (However, the IBA functions involving OpenCV still exist and are
+  defined in `imagebufalgo_opencv.h` as inline functions, so it is up to the
+  application calling these API functions to find and link against OpenCV.)
+
 ## imagebufalgo.h
 
 * The old versions (deprecated since 2.0) of IBA::compare() and
@@ -111,6 +119,8 @@ about being deprecated will be removed in the final 3.0 release.
   cv::Mat.
 * The pre-KWArgs versions of resize, warp, and fit now have deprecation
   warnings. Use the versions that take KWArgs instead.
+* The OpenCV-related functions `to_OpenCV()`, `from_OpenCV()`, and
+  `capture_image()` have moved to the `imagebufalgo_opencv.h` header.
 
 ## imagebufalgo_util.h
 
@@ -193,3 +203,10 @@ about being deprecated will be removed in the final 3.0 release.
   it defines.
 
 
+## python bindings
+
+* The `ImageBufAlgo.capture_image()` function has been removed from the
+  Python bindings. Python scripts that wish to capture images from live
+  cameras should use OpenCV or other capture APIs of choice and then
+  pass the results to OIIO to construct an ImageBuf.
+

src/cmake/fancy_add_executable.cmake

@@ -20,6 +20,7 @@
 #   fancy_add_executable ([ NAME targetname ... ]
 #                         [ SRC source1 ... ]
 #                         [ INCLUDE_DIRS include_dir1 ... ]
+#                         [ SYSTEM_INCLUDE_DIRS include_dir1 ... ]
 #                         [ DEFINITIONS FOO=bar ... ])
 #                         [ COMPILE_OPTIONS -Wno-foo ... ]
 #                         [ LINK_LIBRARIES external_lib1 ... ]

src/cmake/modules/FindOpenCV.cmake

@@ -15,12 +15,9 @@
 
 find_path (OpenCV_INCLUDE_DIR
            NAMES opencv4/opencv2/opencv.hpp opencv2/opencv.hpp
-           PATHS
-               /opt/local/include
-               /usr/local/opt/opencv4
-               /usr/local/opt/opencv3
+           PATHS /opt/local/include /usr/local/opt/opencv4
            PATH_SUFFIXES opencv4
-           )
+          )
 
 set (_ocv_include_root "${OpenCV_INCLUDE_DIR}")
 if (OpenCV_INCLUDE_DIR AND EXISTS "${OpenCV_INCLUDE_DIR}/opencv4/opencv2/core/version.hpp")

src/cmake/pythonutils.cmake

@@ -63,7 +63,7 @@ endmacro()
 # pybind11
 
 macro (setup_python_module)
-    cmake_parse_arguments (lib "" "TARGET;MODULE" "SOURCES;LIBS" ${ARGN})
+    cmake_parse_arguments (lib "" "TARGET;MODULE" "SOURCES;LIBS;INCLUDES;SYSTEM_INCLUDE_DIRS" ${ARGN})
     # Arguments: <prefix> <options> <one_value_keywords> <multi_value_keywords> args...
 
     set (target_name ${lib_TARGET})
@@ -79,6 +79,10 @@ macro (setup_python_module)
 #    add_library (${target_name} MODULE ${lib_SOURCES})
 #
     # Declare the libraries it should link against
+    target_include_directories (${target_name}
+                                PRIVATE ${lib_INCLUDES})
+    target_include_directories (${target_name}
+                                SYSTEM PRIVATE ${lib_SYSTEM_INCLUDE_DIRS})
     target_link_libraries (${target_name}
                            PRIVATE ${lib_LIBS})
 

src/doc/pythonbindings.rst

@@ -3698,18 +3698,6 @@ Import / export
 
 
 
-.. py:method:: ImageBuf ImageBufAlgo::capture_image (cameranum, convert = OpenImageIO.UNKNOWN)
-
-    Capture a still image from a designated camera.
-
-    Example:
-
-    .. code-block:: python
-
-        WebcamImage = ImageBufAlgo.capture_image (0, OpenImageIO.UINT8)
-        WebcamImage.write ("webcam.jpg")
-
-
 
 Functions specific to deep images
 ---------------------------------

src/include/OpenImageIO/imagebufalgo.h

@@ -23,14 +23,6 @@
 
 #include <limits>
 
-#if !defined(__OPENCV_CORE_TYPES_H__) && !defined(OPENCV_CORE_TYPES_H)
-struct IplImage;  // Forward declaration; used by Intel Image lib & OpenCV
-namespace cv {
-    class Mat;
-}
-#endif
-
-
 
 OIIO_NAMESPACE_BEGIN
 
@@ -2345,36 +2337,6 @@ bool OIIO_API make_texture (MakeTextureMode mode,
 /// @}
 
 
-/// Convert an OpenCV cv::Mat into an ImageBuf, copying the pixels (optionally
-/// converting to the pixel data type specified by `convert`, if not UNKNOWN,
-/// which means to preserve the original data type if possible).  Return true
-/// if ok, false if it was not able to make the conversion from Mat to
-/// ImageBuf. Any error messages can be retrieved by calling `geterror()` on
-/// the returned ImageBuf. If OpenImageIO was compiled without OpenCV support,
-/// this function will return false.
-OIIO_API ImageBuf
-from_OpenCV (const cv::Mat& mat, TypeDesc convert = TypeUnknown,
-             ROI roi={}, int nthreads=0);
-
-/// Construct an OpenCV cv::Mat containing the contents of ImageBuf src, and
-/// return true. If it is not possible, or if OpenImageIO was compiled without
-/// OpenCV support, then return false. Any error messages can be retrieved by
-/// calling OIIO::geterror(). Note that OpenCV only supports up to 4 channels,
-/// so >4 channel images will be truncated in the conversion.
-OIIO_API bool to_OpenCV (cv::Mat& dst, const ImageBuf& src,
-                         ROI roi={}, int nthreads=0);
-
-
-/// Capture a still image from a designated camera.  If able to do so,
-/// store the image in dst and return true.  If there is no such device,
-/// or support for camera capture is not available (such as if OpenCV
-/// support was not enabled at compile time), return false and do not
-/// alter dst.
-ImageBuf OIIO_API capture_image (int cameranum = 0,
-                                 TypeDesc convert=TypeUnknown);
-
-
-
 /// Return the "deep" equivalent of the "flat" input `src`. Turning a flat
 /// image into a deep one means:
 ///