========= tesserocr

一个简单的、兼容|Pillow|_的、封装了tesseract-ocr API的光学字符识别(OCR)包装器。

.. image:: https://github.com/sirfz/tesserocr/actions/workflows/build.yml/badge.svg :target: https://github.com/sirfz/tesserocr/actions/workflows/build.yml :alt: Github Actions构建状态

.. image:: https://img.shields.io/pypi/v/tesserocr.svg?maxAge=2592000 :target: https://pypi.python.org/pypi/tesserocr :alt: PyPi上的最新版本

.. image:: https://img.shields.io/pypi/pyversions/tesserocr.svg?maxAge=2592000 :alt: 支持的Python版本

tesserocr使用Cython直接集成了Tesseract的C++ API，这使得源代码简单易读且具有Python风格。当与Python的threading模块一起使用时，它通过在tesseract处理图像时释放GIL，实现了真正的并发执行。

tesserocr设计为友好支持|Pillow|_，但也可以直接用于图像文件。

.. |Pillow| replace:: Pillow .. _Pillow: http://python-pillow.github.io/

要求

需要libtesseract (>=3.04)和libleptonica (>=1.71)。

在Debian/Ubuntu上：

::

$ apt-get install tesseract-ocr libtesseract-dev libleptonica-dev pkg-config

你可能需要手动编译tesseract_以获取更新的版本。注意，如果你有多个tesseract/leptonica安装，可能需要更新你的LD_LIBRARY_PATH环境变量以指向正确的库版本。

构建时需要|Cython|_ (>=0.23)，如果要支持PIL.Image对象，还需要可选的|Pillow|_。

.. _手动编译tesseract: https://github.com/tesseract-ocr/tesseract/wiki/Compiling .. |Cython| replace:: Cython .. _Cython: http://cython.org/

安装

Linux和BSD/MacOS

::

$ pip install tesserocr

安装脚本会尝试检测包含/库目录（如果可用，通过|pkg-config|_），但你可以用自己的参数覆盖它们，例如：

::

$ CPPFLAGS=-I/usr/local/include pip install tesserocr

或者

::

$ python setup.py build_ext -I/usr/local/include

已在Linux和BSD/MacOS上测试

.. |pkg-config| replace:: pkg-config .. _pkg-config: https://pkgconfig.freedesktop.org/

Windows

提供的下载包含执行所需的所有Windows库的独立包。这意味着你的系统不需要额外安装tesseract。

推荐的安装方法是通过Conda，如下所述。

Conda

你可以使用`simonflueckiger <https://anaconda.org/simonflueckiger/tesserocr>`_频道从Conda安装：

::

    > conda install -c simonflueckiger tesserocr

或者使用`conda-forge <https://anaconda.org/conda-forge/tesserocr>`_频道：

::

    > conda install -c conda-forge tesserocr

pip
```

从`simonflueckiger/tesserocr-windows_build/releases <https://github.com/simonflueckiger/tesserocr-windows_build/releases>`_下载对应你的Windows平台和Python安装的wheel文件，然后通过以下方式安装：

::

    > pip install <package_name>.whl

从源码构建

如果你需要Windows tesserocr包，但你的Python版本不被上述项目支持，你可以尝试按照Windows.build.md_中的Windows 64位的分步说明进行操作。

.. _Windows.build.md: Windows.build.md

tessdata

如果无法自动检测tessdata路径，你可能需要指定它。这可以通过设置TESSDATA_PREFIX环境变量或者向PyTessBaseAPI传递路径来实现（例如：PyTessBaseAPI(path='/usr/share/tessdata')）。该路径应包含.traineddata文件，可以在https://github.com/tesseract-ocr/tessdata找到。

确保你有与tesseract --version相匹配的正确版本的traineddata。

你可以使用get_languages函数列出系统当前支持的语言：

.. code:: python

from tesserocr import get_languages

print(get_languages('/usr/share/tessdata'))  # 或适用于你系统的任何其他路径

使用方法

初始化并重用tesseract API实例来处理多个图像：

.. code:: python

from tesserocr import PyTessBaseAPI

images = ['sample.jpg', 'sample2.jpg', 'sample3.jpg']

with PyTessBaseAPI() as api:
    for img in images:
        api.SetImageFile(img)
        print(api.GetUTF8Text())
        print(api.AllWordConfidences())
