![\"Screencast](\"https://raw.githubusercontent.com/caltechlibrary/handprint/master/.graphics/handprint-screencast.gif\")
\n![](\"https://raw.githubusercontent.com/caltechlibrary/handprint/master/.graphics/noun_Hand_733265.png\")
\n=========\n\nA Python program to apply different handwritten text recognition services to images of handwritten text pages, and produce an annotated image (and optionally more) showing the text recognized.\n\n[](http://shields.io)\n[](https://choosealicense.com/licenses/bsd-3-clause)\n[](http://shields.io)\n[](https://github.com/caltechlibrary/handprint/stargazers)\n[](https://data.caltech.edu/records/1268)\n\n\n\n\ud83c\udfc1 Log of recent changes\n-----------------------\n\n_Version 1.0.1_: This version adds instructions for installing from PyPI and fixes a bug writing files downloaded from URLs.\n\n_Version 1.0.0_: This is a sufficiently complete version of Handprint that can finally be called a version 1.0. Changes compared to version 0.10.0 include: new way to provide credential files, new default output (in which results from different services are placed side-by-side in a single large image), new command-line arguments, parallel execution, and more.\n\nThe file [CHANGES](CHANGES.md) contains a more complete change log that includes information about previous releases.\n\nTable of Contents\n-----------------\n\n* [Introduction](#-introduction)\n* [Installation](#-installation)\n * [Install Handprint on your computer](#-install-handprint-on-your-computer)\n * [Add cloud service credentials](#-add-cloud-service-credentials)\n* [Usage](#\ufe0e-usage)\n * [Supported HTR/OCR services](#supported-htrocr-services)\n * [Input files and URLs](#input-files-and-urls)\n * [Annotated output images](#annotated-output-images)\n * [Extended results](#extended-results)\n * [Other options](#other-options)\n * [Command line options summary](#command-line-options-summary)\n* [Known issues and limitations](#known-issues-and-limitations)\n* [Getting help](#-getting-help)\n* [Contributing](#-contributing)\n* [License](#-license)\n* [Authors and history](#-authors-and-history)\n* [Acknowledgments](#\ufe0e-acknowledgments)\n\n\u2600 Introduction\n-------------\n\n![](\"https://raw.githubusercontent.com/caltechlibrary/handprint/master/.graphics/glaser-example-google.jpg\")
\n\nHandprint (_**Hand**written **P**age **R**ecognit**i**o**n** **T**est_) is a small project to examine the performance of alternative services for [handwritten text recognition (HTR)](https://en.wikipedia.org/wiki/Handwriting_recognition). It was developed for use with documents from the [Caltech Archives](http://archives.caltech.edu), but it is completely independent and can be applied to any images of text documents. Services supported include Google's [Google Cloud Vision API](https://cloud.google.com/vision/docs/ocr), Microsoft's Azure [Computer Vision API](https://azure.microsoft.com/en-us/services/cognitive-services/computer-vision/), Amazon's [Textract](https://aws.amazon.com/textract/) and [Rekognition](https://aws.amazon.com/rekognition/), and more. Among other features, Handprint can generate versions of the input images with recognized text overlaid over them, to visualize the results. The image at right shows an example.\n\nHandprint can work with individual images, directories of images, and URLs pointing to images on remote servers. In addition to producing annotated images as output, it can output the raw results from an HTR service as JSON and text files. Handprint can use multiple processor threads for parallel execution.\n\n\u273a Installation and configuration\n-------------------------------\n\nThe instructions below assume you have a Python interpreter installed on your computer; if that's not the case, please first install Python and familiarize yourself with running Python programs on your system.\n\nHandprint includes several adapters for working with cloud-based HTR services from Amazon, Google, and Microsoft. Installing Handprint requires a both installing a copy of Handprint on your computer and supplying your copy with credentials for accessing the cloud services you want to use.\n\n\n### \u24f5 _Install Handprint on your computer_\n\nThe following is probably the simplest and most direct way to install the latest release of Handprint on your computer:\n```sh\nsudo python3 -m pip install handprint --upgrade\n```\n\nAlternatively, you can install the latest version directly from the GitHub repository using the following command:\n```sh\nsudo python3 -m pip install git+https://github.com/caltechlibrary/handprint.git --upgrade\n```\n\n\n### \u24f6 _Add cloud service credentials_\n\nA 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:\n```sh\nhandprint -a SERVICENAME CREDENTIALSFILE.json\n```\n\n_SERVICENAME_ must be one of the service names printed by running `handprint -l`, and `CREDENTIALSFILE.json` must have one of the formats discussed below. When you run this command, Handprint will copy `CREDENTIALSFILE.json` to a private location, and thereafter uses the credentials to access _SERVICENAME_. (The private location is different on different systems; for example, on macOS it is `~/Library/Application Support/Handprint/`.) Examples are given below.\n\n\n#### Microsoft\n\nMicrosoft's approach to credentials in Azure involves the use of [subscription keys](https://docs.microsoft.com/en-us/azure/cognitive-services/computer-vision/vision-api-how-to-topics/howtosubscribe). The format of the credentials file for Handprint just needs to contain a single field:\n\n```json\n{\n \"subscription_key\": \"YOURKEYHERE\"\n}\n```\n\nThe value of \"YOURKEYHERE\" will be a string such as `\"18de248475134eb49ae4a4e94b93461c\"`. To obtain a key, visit [https://portal.azure.com](https://portal.azure.com) and 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 about this can be found in the [Handprint project Wiki pages on GitHub](https://github.com/caltechlibrary/handprint/wiki/Getting-Microsoft-Azure-credentials). Once you have obtained a key, 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 is `myazurecredentials.json`), and use the command discussed above to make Handprint copy the credentials file:\n```sh\nhandprint -a microsoft myazurecredentials.json\n```\n\n#### Google\n\nCredentials for using a Google service account need to be stored in a JSON file that contains many fields. The overall format looks like this:\n\n```\n{\n \"type\": \"service_account\",\n \"project_id\": \"theid\",\n \"private_key_id\": \"thekey\",\n \"private_key\": \"-----BEGIN PRIVATE KEY-----anotherkey-----END PRIVATE KEY-----\\n\",\n \"client_email\": \"emailaddress\",\n \"client_id\": \"id\",\n \"auth_uri\": \"https://accounts.google.com/o/oauth2/auth\",\n \"token_uri\": \"https://oauth2.googleapis.com/token\",\n \"auth_provider_x509_cert_url\": \"https://www.googleapis.com/oauth2/v1/certs\",\n \"client_x509_cert_url\": \"someurl\"\n}\n```\n\nGetting one of these is summarized in the Google Cloud docs for [Creating a service account](https://cloud.google.com/docs/authentication/), but more explicit instructions can be found in the [Handprint project Wiki pages on GitHub](https://github.com/caltechlibrary/handprint/wiki/Getting-Google-Cloud-credentials). 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 is `mygooglecredentials.json`), and use the command discussed above to make Handprint copy the credentials file:\n```sh\nhandprint -a google mygooglecredentials.json\n```\n\n\n#### Amazon\n\nAmazon credentials for AWS take the form of two alphanumeric strings: a _key id_ string and a _secret access key_ string. 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:\n\n```json\n{\n \"aws_access_key_id\": \"YOUR_KEY_ID_HERE\",\n \"aws_secret_access_key\": \"YOUR_ACCESS_KEY_HERE\",\n \"region_name\": \"YOUR_REGION_NAME_HERE\"\n}\n```\n\nGetting this information is, thankfully, a relatively simple process for Amazon's services. Instructions can be found in the [Handprint project Wiki pages on GitHub](https://github.com/caltechlibrary/handprint/wiki/Creating-credentials-for-use-with-Amazon-Rekognition). 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 is `myamazoncredentials.json`), and use _two_ commands to make Handprint copy the credentials file for the two different Amazon services currently supported by Handprint:\n```sh\nhandprint -a amazon-textract myamazoncredentials.json\nhandprint -a amazon-rekognition myamazoncredentials.json\n```\n\n\n\u25b6\ufe0e Usage\n-------\n\nHandprint comes with a single command-line interface program called `handprint`. Here is a screen cast to give a sense for what it's like to run Handprint. Click on the following image:\n\n\n \n
![\"Example](\"https://raw.githubusercontent.com/caltechlibrary/handprint/master/.graphics/clara-barton-page.png\")
\n\n\n### _Input files and URLs_\n\nAfter credentials are installed, running Handprint _without_ the `-a` option will invoke one or more services on files, directories of files, or URLs pointing to files. More specifically, inputs can be supplied in any of the following ways:\n\n* One or more directory paths or one or more image file paths on the local disk, which will be interpreted as images (either individually or in directories) to be processed\n* One or more URLs, which will be interpreted as network locations of image files to be processed\n* If given the `-f` option (`/f` on Windows), a file containing either image paths or image URLs to be processed\n\nHandprint considers each input path individually, and determines when an input is a URL based on whether the given path begins with letters followed by the characters `:/` followed by the rest of the path (e.g., `http://some/other/characters`). If any of the input images are URLs, Handprint will first download the images found at the URLs to a directory indicated by the option `-o` (`/o` on Windows). If a destination directory is not provided via `-o`, the current working directory where Handprint is running is used instead.\n\nNo matter whether files or URLs, each input should be a single image of a document page in which text should be recognized. Handprint reads a number of common formats: JP2, JPEG, PNG, GIF, BMP, and TIFF. However, for simplicity and maximum compatibility with all cloud services, **Handprint always converts all input files to PNG** if they are not already in that format, before sending them to a service. Handprint also resizes images if necessary, to the smallest size accepted by any of the services invoked if an image exceeds that size. (For example, if service A accepts files up to 10 MB in size and service B accepts files up to 5 MB, all input images will be resized to 5 MB before sending them to A and B, even if A could accept a higher-resolution image.)\n\nNote that providing URLs on the command line can be problematic due to how terminal shells interpret certain characters, and so when supplying URLs, it's usually better to store the URLs in a file in combination with the `-f` option (`/f` on Windows).\n\n\n### _Annotated output images_\n\nBy default, Handprint will create a single output file for each input file. This file will be have the suffix `.all-results.png` and contain an annotated version of the results for each service invoked, tiled in a _N_×_N_ grid fashion to produce one (big) output image. Here is a sample output image to illustrate:\n\n\n![\"Example](\"https://raw.githubusercontent.com/caltechlibrary/handprint/master/.graphics/all-results-example.jpg\")
\n
![](\"https://raw.githubusercontent.com/caltechlibrary/handprint/master/.graphics/caltech-round.png\")
\n \n