Initial Linux Qt OpenCV project

docs/windows/DEPENDENCIES.md

@@ -0,0 +1,144 @@
+# chengnan 本地二进制依赖说明
+
+本项目原则：**构建项目所用依赖使用二进制包放在项目目录内，不在本机编译安装依赖，不使用系统 GCC 等编译工具链参与本项目构建。**
+
+## 已删除的非目标依赖
+
+已删除之前为 Linux 本地尝试构建而产生的内容：
+
+- `third_party/opencv-src/`：OpenCV 源码
+- `third_party/opencv-build/`：OpenCV 编译目录
+- `third_party/opencv/`：由源码编译安装出的 Linux OpenCV
+- `third_party/qt-sdk/`：Linux Qt 包
+- `third_party/qt`：Linux Qt 软链接
+- `third_party/opengl-stub/`：Linux 构建验证用 stub
+- `tools/uv/`：uv 工具
+- `tools/pyenv/`：uv 创建的 Python 环境
+- `tools/cmake/`：Linux CMake 二进制
+
+## 当前保留的 Windows 二进制依赖
+
+### Qt 6.7.3 MSVC 2019 64-bit
+
+```text
+third_party/qt-windows-msvc-sdk/6.7.3/msvc2019_64/
+third_party/qt-windows-msvc -> qt-windows-msvc-sdk/6.7.3/msvc2019_64
+```
+
+关键文件：
+
+```text
+third_party/qt-windows-msvc/bin/qmake.exe
+third_party/qt-windows-msvc/bin/windeployqt.exe
+```
+
+### OpenCV 4.10.0 Windows 官方预编译包
+
+```text
+third_party/opencv-windows-extract/opencv/build/
+third_party/opencv-windows -> opencv-windows-extract/opencv/build
+```
+
+关键文件：
+
+```text
+third_party/opencv-windows/x64/vc16/lib/OpenCVConfig.cmake
+third_party/opencv-windows/x64/vc16/lib/opencv_world4100.lib
+third_party/opencv-windows/x64/vc16/bin/opencv_world4100.dll
+```
+
+### Ninja / MinGW 工具包
+
+```text
+third_party/qt-tools/
+```
+
+关键文件：
+
+```text
+third_party/qt-tools/Tools/Ninja/ninja.exe
+third_party/qt-tools/Tools/mingw1120_64/bin/g++.exe
+```
+
+> 注意：项目保留 MinGW 二进制只是备用。当前推荐 MSVC，因为 OpenCV 官方 Windows 二进制是 `vc16`，不能直接给 MinGW 链接。
+
+### Windows CMake 二进制
+
+```text
+tools/cmake-windows/cmake-3.31.6-windows-x86_64/
+tools/cmake-current-windows -> cmake-windows/cmake-3.31.6-windows-x86_64
+```
+
+关键文件：
+
+```text
+tools/cmake-current-windows/bin/cmake.exe
+```
+
+### Windows Python 二进制与虚拟环境脚本
+
+```text
+tools/python-bin/
+scripts/setup-python-venv-windows.ps1
+```
+
+说明：
+
+- `tools/python-bin/` 使用 Python 官方 Windows embeddable zip 二进制包解压得到
+- 不使用 uv
+- 如果需要 Python 包，请在 Windows 上运行：
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\setup-python-venv-windows.ps1
+```
+
+该脚本会优先尝试创建：
+
+```text
+tools/python-venv/
+```
+
+如果 embeddable Python 不支持 `venv`，则会在 `tools/python-bin/` 内安装 pip/aqtinstall，仍然限制在项目目录内。
+
+## Windows 推荐构建方式
+
+由于当前 OpenCV 是官方 MSVC `vc16` 二进制包，推荐使用 MSVC 构建。
+
+在 Windows 上打开：
+
+```text
+x64 Native Tools Command Prompt for VS 2019/2022
+```
+
+进入项目目录后运行：
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\build-windows.ps1 -Toolchain msvc -Deploy
+```
+
+脚本会使用项目内：
+
+- `tools/cmake-current-windows/bin/cmake.exe`
+- `third_party/qt-tools/Tools/Ninja/ninja.exe`
+- `third_party/qt-windows-msvc/`
+- `third_party/opencv-windows/`
+
+## 关于“不使用系统工具链”
+
+当前已经避免使用 Linux 系统 GCC 编译本项目，也删除了通过系统 GCC 编译出来的 OpenCV。
+
+但 MSVC 编译器 `cl.exe` 通常来自 Visual Studio Build Tools。微软没有像 Qt/OpenCV 一样提供适合随项目简单解压携带的独立 MSVC 工具链包。因此：
+
+- 如果允许使用 Windows 已安装的 Visual Studio Build Tools：可直接构建
+- 如果要求连 MSVC 编译器也必须项目内携带：建议改用 MinGW，但需要额外准备 MinGW 版 OpenCV 二进制包
+
+## 当前 Linux 服务器限制
+
+当前服务器是 Linux，只能整理 Windows 二进制依赖和脚本，不能直接运行 Windows 的：
+
+- `cmake.exe`
+- `ninja.exe`
+- `cl.exe`
+- `windeployqt.exe`
+
+因此最终 `.exe` 需要在 Windows 上执行构建脚本生成。

docs/windows/build-windows.ps1

@@ -0,0 +1,86 @@
+param(
+    [ValidateSet("msvc", "mingw")]
+    [string]$Toolchain = "msvc",
+    [string]$BuildDir = "$PSScriptRoot\..\build-windows",
+    [switch]$Deploy
+)
+
+$ErrorActionPreference = "Stop"
+
+$ProjectRoot = Resolve-Path "$PSScriptRoot\.."
+$BuildDir = [System.IO.Path]::GetFullPath($BuildDir)
+$ThirdParty = Join-Path $ProjectRoot "third_party"
+$Tools = Join-Path $ProjectRoot "tools"
+
+$CMakeExe = Join-Path $Tools "cmake-current-windows\bin\cmake.exe"
+if (!(Test-Path $CMakeExe)) {
+    $CMakeExe = Join-Path $Tools "cmake-windows\cmake-3.31.6-windows-x86_64\bin\cmake.exe"
+}
+if (!(Test-Path $CMakeExe)) {
+    throw "未找到项目内 Windows CMake：$CMakeExe"
+}
+
+$NinjaExe = Join-Path $ThirdParty "qt-tools\Tools\Ninja\ninja.exe"
+if (!(Test-Path $NinjaExe)) {
+    $NinjaExe = Join-Path $ThirdParty "qt-tools\Tools\ninja\ninja.exe"
+}
+
+if ($Toolchain -eq "msvc") {
+    $QtPrefix = Join-Path $ThirdParty "qt-windows-msvc"
+    $OpenCvPrefix = Join-Path $ThirdParty "opencv-windows\x64\vc16\lib"
+    $OpenCvBin = Join-Path $ThirdParty "opencv-windows\x64\vc16\bin"
+    $Generator = "Ninja"
+
+    if (!(Test-Path $QtPrefix)) { throw "未找到 Qt MSVC：$QtPrefix" }
+    if (!(Test-Path $OpenCvPrefix)) { throw "未找到 OpenCV MSVC：$OpenCvPrefix" }
+    if (!(Get-Command cl.exe -ErrorAction SilentlyContinue)) {
+        throw "未检测到 cl.exe。请在 x64 Native Tools Command Prompt for VS 中运行本脚本，或先运行 vcvars64.bat。"
+    }
+} else {
+    $QtPrefix = Join-Path $ThirdParty "qt-windows"
+    $OpenCvPrefix = Join-Path $ThirdParty "opencv-windows\x64\vc16\lib"
+    $OpenCvBin = Join-Path $ThirdParty "opencv-windows\x64\vc16\bin"
+    $MingwBin = Join-Path $ThirdParty "qt-tools\Tools\mingw1120_64\bin"
+    $Generator = "Ninja"
+
+    if (!(Test-Path $QtPrefix)) { throw "未找到 Qt MinGW：$QtPrefix" }
+    if (!(Test-Path $MingwBin)) { throw "未找到项目内 MinGW：$MingwBin" }
+    Write-Warning "OpenCV 官方 Windows 预编译包是 MSVC vc16，不适配 MinGW 链接。若要 MinGW 构建，需要另备 MinGW 版 OpenCV 二进制包。"
+
+    $env:PATH = "$MingwBin;$env:PATH"
+    $env:CC = Join-Path $MingwBin "gcc.exe"
+    $env:CXX = Join-Path $MingwBin "g++.exe"
+}
+
+if (!(Test-Path $NinjaExe)) {
+    throw "未找到项目内 Ninja：$NinjaExe"
+}
+
+$env:PATH = "$QtPrefix\bin;$OpenCvBin;$(Split-Path $NinjaExe);$env:PATH"
+$PrefixPath = "$QtPrefix;$OpenCvPrefix"
+
+Write-Host "ProjectRoot: $ProjectRoot"
+Write-Host "Toolchain:   $Toolchain"
+Write-Host "QtPrefix:    $QtPrefix"
+Write-Host "OpenCV:      $OpenCvPrefix"
+Write-Host "BuildDir:    $BuildDir"
+Write-Host "Ninja:       $NinjaExe"
+
+& $CMakeExe -S $ProjectRoot -B $BuildDir -G $Generator `
+    -DCMAKE_BUILD_TYPE=Release `
+    -DCMAKE_MAKE_PROGRAM="$NinjaExe" `
+    -DCMAKE_PREFIX_PATH="$PrefixPath"
+
+& $CMakeExe --build $BuildDir --config Release
+
+if ($Deploy) {
+    $Exe = Join-Path $BuildDir "chengnan.exe"
+    $DeployDir = Join-Path $BuildDir "deploy"
+    New-Item -ItemType Directory -Force -Path $DeployDir | Out-Null
+    Copy-Item $Exe $DeployDir -Force
+    & (Join-Path $QtPrefix "bin\windeployqt.exe") --release --no-translations (Join-Path $DeployDir "chengnan.exe")
+    Copy-Item (Join-Path $OpenCvBin "*.dll") $DeployDir -Force
+    Write-Host "已部署到：$DeployDir"
+}
+
+Write-Host "构建完成。"

docs/windows/setup-deps-windows.ps1

@@ -0,0 +1,19 @@
+param(
+    [string]$InstallRoot = "$PSScriptRoot\..\third_party"
+)
+
+$ErrorActionPreference = "Stop"
+
+$InstallRoot = [System.IO.Path]::GetFullPath($InstallRoot)
+New-Item -ItemType Directory -Force -Path $InstallRoot | Out-Null
+
+Write-Host "本脚本不会写入系统目录，只在项目 third_party 下准备依赖。"
+Write-Host "建议方式："
+Write-Host "1. 安装 Qt Online Installer 时，将安装目录选择为：$InstallRoot\qt-sdk"
+Write-Host "2. 安装组件选择 Qt 6.x / MinGW 或 MSVC 版本。"
+Write-Host "3. 将实际 Qt 编译套件目录复制或软链接到：$InstallRoot\qt"
+Write-Host "   例如：$InstallRoot\qt-sdk\6.7.3\mingw_64 -> $InstallRoot\qt"
+Write-Host "4. 下载 OpenCV Windows 预编译包，解压到：$InstallRoot\opencv"
+Write-Host "5. 然后运行：powershell -ExecutionPolicy Bypass -File scripts\build-windows.ps1"
+Write-Host ""
+Write-Host "如使用 vcpkg，也请将 vcpkg clone 到项目 tools/vcpkg，不要装到系统目录。"

docs/windows/setup-python-venv-windows.ps1

@@ -0,0 +1,29 @@
+param(
+    [string]$PythonBin = "$PSScriptRoot\..\tools\python-bin",
+    [string]$VenvDir = "$PSScriptRoot\..\tools\python-venv"
+)
+
+$ErrorActionPreference = "Stop"
+
+$PythonBin = [System.IO.Path]::GetFullPath($PythonBin)
+$VenvDir = [System.IO.Path]::GetFullPath($VenvDir)
+$PythonExe = Join-Path $PythonBin "python.exe"
+
+if (!(Test-Path $PythonExe)) {
+    throw "未找到项目内 Python 二进制：$PythonExe"
+}
+
+# Windows embeddable Python 不一定带 venv 模块。优先尝试 venv；失败则使用同目录作为隔离 Python 环境安装 pip。
+try {
+    & $PythonExe -m venv $VenvDir
+    $VenvPython = Join-Path $VenvDir "Scripts\python.exe"
+    & $VenvPython -m pip install --upgrade pip setuptools wheel
+    & $VenvPython -m pip install aqtinstall
+    Write-Host "已创建虚拟环境：$VenvDir"
+} catch {
+    Write-Warning "venv 创建失败，改用项目内 embeddable Python 自身作为隔离环境。"
+    & $PythonExe (Join-Path $PythonBin "get-pip.py")
+    & $PythonExe -m pip install --upgrade pip setuptools wheel
+    & $PythonExe -m pip install aqtinstall
+    Write-Host "已在项目内 Python 二进制目录安装 pip/aqtinstall：$PythonBin"
+}