手印:手写页识别测试
handprint的Python项目详细描述
手印
一个python程序,用于将不同的手写文本识别服务应用于手写文本页的图像,并生成一个带注释的图像(可选更多),显示识别的文本。
最近变化日志
版本1.0.1:此版本添加了从pypi安装的说明,并修复了从url下载的文件写入错误。
版本1.0.0:这是一个足够完整的手印版本,最终可以称为版本1.0。与0.10.0版本相比的更改包括:提供凭据文件的新方式、新的默认输出(其中来自不同服务的结果并排放置在单个大图像中)、新的命令行参数、并行执行等。
该文件包含一个更完整的更改日志,其中包含有关以前版本的信息。
目录
简介
手印(手写p年龄recognition
手印可以处理单个图像、图像目录和指向远程服务器上图像的url。除了生成带注释的图像作为输出外,它还可以将htr服务的原始结果输出为json和文本文件。手印可以使用多个处理器线程并行执行。
安装和配置
下面的说明假设您的计算机上安装了python解释器;如果不是这样,请首先安装python并熟悉在系统上运行python程序。
handprint包括几个适配器,用于使用来自亚马逊、谷歌和微软的基于云的htr服务。安装手印需要在您的计算机上安装手印的副本,并为您的副本提供访问要使用的云服务的凭据。
在计算机上安装手印
以下可能是在您的计算机上安装最新版本手印的最简单和最直接的方法:
sudo python3 -m pip install handprint --upgrade
或者,可以使用以下命令直接从github存储库安装最新版本:
sudo python3 -m pip install git+https://github.com/caltechlibrary/handprint.git --upgrade
_添加云服务凭据
在计算机上安装手印后,每个基于云的htr服务都需要一个一次性的配置步骤。此步骤提供带有访问服务凭据的手印。在每种情况下,都使用相同的命令格式:
handprint -a SERVICENAME CREDENTIALSFILE.json
servicename必须是通过运行handprint-l
打印的服务名称之一,并且credentialsfile.json
必须具有下面讨论的格式之一。运行此命令时,handprint会将credentialsfile.json
复制到私有位置,然后fter使用凭据访问servicename。(不同系统上的专用位置不同;例如,在MacOS上,它是~/library/application support/handprint/
)下面给出了示例。
微软
Microsoft在azure中使用凭据的方法包括使用订阅密钥。手印凭证文件的格式只需包含一个字段:
{"subscription_key":"YOURKEYHERE"}
"yourkeyre"的值将是一个字符串,例如"18de248475134eb49ae4a4e94b93461c"
。要获取密钥,请访问https://portal.azure.com并使用您的帐户登录登录。(注意:如果有ad block和umatrix等浏览器安全插件,则需要将其关闭,否则网站将无法工作。)通过对azure门户的身份验证后,可以创建使用azure机器学习服务的凭据。有关这一点的一些注释可以在github上的"handprint project wiki"页面中找到。获取密钥后,使用文本编辑器以上面所示的简单格式创建一个json文件,将该文件保存在计算机上的某个位置(为了本例的目的,假设它是myazurecredentials.json
),并使用上面讨论的命令使手印复制凭据文件:
handprint -a microsoft myazurecredentials.json
谷歌
使用google服务帐户的凭据需要存储在包含许多字段的json文件中。总体格式如下:
{
"type": "service_account",
"project_id": "theid",
"private_key_id": "thekey",
"private_key": "-----BEGIN PRIVATE KEY-----anotherkey-----END PRIVATE KEY-----\n",
"client_email": "emailaddress",
"client_id": "id",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://oauth2.googleapis.com/token",
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
"client_x509_cert_url": "someurl"
}
获取其中一个在创建服务帐户的google cloud文档中进行了总结,但是可以在handprint项目wik中找到更明确的说明。我在github上翻页。从google下载了google凭据文件后,将该文件保存在计算机上的某个位置(在本例中,假设它是mygooglecredentials.json
),然后使用上面讨论的命令进行手印复制凭据文件:
handprint -a google mygooglecredentials.json
亚马逊
aws的amazon凭证采用两个字母数字字符串的形式:a键id字符串和a密钥访问键字符串。此外,需要使用区域标识符调用服务。出于手印的目的,这些文件应以以下格式存储在json文件中:
{"aws_access_key_id":"YOUR_KEY_ID_HERE","aws_secret_access_key":"YOUR_ACCESS_KEY_HERE","region_name":"YOUR_REGION_NAME_HERE"}
幸运的是,获得这些信息对于亚马逊的服务来说是一个相对简单的过程。有关说明,请参阅github上的"手印项目wiki页面"。获得两个字母数字键和一个区域标识符字符串后,使用文本编辑器以上面所示的简单格式创建一个json文件,将该文件保存在计算机上的某个位置(对于本例,假设它是myamazoncredentials.json
),并使用two命令使手印复制凭据手印目前支持的两种不同亚马逊服务的文件:
handprint -a amazon-textract myamazoncredentials.json handprint -a amazon-rekognition myamazoncredentials.json
?使用
handprint附带一个名为handprint
的命令行界面程序。这是一个屏幕投影,让你了解运行手印的感觉。单击以下图像:
如果上一节中描述的安装步骤成功进行,则手印
命令行程序最终应安装在计算机上通常安装软件的位置。从终端shell运行手印应该和在系统上运行任何其他shell命令一样简单:
sudo python3 -m pip install handprint --upgrade0
如果由于某种原因失败,您应该能够使用运行python模块的常规方法从任何地方运行手印:
sudo python3 -m pip install handprint --upgrade1
-h
选项(/h
在Windows上)将使手印
显示一些帮助信息并立即退出。要使handprint发挥更大作用,您可以提供其他参数,指示handprint处理图像文件(或者,指向网络位置的图像文件的url),并对其运行文本识别算法,如下所述。
支持的HTR/OCR服务
handprint可以为htr联系多个云服务。您可以使用-l
选项(/l
在Windows上)使其显示当前实施的服务列表:
sudo python3 -m pip install handprint --upgrade2
默认情况下,handprint将依次运行每个已知服务,创建带注释的图像来表示每个服务的结果。要仅调用特定的服务,请使用-s
选项(/s
在Windows上),后跟服务名称或由逗号分隔的名称列表(例如,Google、Microsoft
)。例如,下面的命令将保存在一个页面上仅调用Microsoft文本识别服务的结果,该页面位于clara barton的未发布草稿书"The li"我童年的生活",可在手印的源目录中找到:
sudo python3 -m pip install handprint --upgrade3
结果如下:
输入文件和URL
安装凭据后,运行handprint而不运行时,-a
选项将调用文件、文件目录或指向文件的url上的一个或多个服务。更具体地说,输入可以通过以下任一方式提供:
- 本地磁盘上的一个或多个目录路径或一个或多个图像文件路径,将被解释为要处理的图像(单独或在目录中)
- 一个或多个URL,将被解释为要处理的图像文件的网络位置
- 如果给定
-f
选项(在Windows上为/f
),则包含要处理的图像路径或图像URL的文件。
handprint单独考虑每个输入路径,并根据给定路径是否以字母开头,后跟字符:/
和路径的其余部分(例如http://some/other/characters
)来确定输入何时是url。如果任何输入图像都是url,handprint将首先将在url中找到的图像下载到由选项-o
指示的目录(在windows上为/o
)。如果目的地目录不是通过-o
提供的,则使用正在运行手印的当前工作目录。
无论是文件还是url,每个输入都应该是应该识别哪个文本。手印可以读取许多常见格式:jp2、jpeg、png、gif、bmp和tiff。但是,为了简单和与所有云服务的最大兼容性,handprint总是在将所有输入文件发送到服务之前,将它们转换为png格式(如果尚未转换为png格式)。如果需要,handprint还会将图像大小调整为任何调用的服务所接受的最小大小(如果图像超过该大小)。(例如,如果服务A接受大小不超过10 MB的文件,而服务B接受大小不超过5 MB的文件,则在将所有输入图像发送到A和B之前,将其大小调整为5 MB,即使A可以接受更高分辨率的图像。)
注意,由于终端shell如何解释某些字符,在命令行上提供url可能会有问题,因此在提供url时,通常最好将url与-f
选项(在windows上为/f
组合存储在一个文件中)。
带注释的输出图像
默认情况下,handprint将为每个输入文件创建一个输出文件。此文件将具有后缀.all results.png
,并包含所调用的每个服务的结果的注释版本,平铺为n×n网格样式以生成一个(大)输出图像。下面是示例输出图像以演示:
上面的2×2图像是通过从handprint源目录运行以下命令生成的:
sudo python3 -m pip install handprint --upgrade4
除非调用-e
扩展结果选项(/e
在Windows上),否则将不会保留单个结果以及对应于每个服务结果的单个注释图像。使用-g
选项(/g
在Windows上)可以跳过生成概览网格图像。
扩展结果
如果使用-e
选项-e
(/e
在windows上),handprint不仅保存包含所有结果的概览图像,而且还保存每个服务结果的单个注释图像、原始数据(通过handprint转换为json文件)和服务提取的文本。这些额外的输出将写入以原始文件命名的文件中,并添加一个表示所使用服务的字符串。例如,名为somefile.jpg
的文件将生成
sudo python3 -m pip install handprint --upgrade5
将url与-e
选项结合使用会产生一个复杂的问题:如何手工打印它所写的文件的名称?一些cms系统使用不透明的方案来存储内容,这些方案在url中不提供清晰的名称,这使得手印等软件工具无法猜测在本地存储中使用哪个文件名是有意义的。更糟糕的是,有些系统会创建非常长的url,因此无法将url本身用作文件名。例如,下面是指向加州理工学院存档中图像的真实URL:
sudo python3 -m pip install handprint --upgrade6
为了处理这种情况,handprint会在遇到url时生成自己的文件名。方案很简单:默认情况下,handprint将使用document-n
,其中n
是一个整数。每次运行手印时,整数都从1
开始,整数计算在命令行或-f
选项指示的文件中找到的URL。在给定的url中找到的图像存储在名为document-n.e的文件中,其中e
是格式扩展名(例如,document-1.jpg
,document-1.png
等)。URL本身存储在r名为document-1.url的文件。因此,当使用-e
选项时,手印生成的文件将如下所示(在本例中,假设源url处的文件为jpeg格式):
sudo python3 -m pip install handprint --upgrade7
基本名称文档
可以使用-b
选项更改(在Windows上为/b
)。例如,使用选项-b einstein
运行手印将导致输出命名为einstein-1.jpg
,einstein-1.url
等。
最后,如果图像对于调用的任何服务来说太大,那么handprint将在将图像发送到任何服务之前调整其大小(如上所述)。它会将压缩图像写入名为file name reduced.ext
的文件,其中filename
是原始文件名,而ext
是文件扩展名。这意味着,如果需要调整图像的大小,则应用文本识别服务的结果将是,例如,
sudo python3 -m pip install handprint --upgrade8
其他选项
默认情况下,手印在运行时生成彩色编码的诊断输出。但是,某些终端或终端配置可能会使读取带有颜色的文本变得困难,因此handprint提供-c
选项(在Windows上为/c
)以关闭彩色输出。
handprint将使用相当于它运行的计算机上内核数的1/2的进程线程,并行地将文件发送到不同的服务。(例如,如果您的计算机有4个内核,则默认情况下最多使用2个线程。)可以使用-t
选项(/t
在Windows上)更改此数字。
如果给定-@
选项(/@
在Windows上),此程序将在运行时打印其他诊断输出;此外,当发生异常时,它将启动Python调试器(pdb
),而不是简单地退出。重要提示:如果在进程线程中调用pdb,某些python版本/平台组合似乎会完全崩溃——如果调试handprint的执行,则很可能会发生这种情况。因此,handprint的调试模式(通过-@
选项)几乎总是必须与-t 1
相结合,以使handprint只使用一个线程。
如果给定-v
选项(在Windows上为/v
),此程序将打印版本和其他信息,然后退出而不执行任何其他操作。
命令行选项摘要
下表总结了所有可用的命令行选项。(注意:在Windows计算机上,/
必须用作前缀字符,而不是-
短划线字符):
-a
a--添加creds
a-b
b--基名称
b-c
--无颜色
-e
--扩展
-f
f--来自文件
从文件中读取文件名或urlf 在命令行中使用名称或url
-g
--无网格
-h
--帮助
-l
--列表
-o
o--输出
将输出写入目录o 找到图像的目录
-q
--安静
工作时不要打印消息 工作时要健谈
-s
s--服务
使用识别服务
"全部"
-t
t--线程
t-v
--版本
-@
--调试
调试模式 正常模式
如果给定了URL,则默认情况下输出将写入document-n
格式的名称,其中n是整数。示例:document-1.jpg
,document-1.google.txt
等。这是因为位于网络内容管理系统中的图像的URL中可能没有任何清晰的名称。
已知问题和限制
以下是当前版本手印的一些已知限制:
- Amazon重新登录API将在图像中最多返回50个单词。
- 根据文件格式的不同,某些服务有不同的文件大小限制,但handprint始终对给定服务的所有文件使用相同的限制。这是代码简化。
获得帮助
如果您发现问题,请将其提交到此存储库的github问题跟踪程序中。
贡献
我很高兴能得到您的帮助和参与,增强手印!请访问贡献指南以获取有关开始的一些提示。
许可证
版权所有(c)2018-2019,加州理工学院。此软件在bsd/mit类型许可下自由分发。有关详细信息,请参见许可证文件。
作者和历史
Mike Hucka从2018年年中开始设计并实施手印。
致谢
用作手印徽标的手的矢量图是由名词项目中的凯文创建的。它是在creative commons下获得许可的。cc-by 3.0许可。
手印得益于一些人的反馈,特别是汤米·凯斯威克、玛丽拉·索普拉诺、彼得·科洛比和斯蒂芬·戴维森的反馈。
手印利用了大量的开源软件包,没有这些软件包,用我们现有的资源开发TURF实际上是不可能的。我想承认这笔债务。按字母顺序排列的包裹是:
- appdirs–用于确定适当平台特定目录的模块
- boto3–Amazon AWS Python版sdk
- colorama–使ANSI转义字符序列在MS Windows终端下工作
- 彩色-终端中的颜色和格式库
- 谷歌API核心、谷歌API Python客户端、谷歌Auth、谷歌Auth-HttpLib2、谷歌云、谷歌云愿景、谷歌API通用协议、谷歌API Python客户端–谷歌API库
- halo–python命令行程序的繁忙微调器
- 人性化–让数字更容易被人类阅读
- httplib2–一个全面的http客户端库
- 图像大小–确定图像的尺寸
- ipdb–ipython调试器
- matplotlib–一个python二维绘图库
- oauth2client–谷歌oauth 2.0库
- 枕头–python图像库的一个分支
- plac–命令行参数分析器
- psutil–跨平台软件包,用于在python中监视进程和系统
- 请求–一个用于python的http库
- 设置工具–用于
setup.py的库
- termcolor–终端输出的ANSI颜色格式
最后,我感谢加州理工学院提供的计算和机构资源。
< div >