Merge pull request #27930 from sirudoi:4.x

Add macOS support for Orbbec Gemini330 camera #27930

### Description of Changes
Adds macOS support for Orbbec Gemini330 in videoio by integrating OrbbecSDK v2. Completes the non-macOS work in [#27230](https://github.com/opencv/opencv/pull/27230).

#### Motivation

[#27230](https://github.com/opencv/opencv/pull/27230) skipped macOS. On macOS, UVC alone lacks required device controls; OrbbecSDK v2 provides them.

#### Key Change
 - macOS: fetch/link OrbbecSDK v2.5.5 (replaces v1.9.4).
 - videoio (macOS): switch OrbbecSDK API usage from v1 to v2.

### Pull Request Readiness Checklist

See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request

- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [x] The feature is well documented and sample code can be built with the project CMake

3rdparty/orbbecsdk/orbbecsdk.cmake

@@ -1,18 +1,34 @@
+ocv_update(ORBBEC_SDK_VERSION "2")
+ocv_update(ORBBEC_SDK_DOWNLOAD_DIR "${OpenCV_BINARY_DIR}/3rdparty/orbbecsdk")
+
 function(download_orbbec_sdk root_var)
-    set(ORBBECSDK_DOWNLOAD_DIR "${OpenCV_BINARY_DIR}/3rdparty/orbbecsdk")
-    set(ORBBECSDK_FILE_HASH_CMAKE "e7566fa915a1b0c02640df41891916fe")
-    ocv_download(FILENAME "v1.9.4.tar.gz"
-                HASH ${ORBBECSDK_FILE_HASH_CMAKE}
-                URL "https://github.com/orbbec/OrbbecSDK/archive/refs/tags/v1.9.4/"
-                DESTINATION_DIR ${ORBBECSDK_DOWNLOAD_DIR}
+    if(ORBBEC_SDK_VERSION STREQUAL "1")
+        set(ORBBEC_SDK_FILE_HASH_CMAKE "e7566fa915a1b0c02640df41891916fe")
+        set(ORBBEC_SDK_GIT_TAG "1.9.4")
+        add_definitions(-DORBBEC_SDK_VERSION_MAJOR=1)
+    elseif(ORBBEC_SDK_VERSION STREQUAL "2")
+        set(ORBBEC_SDK_FILE_HASH_CMAKE "d828ac15618a56b9ae325bada8676e28")
+        set(ORBBEC_SDK_GIT_TAG "2.5.5")
+        add_definitions(-DORBBEC_SDK_VERSION_MAJOR=2)
+    else()
+        message(STATUS "Unsupported OrbbecSDK version: ${ORBBEC_SDK_VERSION}, use default version 2")
+        set(ORBBEC_SDK_FILE_HASH_CMAKE "d828ac15618a56b9ae325bada8676e28")
+        set(ORBBEC_SDK_GIT_TAG "2.5.5")
+        add_definitions(-DORBBEC_SDK_VERSION_MAJOR=2)
+    endif()
+
+    ocv_download(FILENAME "v${ORBBEC_SDK_GIT_TAG}.tar.gz"
+                HASH ${ORBBEC_SDK_FILE_HASH_CMAKE}
+                URL "https://github.com/orbbec/OrbbecSDK/archive/refs/tags/v${ORBBEC_SDK_GIT_TAG}/"
+                DESTINATION_DIR ${ORBBEC_SDK_DOWNLOAD_DIR}
                 ID OrbbecSDK
                 STATUS res
                 UNPACK RELATIVE_URL
                 )
     if(${res})
-        message(STATUS "orbbec sdk downloaded to: ${ORBBECSDK_DOWNLOAD_DIR}")
-        set(${root_var} "${ORBBECSDK_DOWNLOAD_DIR}/OrbbecSDK-1.9.4" PARENT_SCOPE)
+        message(STATUS "OrbbecSDK downloaded to: ${ORBBEC_SDK_DOWNLOAD_DIR}")
+        set(${root_var} "${ORBBEC_SDK_DOWNLOAD_DIR}/OrbbecSDK-${ORBBEC_SDK_GIT_TAG}" PARENT_SCOPE)
     else()
-        message(FATAL_ERROR "Failed to download orbbec sdk")
+        message(FATAL_ERROR "Failed to download OrbbecSDK")
     endif()
 endfunction()

doc/tutorials/app/orbbec_uvc.markdown

@@ -34,6 +34,15 @@ make
 sudo make install
 ```
 
+By default, when `-DOBSENSOR_USE_ORBBEC_SDK=ON` is enabled, OrbbecSDK v2 is used (i.e., `ORBBEC_SDK_VERSION` defaults to `2`); it supports the entire Orbbec Gemini 330 series.
+
+If you need legacy cameras such as Orbbec Femto, Gemini2XL, or Astra+, switch to OrbbecSDK v1 with the flag `-DORBBEC_SDK_VERSION=1`:
+```bash
+  cmake -DOBSENSOR_USE_ORBBEC_SDK=ON -DORBBEC_SDK_VERSION=1 ..
+  make -j
+  sudo make install
+```
+
 Code
 ----
 

modules/videoio/cmake/detect_obsensor.cmake

@@ -13,8 +13,12 @@ if(NOT HAVE_OBSENSOR)
         set(HAVE_OBSENSOR TRUE)
         set(HAVE_OBSENSOR_ORBBEC_SDK TRUE)
         ocv_add_external_target(obsensor "${OrbbecSDK_INCLUDE_DIRS}" "${OrbbecSDK_LIBRARY}" "HAVE_OBSENSOR;HAVE_OBSENSOR_ORBBEC_SDK")
-        file(COPY ${OrbbecSDK_DLL_FILES} DESTINATION ${CMAKE_BINARY_DIR}/bin)
         file(COPY ${OrbbecSDK_DLL_FILES} DESTINATION ${CMAKE_BINARY_DIR}/lib)
+        if(NOT ORBBEC_SDK_VERSION STREQUAL "1")
+          # OrbbecSDK v2 loads some libraries at runtime.
+          file(COPY ${OrbbecSDK_RUNTIME_RESOURCE_FILES} DESTINATION ${CMAKE_BINARY_DIR}/lib)
+          install(DIRECTORY ${OrbbecSDK_RUNTIME_RESOURCE_FILES} DESTINATION ${OPENCV_LIB_INSTALL_PATH})
+        endif()
         install(FILES ${OrbbecSDK_DLL_FILES} DESTINATION ${OPENCV_LIB_INSTALL_PATH})
         ocv_install_3rdparty_licenses(OrbbecSDK ${OrbbecSDK_DIR}/LICENSE.txt)
       endif()

modules/videoio/src/cap_obsensor_liborbbec.cpp

@@ -38,6 +38,9 @@ VideoCapture_obsensor::VideoCapture_obsensor(int, const cv::VideoCaptureParamete
     ob::Context::setLoggerToFile(OB_LOG_SEVERITY_OFF, "");
     config = std::make_shared<ob::Config>();
     pipe = std::make_shared<ob::Pipeline>();
+#if ORBBEC_SDK_VERSION_MAJOR != 1
+    alignFilter = std::make_shared<ob::Align>(OB_STREAM_COLOR);
+#endif
 
     int color_width = params.get<double>(CAP_PROP_FRAME_WIDTH, OB_WIDTH_ANY);
     int color_height = params.get<double>(CAP_PROP_FRAME_HEIGHT, OB_HEIGHT_ANY);
@@ -75,12 +78,25 @@ VideoCapture_obsensor::VideoCapture_obsensor(int, const cv::VideoCaptureParamete
         config->enableStream(depthProfile->as<ob::VideoStreamProfile>());
     }
 
+#if ORBBEC_SDK_VERSION_MAJOR == 1
     config->setAlignMode(ALIGN_D2C_SW_MODE);
+#else
+    config->setFrameAggregateOutputMode(OB_FRAME_AGGREGATE_OUTPUT_ALL_TYPE_FRAME_REQUIRE);
+    pipe->enableFrameSync();
+#endif
 
     pipe->start(config, [&](std::shared_ptr<ob::FrameSet> frameset) {
         std::unique_lock<std::mutex> lk(videoFrameMutex);
+#if ORBBEC_SDK_VERSION_MAJOR == 1
         colorFrame = frameset->colorFrame();
         depthFrame = frameset->depthFrame();
+#else
+        auto alignFrameSet = alignFilter->process(frameset);
+        if (alignFrameSet) {
+            colorFrame = alignFrameSet->as<ob::FrameSet>()->colorFrame();
+            depthFrame = alignFrameSet->as<ob::FrameSet>()->depthFrame();
+        }
+#endif
     });
 
     auto param = pipe->getCameraParam();

modules/videoio/src/cap_obsensor_liborbbec.hpp

@@ -59,6 +59,9 @@ protected:
     std::shared_ptr<ob::VideoFrame> grabbedDepthFrame;
     std::shared_ptr<ob::Pipeline> pipe;
     std::shared_ptr<ob::Config> config;
+#if ORBBEC_SDK_VERSION_MAJOR != 1
+    std::shared_ptr<ob::Align> alignFilter;
+#endif
     CameraParam camParam;
 };