在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

tesseract-ocr/tesseract

菜单

C API

相关源文件

Tesseract 的 C API 为 C 应用程序和其他可以调用 C 函数的编程语言提供了语言绑定。它作为 C++ API（请参阅 TessBaseAPI）的包装器，使没有 C++ 支持的应用程序能够使用 Tesseract 的 OCR 功能。本文档记录了 Tesseract C API 的目的、结构和用法。

概述

C API 由封装 Tesseract C++ 类和方法的函数组成，提供 C 兼容的接口，同时保持相同的功能。C API 处理 C 和 C++ 代码之间的数据类型转换和内存管理。

来源： include/tesseract/capi.h18-41 src/api/capi.cpp1-16

架构

C API 是 C++ API 的一个精简包装。每个 C 函数通常对应 C++ 类中的一个方法，主要类是 TessBaseAPI。API 遵循基于句柄的设计，其中不透明指针（句柄）代表 C++ 对象，函数在此类句柄上操作。

来源： include/tesseract/capi.h42-57 include/tesseract/capi.h58-136

关键组件

基础 API 函数

这些函数创建、配置和使用 Tesseract 的主 API 对象（TessBaseAPI）。

来源： include/tesseract/capi.h187-356 src/api/capi.cpp136-475

渲染器函数

渲染器以多种格式输出 OCR 结果，如纯文本、HOCR、PDF 等。

渲染器类型功能输出格式
文本TessTextRendererCreate()纯 UTF-8 文本
HOCRTessHOcrRendererCreate()带有 OCR 布局信息的 HTML
PDFTessPDFRendererCreate()可搜索 PDF
ALTOTessAltoRendererCreate()ALTO XML 格式
TSVTessTsvRendererCreate()制表符分隔值
BoxTessBoxTextRendererCreate()Box 文件格式
LSTM BoxTessLSTMBoxRendererCreate()LSTM 训练 Box 格式
Word Str BoxTessWordStrBoxRendererCreate()Word 字符串 Box 格式

来源： include/tesseract/capi.h154-169 src/api/capi.cpp55-98

迭代器函数

迭代器允许在页面层次结构的不同级别上遍历 OCR 结果。

迭代器类型目的
TessPageIterator遍历页面元素（块、段落、行、单词）
TessResultIterator访问识别元素的文本和置信度值
TessChoiceIterator检查符号的替代字符选择

来源： include/tesseract/capi.h380-466 src/api/capi.cpp506-679

内存管理

C API 会为各种结果分配内存，这些内存必须由调用者使用特定函数进行释放。

分配类型释放函数
文本字符串TessDeleteText()
文本字符串数组TessDeleteTextArray()
整数数组TessDeleteIntArray()
API 对象特定的删除函数（例如 TessBaseAPIDelete()）
渲染器TessDeleteResultRenderer()
迭代器特定类型的删除函数

来源： include/tesseract/capi.h147-152 src/api/capi.cpp31-53

使用流程

Tesseract C API 的典型使用流程包括以下步骤：

来源： src/api/capi.cpp136-142 src/api/capi.cpp231-243 src/api/capi.cpp307-312 src/api/capi.cpp395-397 src/api/capi.cpp31-33 src/api/capi.cpp473-475

数据类型

不透明句柄

C API 使用不透明指针（句柄）来表示 C++ 对象。

C 类型底层 C++ 类型
TessBaseAPItesseract::TessBaseAPI
TessResultRenderertesseract::TessResultRenderer
TessPageIteratortesseract::PageIterator
TessResultIteratortesseract::ResultIterator
TessMutableIteratortesseract::MutableIterator
TessChoiceIteratortesseract::ChoiceIterator

来源： include/tesseract/capi.h42-57

枚举

C API 定义了几个用于配置和使用的枚举。

枚举描述
TessOcrEngineMode引擎模式选择（LSTM、Legacy、Combined）
TessPageSegMode页面分割模式
TessPageIteratorLevel页面层次结构级别（块、段落、行、单词、符号）
TessPolyBlockType页面上的块类型
TessOrientation页面方向
TessWritingDirection文本书写方向
TessTextlineOrder文本行顺序
TessParagraphJustification段落对齐方式

来源： include/tesseract/capi.h65-134

函数类别

C API 函数可分为几类。

初始化和清理

