User guide

Glyphwise reads text from scanned documents, photos of pages and PDFs, and returns plain text, structured JSON with word positions, or a searchable PDF. It runs locally; nothing is sent anywhere.

What is in this folder

Supported inputs: PDF (text layers are read directly; scanned pages are recognized), TIFF (multi-page), PNG, JPEG, JPEG 2000, JBIG2, GIF, BMP, PNM.

Licence file

Glyphwise is unlocked by a licence file (glyphwise.lic) that you receive with your purchase. Save it, unchanged, in one of these places; the programs look for it in this order:

1. the file named with --license FILE on the command line;
2. the file named by the GLYPHWISE_LICENSE environment variable;
3. glyphwise.lic in the same folder as glyphwise.exe / glyphwise-server.exe (for the C API: the folder of your program);
4. %APPDATA%\Glyphwise\glyphwise.lic (Linux/macOS: ~/.config/glyphwise/glyphwise.lic).

glyphwise --license-info shows which licence is in use, what it covers and when it expires. The check is done on your computer; Glyphwise never contacts a server. The file is plain text and may be opened, but any change to it makes it invalid. A licence lists the parts it covers: ocr (the glyphwise command line), server (the HTTP service) and sdk (the C API).

Without a valid licence the programs run in evaluation mode and say so: glyphwise reads at most 3 pages per run, glyphwise-server returns at most 3 pages per request and stops answering after 25 requests until it is restarted, and the C API returns at most 3 pages per call and stops after 25 calls per process. Recognition quality is the same as in the licensed product.

Command line

glyphwise models\line.bin scan.pdf                          plain text to the console
glyphwise models\line.bin page.png --text page.txt          plain text to a file
glyphwise models\line.bin page.png --json page.json         words with positions and confidence
glyphwise models\line.bin a.tif b.png --pdf searchable.pdf  scans -> one searchable PDF
glyphwise models\line.bin scan.tif --hocr scan.hocr         hOCR (XHTML) for digitization tools
glyphwise models\line.bin scan.tif --alto scan.xml          ALTO v4 XML for library/archive systems
glyphwise models\line.bin scan.tif --review check.tsv       low-confidence words to proof-read
glyphwise models\line.bin scan.pdf --force-ocr              recognize a PDF even if it has a text layer
glyphwise models\line.bin scan.pdf --gpu                    use an NVIDIA (CUDA) or OpenCL GPU if present

Several files can be given at once; they are processed in parallel. --pdf-dpi (default 300) sets the physical page size the scans are placed at in the PDF; set it to the scanning resolution if known.

HTTP service

glyphwise-server --model models\line.bin --addr 127.0.0.1:8080
curl --data-binary @scan.pdf "http://127.0.0.1:8080/ocr"              (JSON)
curl --data-binary @scan.pdf "http://127.0.0.1:8080/ocr?format=text"  (plain text)
curl --data-binary @scan.pdf "http://127.0.0.1:8080/ocr?format=alto"  (ALTO XML; also format=hocr)

The service has no authentication or encryption. Keep it on the loopback address (the default) or behind a proxy that adds both.

C API

glyphwise_open(model_path) returns a handle, glyphwise_recognize(handle, bytes, len, format) returns a string (format 0 = JSON, 1 = text, 2 = hOCR, 3 = ALTO) to release with glyphwise_free_string, and glyphwise_close releases the handle. On failure functions return NULL and glyphwise_last_error() says why.

If your application keeps the licence somewhere other than the places listed under "Licence file", call glyphwise_set_license_file(path) or glyphwise_set_license_text(contents) before glyphwise_open; both return 1 when the licence is accepted. glyphwise_license_status() returns 1 when licensed and 0 in evaluation mode, and glyphwise_license_info() returns the details as text.

GPU

--gpu uses CUDA when an NVIDIA driver and the CUDA runtime compiler (NVRTC) are installed, otherwise OpenCL, otherwise it falls back to the CPU and says so. Results are the same either way; the GPU is faster on large batches.

Accuracy notes

• Best on printed documents scanned at 200–300 dpi. Very small text (< 8 px x-height) and heavy noise reduce accuracy.
• Phone photos of pages work: pages turned sideways or upside down are set upright (also from the photo's orientation tag), a page photographed at an angle on a darker surface is straightened, and shadows and uneven light are evened out. For best results photograph the whole page, flat, in even light, against a darker background. Word boxes always refer to the original photo. --no-prepare turns these repairs off.
• Handwriting is supported but much harder; expect noticeably more errors than on print.
• JSON gives a confidence per word (0–1); low values mark words worth checking. --review FILE lists the words below 0.8 (--review-threshold) with page, line, box and the line's text, ready for a spreadsheet.