Clara OCR Advanced User's Manual

[Main] [FAQ] [Glossary] [Tutorial] [User's Manual] [Developer's Guide]

Welcome. Clara OCR is a free OCR, written for systems supporting the C library and the X Windows System. Clara OCR is intended for the cooperative OCR of books. There are some screenshots available at http://www.claraocr.org/.

This documentation is extracted automatically from the comments of the Clara OCR source code. It is known as "The Clara OCR Advanced User's Manual". It's currently unfinished. First-time users are invited to read "The Clara OCR Tutorial". Developers must read "The Clara OCR Developer's Guide".

CONTENTS

1. Welcome to Clara OCR
2. A first OCR project
3. Complex procedures
4. Reference of the Clara GUI
5. Reference of the menus
6. Reference of command-line switches
7. AVAILABILITY
8. CREDITS

1. Welcome to Clara OCR

Clara is an optical character recognition (OCR) software, a program that tries to identify the graphic images of the characters from a scanned document, converting their digital images to ASC, ISO or other codes.

The name Clara stands for "Cooperative Lightweight chAracter Recognizer".

Clara offers two revision interfaces: a standalone GUI and and a web interface, able to be used by various different reviewers simultaneously. Because of this feature Clara is a "cooperative" OCR (it's also "cooperative" in the sense of its free/open status and development model).

1.1 Early historical notes

For some years now we have tested and used OCR softwares, mainly for old books. Popular OCR softwares (those bundled with scanners) are useful tools. However, OCR is not a simple task. The results obtained using those programs vary largely depending on the the printed document, and, for most texts we're interested on, the results are really poor or even unusable. In fact, it's not a surprise that many digitalization projects prefer not to use OCR, but typists only.

For a programmer, it is somewhat intuitive that OCR could achieve good results even from low quality texts, when an add-hoc approach is used, focusing one specific book (for instance). Within this approach, OCR becomes a matter of finding one software adequate for the texts you're trying to OCR, or perhaps develop a new one. So a free and easy to customize OCR (on the source code level) would be a valuable resource for text digitalization projects.

Dealing with graphics is not among our main occupations, but after analysing many scanned materials, we began to write some simple and specialized recognition tools. More recently (in the third quarter of 1999) a simple X interface linked to a naive bitmap comparison heuristic was written. From that prototype, Clara OCR evolved. Since then, many new ideas from various persons helped to make it better.

1.2 Design notes

It's not a bad idea to enumerate some principles that have driven Clara OCR development. They'll make easier to understand the features and limitations of the software (these principles may change along time).

1. Clara is an OCR for printed texts, not for handwritten texts.

2. Clara was not designed to be used to OCR one or two single pages, but to OCR a large number of documents with the same graphic characteristics (font, size, etc). So it can take advantage of a fine (and perhaps expensive) training. This will be tipically the case when OCRing an entire book.

3. We chose not support directly multiple graphic formats, but only Jeff Poskanzer's raw PBM and PGM. Non-PBM/PGM files will be read through filters.

4. Clara OCR wants to be a tool that makes viable the sum and reuse of human revision effort. Because of this, on the OCR model implemented by Clara, training and revision are one same thing. The revision is a sum of punctual and independent acts and alternates with reprocessing steps along a refinement process.

5. The Clara GUI was implemented and behaves like a minimalistic HTML viewer. This is just an easy and standard way to implement a forms interface.

6. We have tried to make the source code portable across platforms that support the C library and the Xlib. Clara has no special provision to be ported to environments that do not support the Xlib. We avoided to use a higher level graphic environment like Motif, GTK or Qt, but we do not discourage initiatives to add code to Clara OCR adapt or adapt better to these or other graphic environments.

7. We generally try to make the code efficient in terms of RAM usage. CPU and disk usage (for session files) are less prioritary.

1.3 Supported Alphabets

Clara OCR focuses the Latin Alphabet ("a", "b", "c", ...), used by most European languages, and the decimal digits ("0", "1", "2", ...), but we're trying to support as many alphabets as possible.

To say that Clara OCR supports a given alphabet means that Clara OCR

(a) is able to be trained from the keyboard for the symbols of that alphabet, eventually applying some transliteration from that alphabet to latin. For instance, when OCRing a greek text, if the user presses the latin "a" key (assuming that the keyboard has latin labels), Clara is expected to train the current symbol as "alpha".

(b) knows the vertical alignment of each letter of that alphabet, for instance, knows that the bottom of an "e" is aligned at the baseline;

(d) contains code to help avoiding common mistakes, like recognizing "e" as "c", "l" as "1", etc.

To say that Clara OCR supports a given alphabet does not necessarily mean that Clara OCR

(a) knows some particular encoding (ISO-8859-X, Unicode, etc) for that alphabet;

(b) contains or is able to use fonts for that alphabet to display the OCR output on the PAGE (OUTPUT) window.

Even ignoring the standard encondings for one given alphabet (e.g. ISO-LATIN-7 for Greek), Clara eventually will be able to produce output using TeX macros, like {\Alpha}.

1.4 Clara vs the others

Clara differs from other OCR softwares in various aspects:

1. Most known OCRs are non-free and Clara is free. Clara focus the X Windows System. Clara offers batch processing, a web interface and supports cooperative revision effort.

2. Most OCR softwares focus omnifont technology disregarding training. Clara does not implement omnifont techniques and concentrate on building specialized fonts (some day in the future, however, maybe we'll try classification techniques that do not require training).

3. Most OCR softwares make the revision of the recognized text a process totally separated from the recognition. Clara pragmatically joins the two processes, and makes training and revision one same thing. In fact, the OCR model implemented by Clara is an interactive effort where the usage of the heuristics alternates with revision and visual fine-tuning of the OCR, guided by the user experience and feeling.

4. Clara allows to enter the transliteration of each pattern using an interface that displays a graphic cursor directly over the image of the scanned page, and builds and maintains a mapping between graphic symbols and their transliterations on the OCR output. This is a potentially useful mechanism for documentation systems, and a valuable tool for typists and reviewers. In fact, Clara OCR may be seen as a productivity tool for typists, instead of a typical OCR.

5. Most OCR softwares are integrated to scanning tools offerring to the user an unified interface to execute all steps from scanning to recognition. Clara does not offer one such integrated interface, so you need a separate software (e.g. SANE) to perform scanning.

6. Most OCR softwares expect the input to be a graphic file encoded in tiff or other formats. Clara supports only raw PBM/PGM.

1.5 The requirements

Clara OCR will run on a PC (386, 486 or Pentium) with GNU/Linux and Xwindows. Clara OCR will hopefully compile and run on a PC with any unix-like operating system and Xwindows. Currently Clara OCR won't run on big-endian CPUs (e.g. Sparc) nor on systems lacking X windows support (e.g. MS-Windows). Higher-level libraries like Motif, GTK or Qt are not required.

A relatively fast CPU is recommended (300MHz or more). Memory usage depends on the documents, and may range from some few megabytes to various tenths os megabytes The normal operation will create session files on your hard disk, so some megabytes of free disk space are required (a large project may require plents of gigabytes). Clara OCR can read and write gzipped files (see the -z command-line switch).

If you need to build the executable and/or the documentation, then an ANSI C compiler (with some GNU extensions) and a (version 5) perl interpreter are required.

1.6 How to download and compile Clara

For those who need to download and compile the source code (hopefully this will be unnecessary for most users as soon as Clara binary distributions become available), it may be downloaded from http://www.claraocr.org/. It's a compressed tar archive with a name like clara-x.y.tar.gz (x.y is the version number).

The compilation will generally require no more than issue the following commands on the shell prompt:

$ gunzip clara-x.y.tar.gz $ tar xvf clara-x.y.tar $ cd clara-x.y $ make $ make doc

Now you can copy the executable (the file "clara") to some directory of binaries (like /usr/local/bin), and the man page (file "clara.1") to some directory of man pages (like /usr/local/man/man1). By now there is no "make install" to perform these copies automatically.

If some of these steps fail, please try to obtain assistance from your local experts. They will solve most simple problems concerning wrong paths or compiler options. You can also read the subsection "Compilation and startup pitfalls".

1.7 Compilation and startup pitfalls

This subsection is intended to help people that are experiencing fatal errors when building the executable or when starting it. After each error message we'll point out some hints.

Bear in mind that most hints given below are very elementary concerning Unix-like systems. If you have problems, try to read all hints because details explained once are not repeated. If you cannot understand them, please try to ask your local experts, or try to read an introductory book on Unix things. Please don't email questions like these to the Clara developers, except when the hint suggests it.

1. Path-related pitfalls

$ make bash: make: command not found

The shell could not find the "make" utility. Maybe there is no such utility installed on your system, or maybe the path to it is unknown to the shell. You can try to find the "make" utility with a command like

$ find /usr -name make -print

The following command will display the current path:

$ echo $PATH

Remember that on Unix-like systems the environment is per-process. So if you change the PATH variable on the shell prompt within an xterm, this won't affect the other running shells (on the other xterms). Remember that the Unix shells expect to be explicitly informed about which variables must be exported to subprocesses (use "export" in Bourne-like shells and "setenv" on C-like shells).

$ make gcc -I/usr/X11R6/include -g -c gui.c -o gui.o make: gcc: Command not found make: *** [gui.o] Error 127

The make utility could not find the gcc compiler. Check if gcc is installed. If not, check if some other C compiler is installed (for instance, "cc"), and edit the makefile to chage the value of the CC variable.

If you don't know what I'm speaking about, take a look on the directory where the Clara source codes are, and you'll see there a file named "makefile". This file contains the names of the tools to be used and rules to build the Clara executable. It contains also important paths, like those where the system headers (files .h) and libraries can be found. If the names or the paths don't reflect those on your system, you need to edit the makefile accordingly.

$ make gcc -I/usr/X11R6/include -g -c gui.c -o gui.o In file included from gui.c:16: gui.h:12: X11/Xlib.h: No such file or directory make: *** [gui.o] Error 1

The compiler could not find the header Xlib.h. Maybe your system does not include such header, or maybe it is on another directory not explicited on the makefile through the INCLUDE variable.

$ make gcc -o clara clara.o skel.o gui.o mc.o ... /usr/bin/ld: cannot open -lX11: No such file or directory make: *** [clara] Error 1

The linker could not find the X11 library. Maybe your system does not include such library, or maybe it is on another directory not explicited on the makefile through the LIBPATH variable.

2. Compilation pitfalls

$ make gcc -I/usr/X11R6/include -g -c clara.c -o clara.o clara.c:70: parse error before `int' make: *** [clara.o] Error 1

A syntax error on the line 70 of the file clara.c. Double check if the sources were not changed. Try to obtain the sources again. If you're a programmer, try to fix the problem. In any case, report it to claraocr@claraocr.org.

$ make clara.c: In function `process_cl': clara.c:2293: `ZPS' undeclared (first use in this function) clara.c:2293: (Each undeclared identifier is reported only once clara.c:2293: for each function it appears in.) make: *** [clara.o] Error 1

A reference to an undeclared variable. Double check if the sources were not changed. Try to obtain the sources again. If you're a programmer, try to fix the problem. In any case, report it to claraocr@claraocr.org.

3. Runtime pitfalls

$ clara & [1] 1924 bash: clara: command not found

The Clara executable does not exist or is not on the path. Most Unix systems don't include the current directory ("./") on the path, so if you're trying to start Clara from the directory where it was compiled, specify the current directory ("./clara").

$ ./clara & [1] 1922 _X11TransSocketUNIXConnect: Can't connect: errno = 111 cannot connect to X server

Clara could not connect the X server. The X Windows System is a client-server system. The applications (xterm, xclock, etc) connect to a display server (the X server). If the server is not running, clients cannot connect to it. In some cases, it's required to inform explicitly the client about the server it must connect, using the environment variable DISPLAY.

$ ./clara Segmentation fault (core dumped)

If you can reproduce the problem, report it to claraocr@claraocr.org. If you're a programmer and Clara was compiled with the -g option, try a debugger to locate the point of the source code where the segmentation fault happened. Using gdb, it's quite easy:

$ gdb clara (gdb) run

Now try to reproduce the steps that led to the segmentation fault.

2. A first OCR project

Clara OCR is intended to OCR a relatively large collection of pages at once, typically a book. So we will refer the material that we are OCRing as "the book".

Let's describe a small but real project as an example on how to use Clara to OCR one "book". This section is in fact an in-depth tutorial on using Clara OCR. In order to try all techniques explained along this section, please download and uncompress the file referred as "page 143" of Manuel Bernardes Branco Dictionary (Lisbon, 1879), available at http://www.claraocr.org. It's a tarball containing the two text columns (one per file) of that page.

Just to make the things easier, we will assume that the files 143-l.pgm and 143-r.pgm were downloaded to the directory /home/clara/books/MBB/pgm/. We will assume also that the programs "clara", and "selthresh" are on the PATH. Some programs required to handle PBM files (pgmtopbm, pnmrotate and others, by Jef Poskanzer) are also required. These programs can be easily found around there, and are included on most free operating systems.

2.1 Scanning and thresholding

Clara OCR cannot scan paper documents by itself. Scanning must be performed by another program. The Clara OCR development effort is using SANE (http://www.mostang.com/sane) to produce 600 or 300 dpi images. The Clara OCR heuristics are tuned to 600 dpi.

Scanners offer three scanning modes: black-and-white (also known as "bitmap" or "lineart", however the meaning of these words may vary depending on the context), "grayscale" and "color". Clara OCR requires black-and-white or grayscale input. Both black-and-white and grayscale images may be saved in a variety of formats by scanning programs. However, only PBM (for black-and-white) and PGM (for grayscale) formats are recognized. Generally grayscale 600 or 300 dpi will be the best choice, but black-and-white 600 dpi may be good for new, high quality printed materials. If your scanning program do not support the PBM or PGM formats, try to save the images in TIFF format and convert to PBM or PGM using the command tifftopnm. If for some reason the TIFF format cannot be used, choose any other format that preserves all data (don't use "compressing" formats like JPEG), and for which a conversion tool is available, to convert it to PBM or PGM.

Remark: Programs that scan or handle (e.g. rotate) images may sometimes perform unexpected tasks, as applying dithering or reducing algorithms by themselves. An image transformed to become nice or small may be useless for OCR purposes.

Remark: The PBM and PGM formats do not carry the original resolution (dots-per-inch) at which the image was scanned. As some heuristics require that information, Clara OCR expects to be informed about it through the command-line switch -y (so take note of the resolution used).

Grayscale means that each pixel assumes one gray "level", typically from 0 (black) to 255 (white). This is a good choice for scanning old or low-quality printed materials, because it's possible to use specialized programs to analyse the image and choose a "threshold", in such a way that all pixels above that threshold will be considered "white", and all others will be considered black (when scanning in black-and-white mode, the threshold is chosen by the scanning program or by the user). The threshold may be global (fixed for the entire page) or local (vary along the page).

In most cases grayscale will achieve better results. However, as grayscale images are much larger than black-and-white images, 300 dpi (instead of 600 dpi) may be mandatory when using grayscale due to disk consumption requirements.

Remark: Try to limit yourself to the optical resolution oferred by the scanner. Most old scanners are 300 dpi, but the scanning software obtains higher resolutions through interpolation. Newer scanners may be optical 600 dpi or 1200 dpi or more.

Remark: the page 143 of Manuel Bernardes Branco Dictionary that we're using along these tests was scanned using the SANE scanimage command:

scanimage -d microtek2:/dev/sga --mode gray -x 150 -y 210 --resolution 300 > 143.pgm

Thresholding is not the only method for converting grayscale images to black-and-white (such conversion is also called "binarization"), but it's the current method used by Clara OCR. In practice, a too low threshold will brake many symbols on their thin parts, and a too high threshold will link symbols together (in the figure, an "a-i" link and a broken "u").

XX XX XXXXX XXX XXX XXX X XX XX XX XX XX XX XX XX XXXXXXX XX XX XX X XX XX XX XX X XX XX XX XX XXXXX XXXXXXX XX XXXX

It's a hard task to detect broken and linked symbols. The Clara OCR heuristics that handle these cases are incipient, so thresholding must must be carefully performed, in order to not compromise the OCR results. If the printing intensity, the noise level or the paper quality vary from page to page, thresholding must be performed on a per-page basis.

Remark: Now you can try avoid links in segmentation step. Just set "Try avoid links" parameter in Tune tab. (Normal values <=1)

The four thresholding methods currently avaliable are: manual (global), histogram-based (global), classification-based (local), classification-based (global).

2.2 Manual and histogram-based (global)

Histogram-based thresholding is the default method. It computes automatically a thresholding value based on the distribution of grayshades. To use it, just enter the TUNE tab and select (it's selected by default) the "use histogram-based global thresholder". To make a try, load a PGM image and press OCR or ask the Segmentation OCR step.

Remark: You can correct the automatic-detected threshold with "Threshold factor" in Tune tab.

A global thresholding value can be manually specified. This corresponds to the "use manual global thresholder" entry. The choice of the thresholding value is performed through a visul interface called "instant thresholding". To use it, load one PGM image and select the "Instant thresholding" entry (Edit menu). Then use '<', '>', '+' and '-' to change the thresholding value. When ok, press ESC. Note that the selected value will be applied only when the segmentation step runs.

2.3 Classification-based (local)

Global thresholding does not address those cases where the printing intensity (or paper properties) vary along one same page. Local thresholding methods are required on such cases. Clara OCR implements a classification-based local (per-symbol) thresholder. Saying that it's classification-based means that the OCR engine is used to choose the threshold. In other words, the threshold chosen is that for which the classifier successfully recognized the symbol (in fact, this is a brute-force approach).

The local binarizer can be manually applied at any symbol. To do so, load one PGM page and click any symbol directly on the PAGE tab. Two thresholding values will be chosen. The pixels found to be "black" for each one are painted "black" (smaller value) and "gray" (larger value). At this moment, it's possible to add the thresholded symbol as a pattern (just press the key corresponding to its transliteration). Remember that this thresholder relies on the classifier, so if the OCR is not trained, you'll get no benefit.

Two versions of the local binarizer were developed, a "weak" one and a "strong" one. The "weak" one just tries to change the threshold on those symbols not successfully classified using the default threshold. The "strong" one (unfinished) also tries to criticize locally the segmentation results. By default, the weak version is used. To try the strong one, check the corresponding checkbox at the TUNE tab.

Remark: As an alternative, use the "Balance" feature + global thresholding.

2.4 Classification-based (global)

Clara OCR includes a simple threshold selection script to compute global best thresholds based on classification results. Let's try it on our 2-page book. Just create a directory, cd to it and run the selthresh script informing the resolution and the names of the images:

$ cd /home/clara/books/BC $ mkdir pbm $ cd pbm $ selthresh -y 300 -l 0.45 0.55 ../pgm/*pgm selthresh: scaling 2 times Best thresholds: 143-l.pgm 0.49 143-r.pgm 0.51

In this case, selthresh will require around 4 minutes to complete on a 500MHz CPU. For larger collections of pages, selthresh may take much longer to complete (hours or days). If needed, the execution can be safely interrupted using Control-C (it's ok to shutdown the machine while selthresh is running). The execution can be safely restarted from the point where it was interrupted typing again the same command: