OpenCV text 模块 Windows 下 Tesseract OCR 依赖安装实战指南
OpenCV text 模块 Windows 下 Tesseract OCR 依赖安装实战指南
本指南完整讲解如何基于 opencv_contrib 仓库的 text 模块(场景文本检测与识别模块),在 Windows 环境中通过 git-bash 与 CMake 从源码编译 zlib、libpng、leptonica、Tesseract,并最终构建出带 Tesseract OCR 能力的 OpenCV。读完本文你将掌握:依赖目录如何规划、两套安装脚本逐行含义、OpenCV 侧如何探测与链接 Tesseract,以及语言数据与运行环境(TESSDATA_PREFIX、PATH)的最终配置方法。
本文以仓库内教程 install_tesseract.markdown 为主体,并结合 text 模块的 CMake 配置 与 OCR 源码实现 进行原理层面的佐证。
为什么 text 模块需要 Tesseract
opencv_contrib 的 text 模块提供场景文本检测(Extremal Region、SWT、CNN)与识别(OCR)能力。其中 OCR 部分默认依赖两个独立引擎:
- OCRTesseract:封装 tesseract-ocr 官方 C++ API(
tesseract::TessBaseAPI); - OCRHMMDecoder / OCRBeamSearchDecoder:OpenCV 自带的 HMM / Beam Search 解码器(不依赖外部库)。
OCRTesseract 的声明位于 ocr.hpp:
CV_WRAP static Ptr<OCRTesseract> create(const char* datapath=NULL, const char* language=NULL,
const char* char_whitelist=NULL, int oem=OEM_DEFAULT, int psmode=PSM_AUTO);
从源码看,ocr_tesseract.cpp 中的实现类 OCRTesseractImpl 内部持有 tesseract::TessBaseAPI tess; 成员,通过 tess.Init()、tess.SetImage()、tess.Recognize()、tess.GetUTF8Text() 完成识别,并通过 tesseract::ResultIterator 输出每个词/行的矩形框与置信度。这些代码全部被 #ifdef HAVE_TESSERACT 包裹——如果构建时没有正确安装并链接 Tesseract,HAVE_TESSERACT 不会被定义,OCRTesseract 运行时只会输出 "Tesseract not found" 并返回空结果。因此,能否让 OpenCV 在 Windows 上"看得见" Tesseract,是本文安装流程的全部意义所在。
环境准备与目录规划
按原教程的假设,你需要先完成以下前置条件:
- 已按 OpenCV 官方 Windows 安装教程(git-bash 构建方式)在
c:/lib下安装好 opencv 与 opencv_contrib 源码,两者平级存放; - git-bash 版本 ≥ 2.14.1(本教程所有命令均在 git bash 命令行中执行);
- CMake 版本 ≥ 3.9.1;
- Visual Studio 2015(64 位),对应 CMake 生成器名
Visual Studio 14 2015 Win64——原脚本明确假设使用 VS2015 64 位,若你使用其他 VS 版本,需同步替换生成器名称与工具链。
依赖源码规划如下(全部与 opencv、opencv_contrib 平级放在 c:/lib 下):
| 目录 | 内容 | 来源 |
|---|---|---|
c:/lib/opencv |
OpenCV 主仓库 | 官方源码 |
c:/lib/opencv_contrib |
本仓库(extra modules) | 官方源码 |
c:/lib/zlib |
zlib 1.2.11 | 官方发布包(zlib1211.zip) |
c:/lib/lpng |
libpng 1.6.32 | 官方发布包(lpng1632.zip) |
c:/lib/leptonica |
leptonica(master) | 官方 Git 仓库克隆 |
c:/lib/tesseract |
tesseract(master) | 官方 Git 仓库克隆 |
说明:zlib 与 libpng 的官方发布包下载地址在原文中给出,请以各项目官方发布渠道为准;解压时必须把 lpng 解压到名为
lpng的文件夹、zlib 解压到名为zlib的文件夹,且两者必须与 opencv、opencv_contrib 处于同一目录(c:/lib),否则后续脚本中的相对路径将失效。
第一步:编译 zlib 与 libpng(installpngzlib.sh)
将以下脚本以 installpngzlib.sh 为名保存到 c:/lib:
#!/bin/bash
myRepo=$(pwd)
CMAKE_CONFIG_GENERATOR="Visual Studio 14 2015 Win64"
RepoSource=zlib
mkdir Build/$RepoSource
pushd Build/$RepoSource
cmake . -G"Visual Studio 14 2015 Win64" \
-DCMAKE_INSTALL_PREFIX:PATH="$myRepo"/install/zlib -DINSTALL_BIN_DIR:PATH="$myRepo"/install/zlib/bin \
-DINSTALL_INC_DIR:PATH="$myRepo"/install/zlib/include -DINSTALL_LIB_DIR:PATH="$myRepo"/install/zlib/lib "$myRepo"/"$RepoSource"
cmake --build . --config release
cmake --build . --target install --config release
cmake --build . --config debug
cmake --build . --target install --config debug
popd
RepoSource=lpng
mkdir Build/$RepoSource
pushd Build/$RepoSource
cp "$myRepo"/"$RepoSource"/scripts/pnglibconf.h.prebuilt "$myRepo"/"$RepoSource"/pnglibconf.h
cmake . -G"Visual Studio 14 2015 Win64" \
-DZLIB_INCLUDE_DIR:PATH="$myRepo"/install/zlib/include -DZLIB_LIBRARY_DEBUG:FILE="$myRepo"/install/zlib/lib/zlibstaticd.lib \
-Dld-version-script:BOOL=OFF -DPNG_TESTS:BOOL=OFF -DAWK:STRING= \
-DZLIB_LIBRARY_RELEASE:FILE="$myRepo"/install/zlib/lib/zlibstatic.lib -DCMAKE_INSTALL_PREFIX="$myRepo"/Install/"$RepoSource" \
"$myRepo"/"$RepoSource"
cmake --build . --config release
cmake --build . --target install --config release
cmake --build . --config debug
cmake --build . --target install --config debug
popd
脚本逐段解读:
myRepo=$(pwd):记录仓库根目录(执行脚本时须位于c:/lib)。- zlib 段:在
Build/zlib目录内用 VS2015 Win64 生成器配置 zlib,安装前缀指向install/zlib,同时显式指定 bin / include / lib 三个安装子目录;随后分别以release与debug两种配置执行编译与install目标,产出zlibstatic.lib(Release)与zlibstaticd.lib(Debug)——这两个库文件名会在 libpng 配置中被引用。 - lpng 段:先将 libpng 自带的预生成头文件
scripts/pnglibconf.h.prebuilt复制为pnglibconf.h(Windows 下没有 GNU awk,跳过 pnglibconf 的动态生成),再配置 libpng:通过ZLIB_INCLUDE_DIR、ZLIB_LIBRARY_DEBUG、ZLIB_LIBRARY_RELEASE把上一步安装的 zlib 头文件与静态库传给 libpng;-DPNG_TESTS:BOOL=OFF关闭 PNG 测试;-DAWK:STRING=显式置空 awk 工具。同样执行 release / debug 两轮构建与安装。
最后在 git bash 命令行中执行:
./installpngzlib.sh
构建产物将位于 c:/lib/install/zlib 与 c:/lib/Install/lpng(注意脚本中 lpng 的安装前缀写作 Install/lpng,与 zlib 的 install/zlib 大小写不一致,这是原脚本的历史写法,后续步骤按各自实际路径引用即可)。
第二步:编译 leptonica 与 tesseract(installTesseract.sh)
将以下脚本以 installTesseract.sh 为名保存到 c:/lib:
#!/bin/bash
function MAJGitRepo
{
if [ ! -d "$myRepo/$1" ]; then
echo "clonning ${1}"
git clone $2
mkdir Build/$1
else
echo "update $1"
cd $1
git pull --rebase
cd ..
fi
}
echo "Installing leptonica and tesseract"
myRepo=$(pwd)
CMAKE_CONFIG_GENERATOR="Visual Studio 14 2015 Win64"
MAJGitRepo leptonica https://github.com/DanBloomberg/leptonica.git
RepoSource=leptonica
pushd Build/$RepoSource
cmake -G"$CMAKE_CONFIG_GENERATOR" -DCMAKE_INSTALL_PREFIX="$myRepo"/Install/leptonica "$myRepo/$RepoSource"
echo "************************* $Source_DIR -->debug"
cmake --build . --config release
cmake --build $RepoSource --target install --config release
popd
RepoSource=tesseract
MAJGitRepo $RepoSource https://github.com/tesseract-ocr/tesseract.git
pushd Build/$RepoSource
cmake -G"$CMAKE_CONFIG_GENERATOR" -DBUILD_TRAINING_TOOLS:BOOL=OFF -DCMAKE_INSTALL_PREFIX="$myRepo"/Install/tesseract -DLeptonica_DIR:PATH="$myRepo"/Install/leptonica/cmake -DPKG_CONFIG_EXECUTABLE:BOOL=OFF "$myRepo"/"$RepoSource"
echo "************************* $Source_DIR -->release"
cmake --build . --config release
cmake --build . --target install --config release
popd
RepoSource=opencv
pushd Build/$RepoSource
CMAKE_OPTIONS='-DBUILD_PERF_TESTS:BOOL=OFF -DBUILD_TESTS:BOOL=OFF -DBUILD_DOCS:BOOL=OFF -DWITH_CUDA:BOOL=OFF'
cmake -G"$CMAKE_CONFIG_GENERATOR" \
-DTesseract_INCLUDE_DIR:PATH="${myRepo}"/Install/tesseract/include -DTesseract_LIBRARY="${myRepo}"/Install/tesseract/lib/tesseract400.lib -DLept_LIBRARY="${myRepo}"/Install/leptonica/lib/leptonica-1.74.4.lib \
$CMAKE_OPTIONS -DOPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules \
-DINSTALL_CREATE_DISTRIB=ON -DCMAKE_INSTALL_PREFIX="$myRepo"/install/"$RepoSource" "$myRepo/$RepoSource"
echo "************************* $Source_DIR -->devenv debug"
cmake --build . --config debug
echo "************************* $Source_DIR -->devenv release"
cmake --build . --config release
cmake --build . --target install --config release
cmake --build . --target install --config debug
popd
原文中的两个
git clone地址分别指向 leptonica 与 tesseract 的官方 Git 仓库,请以两个项目官方页面提供的克隆地址为准。脚本中MAJGitRepo函数负责"不存在则克隆、已存在则git pull --rebase更新"。
脚本逐段解读:
- leptonica 段:克隆后进入
Build/leptonica,用 VS2015 Win64 生成器配置,安装前缀为Install/leptonica,随后执行 release 构建与安装。这里注意原脚本将 install 目标写作cmake --build $RepoSource --target install --config release($RepoSource作为目录参数传入),实际执行时更稳妥的写法是cmake --build . --target install --config release,效果一致。 - tesseract 段:克隆 tesseract(master)后配置:
-DBUILD_TRAINING_TOOLS:BOOL=OFF:关闭训练工具(tesseract 训练工具链依赖更多第三方库,OCR 运行不需要);-DCMAKE_INSTALL_PREFIX=Install/tesseract:安装到独立前缀;-DLeptonica_DIR=Install/leptonica/cmake:向 tesseract 提供 leptonica 的 CMake 包位置;-DPKG_CONFIG_EXECUTABLE:BOOL=OFF:Windows 下没有 pkg-config,显式关闭。
- opencv 段:回到
Build/opencv重新配置 OpenCV(详见下一步)。
第三步:将 Tesseract 接入 OpenCV 构建
第三步的关键 cmake 参数如下:
CMAKE_OPTIONS='-DBUILD_PERF_TESTS:BOOL=OFF -DBUILD_TESTS:BOOL=OFF -DBUILD_DOCS:BOOL=OFF -DWITH_CUDA:BOOL=OFF -DBUILD_EXAMPLES:BOOL=OFF'
即:不构建性能测试、不构建测试、不构建文档、不启用 CUDA、不构建示例,只做最小可用的构建(原脚本将 BUILD_EXAMPLES:BOOL=OFF 写在说明中,实际命令行以 CMAKE_OPTIONS 中的前三项为准)。
OpenCV 侧三个 Tesseract 相关变量的含义:
| CMake 变量 | 值(示例) | 作用 |
|---|---|---|
Tesseract_INCLUDE_DIR |
c:/lib/Install/tesseract/include |
告诉 OpenCV 去哪里找 tesseract/baseapi.h |
Tesseract_LIBRARY |
c:/lib/Install/tesseract/lib/tesseract400.lib |
链接 tesseract 导入库(tesseract400.lib 对应当时 tesseract 4.0 的导出库命名) |
Lept_LIBRARY |
c:/lib/Install/leptonica/lib/leptonica-1.74.4.lib |
链接 leptonica 导入库(leptonica-1.74.4.lib 对应当时 leptonica 1.74.4 版本) |
另外两个关键开关:
-DOPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules:把本仓库的 extra modules(含 text 模块)纳入构建;-DINSTALL_CREATE_DISTRIB=ON:生成可分发的安装包目录。
版本提示:
tesseract400.lib与leptonica-1.74.4.lib这两个库名对应原文撰写时的 tesseract 4.x / leptonica 1.74.4 版本。若你克隆到更新的版本,库文件名(以及 leptonica 的版本号部分)会随之变化,需要以Install/xxx/lib目录下实际生成的.lib文件名修改这两个变量,这是最常见的踩坑点。
配置完成后依次执行:
cmake --build . --config debug
cmake --build . --config release
cmake --build . --target install --config release
cmake --build . --target install --config debug
即 debug / release 两轮构建并安装到 c:/lib/install/opencv。
源码视角:OpenCV 如何检测并链接 Tesseract
理解安装流程背后的探测机制,能帮助你排查"Tesseract: NO"的问题。text 模块的 CMake 逻辑分三层:
- 模块级开关:init.cmake 通过
OCV_OPTION(WITH_TESSERACT "Include Tesseract OCR library support" ...)定义开关(默认在非交叉编译环境下开启),再调用find_package(Tesseract QUIET)优先查找 CMake 标准位置的 Tesseract 包;找不到时再include模块自带的 fallback 查找脚本。 - 回退查找:FindTesseract.cmake 依次执行
ocv_check_modules(Tesseract tesseract)、在/usr/include、/usr/local/include查找tesseract/baseapi.h、在/usr/lib、/usr/local/lib查找tesseract与lept库。Windows 上手写的Tesseract_INCLUDE_DIR/Tesseract_LIBRARY/Lept_LIBRARY正是走这套回退路径。 - 编译可用性验证:找到头文件与库之后,init.cmake 会执行
try_compile,用 tesseract_test.cpp(仅#include <tesseract/baseapi.h>、<tesseract/resultiterator.h>并实例化tesseract::TessBaseAPI)实际链接一次。编译链接通过才置HAVE_TESSERACT 1并创建ocv.3rdparty.tesseract接口目标,随后 CMakeLists.txt 中的ocv_target_link_libraries(${the_module} LINK_PRIVATE ocv.3rdparty.tesseract)才会把 Tesseract 链进 text 模块。
最终,HAVE_TESSERACT 会写入由 text_config.hpp.in 生成的 text_config.hpp(#cmakedefine HAVE_TESSERACT)。而 ocr_tesseract.cpp 中 #ifdef HAVE_TESSERACT 分支内的 tess.Init(datapath, lang, (tesseract::OcrEngineMode)oem)、tess.SetPageSegMode(...)、tess.SetVariable("tessedit_char_whitelist", ...) 等调用才会被真正编译进库。
因此,配置 OpenCV 时观察 cmake 输出中的 Tesseract: YES (ver ...) 或 Tesseract: NO 是判断集成是否成功的第一信号;若显示 NO,通常意味着上面第三步的三个变量路径写错、库版本名不匹配,或 try_compile 链接失败(可在 OPENCV_DEBUG_TESSERACT_BUILD 开启时查看详细错误输出)。
第四步:语言数据(tessdata)与运行环境配置
构建完成不等于可以直接识别,还需要语言数据与动态库路径:
- 获取语言文件:tesseract 的识别依赖训练好的语言数据(
eng.traineddata等)。原文给出两种方式:- 克隆 tesseract 官方的 tessdata 语言数据仓库(包含全部语言);
- 或只复制你需要的语言文件到某个文件夹,例如
c:/lib/install/tesseract/tessdata。
- 设置 TESSDATA_PREFIX:如果语言文件放在新建的文件夹(而不是与可执行文件同目录),则必须新增系统环境变量
TESSDATA_PREFIX,值为c:/lib/install/tessdata(即 tessdata 的父目录,注意不要带上\tessdata本身)。如果你不想新建文件夹,则把语言文件复制到与可执行程序相同的目录即可,无需设置该变量。 - 配置动态库搜索路径:运行 OCR 程序时,Windows 需要能找到
tesseract400.dll与leptonica-1.74.4.dll。两种做法任选其一:- 把
c:/lib/install/leptonica/bin与c:/lib/install/tesseract/bin加入系统的PATH环境变量; - 或直接把这两个 DLL 复制到你的 exe 所在目录,与可执行文件放在一起。
- 把
TESSDATA_PREFIX 的取值与 OCR API 的 datapath 参数存在对应关系:在 ocr.hpp 中 OCRTesseract::create 的 datapath 参数被描述为 "tessdata 的父目录,以 / 结尾,或传 NULL 使用系统默认目录",language 参数是 ISO 639-3 语言代码(默认 "eng")。TESSDATA_PREFIX 正是 tesseract 自身在系统默认目录之外定位语言数据的另一条途径。
验证安装与后续使用
完成上述四步后,可通过以下方式确认整条链路可用:
- 重新配置 OpenCV 时,cmake 输出出现
Tesseract: YES,且text_config.hpp中HAVE_TESSERACT被定义; - 运行示例程序。仓库中的 end_to_end_recognition.cpp 展示了"ER 文本检测 + Tesseract 识别"的完整流程,核心一行是:
Ptr<OCRTesseract> ocr = OCRTesseract::create();
然后对每个检测框执行:
ocr->run(group_img, output, &boxes, &words, &confidences, OCR_LEVEL_WORD);
- 按需调参。
OCRTesseract::create的五个参数(均在 ocr.hpp 中声明)可结合实际场景调整:
| 参数 | 默认值 | 说明 |
|---|---|---|
datapath |
NULL(使用系统默认目录) | tessdata 父目录,以 / 结尾 |
language |
NULL(即 "eng") |
ISO 639-3 语言代码,如 eng、chi_sim |
char_whitelist |
NULL(即空串,全部字符) | 识别字符白名单;OpenCV 4.7.0/3.19.0 起默认从 [0-9a-zA-Z] 改为空串 |
oem |
OEM_DEFAULT |
OCR 引擎模式(Tesseract-only / Cube / 组合 / 默认) |
psmode |
PSM_AUTO |
页面分割模式(自动版式分析、单行、单词、单字符等) |
相关可运行示例还包括 textdetection.cpp(纯文本检测)、webcam_demo.cpp(摄像头实时检测 + Tesseract 识别)、character_recognition.cpp(字符级识别)等。
常见问题与注意事项汇总
- "Tesseract: NO":优先检查第三步三个变量的路径与实际文件是否存在,特别注意
tesseract400.lib/leptonica-1.74.4.lib是否与当前克隆版本的实际库名一致。 - VS 版本不同:全文假设
Visual Studio 14 2015 Win64,若使用 VS2017/2019/2022,需替换为对应生成器名(如Visual Studio 17 2022等),并注意工具链位数保持一致。 - debug/release 库不匹配:zlib 的
zlibstaticd.lib对应 Debug、zlibstatic.lib对应 Release,配置 libpng 时已分别指定;后续 OpenCV 链接 tesseract/leptonica 时同样建议保持配置一致。 - 运行期找不到 DLL:这是"编译成功但运行报缺少 dll"的最常见原因,按第四步配置
PATH或复制 DLL 即可解决。 - 语言文件缺失:未配置
TESSDATA_PREFIX且语言文件不在可执行文件目录时,tesseract 初始化(tess.Init)会失败,OCRTesseract会输出 "Could not initialize tesseract"。
按照本文四个步骤依次执行,即可在 Windows 上得到带 Tesseract OCR 能力的 OpenCV(含 text 模块)构建,为后续的场景文本检测与识别开发打下完整的依赖基础。