TessBaseAPICreate()
TessBaseAPIDelete()
TessBaseAPIInit1(), TessBaseAPIInit2(), TessBaseAPIInit3(), TessBaseAPIInit4(), TessBaseAPIInit5()
TessBaseAPIEnd()

来源： include/tesseract/capi.h187-237 src/api/capi.cpp136-259

图像设置与处理

TessBaseAPISetImage(), TessBaseAPISetImage2()
TessBaseAPISetSourceResolution()
TessBaseAPISetRectangle()
TessBaseAPIRecognize()
TessBaseAPIProcessPages(), TessBaseAPIProcessPage()

来源: include/tesseract/capi.h264-317 src/api/capi.cpp307-409

结果检索

TessBaseAPIGetUTF8Text()
TessBaseAPIGetHOCRText()
TessBaseAPIGetAltoText()
TessBaseAPIGetTsvText()
TessBaseAPIGetBoxText()
TessBaseAPIGetLSTMBoxText()
TessBaseAPIGetWordStrBoxText()
TessBaseAPIGetUNLVText()
TessBaseAPIMeanTextConf()
TessBaseAPIAllWordConfidences()

来源: include/tesseract/capi.h323-339 src/api/capi.cpp419-461

配置

TessBaseAPISetVariable()
TessBaseAPISetDebugVariable()
TessBaseAPIGetIntVariable()
TessBaseAPIGetBoolVariable()
TessBaseAPIGetDoubleVariable()
TessBaseAPIGetStringVariable()
TessBaseAPIPrintVariables()
TessBaseAPIPrintVariablesToFile()
TessBaseAPISetPageSegMode()
TessBaseAPIGetPageSegMode()

来源: include/tesseract/capi.h201-255 src/api/capi.cpp172-295

渲染器管理

TessTextRendererCreate()
TessHOcrRendererCreate()
TessPDFRendererCreate()
TessAltoRendererCreate()
TessTsvRendererCreate()
TessBoxTextRendererCreate()
TessLSTMBoxRendererCreate()
TessWordStrBoxRendererCreate()
TessDeleteResultRenderer()
TessResultRendererInsert()
TessResultRendererBeginDocument()
TessResultRendererAddImage()
TessResultRendererEndDocument()

来源: include/tesseract/capi.h154-184 src/api/capi.cpp55-134

迭代器管理

TessPageIteratorDelete()
TessResultIteratorDelete()
TessChoiceIteratorDelete()
TessPageIteratorCopy()
TessResultIteratorCopy()
TessResultIteratorGetPageIterator()
TessPageIteratorNext()
TessResultIteratorNext()
TessChoiceIteratorNext()

来源: include/tesseract/capi.h381-466 src/api/capi.cpp506-679

最佳实践

  1. 内存管理:

    • 始终免费提供 API 返回的资源，并附带相应的删除函数
    • 完成后删除 API 对象

  2. 初始化:

    • 始终提供有效的 tessdata 路径和相应语言文件
    • 检查初始化函数的返回值

  3. 错误处理:

    • 检查可能失败的函数的返回值
    • 对长时间运行的操作使用进度和取消机制

  4. 多线程:

    • 每个线程应有自己的 TessBaseAPI 实例
    • 请勿在线程之间共享 API 对象

  5. 图像要求:

    • 提供足够分辨率的图像（推荐 300 DPI）
    • 为获得最佳效果，请预处理图像以提高对比度并减少噪点

来源: include/tesseract/capi.h1-14 src/api/capi.cpp1-16

内部实现

C API 是 Tesseract OCR 引擎 C++ API 的一个薄层封装。每个 C 函数通常

  1. 接收一个句柄和其他参数
  2. 解引用句柄以获取 C++ 对象
  3. 调用相应的 C++ 方法
  4. 在必要时将返回值转换为 C 兼容类型

来源: src/api/capi.cpp20-29 src/api/capi.cpp35-41

结论

Tesseract C API 为 C 应用程序和其他语言绑定提供了 Tesseract OCR 引擎的完整接口。它通过不透明句柄和基于函数的接口，在提供 C 兼容性的同时，反映了 C++ API 的功能。通过遵循文档中记载的内存管理和使用模式，开发人员可以有效地将 Tesseract OCR 功能集成到他们的 C 应用程序中。