Merge branch 4.x

doc/js_tutorials/js_assets/js_image_arithmetics_bitwise.html

@@ -82,7 +82,7 @@ cv.bitwise_and(logo, logo, imgFg, mask);
 // Put logo in ROI and modify the main image
 cv.add(imgBg, imgFg, sum);
 
-dst = src.clone();
+dst = src.mat_clone();
 for (let i = 0; i < logo.rows; i++) {
     for (let j = 0; j < logo.cols; j++) {
         dst.ucharPtr(i, j)[0] = sum.ucharPtr(i, j)[0];

doc/js_tutorials/js_assets/js_imgproc_camera.html

@@ -248,7 +248,7 @@ function backprojection(src) {
         if (base instanceof cv.Mat) {
             base.delete();
         }
-        base = src.clone();
+        base = src.mat_clone();
         cv.cvtColor(base, base, cv.COLOR_RGB2HSV, 0);
     }
     cv.cvtColor(src, dstC3, cv.COLOR_RGB2HSV, 0);

doc/js_tutorials/js_assets/js_intelligent_scissors.html

@@ -53,7 +53,7 @@ canvas.addEventListener('click', e => {
 });
 canvas.addEventListener('mousemove', e => {
     let x = e.offsetX, y = e.offsetY; //console.log(x, y);
-    let dst = src.clone();
+    let dst = src.mat_clone();
     if (hasMap && x >= 0 && x < src.cols && y >= 0 && y < src.rows)
     {
         let contour = new cv.Mat();

doc/js_tutorials/js_core/js_basic_ops/js_basic_ops.markdown

@@ -77,12 +77,14 @@ How to copy Mat
 There are 2 ways to copy a Mat:
 
 @code{.js}
-// 1. Clone
-let dst = src.clone();
+// 1. Clone (deep copy)
+let dst = src.mat_clone();
 // 2. CopyTo(only entries indicated in the mask are copied)
 src.copyTo(dst, mask);
 @endcode
 
+@note In OpenCV.js, use `mat_clone()` instead of `clone()` to ensure deep copy behavior. The `clone()` method may perform shallow copy due to Emscripten embind limitations.
+
 How to convert the type of Mat
 ------------------------------
 

doc/py_tutorials/py_setup/py_pip_install/py_pip_install.markdown

@@ -0,0 +1,116 @@
+# Install OpenCV for Python with pip {#tutorial_py_pip_install}
+
+This quick-start shows the **recommended** way for most users to get OpenCV in Python: install from
+**PyPI** with `pip`. It also explains virtual environments, platform notes, and common troubleshooting.
+If you need OS‑specific alternatives (system packages or source builds), see the OS pages linked
+below, but those are **not required** for typical Python use.
+
+@note: OpenCV team maintains **PyPI** packages only. Conda distributions and platform specific builds
+are community builds and hardware vendor builds and may differ from the official one.
+
+## Quick start
+
+```bash
+# 1) Create and activate a virtual environment (recommended)
+python -m venv .venv
+# Windows:
+.venv\Scripts\activate
+# Linux/macOS:
+source .venv/bin/activate
+
+# 2) Upgrade pip tooling
+python -m pip install --upgrade pip setuptools wheel
+
+# 3) Install OpenCV from PyPI (choose ONE)
+pip install opencv-python          # main package (most users)
+# or
+pip install opencv-contrib-python  # + extra modules (contrib)
+# or
+pip install opencv-python-headless # no GUI/backends (servers/CI)
+# or
+pip install opencv-contrib-python-headless # no GUI/backends with extra modules (servers/CI)
+```
+
+### Tiny hello‑world
+
+```python
+import cv2 as cv
+import numpy as np
+
+print("OpenCV:", cv.__version__)
+img = np.zeros((120, 400, 3), dtype=np.uint8)
+cv.putText(img, "OpenCV OK", (10, 80), cv.FONT_HERSHEY_SIMPLEX, 2, (255,255,255), 3)
+# If you installed a non-headless build, you can display a window:
+# cv.imshow("hello", img); cv.waitKey(0)
+# Always safe (headless or not): save to file
+cv.imwrite("hello.png", img)
+```
+
+## Virtual environments and IDEs
+
+Using a virtual environment keeps project dependencies isolated. Tools that create or activate envs include:
+
+- `venv` (built-in) and `virtualenv`
+- Conda environments
+- IDEs (VS Code, PyCharm) that may **auto-create and auto-activate** an env per workspace
+
+If imports fail inside an IDE, verify the interpreter selected by the IDE matches the environment
+where you installed OpenCV.
+
+## OS notes
+
+- **Linux:** Your default Python may be `python3`. Use `python3 -m venv .venv` and `python3 -m pip ...`.
+If you cannot use a virtual env, `pip --user` installs to your home directory: `python3 -m pip install --user opencv-python`.
+- **Windows:** Install Python from [python.org] or via `winget install Python.Python.3`. Make sure
+**“Add python to PATH”** is enabled or use the **“Open in terminal”** from your IDE, which selects
+the right interpreter automatically.
+- **macOS:** Use the system `python3` or a managed one (Homebrew or Python.org).
+Always prefer a virtual environment.
+- **Raspberry Pi / ARM boards:** Prebuilt wheels may not exist for some Pi OS / Python combinations.
+See **Troubleshooting** below.
+
+## Choosing a PyPI variant
+
+- `opencv-python`: core OpenCV modules with GUI/backends
+- `opencv-contrib-python`: includes **contrib** modules in addition to the core
+- `opencv-python-headless`: no GUI/backends (ideal for servers/containers/CI)
+- `opencv-contrib-python-headless`: contrib + headless
+
+Install exactly **one** of these per environment.
+
+## Troubleshooting
+
+Please start with opencv-python project [README](https://github.com/opencv/opencv-python/blob/4.x/README.md)
+
+**Pip is trying to build from source**
+Symptoms: very long build step, CMake errors, compiler errors.
+Fixes:
+- Upgrade build tooling: `python -m pip install --upgrade pip setuptools wheel`
+- Ensure your Python version is supported by the chosen package.
+- If you are on an uncommon platform or Python build, switch to a supported Python or try a different
+variant (headless vs non‑headless).
+
+**“No matching distribution found” or “Unsupported wheel”**
+- Confirm your Python version (e.g., `python -V`). Choose a wheel that supports that version
+(manylinux/macOS/Windows wheels on PyPI target specific Python versions).
+- Create a fresh virtual environment with a mainstream Python (e.g., 3.10–3.12 for now) and reinstall.
+
+**Raspberry Pi / ARM**
+- Wheels may lag behind new Python/Pi OS releases. Try `opencv-python-headless` first. If
+unavailable, consider system packages for camera/GUI pieces, or build from source following
+the OS page linked below.
+
+**Import works in terminal but fails in IDE**
+- The IDE is using a different interpreter. Select the **same** environment inside your
+IDE’s interpreter settings.
+
+## What about system packages or building from source?
+
+For beginners using Python, **PyPI is recommended**. Native distribution packages and full source
+builds are better suited to advanced users with platform‑specific needs. You can still find them on
+the OS‑specific pages, moved under “Alternatives.”
+
+## See also
+
+- @ref tutorial_py_root
+- OS pages: @ref tutorial_py_setup_in_windows, @ref tutorial_py_setup_in_ubuntu, @ref tutorial_py_setup_in_fedora

doc/py_tutorials/py_setup/py_setup_in_ubuntu/py_setup_in_ubuntu.markdown

@@ -1,6 +1,8 @@
 Install OpenCV-Python in Ubuntu {#tutorial_py_setup_in_ubuntu}
 ===============================
 
+@note: Please prefer binaries distributed with PyPI, if possible. See @ref tutorial_py_pip_install for details.
+
 Goals
 -----
 

doc/py_tutorials/py_setup/py_setup_in_windows/py_setup_in_windows.markdown

@@ -18,13 +18,13 @@ Installing OpenCV from prebuilt binaries
 
 -#  Below Python packages are to be downloaded and installed to their default locations.
 
-    -#  Python 3.x (3.4+) or Python 2.7.x from [here](https://www.python.org/downloads/).
+    -#  Python 3.x (3.4+) from [here](https://www.python.org/downloads/).
 
     -#  Numpy package (for example, using `pip install numpy` command).
 
     -#  Matplotlib (`pip install matplotlib`) (*Matplotlib is optional, but recommended since we use it a lot in our tutorials*).
 
--#  Install all packages into their default locations. Python will be installed to `C:/Python27/` in case of Python 2.7.
+-#  Install all packages into their default locations. Python will be installed to `C:/Python34/` in case of Python 3.4.
 
 -#  After installation, open Python IDLE. Enter **import numpy** and make sure Numpy is working fine.
 
@@ -32,11 +32,11 @@ Installing OpenCV from prebuilt binaries
     [SourceForge site](https://sourceforge.net/projects/opencvlibrary/files/)
     and double-click to extract it.
 
--#  Goto **opencv/build/python/2.7** folder.
+-#  Goto **opencv/build/python/3.4** folder.
 
--#  Copy **cv2.pyd** to **C:/Python27/lib/site-packages**.
+-#  Copy **cv2.pyd** to **C:/Python34/lib/site-packages**.
 
--#  Copy the **opencv_world.dll** file to **C:/Python27/lib/site-packages**
+-#  Copy the **opencv_world.dll** file to **C:/Python34/lib/site-packages**
 
 -#  Open Python IDLE and type following codes in Python terminal.
     @code

doc/py_tutorials/py_setup/py_table_of_contents_setup.markdown

@@ -6,6 +6,11 @@ Introduction to OpenCV {#tutorial_py_table_of_contents_setup}
     Getting Started with
     OpenCV-Python
 
+-   @subpage tutorial_py_pip_install
+
+    Install OpenCV for
+    Python with pip
+
 -   @subpage tutorial_py_setup_in_windows
 
     Set Up

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
 ----
 

doc/tutorials/introduction/linux_gdb_pretty_printer/linux_gdb_pretty_printer.markdown

@@ -1,7 +1,7 @@
 Using OpenCV with gdb-powered IDEs {#tutorial_linux_gdb_pretty_printer}
 =====================
 
-@prev_tutorial{tutorial_linux_install}
+@prev_tutorial{tutorial_oneapi_install}
 @next_tutorial{tutorial_linux_gcc_cmake}
 
 |    |    |

doc/tutorials/introduction/linux_install/linux_install.markdown

@@ -2,7 +2,7 @@ Installation in Linux {#tutorial_linux_install}
 =====================
 
 @prev_tutorial{tutorial_env_reference}
-@next_tutorial{tutorial_linux_gdb_pretty_printer}
+@next_tutorial{tutorial_oneapi_install}
 
 |    |    |
 | -: | :- |

doc/tutorials/introduction/oneapi_install/oneapi_install.markdown

@@ -0,0 +1,106 @@
+Building OpenCV with oneAPI {#tutorial_oneapi_install}
+===========================
+
+
+@prev_tutorial{tutorial_linux_install}
+@next_tutorial{tutorial_linux_gcc_cmake}
+
+|    |    |
+| -: | :- |
+| Original author | Alessandro de Oliveira Faria |
+| Compatibility | OpenCV >= 4.11.0 |
+
+@tableofcontents
+
+# Quick start {#tutorial_oneapi_install_quick_start}
+
+**oneAPI** is Intel's open initiative (now also maintained by the UXL Foundation) that combines a specification and a set of toolkits for programming CPUs, GPUs, FPGAs and NPUs with a single code base. The core is the SYCL standard (single-source C++ for parallelism), complemented by high-performance libraries — oneTBB (parallelism), oneMKL (linear algebra), oneDNN (neural networks), oneVPL (video), etc. Thus, when you compile with oneAPI's DPC++ (icpx) compiler, the binary gains optimized execution paths that choose, at runtime, the best vector instructions or the available device, without changing the source code.
+
+## Why compile OpenCV with the oneAPI ecosystem when targeting the CPU:
+
+* Simple, because by enabling the CMake options -DWITH_SYCL=ON -DWITH_TBB=ON -DWITH_ONEDNN=ON -DWITH_IPP=ON and using the icpx compiler, the OpenCV core starts to directly invoke oneAPI libraries.
+* oneDNN replaces the generic kernels of the cv::dnn layer with implementations that exploit AVX2, AVX-512, AMX and VNNI, accelerating convolutions, matmul and network post-processing by up to 3-5× on modern CPUs.
+* oneTBB takes over the thread pool, scheduling filters like cv::resize, cv::GaussianBlur or the G-API pipeline across all cores without busy-wait.
+* IPP (now distributed via oneAPI Base Toolkit) provides optimized intrinsic routines for elementary operations (SAD, DFT, median blur), which OpenCV calls when it encounters the HAVE_IPP macro.
+* All this happens transparently: the source code that uses cv::Mat remains the same, but the linked symbols point to vectorized versions, and the internal dispatcher selects the appropriate vector width at runtime.
+
+
+## CPU Processor Requirements
+
+Systems based on Intel® 64 architectures below are supported both as host and target platforms.
+
+* Intel® Core™ processor family or higher
+* Intel® Xeon® processor family
+* Intel® Xeon® Scalable processor family
+
+
+### Requirements for Accelerators
+
+* Integrated GEN9 (and higher) GPUs. See source in Intel® Graphics Compiler for OpenCL™
+* FPGA Card: see Intel(R) DPC++ Compiler System Requirements.
+
+### Disk Space Requirements
+
+* 3.3 GB of disk space (minimum) on a standard installation.
+
+@note: During the installation process, the installer may need up to 6 GB of additional temporary disk storage to manage the download and intermediate installation files.
+
+
+### Memory Requirements
+
+* 8 GB RAM recommended
+
+
+## How To install oneAPI
+
+Installing oneAPI: To quickly set up the oneAPI ecosystem on openSUSE, simply follow the official guide https://www.intel.com/content/www/us/en/developer/articles/guide/installation-guide-for-oneapi-toolkits.html, which shows you how to enable the distribution’s dedicated repository (zypper ar … oneAPI) and install the metapackages ― for example, intel-basekit (DPC++, TBB, oneDNN, IPP compilers) and, optionally, intel-hpckit or intel-renderkit if you need HPC or graphics tools. The guide also explains post-installation tweaks, such as loading the environment with source /opt/intel/oneapi/setvars.sh , ensuring that the binaries (icpx, dpcpp) and libraries are immediately available in your shell for compiling and running accelerated applications.
+
+## Download, Github Instruction, Build and Install
+
+1. Below are the commands to download last version (latest release on the date of publication of this text):
+
+```
+git clone https://github.com/opencv/opencv.git
+```
+
+2. and make sure you are using branch 4.*:
+
+```
+git status
+On branch 4.x
+```
+
+3. Navigate to OpenCV repository and prepare the build folder:
+
+```
+cd opencv
+mkdir build
+cd build
+```
+
+4. Set up Intel oneAPI environment variables. For default installation:
+
+```
+source /opt/intel/oneapi/setvars.sh
+```
+
+5. Run CMake * with Intel® oneAPI DPC++/C++ Compiler to configure the project:
+
+```
+ cmake -DCMAKE_C_COMPILER=icx \
+       -DCMAKE_CXX_COMPILER=icpx
+       -DCMAKE_CXX_FLAGS="-march=native -mavx -mfma -msse -msse2" ..
+ cmake --build .
+```
+6. Now Make sure openCV* is compiled with Intel® oneAPI DPC++/C++ Compiler and install:
+
+```
+readelf -p .comment bin/opencv_annotation
+String dump of section '.comment':
+  [     0]  GCC: (SUSE Linux) 13.3.1 20250313 [revision 4ef1d8c84faeebffeb0cc01ee22e891b41e5c4e0]
+  [    56]  GCC: (SUSE Linux) 12.3.0
+  [    6f]  Intel(R) oneAPI DPC++/C++ Compiler 2025.1.1 (2025.1.1.20250418)
+make install
+```
+
+Have fun...

doc/tutorials/introduction/table_of_content_introduction.markdown

@@ -9,6 +9,7 @@ Introduction to OpenCV {#tutorial_table_of_content_introduction}
 
 ##### Linux
 -   @subpage tutorial_linux_install
+-   @subpage tutorial_oneapi_install
 -   @subpage tutorial_linux_gdb_pretty_printer
 -   @subpage tutorial_linux_gcc_cmake
 -   @subpage tutorial_linux_eclipse

doc/tutorials/introduction/windows_install/windows_install.markdown

@@ -379,6 +379,9 @@ our OpenCV library that we use in our projects. Start up a command window and en
 
     setx OpenCV_DIR D:\OpenCV\build\x64\vc17     (suggested for Visual Studio 2022 - 64 bit Windows)
     setx OpenCV_DIR D:\OpenCV\build\x86\vc17     (suggested for Visual Studio 2022 - 32 bit Windows)
+
+    setx OpenCV_DIR D:\OpenCV\build\x64\vc18     (suggested for Visual Studio 2026 - 64 bit Windows)
+    setx OpenCV_DIR D:\OpenCV\build\x86\vc18     (suggested for Visual Studio 2026 - 32 bit Windows)
 @endcode
 Here the directory is where you have your OpenCV binaries (*extracted* or *built*). You can have
 different platform (e.g. x64 instead of x86) or compiler type, so substitute appropriate value.