Package: handprint
HandprintTheHandwrittenPageRecognitionTestis a command-line program that invokes HTR (handwritten text recognition) services on images of document pages.  It can produce annotated images showing the results, compare the recognized text to expected text, save the HTR service results as JSON and text files, and more.Log of recent changesVersion 1.5.6: This release updates dependency versions inrequirements.txtandPipfile, to address a security issue in Pillow. It also removes the internal copy of network utilities in favor of using thenetwork_utilsmodule fromCommonPy. There are no functional or API changes in this release.Table of ContentsIntroductionInstallation and configurationInstall Handprint on your computerAdd cloud service credentialsUsageGetting helpContributingLicenseAuthors and historyAcknowledgmentsIntroductionHandprint (HandwrittenPageRecognitionTest) is a tool for comparing alternative services for offlinehandwritten text recognition (HTR).  It was developed for use with documents from theCaltech Archives, but it is completely independent and can be applied to any images of text documents.Handprint can generate images with recognized text overlaid over them to visualize the results.  The image at right shows an example.  Among other features, the software can also display bounding boxes, threshold results by confidence values, compare full-text results to expected/ground-truth results, and output the raw results from an HTR service as JSON and text files. It can work with individual images, directories of images, and URLs pointing to images on remote servers. Finally, Handprint can use multiple processor threads for parallel execution.Services supported include Google'sGoogle Cloud Vision API, Microsoft's AzureComputer Vision API, and Amazon'sTextractandRekognition.  The framework for connecting to services could be expanded to support others as well (and contributions are welcome!).Installation and configurationThe instructions below assume you have a Python interpreter version 3.8 or higher installed on your computer; if that's not the case, please first install Python and familiarize yourself with running Python programs on your system. If you are unsure of which version of Python you have, you can find out by running the following command in a terminal and inspecting the results:# Note: on Windows, you may have to use "python" instead of "python3"python3--versionNote for Mac users: if you are using macOS Catalina (10.15) or later and have never runpython3, then the first time you do, macOS will ask you if you want to install the macOS command-line developer tools.  Go ahead and do so, as this is the easiest way to get a recent-enough Python 3 on those systems.Handprint includes several adapters for working with cloud-based HTR services from Amazon, Google, and Microsoft, but does not include credentials for using the services.  To be able to use Handprint, you mustbothinstall a copy of Handprint on your computerandsupply your copy with credentials for accessing the cloud services you want to use.  See below for more.⓵Install Handprint on your computerApproach 1: using the standalone Handprint executablesBeginning with version 1.5.1, runnable self-contained single-file executables are available for select operating system and Python version combinations – to use them, youonlyneed a Python 3 interpreter and a copy of Handprint, butdo notneed to runpip installor other steps. Please click on the relevant heading below to learn more.macOSVisit theHandprint releases pageand look for the ZIP files with names such as (e.g.)handprint-1.5.4-macos-python3.8.zip. Then:Download the one matching your version of PythonUnzip the file (if your browser did not automatically unzip it for you)Open the folder thus created (it will have a name likehandprint-1.5.4-macos-python3.8)Look inside forhandprintand move it to a location where you put other command-line programs (e.g.,/usr/local/bin)LinuxVisit theHandprint releases pageand look for the ZIP files with names such as (e.g.)handprint-1.5.4-linux-python3.8.zip. Then:Download the one matching your version of PythonUnzip the file (if your browser did not automatically unzip it for you)Open the folder thus created (it will have a name likehandprint-1.5.4-linux-python3.8)Look inside forhandprintand move it to a location where you put other command-line programs (e.g.,/usr/local/bin)WindowsStandalone executables for Windows are not available at this time. If you are running Windows, please use one of the other methods described below.Approach 2: usingpipxYou can usepipxto install Handprint. Pipx will install it into a separate Python environment that isolates the dependencies needed by Handprint from other Python programs on your system, and yet the resultinghandprintcommand wil be executable from any shell – like any normal application on your computer. If you do not already havepipxon your system, it can be installed in a variety of easy ways and it is best to consultPipx's installation guidefor instructions. Once you have pipx on your system, you can install Handprint with the following command:pipxinstallhandprintPipx can also let you run Handprint directly usingpipx run handprint, although in that case, you must always prefix every Handprint command withpipx run.  Consult thedocumentation forpipx runfor more information.Approach 3: usingpipIf you prefer, you can install Handprint withpip.  If you don't havepippackage or are uncertain if you do, please consult thepip installation instructions. Then, to install or upgrade Handprint from the Python package repository, run the following command:python3-mpipinstallhandprint--upgrade⓶Add cloud service credentialsA one-time configuration step is needed for each cloud-based HTR service after you install Handprint on a computer.  This step supplies Handprint with credentials to access the services.  In each case, the same command format is used:handprint-aSERVICENAMECREDENTIALSFILE.jsonSERVICENAMEmust be one of the service names printed by runninghandprint -l, andCREDENTIALSFILE.jsonmust have one of the formats discussed below.  When you run this command, Handprint copiesCREDENTIALSFILE.jsonto a private location, and thereafter uses the credentials to accessSERVICENAME.  (The private location is different on different systems; for example, on macOS it is~/Library/Application Support/Handprint/.)  Examples are given below.MicrosoftMicrosoft's approach to credentials in Azure involves the use ofsubscription keys.  The format of the credentials file for Handprint needs to contain two fields:{"subscription_key":"YOURKEYHERE","endpoint":"https://ENDPOINT"}The value"YOURKEYHERE"will be a string such as"18de248475134eb49ae4a4e94b93461c", and it will be associated with an endpoint URI such as"https://westus.api.cognitive.microsoft.com".  To obtain a key and the corresponding endpoint URI, visithttps://portal.azure.comand sign in using your account login.  (Note: you will need to turn off browser security plugins such as Ad Block and uMatrix if you have them, or else the site will not work.)  Once you are authenticated to the Azure portal, you can create credentials for using Azure's machine-learning services.  Some notes all about this can be found in theHandprint project Wiki pages on GitHub.Once you have obtained both a key and an endpoint URI, use a text editor to create a JSON file in the simple format shown above, save that file somewhere on your computer (for the sake of this example, assume it ismyazurecredentials.json), and use the command discussed above to make Handprint copy the credentials file:handprint-amicrosoftmyazurecredentials.jsonGoogleCredentials for using a Google service account need to be stored in a JSON file that contains many fields.  The overall format looks like this:{"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"}Getting one of these is summarized in the Google Cloud docs forCreating a service account, but more explicit instructions can be found in theHandprint project Wiki pages on GitHub.  Once you have downloaded a Google credentials file from Google, save the file somewhere on your computer (for the sake of this example, assume it ismygooglecredentials.json), and use the command discussed above to make Handprint copy the credentials file:handprint-agooglemygooglecredentials.jsonAmazonAmazon credentials for AWS take the form of two alphanumeric strings: akey idstring and asecret access keystring.  In addition, the service needs to be invoked with a region identifier.  For the purposes of Handprint, these should be stored in a JSON file with the following format:{"aws_access_key_id":"YOUR_KEY_ID_HERE","aws_secret_access_key":"YOUR_ACCESS_KEY_HERE","region_name":"YOUR_REGION_NAME_HERE"}Getting this information is, thankfully, a relatively simple process for Amazon's services. Instructions can be found in theHandprint project Wiki pages on GitHub.  Once you have obtained the two alphanumeric keys and a region identifier string, use a text editor to create a JSON file in the simple format shown above, save that file somewhere on your computer (for the sake of this example, assume it ismyamazoncredentials.json), and usetwocommands to make Handprint copy the credentials file for the two different Amazon services currently supported by Handprint:handprint-aamazon-textractmyamazoncredentials.json
handprint-aamazon-rekognitionmyamazoncredentials.jsonUsagePlease see thedocumentation sitefor detailed documentation for Handprint.Getting helpIf you find an issue, please submit it inthe GitHub issue trackerfor this repository.ContributingI would be happy to receive your help and participation with enhancing Handprint!  Please visit theguidelines for contributingfor some tips on getting started.If you plan on doing any development on Handprint, you may want to install the package dependencies listed inrequirements-dev.txt, e.g., using a command such as the following. This will install dependencies necessary to runpytest.python3 -m pip install -r requirements-dev.txtLicenseSoftware produced by the Caltech Library is Copyright © 2018–2022 California Institute of Technology.  This software is freely distributed under theBSD 3-clause OSI license.  Please see theLICENSEfile for more information.Authors and historyMike Huckadesigned and implemented Handprint beginning in mid-2018.AcknowledgmentsThevector artworkof a hand used as a logo for Handprint was created byKevinfor theNoun Project.  It is licensed under the Creative CommonsCC-BY 3.0license.Handprint benefitted from feedback from several people, notably from Tommy Keswick, Mariella Soprano, Peter Collopy and Stephen Davison.Handprint makes use of numerous open-source packages, without which it would have been effectively impossible to develop Handprint with the resources we had.  I want to acknowledge this debt.  In alphabetical order, the packages are:aenum– advanced enumerations for Pythonappdirs– module for determining appropriate platform-specific directoriesboltons– package of miscellaneous Python utilitiesboto3– Amazon AWS SDK for Pythonbun– a set of basic user interface classes and functionsCommonPy– a collection of commonly-useful Python functionsfastnumbers– number testing and conversion functionsgoogle-api-core, google-api-python-client, google-auth, google-auth-httplib2, google-cloud, google-cloud-vision, googleapis-common-protos, google_api_python_client– Google API librariesgrpcio– open-source RPC frameworkhumanize– make numbers more easily readable by humansimagesize– determine the dimensions of an imageipdb– the IPython debuggermatplotlib– a Python 2-D plotting librarynumpy– package for scientific computing in PythonPillow– a fork of the Python Imaging Libraryplac– a command line argument parserpsutil– cross-platform package for process and system monitoring in PythonPyMuPDF– Python bindings for the MuPDF rendering libraryrequests– an HTTP library for PythonRich– library for writing styled text to the terminalsetuptools– library forsetup.pySidetrack– simple debug logging/tracing packageStringDist– library for calculating string distancestextdistance– compute distances between text sequencesurllib3– Python HTTP libraryValidator Collection– Python library of 60+ commonly-used validator functionswheel– setuptools extension for building wheelsFinally, I am grateful for computing & institutional resources made available by the California Institute of Technology.