# 在with语句（上下文管理器）中使用时，api会自动完成。
# 否则，当不再需要api时，应该显式调用api.End()。

PyTessBaseAPI暴露了几个tesseract API方法。确保阅读它们的文档字符串以获取更多信息。

使用可用辅助函数的基本示例：

.. code:: python

import tesserocr
from PIL import Image

print(tesserocr.tesseract_version())  # 打印tesseract-ocr版本
print(tesserocr.get_languages())  # 打印tessdata路径和可用语言列表

image = Image.open('sample.jpg')
print(tesserocr.image_to_text(image))  # 打印图像的ocr文本
# 或者
print(tesserocr.file_to_text('sample.jpg'))

image_to_text和file_to_text可以与threading一起使用，以高效地并发处理多个图像。

高级API示例

GetComponentImages示例：

.. code:: python

    from PIL import Image
    from tesserocr import PyTessBaseAPI, RIL
image = Image.open('/usr/src/tesseract/testing/phototest.tif')
with PyTessBaseAPI() as api:
    api.SetImage(image)
    boxes = api.GetComponentImages(RIL.TEXTLINE, True)
    print('找到 {} 个文本行图像组件。'.format(len(boxes)))
    for i, (im, box, _, _) in enumerate(boxes):
        # im 是一个 PIL 图像对象
        # box 是一个包含 x, y, w 和 h 键的字典
        api.SetRectangle(box['x'], box['y'], box['w'], box['h'])
        ocrResult = api.GetUTF8Text()
        conf = api.MeanTextConf()
        print(u"框[{0}]: x={x}, y={y}, w={w}, h={h}, "
              "置信度: {1}, 文本: {2}".format(i, conf, ocrResult, **box))

方向和脚本检测（OSD）：

from PIL import Image
from tesserocr import PyTessBaseAPI, PSM

with PyTessBaseAPI(psm=PSM.AUTO_OSD) as api:
    image = Image.open("/usr/src/tesseract/testing/eurotext.tif")
    api.SetImage(image)
    api.Recognize()

    it = api.AnalyseLayout()
    orientation, direction, order, deskew_angle = it.Orientation()
    print("方向: {:d}".format(orientation))
    print("书写方向: {:d}".format(direction))
    print("文本行顺序: {:d}".format(order))
    print("倾斜角度: {:.4f}".format(deskew_angle))

或者使用 OSD_ONLY 页面分割模式更简单：

from tesserocr import PyTessBaseAPI, PSM

with PyTessBaseAPI(psm=PSM.OSD_ONLY) as api:
    api.SetImageFile("/usr/src/tesseract/testing/eurotext.tif")

    os = api.DetectOS()
    print("方向: {orientation}\n方向置信度: {oconfidence}\n"
          "脚本: {script}\n脚本置信度: {sconfidence}".format(**os))

使用 tesseract 4+ 获取更易读的信息（演示 LSTM 引擎使用）：

from tesserocr import PyTessBaseAPI, PSM, OEM

with PyTessBaseAPI(psm=PSM.OSD_ONLY, oem=OEM.LSTM_ONLY) as api:
    api.SetImageFile("/usr/src/tesseract/testing/eurotext.tif")

    os = api.DetectOrientationScript()
    print("方向: {orient_deg}\n方向置信度: {orient_conf}\n"
          "脚本: {script_name}\n脚本置信度: {script_conf}".format(**os))

单个符号的分类器选择迭代器：

from __future__ import print_function

from tesserocr import PyTessBaseAPI, RIL, iterate_level

with PyTessBaseAPI() as api:
    api.SetImageFile('/usr/src/tesseract/testing/phototest.tif')
    api.SetVariable("save_blob_choices", "T")
    api.SetRectangle(37, 228, 548, 31)
    api.Recognize()

    ri = api.GetIterator()
    level = RIL.SYMBOL
    for r in iterate_level(ri, level):
        symbol = r.GetUTF8Text(level)  # r == ri
        conf = r.Confidence(level)
        if symbol:
            print(u'符号 {}, 置信度: {}'.format(symbol, conf), end='')
        indent = False
        ci = r.GetChoiceIterator()
        for c in ci:
            if indent:
                print('\t\t ', end='')
            print('\t- ', end='')
            choice = c.GetUTF8Text()  # c == ci
            print(u'{} 置信度: {}'.format(choice, c.Confidence()))
            indent = True
        print('---------------------------------------------')