%% LyX 1.1 created this file.  For more info, see http://www.lyx.org/.
%% Do not edit unless you really know what you are doing.
\documentclass[a4paper,english]{book}
\usepackage[T1]{fontenc}
\usepackage[latin1]{inputenc}
\usepackage{fancyhdr}
\pagestyle{fancy}
\usepackage{babel}
\usepackage{color}
\usepackage{makeidx}
\makeindex

\makeatletter

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LyX specific LaTeX commands.
\providecommand{\LyX}{L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\@}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Textclass specific LaTeX commands.
 \newenvironment{lyxlist}[1]
   {\begin{list}{}
     {\settowidth{\labelwidth}{#1}
      \setlength{\leftmargin}{\labelwidth}
      \addtolength{\leftmargin}{\labelsep}
      \renewcommand{\makelabel}[1]{##1\hfil}}}
   {\end{list}}
 \newenvironment{lyxcode}
   {\begin{list}{}{
     \setlength{\rightmargin}{\leftmargin}
     \raggedright
     \setlength{\itemsep}{0pt}
     \setlength{\parsep}{0pt}
     \normalfont\ttfamily}%
    \item[]}
   {\end{list}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% User specified LaTeX commands.
\pagestyle{fancy}
\renewcommand{\chaptermark}[1]{\markboth{#1}{}}
\renewcommand{\sectionmark}[1]{\markright{\thesection\ #1}}
\fancyhead{}
\fancyfoot{}
\fancyhead[LE,RO]{\bfseries\thepage}
\fancyhead[LO]{\bfseries GOCR\ API\ Documentation}
\fancyhead[RE]{\bfseries \leftmark}
\renewcommand{\headrulewidth}{0.5pt}
\addtolength{\headheight}{0.5pt}
\fancypagestyle{plain}{%
   \fancyhead{} 
   \renewcommand{\headrulewidth}{0pt} %
}

\makeatother
\begin{document}
\pagenumbering{roman} 


\title{\underbar{\Huge libGOCR API}\\
\underbar{\Huge GNU }\\
\underbar{\Huge Optical }\\
\underbar{\Huge Character }\\
\underbar{\Huge Recognition}{\normalsize  }}


\bigskip{}
\author{Bruno Barberi Gnecco \emph{brunobg}@\emph{sourceforge.net}}

\maketitle
GOCR is \copyright 2000 Jrg Schulenburg. All rights reserved.

GOCR API and this manual are \copyright 2001 Bruno Barberi Gnecco.
All rights reserved.

\tableofcontents{}


\chapter{Introduction}

\pagenumbering{arabic} \setcounter{page}{1}GOCR is an attempt to fulfill
a large gap in the Linux world: the lack of an OCR program. At the
time the project started, there were some available, but their quality
was very deceptive. Licensed using the LGPL license, it can be used
by anyone.

As of the 0.3.x versions, it was decided that gocr, until then a stand-alone
program, should become a library. I (Bruno) decided then to be responsible
for it, and this is the result. I hope I made a good work, or at least
something that's quite usable.

This documentation covers three different views on the API, which
are the layers it's subdivided. First, there's the GOCR frontend API
itself, which allows you to write a program that uses the library
to do some OCRing. It's a small set of functions that allow you to
decide what operations should be done, and in what order, and to tune
some of the attributes of the library. Second, there's the module
interface. GOCR library let you write new pieces of code or to complement
the existing ones without recompiling; we call these pieces \emph{modules},
but many other programs call them plugins. It's just nomenclature.
This API is fully independent of the first one, and has a completely
different functionality. Last, but not least, is the internal GOCR
API. You don't need to know what it is, or even that it exists, but
it's what joins the two first API's, all the modules you're using,
the program you wrote, and makes it all work together, or not. It's
GOCR itself, and you only want to know about it if you want to develop
GOCR.

With the API, there is the possibility of writing wrappers, or bindings,
to other languages. C++ and Python are on the list, and soon will
be available.

This document was written not only as a reference, but as a tutorial
too; the language is light, a handful of jokes are spread around,
etc. The code is well documented, and automatic documentation, man
pages, etc, can be generated using Doxygen.


\section{About this document}

This file documents libgocr. Unless you are developin frontends or
modules, you shouldn't be reading it. It's filled with technical information
and documentation of functions, and just the last phrase probably
made 50\% of whomever read it immediately close the window <grin>.
In case this file is not what you are looking for, you can take a
look at the {}``Brief introduction'' documentation (which is not
written yet, so you may read section\ref{introduction to modules}). 

Take notice that, while we try to keep this file uptodated, it's inevitable
to forget something and impossible to keep the latest improvements
in code in synchrony with this file. Since the file is intended to
be a user's guide and not a reference guide, it's not so bad. Always
keep in mind that the automatically generated documentation (with
Doxygen) is more accurate (but less complete). 


\section{Authors and contact information}

GOCR project was created by Jrg Schulenburg \\
<\texttt{Joerg.Schulenburg@physik.uni-magdeburg.de}>. 

It's currently hosted at Sourceforge: \texttt{http://jocr.sourceforge.net}
(yes, with a 'j').

Other developers joined the effort, and several people send patches,
bug reports and ideas. 

The API was designed and this manual was written by Bruno Barberi
Gnecco <\texttt{brunobg@geocities.com}> 


\section{Version information/development plan}

This manual contains the 0.7.1 API standard. 0.7.x versions are development
versions, which will be used until a stable, usable and complete version
is reached. By that time, version number will be upgraded to 0.9.
The 0.9.x versions will be for debugging and testing, because minor
corrections are to be expected. Once it's good enough to be widely,
publicly used, it will be 1.0.

So, in other words, while it's not 1.0, you can't blame us that it
sucks and doesn't work. After that, it's OK. :-)


\subsection{Current status}

The frontend API is pratically stable, but new additions will come.
A new image loading system was designed and implemented (0.7.1). A
wrapper to a GUI system is being designed, so modules can interact
with the user.

The internal API is being done solidly, to avoid future problems.
I'm taking special care to make sure that it's a good system, and
will support the rest well. There's a real bunch of fprintf's to the
inevitable debugging. ;-)

The module API is not stable. It's being developed. The general idea,
however, is here.


\chapter{Frontend API}

GOCR API is a simple set of functions that let you easily write a
frontend. You are responsible for what modules you are calling. A
module is simply a piece of code that performs a certain kind of function;
it will be explained more detailedly below.


\section{Initializing and finalizing}

The header that contains the prototypes, etc is \texttt{gocr.h}.

It's mandatory that you call two functions when using GOCR. They are:

\begin{lyxcode}
int~gocr\_init\index{gocr\_init}~(~int~argc,~char~{*}{*}argv~);

void~gocr\_finalize\index{gocr\_finalize}~(~void~);
\end{lyxcode}
The first function parses the arguments your program got, setups all
the internal structures of GOCR, initializes all that it's needed
to run. It must be called before any other GOCR function. It returns
0 if GOCR could be correctly initialized, -1 otherwise. This is a
constant in the API: if a function returns -1, it failed. You should
always test the return values. GOCR also outputs to stderr what was
the problem.

At the end of your program, or when you don't intend to use GOCR anymore,
you must call the second function. 

Currently, GOCR accept the following arguments: none yet.


\section{Attributes\index{Attributes}\label{attributes}}

After calling \texttt{gocr\_init()}, the next thing to do is to set
the attributes of the library. These are parameters that let you tune
several aspects of the API. They can be set and read using these two
functions:

\begin{lyxcode}
int~gocr\_setAttribute\index{gocr\_setAttribute}~(~gocr\_AttributeType~t,~void~{*}value~);

void~{*}gocr\_getAttribute\index{gocr\_getAttribute}~(~gocr\_AttributeType~t~);
\end{lyxcode}
The first function sets the attribute \texttt{t} with a value \texttt{value}.
The second returns the current value of attribute \texttt{t}. The
list of attributes currently supported and the values you can pass
to them is:

\vspace{0.3cm}
{\centering \begin{tabular}{|l|l|p{5cm}|p{0.75cm}|}
\hline 
{\small Attribute type}&
{\small Value}&
{\small Function}&
{\small Default }\\
\hline
\hline 
{\small LIBVERSION} &
{\small string}&
{\small Returns a string containing the library version. This is a
read-only attribute.}&
{\small none}\\
\hline 
{\small VERBOSE}  &
{\small an integer from 0 to 3}&
\parbox[t]{5cm}{{\small Sets the level of output: }\\
{\small 0 nothing; }\\
{\small 1 error messages; }\\
{\small 2 warnings and errors;}\\
{\small 3: everything. Used mostly for debugging.}}&
{\small 1}\\
\hline 
{\small BLOCK\_OVERLAP}&
{\small boolean}&
{\small If true, allows two blocks to overlap}&
{\small FALSE}\\
\hline 
{\small NO\_BLOCK} &
{\small boolean}&
{\small If true, and no block was found, creates a block covering
whole image.}&
{\small TRUE}\\
\hline
\hline 
CHAR\_OVERLAP&
{\small boolean}&
{\small If true, allows characters to overlap}&
{\small TRUE}\\
\hline 
CHAR\_RECTANGLES&
{\small boolean}&
{\small If true, all characters are selected as rectangles}&
{\small TRUE}\\
\hline 
FIND\_ALL &
{\small boolean}&
{\small If true, first find all characters, saving in memory, and
then process.}&
{\small FALSE}\\
\hline 
{\small ERROR\_FILE}&
{\small (FILE {*}) variable}&
{\small Sets the error messages output file.}&
{\small stderr}\\
\hline 
{\small PRINT}       &
{\small an integer from 0 to 6}&
\parbox[t]{5cm}{What is printed:{\small }\\
{\small 0: only data bit (. = white, {*} = black)}\\
{\small 1: marked bits (mark1 + 2{*}mark2 + 4{*}mark3)}\\
{\small 2: data and marked bits: if white, a\ldots{}h;if black, marked
bits->A\ldots{}H}\\
{\small 3: only isblock bit (. = is not block, {*} = is block)}\\
{\small 4: only ischar bit (. = is not char, {*} = is char)}\\
{\small 5: complete byte, in hexadecimal}\\
{\small 6: complete byte, in ASCII}}&
{\small 0}\\
\hline
\hline 
{\small PRINT\_IMAGE} &
{\small boolean}&
{\small If true, gocr\_print{*} functions will print the image associated
with the structure.}&
{\small 1}\\
\hline
\end{tabular}\par}
\vspace{0.3cm}

Boolean values are either GOCR\_TRUE or GOCR\_FALSE. \emph{Do not
use TRUE or FALSE, since they are defined with different values by
Unicode.}

Some module packages may require certain attributes; take a look at
their documentation. They may automatically set these attributes,
so don't be stubborn and override. Certain functions of libgocr may
lock some attributes, to avoid chaos.


\section{Images\index{Images}}

If the purpose of your program isn't opening an image and processing
it to turn into some kind of text, you are reading the wrong document
;-). GOCR currently works this way: you open an image, let the modules
process it, and close it. This can be done any number of times you
want. Image loading and closing is done using:

\begin{lyxcode}
int~~gocr\_imageLoad\index{gocr\_imageLoad}(~const~char~{*}filename,~void~{*}data~);

void~gocr\_imageClose\index{gocr\_imageClose}~(~void~);
\end{lyxcode}
well, they are pretty clear. \texttt{gocr\_imageLoad()} returns 0
in case of success, -1 otherwise. If you try to open an image while
there's one already open, \texttt{gocr\_imageLoad()} will return -1.

Image loading is part of a module, and \texttt{gocr\_imageLoad()}
may be overriden. Libgocr provides a default one, which is capable
of opening the most common image types. It accepts, as the second
argument, one of these:

\begin{lyxlist}{00.00.0000}
\item [GOCR\_BW]Convert to black and white.
\item [GOCR\_GRAY]Convert to grayscale.
\item [GOCR\_COLOR]Convert to RGB (24 bit) color.
\item [GOCR\_NONE]Do not convert.
\end{lyxlist}

\section{Modules\label{api-modules}}


\subsection{Introduction to modules\index{modules!introduction}\label{introduction to modules}}

There are three things that could be called a \emph{module} in GOCR,
so here's a thorough specification:

\begin{itemize}
\item the module\index{modules!type} type. There are many different types
of modules, as explained below. For example, there's a imageFilter
type, that may be used to do clean the image dust, for example, and
a charRecognizer, that is intended to get a small image of a single
character and find out which one it is. When I refer to \emph{module},
I usually mean an instance of a module type.
\item the function \index{modules!function}. Each module type may have
several different functions. For example, imageFilter module may have
a function to increase contrast, another to clean dust, and a third
to remove coffee mug stains. These are called \emph{module functions},
or simply \emph{functions}.
\item the file, which ends with .so, and is a shared object. In our terminology,
this is a \emph{shared object file}\index{shared object file}, or
(same thing different name) a \emph{module package}\index{modules!package}.
This file contains the module functions, which may be of different
module types.
\end{itemize}
There are several module types\index{modules!types}:

\vspace{0.3cm}
{\centering \begin{tabular}{|c|p{4cm}|p{4cm}|}
\hline 
Module type&
Function&
Examples\\
\hline
\hline 
imageLoader &
Loads an image.&
Load images. There can be only oneimage loader. \\
\hline 
imageFilter&
Filter the image.&
Dust removal, etc.\\
\hline 
blockFinder &
Find blocks, i.e., groups of similar dataand add information of its
content.&
Find pictures, find columns of text,find mathematical expressions.\\
\hline 
charFinder &
Frame characters, and add informationof its content.&
Frame characters, font recognition.\\
\hline 
charRecognizer&
Recognize the framed characters.&
Italic, bold, greek specialiazed OCR.\\
\hline 
contextCorrection &
Try to recognize the still unrecognized characters.&
Spell checker, ligature checker.\\
\hline 
outputFormatter&
Output data to some format and file.&
HTML output, \LaTeX\ output.\\
\hline
\end{tabular}\par}
\vspace{0.3cm}

All of the modules (except imageLoader) may be composed of several
different functions, which may be in different module packages. The
following sections explain how to load modules, set their order, and
run them.


\subsection{Loading shared object files\index{shared object files!loading}\index{modules!loading!files} }

The first thing to do, when you want to add some function to a module,
is to open its file. All the work is done internally by the library,
and you just need to call:

\begin{lyxcode}
int~gocr\_moduleLoad\index{gocr\_moduleLoad}~(~char~{*}filename~);
\end{lyxcode}
If \texttt{filename} is just the filename, libgocr will search for
the file in the following directories:

\begin{itemize}
\item A colon-separated list of directories in the user's LD\_LIBRARY path
environment variable. 
\item The list of libraries specified in /etc/ld.so.cache. 
\item /usr/lib, followed by /lib.
\item The directory libgocr was installed in.
\end{itemize}
This function returns a module id (that can be used to set attributes,
see below) if the operation was successful, -1 otherwise.


\subsection{Setting module attributes\label{module attributes}\index{modules!attributes}}

Some module packages allow you to set their attributes. You can do
this using this function:

\begin{lyxcode}
int~gocr\_moduleSetAttribute\index{gocr\_moduleSetAttribute}~(~int~id,~void~{*}a,~void~{*}b~);
\end{lyxcode}
\begin{description}
\item [id]is the module package id
\item [a,~b]fields are passed directly to the module package, refer to
its documentation to know how to use them. 
\end{description}
The function returns -1 in case of some internal error, or the value
returned by the module package.


\subsection{Loading module functions\index{modules!loading!functions} }

Since a shared object file may have several different module functions,
and you may be interested only in one of them, GOCR enables you to
decide exactly which module function should be run, and the order
they do that. The functions that load module functions are:

\begin{lyxcode}
int~gocr\_functionAppend\index{gocr\_functionAppend}~(~gocr\_moduleType~t,~
\begin{lyxcode}
char~{*}functionname,~void~{*}data~);~
\end{lyxcode}
int~gocr\_functionInsertBefore\index{gocr\_functionInsertBefore}~(~gocr\_moduleType~t,~
\begin{lyxcode}
char~{*}functionname,~void~{*}data,~int~id~);~
\end{lyxcode}
int~gocr\_functionDeleteById\index{gocr\_deleteModule}~(~int~id~);
\end{lyxcode}
Module functions are internally saved in a linked list, but you don't
have to know that (so, I shouldn't haven written\ldots{} well, knowledge
is never too much). Let's first see \texttt{gocr\_functionAppend}.
The arguments are: 

\begin{description}
\item [t]the module type, as in the first column of the table above.
\item [functionname]this is the name of the module function you want to
load. Refer to the documentation that should come with the shared
file object.
\item [data]this is a parameter that will be passed to the function when
it's called. It's a pointer, that you are responsible for allocation.
Do not free it until you call \texttt{gocr\_functionDelete} or \texttt{gocr\_finalize}.
Being a void pointer, you can pass anything to it. If you need more
than one argument, use a structure. Read the module function docs
to know what you can do with this.
\end{description}
\texttt{gocr\_functionAppend} returns -1 in case of error, or a non-negative
number if successful. This number is the function's ID. It can be
used if you want to do access this function.

\texttt{gocr\_functionDeleteById} is straight forward. Its sole argument
is the id of the module function you want to delete. As usual, returns
-1 if error, 0 on success.

Last, but not least, there's \texttt{gocr\_functionInsertBefore}.
It works like its counterpart \texttt{gocr\_functionAppend}, but there's
a difference: it allows you to insert a function in the middle of
the list. Good for the absent minded ones. The first three arguments
are the same of \texttt{gocr\_functionAppend}, and the fourth argument
is the id of the function that is be just after the position you want
to insert the new function. So, if you want to insert a function in
the first position, you should pass the id of the current first position
function. Hm. Read it again, and it should become clearer. ;-)

The order of the inclusion is very important, since it will determine
the order of running. So, if you add a module function to recognize
cyrilic text before latin text and try to decode a latin text, it'll
be much slower than if you did vice-versa. Always sort the functions
by the probability of their usefullness.

Note that you don't need to specify in which shared object file the
function is; GOCR does it automatically for you. 


\subsection{Running modules\index{modules!running} }

Now that you did everything, there remains only to run the modules.
GOCR allows you to run them all at once, module by module, or module
function by module function:

\begin{lyxcode}
int~gocr\_runModuleFunction\index{gocr\_runModuleFunction}~(~int~id~);~

int~gocr\_runModuleType\index{gocr\_runModuleType}~(~gocr\_moduleType~t~);

int~gocr\_runAllModules\index{gocr\_runAllModules}~(~void~);
\end{lyxcode}
The functions are simple to use. \texttt{gocr\_runAllModules} runs
all the modules, taking care of how it's done. For example, charFinder
module functions must be called one for each block. It's not a trivial
for(), and this is the recommended way to do it. It follows the order
that you provided when you appended and inserted the module functions,
as described in the last section.

\textcolor{magenta}{The two other functions are currently not working,
due to design issues.}

\texttt{gocr\_runModuleType} runs a specific module. There's no care
taken of the internal data, which must be manually updated. It may
be useful if you want just to apply some filters to the image, for
example, or if you want to do a different implementation of the existing
\texttt{gocr\_runAllModules}.

Last there's \texttt{gocr\_runModuleFunction}. It runs just one module
function, and also doesn't take care of internal data. If you want
to use it, you probably know what you are doing.

All functions return 0 on success, -1 on error.


\subsection{Closing modules\index{modules!closing}}

It's possible to close a module. \texttt{gocr\_finalize} automatically
takes care of closing all modules, but if you have some special reason
to close a module, you can do it. Libgocr automatically deletes all
the module functions of this module. Just call:

\begin{lyxcode}
void~gocr\_moduleClose\index{gocr\_moduleClose}~(~int~id~);
\end{lyxcode}
And that's it.


\section{A simple example}

Ok, time to do something concrete. 

Usually examples are neat little programs, heavily commented, that
do something completely useless. Since this is a tradition, I was
unable to refrain using it. Unfortunadly GOCR can't do {}``Hello
World'', and so I had to imagine something equally uninteresting,
and I used the filter example I just told you.

\begin{lyxcode}
{\small /{*}~filter.c}{\small \par}

~{\small {*}~A~simple~program,~that~applies~a~filter~to~a}{\small \par}

~{\small {*}~image,~and~outputs~the~image.}{\small \par}

~{\small {*}/}{\small \par}

~{\small }{\small \par}

{\small \#include~<gocr.h>}{\small \par}

{\small int~main(int~argc,~char~{*}{*}argv)~\{~}{\small \par}
\begin{lyxcode}
{\small /{*}~Initialize~the~library~{*}/}{\small \par}

{\small if~(~gocr\_init(argc,~argv)~==~-1~)}{\small \par}
\begin{lyxcode}
{\small exit(1);}{\small \par}
\end{lyxcode}
{\small /{*}~Set~output~to~zero~{*}/}{\small \par}

{\small if~(~gocr\_setAttribute(VERBOSE,~0)~==~-1~)}{\small \par}
\begin{lyxcode}
{\small exit(1);~}{\small \par}
\end{lyxcode}
{\small /{*}~Load~a~shared~object~file~{*}/}{\small \par}

{\small if~(~gocr\_moduleLoad(''modulename.so'')~==~-1~)}{\small \par}
\begin{lyxcode}
{\small exit(1);}{\small \par}
\end{lyxcode}
{\small /{*}~Load~a~module~function~that~cleans~dust~{*}/}{\small \par}

{\small if~(~gocr\_functionAppend(imageFilter,~''cleanDust'',~NULL)~!=~-1~)~}{\small \par}
\begin{lyxcode}
{\small exit(1);}{\small \par}
\end{lyxcode}
{\small /{*}~Load~a~module~function~that~outputs~an~image~{*}/}{\small \par}

{\small if~(~gocr\_functionAppend(outputFormatter,~''imageOutput'',~}~\\
~{\small ~~~~~~~~~~~~~~~~~~''output.jpg'')~!=~-1~)~}{\small \par}
\begin{lyxcode}
{\small exit(1);}{\small \par}
\end{lyxcode}
{\small /{*}~Load~the~image~{*}/}{\small \par}

{\small if~(~gocr\_imageLoad(''image.jpg'',~(void~{*})GOCR\_NONE)~)}{\small \par}
\begin{lyxcode}
{\small exit(1);}{\small \par}
\end{lyxcode}
{\small /{*}~Run~all~modules.~{*}/}{\small \par}

{\small gocr\_runAllModules();}{\small \par}

{\small /{*}~Ok,~say~good~bye~{*}/}{\small \par}

{\small gocr\_finalize();}{\small \par}
\end{lyxcode}
{\small \}}{\small \par}
\end{lyxcode}
The usual comments, now. Notice that two module functions were loaded.
The first cleans `dust' of the image, i.e., those nasty pixels that
are black in what should be a perfectly white background. The second
module outputs the image after the cleaning. Notice how this hypothetical
module function takes as argument the name of the output file. 

When you call \texttt{gocr\_finalize()}, it takes care of unloading
shared objects, deleting module functions, closing the image, etc.
Don't worry with hundreds or close()s, free()s, etc.


\section{Serious tweaking}

\textcolor{magenta}{This is under serious review}

Although libgocr has several module types, you don't have to use them
all, and is free to abuse of the architecture. In fact, only doing
so you'll be able to take full advantage of libgocr's power.

Let's say, for example, that you are writing an algorithm that skips
the segmentation process, finding characters directly. At first, it
seems that such algorithm would be completely incompatible with libgocr's
structure; but it's not. Here are some possible solutions:

\begin{itemize}
\item use the algorithm as a blockFinder module, and do not use any charFinder
or charRecognizer modules. This way you work with the entire image.
\item use the algorithm as a charFinder module. It allows the separation
of the image in blocks, and you can treat it block as a whole image.
It's also 100\% compatible with other charFinder modules.
\end{itemize}
\indent You may think that this is an ugly hack, but it's not. I'll
explain why: since the architecture of libgocr is modular, and the
modules can be used independently (with certain exceptions), it's
not only OK to do it, it's designed to be used this way. The module
types had to be given names, but it's as wrong to think that a charFinder
module should only frame characters as to think that charRecognizer
can only recognize usual characters, and not musical notes. 

Something else: do not get stuck with \texttt{gocr\_runAllModules()}.
Since you may change interpretation of module types, it may be interesting
to run them in a different way, skip some, run some twice, allow feedback,
etc.

The question that arises now is: why not make the modules objetcs,
similarly to what is done with block types (see \ref{block types})? 

\begin{itemize}
\item To do so, the module type objects (MTO) would need to have their own
\texttt{run()} methods. Since some modules use information of their
predecessors (charFinder uses blockFinder, charRecognizer uses charFinder),
MTOs would have to be attached to each other, making a mess.
\item There could be an unnecessary multiplication of MTOs. It would be
very easy to decide that {}``I don't like that MTO, because the method
names are too big'', and write a new MTO with the same functionality. 
\item Compatibility. Current module types are 100\% compatible with each
other, sharing common structures and variables. Since they are part
of libgocr, you are assured that your module will be compatible with
any other module, something that would not happen with MTOs.
\item Current architecture was carefully designed to work well and in a
broad range of situations, and abusing of it is legal.
\end{itemize}
If you need to create a new module type, it's likely to be a very
specific situation, where you do not care about compatibility. 


\section{GUI wrapper - message system}

Note: this is being designed currently, so changes may happen at any
time.

In order to let modules communicate with users, libgocr implemens
a simple GUI wrapper: the module can open a window with some of the
most used widgets (text fields, buttons, etc), and get the result
directly. The GUI is \emph{very} high level, so the implementation
can be done in any API you are using to code your frontend. In short,
the GUI wrapper is just a message system, allowing the modules to
communicate with users, ask questions, etc. The GUI should take care
of how widgets are arranged in the window.

Most functions are documented only in the source code while the architecture
is not stable yet. Check the automatic documentation.


\subsection{Registering your callbacks}

The first thing to do is to register your own callbacks, so whenever
a module calls a function it's passed to you. The following function
does it:

\begin{lyxcode}
int~gocr\_guiSetFunction~(~gocrGUIFunction~type,~void~{*}func~);
\end{lyxcode}
Where \texttt{func} is a pointer to the callback function (converted
to \texttt{void {*}}), and \texttt{type} is one of the following:

\begin{tabular}{|c|c|}
\hline 
Type&
Arguments\\
\hline
\hline 
gocrBeginWindow&
( wchar\_t {*}title, wchar\_t {*}{*}buttons )\\
\hline 
gocrEndWindow&
\\
\hline 
gocrDisplayCheckButton&
\\
\hline 
gocrDisplayImage&
\\
\hline 
gocrDisplayRadioButtons&
\\
\hline 
gocrDisplaySpinButton&
\\
\hline 
gocrDisplayText&
\\
\hline 
gocrDisplayTextField&
\\
\hline
\end{tabular}


\subsection{Problems to solve}

Previews would be nice, but would need interaction, so pointers to
functions. it would add complexity, and I am not sure how portable
it would be.

Add some way to let the gui know what attributes can be set.


\chapter{Modules API}

This chapter is intended to those that want to write a module. Please
take a look at section \ref{api-modules} first. 

It's necessary to include the file \texttt{gocr\_module.h}, which
defines all the necessary stuff. Unless you need some function declared
there, there's no need to include \texttt{gocr.h}.


\section{Modules in brief\index{modules!predefined functions}}

There are some things to say about modules that apply to all types.

Upon loading a shared object file, GOCR tries to call a function with
the following prototype:

\begin{lyxcode}
int~gocr\_initModule~(~void~);
\end{lyxcode}
so, if you need to initialize some data, just declare this function.
If the function returns something different than 0, it's assumed that
some error occured, and the module package is imediately closed.

Similarly, when a module package is closed, GOCR tries to call

\begin{lyxcode}
void~gocr\_closeModule~(~void~);
\end{lyxcode}
which you can use to free memory, etc.%
\footnote{You may be wondering about the \_init and \_fini symbols, used by
libdl. GOCR doesn't use libdl directly, since libdl is not portable.
To avoid conflicts and undefined behavior, do not define \_init or
\_fini. The same is valid for any other library similar to libdl,
such as shl\_load, LoadLibrary, load\_add\_on, etc.
}

Besides these two functions, there's a third function, also optional,
that may be used to set attributes in real time:

\begin{lyxcode}
int~gocr\_setAttribute~(~char~{*}field,~char~{*}data~);
\end{lyxcode}
The first argument, \texttt{field}, is the attribute name. The second,
\texttt{data}, is the value that the attribute should be set to.

Note that all the three functions are optional, and do not need to
be declared. You may use whichever you need (e.g., you may declare
\texttt{gocr\_closeModule} without \texttt{gocr\_initModule}).

Besides these functions, there are variable that your code \emph{must}
export, containing information about your module:

\begin{lyxcode}
gocrModuleInfo~gocr\_externalModuleData;
\end{lyxcode}
which is a structure of the following format:

\begin{lyxcode}

\end{lyxcode}

\subsection{Module Development Kit\index{modules!module development kit}}

To load shared object files, GOCR uses libltdl, which is included
in libtool. It's a bit less straight forward than working with libdl
directly, but in return it's much more portable.

If you never worked with libraries, libdl, or just don't have a clue
of what I'm talking about, and {}``just want to write this module
to recognize handwriting, man, that's all'', don't worry. The developers
of GOCR have spent countless hours to make your life easier%
\footnote{That is, I spent some time I had nothing to do developing methods
to let you spend some time you have nothing to do developing.
}. You don't even have to know anything of the confusing world of libraries,
shared, static, cryptic gcc arguments, weird makefiles and confusing
configures.

All you have to do is write your code, and get the module development
kit (MDK) from http://jocr.sourceforge.net/download.html. This package
is a whole bunch of files that take care of the libtool, automake,
autoconf, and every other little pesty thing that would add hours
of work, while you tried to figure out what the hell did you forget
in Makefile.am. Or configure.in. See, that's what I'm talking about.

The MDK comes with it's own documentation, which you should read before
you start coding. All you have to do, however, is to edit the \texttt{module-setup}
script, fill some of its fields properly, and run it. It will create
all necessary files, and all you have to do is run \texttt{./configure}
to create the Makefiles.

That's it. If you think it's too much work, do all the rest yourself
;). Note that to use the MDK you need the automake/autoconf packages
installed in your computer. They are available at your closest GNU
repository. Anyway, as I said, MDK is properly documented, so read
it.


\subsection{Packaging\index{modules!packaging} and releasing\index{modules!releasing}}

Here are some guidelines to help you release your module:

\begin{itemize}
\item \textbf{Write documentation}. This is a complete must, because if
you don't write it, people won't know what module functions are available
in the package, and won't be able to use your module, and then I think
you'd missing the point. Be sure to explain what each module function
does, and what arguments it may receive.
\item It's a good idea to add a prefix to the module functions of a module
package. For example: foo\_clean(), foo\_recognize(). 
\item Do not duplicate code. If someone already did what you want, don't
replicate it in your code. By the other hand, don't ask to the user
to have several libraries of module packages; if you need only a function,
have it in your own code (respect the software license).
\item There's already a easy way to package: type \texttt{make dist}. It
will generate the appropriate tar file.
\item Read the Software Release Practice HOWTO.
\item Take a look at existing modules. If you are having some problem, chances
are that by peeking at other's work you can find a solution. This
is one of the most important laws of software coding. Be nice and
add a thanks note to your documentation.
\end{itemize}

\section{imageLoader\index{module!image}}

This module is a special one; every good rule must have a exception.
The differences between imageLoader and the other modules are:

\begin{itemize}
\item There may be only one function in the image loader module at a time,
which makes sense, since there may be only one open image at a time.
\item The imageLoader function may be accessed directly by calling \texttt{gocr\_imageLoad()}.
\item This module is not called by the \texttt{gocr\_run{*}Modules()} functions.
\end{itemize}
libGOCR has a default image loader module, which currently opens the
following images types%
\footnote{Subject to availability of certain libraries. See the README file.
}:

\begin{itemize}
\item .pnm 
\item .pbm 
\item .pgm 
\item .ppm
\item .jpg/.jpeg 
\item .gif 
\item .bmp 
\item .tiff 
\item .png
\end{itemize}

\subsection{Image\index{image} and pixels\index{pixels}}

When implementing libGOCR, the question arised: should we use grayscale?
Is black and white enough? What about colors? We decided to use black
and white only, since it seemed more than enough, and saved memory.
Later, it was realized that color would be essential to some recognition
systems --- specially if you want to use libGOCR to recognize something
other than plain text. The design was changed, and now libGOCR support
these image types%
\footnote{Pixel size is in bytes, and is valid only for the x86 architecture
(although if you have a decent compiler and sizeof(char)==1 then the
results are likely to be the same o others).
}:

\vspace{0.3cm}
{\centering \begin{tabular}{|c|c|c|}
\hline 
Type&
Symbol &
Pixel size\\
\hline
\hline 
Black \& white&
GOCR\_BW&
1\\
\hline 
Grayscale&
GOCR\_GRAY&
2\\
\hline 
Color&
GOCR\_COLOR&
4\\
\hline 
User-defined&
GOCR\_OTHER&
-\\
\hline
\end{tabular}\par}
\vspace{0.3cm}

You may only access the image indirectly. 

The whole point of using an image is that you can access pixels individually,
so, after several conferences and hundreds of emails, we decided that
yes, we would have pixels in our images. Ok, the joke was not funny.

To support the different image types, a slight hack was done in the
gocrImageData structure, which contains the individual pixel data
(section \ref{create image type} has info about it, but you definitely
don't need to know). In fact, you only won: you can access any image
type just as if it's the type you want; that is, suppose the image
loaded is in color, but you want to work in black and white: you can.
The functions are:

\begin{lyxcode}
void~gocr\_imagePixelSetBW\index{gocr\_imagePixelSetBW}~(~gocrImage~{*}image~
\begin{lyxcode}
int~x,~int~y,~unsigned~char~data~);~
\end{lyxcode}
unsigned~char~gocr\_imagePixelGetBW\index{gocr\_imagePixelGetBW}~(~gocrImage~{*}image,~
\begin{lyxcode}
int~x,~int~y~);~
\end{lyxcode}
void~gocr\_imagePixelSetGray\index{gocr\_imagePixelSetGray}~(~gocrImage~{*}image,~
\begin{lyxcode}
int~x,~int~y,~unsigned~char~data~);~
\end{lyxcode}
unsigned~char~gocr\_imagePixelGetGray\index{gocr\_imagePixelGetGray}~(~gocrImage~{*}image,~
\begin{lyxcode}
int~x,~int~y~);~
\end{lyxcode}
void~gocr\_imagePixelSetColor\index{gocr\_imagePixelSetColor}~(~gocrImage~{*}image,~
\begin{lyxcode}
int~x,~int~y,~unsigned~char~data{[}3{]}~);~
\end{lyxcode}
unsigned~char~{*}gocr\_imagePixelGetColor\index{gocr\_imagePixelGetColor}~(~gocrImage~{*}image,~
\begin{lyxcode}
int~x,~int~y~);
\end{lyxcode}
\end{lyxcode}
Examples\index{pixel!examples}:

\begin{lyxcode}
if~(~gocr\_imagePixelGetBW(img,0,0)~==~GOCR\_WHITE~)
\begin{lyxcode}
gocr\_pixelPixelSetBW(img,0,0,GOCR\_BLACK);
\end{lyxcode}
~

for~(~i~=~0;~i~<~img->width;~i++~)
\begin{lyxcode}
for~(~j~=~0;~j~<~img->height;~j++~)
\begin{lyxcode}
if~(~gocr\_imagePixelGetGray(img,i,j)~>~threshold~)
\begin{lyxcode}
gocr\_imagePixelSetBW(img,i,j,~GOCR\_WHITE);
\end{lyxcode}
else
\begin{lyxcode}
gocr\_imagePixelSetBW(img,i,j,~GOCR\_BLACK);
\end{lyxcode}
\end{lyxcode}
\end{lyxcode}
\end{lyxcode}
The only thing to note is that, if you provide (x,y) coordinates out
of bounds, the functions will return 0, which is also a valid value
for a pixel.

Each pixel has three fields that may be used as flags. They are boolean
variables, and to access them use:

\begin{lyxcode}
int~gocr\_pixelGetMark1\index{gocr\_pixelGetMark}~(~gocrImage~{*}image,~int~x,~int~y~);~

int~gocr\_pixelSetMark1\index{gocr\_pixelSetMark}~(~gocrImage~{*}image,~int~x,~int~y,~
\begin{lyxcode}
char~value~);~
\end{lyxcode}
int~gocr\_pixelGetMark2\index{gocr\_pixelGetMark}~(~gocrImage~{*}image,~int~x,~int~y~);~

int~gocr\_pixelSetMark2\index{gocr\_pixelSetMark}~(~gocrImage~{*}image,~int~x,~int~y,~
\begin{lyxcode}
char~value~);~
\end{lyxcode}
int~gocr\_pixelGetMark3\index{gocr\_pixelGetMark}~(~gocrImage~{*}image,~int~x,~int~y~);~

int~gocr\_pixelSetMark3\index{gocr\_pixelSetMark}~(~gocrImage~{*}image,~int~x,~int~y,~
\begin{lyxcode}
char~value~);
\end{lyxcode}
\end{lyxcode}
They are pretty clear, and return -1 in case of error.


\subsection{The module}

The \texttt{imageLoader} module has the following prototype:

\begin{lyxcode}
int~gocr\_imageLoaderFunction~(~const~char~{*}filename,~
\begin{lyxcode}
void~{*}data~);
\end{lyxcode}
\end{lyxcode}
which, of course, may be named whatever you want. It's directly accessible
by the user (by calling \texttt{gocr\_imageLoad\index{gocr\_imageLoad}}),
and you can use the \texttt{data} field to pass arguments. 

GOCRlib provides a default image loader, which handles the most common
formats, and can convert images to any of the GOCRlib supported types
(GOCR\_BW, GOCR\_GRAY, GOCR\_COLOR) by using one of these symbols
as argument. You should use GOCR\_BW whenever you don't need extra
information, since it's likely to take much less memory than the others.

\textcolor{magenta}{It can be accessed with gocr\_moduleAppend/etc
by using {}``default'' as argument. etc}


\subsection{Creating your own image type\index{image type}\label{create image type}}

This is not currently supported. It may be taken out, since C is unlikely
to let us do it easily.

If you need to create a special type, here's how to do it. It's not
recommended that you do it, for the following reasons:

\begin{itemize}
\item it's likely to be incompatible with current modules.
\item blabla
\end{itemize}
What you need to do is quite simple. Declare your pixel like this:

\begin{lyxcode}
struct~mypixel~\{\index{gocrPixel}
\begin{lyxcode}
unsigned~char~pad~:~1;~/{*}~pad~pixel~{*}/

unsigned~char~mark1~:~1;~/{*}~user~defined~marker~1~{*}/~

unsigned~char~mark2~:~1;~/{*}~user~defined~marker~1~{*}/~

unsigned~char~mark3~:~1;~/{*}~user~defined~marker~1~{*}/~

unsigned~char~isblock~:~1;~/{*}~is~part~of~a~block?~{*}/~

unsigned~char~ischar~:~1;~/{*}~is~part~of~a~character?~{*}/~

unsigned~char~private1:~1;~/{*}~internal~field.~{*}/~

unsigned~char~private2:~1;~/{*}~internal~field.~{*}/~~\\


/{*}~your~data~goes~here~{*}/
\end{lyxcode}
\};~

typedef~struct~mypixel~MyPixel;
\end{lyxcode}
You should name your data field \texttt{value}.

More: struct size, etc.


\section{imageFilter}

It my be interesting to apply some filters to the image, to remove
dust, etc. The functions of this module will get the image and apply
the filter to it.

Prototype is

\begin{lyxcode}
int~gocr\_imageFilterFunction~(~gocrImage~{*}image,~void~{*}v~);
\end{lyxcode}
You can work freely with the image, and apply any filters you desire;
remember that modules that were not written by you may be used too,
so do not apply a filter that changes the image data (gradient, laplacian,
Fourier transform, etc). As a special note, do not create (complete)
copies of the data, since it's likely to be big (expect a few megabytes
for the image size).

\textcolor{magenta}{todo: document application of filters to blocks
of data, which may be transformations, etc.}


\section{blockFinder\index{blockFinder}}

The objective of this module type is to divide the image in a number
of blocks. A \emph{block}\index{blocks} is a set of pixels that are
part of the original image, whose contents are all of the same type.
Examples: a picture, a text column, a mathematical expression, a title.

You must take care to avoid recognizing what should be only one block
into more than one. Sometimes that's perfectly fine: for example,
if a picture is recognized as two blocks, as long as they don't intersect
each other, the only price to pay is to have two image files saved
instead of only one; or if a text column is divided in half, along
the horizontal, the output is likely to not take notice. But if the
column is divided along the vertical, you may have a bad output. It's
easier to say than to do, but a warning never hurts.

The prototype of a blockFinder function is:

\begin{lyxcode}
void~gocr\_blockFinder~(~gocrImage~{*}img,~void~{*}v~);
\end{lyxcode}

\subsection{Block types\index{blocks!types}\label{block types}}

Besides finding each block, you should try to recognize what kind
of information that block carries. This will make the work of subsequent
modules much easier, and will improve the speed of the processing.

GOCR automatically defines three types of blocks:

\vspace{0.3cm}
{\centering \begin{tabular}{|c|}
\hline 
Block type\\
\hline 
TEXT\\
\hline 
PICTURE\\
\hline 
MATH\_EXPRESSION\\
\hline
\end{tabular}\par}
\vspace{0.3cm}

\noindent but you can define new types, as explained below. The default
is TEXT. 

The block types are objects, which all derive from a common parent,
\texttt{gocrBlock}. This allows any module to access the block, regardless
of its type. This is what allows you to create new block types on
the fly. To do that, you must first define the \texttt{struct} of
your new block type, which must be in the following format:

\begin{lyxcode}
struct~newblocktype~\{
\begin{lyxcode}
gocrBlock~b;

/{*}~other~fields~{*}/
\end{lyxcode}
\};
\end{lyxcode}
It's absolutely necessary that the first field of your structure be
\texttt{gocrBlock b}. This is what allows to cast your structure to
a simple \texttt{gocrBlock} (If you are wondering why the hell I didn't
use C++ instead of C, these are the reasons: it's easier to use C
from C++ than the opposite; I have much more experience with C than
C++; there are several people that program in C but not in C++; the
use of C as an OO language, although slightly obfuscated, has proven
to be possible and used in successful projects, such as GTK; C++ name
mangling makes it more difficult to write modules, and is not supported
yet by libtool).

You must register your block type\index{blocks!type!registering},
to make GOCR aware of its existance. To do that, use the following
function:

\begin{lyxcode}
blockType~gocr\_blockTypeRegister\index{gocr\_blockTypeRegister}~(~char~{*}name~);
\end{lyxcode}
This function takes the \texttt{name} of your new block type, registers
it, and returns a non negative number, which is the block type id\index{blocks!type!id},
or -1 if some error occurred. This id should be saved, to provide
a quick way to check what is the block type. Alternatively, you can
use:

\begin{lyxcode}
blockType~gocr\_blockTypeGetByName\index{gocr\_blockTypeGetByName}~(~char~{*}name~);
\end{lyxcode}
which returns the id of a already registered block type, or -1 if
none was found. Since this function is kind of slow, as it must compare
the string given to every other block type name registered, it's a
good idea to save the id in a variable. Last, a convenience:

\begin{lyxcode}
const~char~{*}gocr\_blockTypeGetNameByType~(~gocrblockType~t~);
\end{lyxcode}
given the block type, returns its name. Do not free this string.


\subsection{Finding blocks}

Once you find a block, you have to notify GOCR:

\begin{lyxcode}
int~gocr\_blockAdd\index{gocr\_blockAdd}~(~gocrBlock~{*}b~);
\end{lyxcode}
You are responsible for filling the \texttt{x0}, \texttt{x1}, \texttt{y0},
\texttt{y1} and \texttt{t} fields of the block structure, and \emph{only}
those (well, if you fill anything else nothing will happen, you'll
just be wasting processor time). You can pass the address of a derived
block type to it. The function returns 0 if OK, -1 if error (if the
block type isn't registered, it's considered an error). If two blocks
overlap, and the BLOCK\_OVERLAP flag is set to 0, the function returns
-2.%
\footnote{In the future, it will be possible to have blocks of any format, using
a system similar to the used in characters currently. The problems
are two: outputFormatter, and how to save the data without memory
waste. 
}


\subsection{Blocks are more than frames\index{blocks!paradigm}}

The blockFinder module is really half of the core of GOCR. It's responsible
to setup everything to make the recognition itself a simple (ahn,
simpler) task. It should, therefore, do all that it can in order to
make the next two modules perform a simple, linear operation. 

Here's a description of what the module function should do for the
three basic block types:


\subsubsection{Text block\index{blocks!text!description}}

\textcolor{magenta}{This structure will probably be severely changed.}

The text block structure is:

\begin{lyxcode}
struct~gocrtextblock~\{~\index{gocrTextBlock}
\begin{lyxcode}
gocrBlock~b;~~~/{*}~parent;~must~be~first~field~{*}/~

List~~linelist;~
\end{lyxcode}
\};~

typedef~struct~gocrtextblock~gocrTextBlock;
\end{lyxcode}
The \texttt{gocrBlock b}, as described above, is used to perform OO,
and must be the first field. The only other field is a linked list
(see section\ref{linked list}) of text lines:

\begin{lyxcode}
struct~line~\{~\index{gocrLine}
\begin{lyxcode}
int~~x0,~x1;~/{*}~x-boundaries~{*}/

int~~m0,~m1,~m2,~m3;~/{*}~y-boundaries~{*}/

List~~boxlist;~
\end{lyxcode}
\};~typedef~struct~line~gocrLine;
\end{lyxcode}
the \texttt{x0} and \texttt{x1} fields are the vertical boundaries,
and the \texttt{m?} fields are y boundaries:

\vspace{0.3cm}
{\centering \begin{tabular}{|c|c|}
\hline 
Field&
Description\\
\hline
\hline 
m0&
Top boundary\\
\hline 
m1&
Middle\\
\hline 
m2&
Baseline\\
\hline 
m3&
Bottom\\
\hline
\end{tabular}\par}
\vspace{0.3cm}

PICTURE describing them

These fields are of utmost importance to the charRecognizer and charFinder
modules, and their correct determination is crucial. Last is \texttt{boxlist},
which is a list of \texttt{Boxes}, a structure described in the next
section.


\subsubsection{Picture block\index{blocks!picture!description}}

This is a very simple structure:

\begin{lyxcode}
struct~gocrpictureblock~\{~
\begin{lyxcode}
gocrBlock~b;~/{*}~parent;~must~be~first~field~{*}/~

char~{*}name;~
\end{lyxcode}
\}; 

typedef struct gocrpictureblock gocrPictureBlock;

\end{lyxcode}
The structure contains only one field, \texttt{name}, which is the
name of the file to which the picture will be saved.


\subsubsection{Math block\index{blocks!math!description}}

Will use trees. To do.


\subsection{Final considerations}

If no block was found, NO\_BLOCK is set to 1 and \texttt{gocr\_runAllModules()}
was called, GOCR creates a block covering the entire image, and continues
to process the image, calling the charFinder module. If NO\_BLOCK
is set to 0, then \texttt{gocr\_runAllModules} returns -1.


\section{charFinder\index{charFinder}}

This module should parse each block and frame every character found.
It should also provide information about the character, such as if
it's bold or italic, the font, etc. This information is used by the
charRecognizer module functions to quickly check if they will be able
to recognize the character or will just waste processing time. Prototype:

\begin{lyxcode}
int~gocr\_charFinder~(~gocrBlock~{*}b,~void~{*}v~);
\end{lyxcode}
In more detail, what should happen in this module is in this pseudo
code:

\begin{lyxcode}
sweep~the~block

for~each~character~\{
\begin{lyxcode}
find~pertinent~pixels

find~pertinent~attributes
\end{lyxcode}
\}

return~0
\end{lyxcode}
The function should return 0 if it took care of the block, -1 otherwise
(for example, you don't recognize the block type).

The way you sweep the block is completely on yourself, and but it
must be done in a way that the outputFormatter module will understand.
It makes sense. at least when parsing text, to sweep as one would
read it (which means that you are not stuck to left to right, top
to bottom languages). GOCR saves the characters in the order you add
them. \textcolor{red}{Talk about how charRecognizer will receive the
data and add to a linked list, etc. Add some way to override this
default behaviour of adding characters to the list }


\subsection{Getting block information\index{blocks!in charFinder}}

The charFinder module functions are specialized in certain block types,
and thus get extra information from the blockFinder module. They must
be so, otherwise they won't be able to read properly the block structure,
which must be cast to the appropriate type. Your module function is
likely to be something like this:

\begin{lyxcode}
gocrBlockType~your\_block\_type;~\\


int~charFinderFunction~(~gocrBlock~{*}b,~void~{*}v~)~\{
\begin{lyxcode}
switch~(~b->type~)~\{
\begin{lyxcode}
case~TEXT:
\begin{lyxcode}
gocrTextBlock~{*}tb~=~(gocrTextBlock~{*})b;

/{*}~your~code~{*}/

return~0;
\end{lyxcode}
case~YOUR\_BLOCK\_TYPE:
\begin{lyxcode}
your\_block\_struct~{*}mb~=~(your\_block\_struct~{*})b;

/{*}~your~code~{*}/

return~0;
\end{lyxcode}
case~PICTURE:

default:
\begin{lyxcode}
return~-1;
\end{lyxcode}
\end{lyxcode}
\}
\end{lyxcode}
\}
\end{lyxcode}
This hypothetical function can deal with text blocks and a special
block type that was previously registered, but not pictures or anything
else; if you can't process a block, return -1; if you could, return
0. Currently, once a function process a block, GOCR supposes that
it could do all the job there was to be done, and no other function
is called (this is to avoid processing the same block twice and ending
with duplicated information). Future versions may allow partial processing.


\subsection{Delimiting characters\index{characters!creating}}

To delimit a character, GOCR API provides a set of functions that
let you select only the pixels that are part of the character.

First thing to do is to declare that you are starting a new character:

\begin{lyxcode}
int~gocr\_charBegin\index{gocr\_charBegin}~(~void~);
\end{lyxcode}
This function returns -1 in case something is wrong; starting a character
without ending the last one is considered an error. To end a character:

\begin{lyxcode}
int~gocr\_charEnd\index{gocr\_charEnd}~(~void~);
\end{lyxcode}
This function creates an image that is initially filled with the background
color, with all bits unset. This image is big enough to contain all
the pixels selected; these pixels are copied to the new image (only
the data, the info bits are still unset), and will be passed to the
charRecognizer module. \textcolor{red}{gocr\_charEnd automatically
calls the charRecognizer module? Explain FIND\_ALL}

Between these two functions, you can set the pixels of the character,
using the functions explained below. The \texttt{action} field is
common to all of them; if GOCR\_SET, then the function will select;
if GOCR\_UNSET, the function will unselect.

\begin{lyxcode}
int~gocr\_charSetPixel\index{gocr\_charSetPixel}~(~int~action,~int~x,~int~y~);~
\end{lyxcode}
Selects the pixel at (x, y).

\begin{lyxcode}
int~gocr\_charSetAllNearPixels\index{gocr\_charSetAllNearPixels}~(~int~action,~int~x,~int~y,~
\begin{lyxcode}
int~connect~);~
\end{lyxcode}
\end{lyxcode}
If \texttt{connect} is 4, selects all the pixels of the same color
that are 4-connected with the pixel at (x, y); if connect is 8, selects
all the pixels of the same color that are 8-connected with the pixel
at (x, y). If \texttt{connect} is neither 4 nor 8, the function assumes
4-connection.

\begin{lyxcode}
int~gocr\_charSetRect\index{gocr\_charSetRect}~(~int~action,~int~x0,~int~y0,~int~x1,~
\begin{lyxcode}
int~y1~);
\end{lyxcode}
\end{lyxcode}
Selects all pixels contained at the rectangle defined by (x0, y0)
and (x1, y1). These points don't need to be top left and right bottom;
they can be any diagonally opposite vertices. Internally, however,
GOCR always convert (x0, y0) to be top left and (x1, y1) to be bottom
right. This is valid for any function that takes two points defining
a rectangle as arguments.

If you change your mind after a call to \texttt{gocr\_charBegin},
you can still save the nation:

\begin{lyxcode}
void~gocr\_charAbort\index{gocr\_charAbort}~(~void~);
\end{lyxcode}
This function aborts a character begun using gocr\_charBegin. All
changes done by the gocr\_charSet{*} functions since the last call
to gocr\_charBegin are undone.

When you can \texttt{gocr\_charEnd}, the character can be saved as
a simple rectangle that covers all the pixels you selected, or saving
each individual pixel. While the later gives a lot more freedom, letting
you select awkward regions, it consumes about 12.5\% more memory,
and is slower. \textcolor{magenta}{This is controlled by the CHAR\_RECTANGLES
flag. Done as argument to gocr\_charEnd?}


\subsection{Setting attributes\index{characters!attributes}}

Setting attributes of the text can get quite complicated if you want
to be fancy. It was decided to design a very simple, yet powerful
system, that should be able to handle most of the stuff you ever need.
First, a reminding note: these attributes should only be those that
are applied directly to the text, such as bold, italic, font type,
etc.

As usual in GOCR, the first thing to do is to create the attribute:

\begin{lyxcode}
int~gocr\_charAttributeRegister\index{gocr\_charAttributeCreate}~(~char~{*}name,~
\begin{lyxcode}
gocrCharAttributeType~t,~char~{*}format~);
\end{lyxcode}
\end{lyxcode}
\begin{description}
\item [name]attribute name; must be unique. We recommend to use capital
letters, but it's up to you.
\item [type]there are two possible values: 

\begin{description}
\item [SETTABLE]the attribute works like a flag: either it's set, or not
set. Example: boldness.
\item [UNTIL\_OVERRIDEN]the attribute is valid for ever; you can only change
it's values. Example: font. There must always be a font type and size,
but they may change during the text.
\end{description}
\item [format]this field is used to store any attributes of the attribute
(wow). It will be explained below, with a example.
\end{description}
As usual, the function returns 0 if OK, -1 if error (inserting an
existant attribute is considered an error). Now that you created your
attributes, you are processing the text and find that you need to
set an attribute. Do it with the following function:\textcolor{magenta}{This
function name may be changed.}

\begin{lyxcode}
int~gocr\_charAttributeInsert\index{gocr\_charAttributeInsert}~(~char~{*}name,~...~);~
\end{lyxcode}
\begin{description}
\item [name]attribute name.
\end{description}
I bet you are probably wondering how the hell this stuff works. Me
too. Uh, I mean, it's easier to understand using an example. The first
one is simple:

\begin{lyxcode}
gocr\_charAttributeRegister(\char`\"{}BOLD\char`\"{},~SETTABLE,~NULL);



gocr\_charAttributeInsert(\char`\"{}BOLD\char`\"{});

/{*}~insert~some~text~{*}/

gocr\_charAttributeInsert(\char`\"{}BOLD\char`\"{});
\end{lyxcode}
Quite easy: first you register the bold style. It's a settable attribute,
and since you don't need any extra information, the \texttt{format}
field is NULL. Then, when processing the text, you find a word in
bold. What you do is simple: insert a bold, insert the text, insert
another bold. Since it's a settable attribute, the second one cancels
the effect.

Let's do something fancier now:

\begin{lyxcode}
gocr\_charAttributeRegister(\char`\"{}FONT\char`\"{},~UNTIL\_OVERRIDEN,~\char`\"{}\%s~\%d\char`\"{});



gocr\_charAttributeInsert(\char`\"{}FONT\char`\"{},~\char`\"{}Arial\char`\"{},~18);

/{*}~insert~some~text~{*}/

gocr\_charAttributeInsert(\char`\"{}FONT\char`\"{},~\char`\"{}TimesNewRoman\char`\"{},~12);

/{*}~insert~some~more~text~{*}/
\end{lyxcode}
Now the explanation of the \texttt{format} field: it's just a printf-like
format field! So, you can save whatever you want in a format that
will be easily read by anybody, even if they do not know what it means
--- this is specially good when you are writing a outputFormatter
module. When you insert the attribute, you pass the arguments to the
format string. So, what happens in the example: we create an attribute
{}``FONT'', which is valid for ever. Note that, although it's valid
for ever, it only starts to have effect when you first call \texttt{gocr\_charAttributeInsert},
because you need to set its internal attributes (even if it doesn't
have any). In the example, you are parsing a page, and finds that
the title is typeset in Arial, size 18. The text in in Times New Roman,
size 12.

Always remember that this system is subject to all the limitations
of printf and scanf. For example: in scanf, \%s reads a string up
to the first white space, so you can't use spaces in a \%s string,
even though printf accepts it. And, since GOCR does not check the
format string, if you screw it up you are screwing everything.


\section{charRecognizer\index{charRecognizer}}

This is the core of the OCRing. This module, using some ingenious
algorithm, must be able to find that the bitmap it processed is a
certain character. Prototype:

\begin{lyxcode}
{\small void~gocr\_charRecognizer~(~gocrImage~{*}pix,~gocrBox~{*}b,~void~{*}v~);}{\small \par}
\end{lyxcode}
\texttt{pix} is an image of the framed character, whose structure
\texttt{gocrImage} is described in section \ref{image structure}.
There are two reasons to prefer to access \texttt{pix} than the \texttt{get/setData}:
first, the former is much smaller, and will be entirely in the processor's
cache, therefore being accessed much more quickly; second, the former
starts on 0, while you'll have to add b->x0 and b->y0 to the latter.
Of course, you may still use the \texttt{set/getData} functions.


\subsection{Using UNICODE\copyright\index{UNICODE}}

Quoting from a document by Markus Kuhn <Markus.Kuhn@cl.cam.ac.uk>
that can be found at: http://www.cl.cam.ac.uk/\textasciitilde{}mgk25/unicode.html.
It's a very good document, and you should read it.

\begin{quotation}
What is UNICODE?

Historically, there have been two independent attempts to create a
single unified character set. One was the ISO 10646 project of the
International Organization for Standardization (ISO), the other was
the Unicode Project organized by a consortium of (initially mostly
US) manufacturers of multi-lingual software. Fortunately, the participants
of both projects realized around 1991 that two different unified character
sets is not what the world needs. They joined their efforts and worked
together on creating a single code table. Both projects still exist
and publish their respective standards independently, however the
Unicode Consortium and ISO/IEC JTC1/SC2 have agreed to keep the code
tables of the Unicode and ISO 10646 standards compatible and they
closely coordinate any further extensions. Unicode 1.1 corresponds
to ISO 10646-1:1993 and Unicode 3.0 corresponds to ISO 10646-1:2000. 
\end{quotation}
In GOCR, we adopted the Unicode Standard version 3.0. To the programmer
using GOCR, this is a very simple way to deal with characters that
are not in the ASCII or the ISO-8859-1 table, and let one to support
any language.

Support in GOCR is very simple, as it should be. There's a list \#defining
some of the characters in \texttt{unicode.h}. Note that only a small
portion of the Unicode set is present there, which reflect what we
hope to be able to recognize in the near future, and what we already
do. If you need to support other characters not found there, please
feel free to. Be sure to use their correct codes; you can get a full
list of them in:

\begin{lyxcode}
http://www.unicode.org
\end{lyxcode}
and if you notify us, we add them to the header. As GOCR treats the
codes as simple numbers, it doesn't matter if it's in the header or
not. The only problem you may find is with the outputFormatter plugin,
which may not support some characters.

In short, GOCR uses UCS-4 encoding \emph{internally}. This is much
easier to handle by the programmer than UTF-8 encoding, and should
not pose problems provided that you use \texttt{wcs{*}} functions
instead of the usual \texttt{str{*}} functions. The OutputFormatter
module can be used to export UTF-8 text or whatever you need.

The \texttt{wchar\_t} type is used to handle wide characters. If needed,
we assume that \texttt{wchar\_t} is 32 bits long, which is the default
these days, but a 16-bit \texttt{wchar\_t} may work if you don't use
characters whose code is larger than 0xFFFF (65535).

GOCR provides a simple function that helps to compose characters and
accents:

\begin{lyxcode}
wchar\_t~gocr\_compose\index{gocr\_compose}~(~wchar\_t~main,~wchar\_t~modifier~);
\end{lyxcode}
Now the arguments: \texttt{main} is the character, and \texttt{modifier}
is the accent; the function returns the code of the accented character.
Example:

\begin{lyxcode}
character~=~gocr\_compose(~a,~ACUTE\_ACCENT~);
\end{lyxcode}
returns the code of the character . Currently this function supports
the following:

\vspace{0.3cm}
{\centering \begin{tabular}{|c|c|}
\hline 
Modifier&
Characters\\
\hline
\hline 
ACUTE\_ACCENT&
aeiouy AEIOUY\\
\hline 
CEDILLA&
c C\\
\hline 
TILDE&
ano ANO\\
\hline 
GRAVE\_ACCENT&
aeiou AEIOU\\
\hline 
DIAERESIS&
aeiouy AEIOUY\\
\hline 
CIRCUMFLEX\_ACCENT&
aeiou AEIOU\\
\hline 
RING\_ABOVE&
a A\\
\hline 
e or E ( \ae, \oe)&
ao AO\\
\hline
\end{tabular}\par}
\vspace{0.3cm}

Besides that, it also supports a latin\( \rightarrow  \)greek character
translation, if you pass 'g' as \texttt{modifier}. See the table for
reference.
\begin{table}[htb]
\vspace{0.3cm}
{\centering \begin{tabular}{|c|c|}
\hline 
Latin&
Greek\\
\hline
\hline 
a&
\( \alpha  \)\\
\hline 
b&
\( \beta  \)\\
\hline 
g&
\( \gamma  \)\\
\hline 
d&
\( \delta  \)\\
\hline 
e&
\( \epsilon  \)\\
\hline 
z&
\( \zeta  \)\\
\hline 
h&
\( \eta  \)\\
\hline 
q&
\( \theta  \)\\
\hline 
i&
\( \iota  \)\\
\hline 
k&
\( \kappa  \)\\
\hline 
l&
\( \lambda  \)\\
\hline 
m&
\( \mu  \)\\
\hline 
n&
\( \nu  \)\\
\hline 
x&
\( \xi  \)\\
\hline 
o&
o\\
\hline 
p&
\( \pi  \)\\
\hline 
r&
\( \rho  \)\\
\hline 
\&&
\( \varsigma  \)\\
\hline 
s&
\( \sigma  \)\\
\hline 
t&
\( \tau  \)\\
\hline 
y&
\( \upsilon  \)\\
\hline 
f&
\( \phi  \)\\
\hline 
c&
\( \chi  \)\\
\hline 
v&
\( \psi  \)\\
\hline 
w&
\( \omega  \)\\
\hline
\end{tabular}\par}


\caption{Latin\protect\( \rightarrow \protect \)greek reference for gocr\_compose.}
\end{table}


If \texttt{main} is a capital letter, the returning characters will
also be capital letters. Support of greek accents (tonos, dialytika,
etc) is under way.


\subsection{Setting characters}

When you are ready to add a character, use:

\begin{lyxcode}
int~gocr\_boxCharSet\index{gocr\_boxCharSet}~(~gocrBox~{*}b,~wchar\_t~w,~float~prob~);
\end{lyxcode}
The arguments are:

\begin{lyxlist}{00.00.0000}
\item [\textbf{b}]the box you are processing.
\item [\textbf{w}]the character code.
\item [\textbf{prob}]the probability that the recognition is correct: 0.0
is none (which will take the character out of the list) and 1.0 is
100\% sure.
\end{lyxlist}
The most probable character will be returned later, etc


\subsection{Attributes again\index{boxes!attributes}}

The charFinder may not have found all the attributes of a character.
Don't worry: this module may access the \texttt{\textcolor{magenta}{gocr\_charAttributeSet}}
too.

talk about using charAttribute funcitons here too, and how is gocrBox
importnat here


\section{contextCorrection\index{contextCorrection}}

After everything, there will remain some characters that weren't recognized,
and it's the task of this module to recognize them. These characters
can be divided in three groups%
\footnote{It's widely known that there are two types of people, those who separate
people in two groups and those who don't. You might argue that there
are three groups: those who separate people in three groups, those
who don't separate people in groups, and those who can't decide. But
then there are four groups: you must include those who separate people
in two groups. And, since we are separating people in four groups,
there is a fifth group. The problem is those idiots that can't make
up their minds.
}:

\begin{itemize}
\item merged characters. Due to imperfections of the original text, two
or more characters ended touching it other, and should be separated.
Ligatures may fall in this group too.
\item unsupported characters. There's not much to do with these; they just
are not supported by any of the modules.
\item unrecognizable characters. Bad printing, bad scanning or some accident
with the original document could have rendered some of the characters
unrecognizable. They can be recognized by using some filter and reprocessing,
or to use the context.
\end{itemize}
So, these are the issues you must consider. 


\subsection{Accessing text}

TODO.


\subsection{Splitting characters\index{characters!splitting}}

GOCR provides a set of functions similar, or better, (almost) identical
to those used to create characters to split them.

Let's take a look of the situation: you have added a character that
you later find out is in fact composed of two (or more, but let's
assume two for simplicity; you can take care of more applying this
procedure several times) characters. How to split them? Although you
could delete the box, taking care of saving its attributes, create
two new characters, etc, there's an easier way to do it:

\begin{lyxcode}
int~gocr\_charSplitBegin\index{gocr\_charSplitBegin}~(~gocrBox~{*}box~);
\end{lyxcode}
\begin{description}
\item [box]the box to be splited.
\end{description}
Now you can work just as if you were adding a character. All the \texttt{gocr\_charSet}
functions can be used as usual. When you are done, call

\begin{lyxcode}
int~gocr\_charSplitEnd\index{gocr\_charSplitEnd}~(~void~);
\end{lyxcode}
It's time for the fine print. First, what happens: all the pixels
you select will be part of the a new box. This box is inserted in
the list \emph{before} the original one, which is updated to hold
the rest of the pixels only. All attributes that were part of the
original box are now transferred to the new one (so, the original
one doesn't have any attributes anymore; but since they are applied
to the box before it, they are applied to it too). You can call \texttt{gocr\_Abort}
just as if you were adding a character. 

\textcolor{magenta}{Future: there may be a flag to set which of the
boxes goes before which.}


\subsection{Joining characters}

Still not planned.


\section{outputFormatter\index{outputFormatter}}

Once it's all done, the user usually wants the output sent to a file
in some way that he/she can read it, instead of the beautiful, complex
structures that are spread all over the computer memory. This module
should satisfy this caprice. The prototype is:

\begin{lyxcode}
void~({*}outputFormatter)~(List~{*}bl,~void~{*}v);
\end{lyxcode}
where the list contains all the blocks, in the order you added them.
\textcolor{magenta}{This module may be changed in the near future.}

Each block has a field called \texttt{text} which contains all the
characters of the block and the attributes. If you just want to dump
them, lousily converted to ascii, here's an example of what you may
do:

\begin{lyxcode}
for\_each\_data(bl)~\{~
\begin{lyxcode}
wchar\_t~{*}w~=~((gocrBlock~{*})list\_get\_current(bl))->text;~

while~({*}w)~
\begin{lyxcode}
putc({*}w++);
\end{lyxcode}
\end{lyxcode}
\}~end\_for\_each(bl);
\end{lyxcode}
You can read more about lists in section \ref{linked list}.


\subsection{Dealing with unknown characters}

Since the user may be using any modules available, it's possible that
they recognize some characters that are not supported by the outputFormatter
function. Some may be not even in the UNICODE standard.

We suggest three ways to deal with this situation. The first is to
print the code in a readable format: U39A0, for example. The user
probably can find what character is this, and using and editor easily
replace the code by whatever he wants.

The second suggestion is to let the user provide some mappings of
his own, either by a configuration file or by using the gocr\_setModuleAttribute
(see \ref{module attributes}). This is our preferred solution, since
it allows user customization with minimum effort.

The third suggestion is to ask the user on the fly.


\subsection{Dealing with unknown attributes}

TODO


\chapter{Modules in deep}

While last chapter focused in an overview of what you have to do,
this chapter presents utilities that are part of the GOCR module API,
written to make your life a bit easier.


\section{Printing image, blocks and boxes\index{boxes!printing}}

GOCR provides a number of functions that print images, blocks or boxes,
which are very helpful for debugging. How the image is printed depends
of the PRINT attribute and the output file is controlled by the ERROR\_FILE
attribute (see section \ref{attributes}).

\begin{lyxcode}
int~gocr\_printBlock\index{gocr\_printBlock}~(~gocrBlock~{*}b~);~
\end{lyxcode}
Prints all information in \texttt{gocrBlock {*}b}, if PRINT\_IMAGE
is GOCR\_TRUE, prints framed image too. Here's an example of what
is printed (PRINT = 0):

\begin{lyxcode}
Block:~x0:1,~y0:1,~x1:117,~y1:16;~type~TEXT~

..{*}{*}........{*}{*}{*}{*}{*}{*}......{*}{*}{*}{*}{*}{*}{*}..........{*}{*}.....{*}{*}{*}{*}{*}{*}{*}{*}..~

{*}{*}{*}{*}.......{*}....{*}{*}{*}....{*}.....{*}{*}..........{*}{*}.....{*}{*}{*}{*}{*}{*}{*}...~

..{*}{*}......{*}{*}.....{*}{*}{*}...{*}{*}....{*}{*}{*}........{*}{*}{*}.....{*}.........~

..{*}{*}......{*}{*}{*}....{*}{*}{*}...{*}{*}....{*}{*}{*}.......{*}{*}{*}{*}.....{*}.........~

..{*}{*}......{*}{*}{*}.....{*}{*}.........{*}{*}........{*}.{*}{*}.....{*}.........~

..{*}{*}.......{*}{*}....{*}{*}{*}........{*}{*}{*}.......{*}{*}.{*}{*}.....{*}..{*}{*}{*}....~

..{*}{*}.............{*}{*}{*}.......{*}{*}{*}.......{*}{*}..{*}{*}.....{*}{*}{*}{*}.{*}{*}...~

..{*}{*}............{*}{*}{*}......{*}{*}{*}{*}{*}.......{*}...{*}{*}.....{*}{*}....{*}{*}..~

..{*}{*}............{*}{*}{*}.........{*}{*}{*}.....{*}{*}...{*}{*}...........{*}{*}{*}.~

..{*}{*}...........{*}{*}{*}...........{*}{*}{*}....{*}....{*}{*}............{*}{*}.~

..{*}{*}..........{*}{*}{*}............{*}{*}{*}...{*}.....{*}{*}............{*}{*}.~

..{*}{*}.........{*}{*}.......{*}{*}{*}.....{*}{*}...{*}{*}{*}{*}{*}{*}{*}{*}{*}{*}{*}.{*}{*}{*}.....{*}{*}.~

..{*}{*}.........{*}.....{*}..{*}{*}{*}.....{*}{*}.........{*}{*}....{*}{*}{*}....{*}{*}{*}.~

..{*}{*}........{*}......{*}..{*}{*}{*}....{*}{*}{*}.........{*}{*}....{*}{*}.....{*}{*}{*}.~

..{*}{*}.......{*}{*}{*}{*}{*}{*}{*}{*}{*}..{*}{*}.....{*}{*}{*}.........{*}{*}.....{*}.....{*}{*}..~

{*}{*}{*}{*}{*}{*}{*}...{*}{*}{*}{*}{*}{*}{*}{*}{*}{*}...{*}{*}{*}..{*}{*}{*}........{*}{*}{*}{*}{*}{*}{*}..{*}{*}{*}.{*}{*}{*}...
\end{lyxcode}
Same for boxes:

\begin{lyxcode}
int~gocr\_printBox\index{gocr\_printBox}~(~gocrBox~{*}b~);
\end{lyxcode}
prints all information in \texttt{gocrBox {*}b}; if PRINT\_IMAGE is
GOCR\_TRUE, prints framed image too. 

\begin{lyxcode}
int~gocr\_printBox2\index{gocr\_printBox}~(~gocrBox~{*}b1,~gocrBox~{*}b2~);
\end{lyxcode}
Prints two boxes, side by side. Neat for that quick check of what
the heck is going wrong.

\begin{lyxcode}
int~gocr\_printArea\index{gocr\_printArea}~(~gocrImage~{*}image,~int~x0,~

int~y0,~int~x1,~int~y1~);~
\end{lyxcode}
Prints the part of the \texttt{image} framed by the (x0, y0) and (x1,
y1) coordinates.


\section{Linked lists\index{linked lists}\label{linked list}}

Internally, GOCR abuses of linked lists to store information. They
are very useful for this kind of program, and you may need them. Include
\texttt{list.h}, and take advantage of our linked list functions,
which were thoroughly tested! FREE!

\begin{lyxcode}
void~list\_init~(~List~{*}l~);~
\end{lyxcode}
Must be called before you do any operations with the list, otherwise
strange behaviors may occur. It doesn't not allocate memory, and so
must received a non-NULL pointer.

\begin{lyxcode}
int~list\_app~(~List~{*}l,~void~{*}data~);~
\end{lyxcode}
Appends an element \texttt{data} to the end of the list. Returns 0
if OK, 1 otherwise.

\begin{lyxcode}
int~list\_del~(~List~{*}l,~void~{*}data~);~
\end{lyxcode}
Deletes the node containing data. Use carefully. See \texttt{for\_each\_data},
below.

\begin{lyxcode}
int~list\_empty~(~List~{*}l~);
\end{lyxcode}
Returns 1 if the list is empty, 0 otherwise.

\begin{lyxcode}
void~list\_free~(~List~{*}l~);~
\end{lyxcode}
Frees the list structure and nodes. Does not free the data stored
in it.

\begin{lyxcode}
void~{*}list\_get\_current(l)~(~List~{*}l~);
\end{lyxcode}
Returns the data in the current node. See \texttt{for\_each\_data},
below.

\begin{lyxcode}
void~{*}list\_get\_cur\_prev(l)~(~List~{*}l~);
\end{lyxcode}
Returns the data stored before the current node. See \texttt{for\_each\_data},
below.

\begin{lyxcode}
void~{*}list\_get\_cur\_next(l)~(~List~{*}l~);
\end{lyxcode}
Returns the data stored after the current node. See \texttt{for\_each\_data},
below.

\begin{lyxcode}
void~{*}list\_get\_header~(~List~{*}l~);
\end{lyxcode}
Returns the data in the first node.

\begin{lyxcode}
void~{*}list\_get\_tail(l)~(~List~{*}l~);
\end{lyxcode}
Returns the data in the last node.

\begin{lyxcode}
int~list\_ins~(~List~{*}l,~void~{*}data\_after,~void~{*}data~);~
\end{lyxcode}
Inserts \texttt{data} before \texttt{data\_after}.

\begin{lyxcode}
void~{*}~list\_next~(~List~{*}l,~void~{*}data~);~
\end{lyxcode}
Returns the data stored after \texttt{data}.

\begin{lyxcode}
void~{*}~list\_prev~(~List~{*}l,~void~{*}data~);~
\end{lyxcode}
Returns the data stored before \texttt{data}.

\begin{lyxcode}
{\small void~list\_sort(List~{*}l,~int~({*}compare)(const~void~{*},~const~void~{*}));}{\small \par}
\end{lyxcode}
Similar to qsort: sorts the list. \texttt{compare} function must return
an integer less than, equal to, or greater than zero if the first
argument is considered to be respectively less than, equal to, or
greater than the second. If two members compare as equal, their order
in the sorted array is undefined. Uses a bubble sort to do the task.

\begin{lyxcode}
int~list\_total~(~List~{*}l~);
\end{lyxcode}
Returns the total number of nodes in the linked list.

\begin{lyxcode}
for\_each\_data~(~List~{*}l~)~\{
\begin{lyxcode}
code
\end{lyxcode}
\}~end\_for\_each~(~List~{*}l~);
\end{lyxcode}
This piece of code implements a for that sweeps the entire list, node
by node. You can get the current node data using \texttt{list\_get\_current},
the data before it using \texttt{list\_get\_cur\_prev}, and the data
after it using \texttt{list\_get\_cur\_next}. Use these functions
if possible instead of \texttt{list\_next} and \texttt{list\_prev},
since they are much faster. 

You can nest \texttt{for\_each\_data}, but take care when you call
\texttt{list\_del}, since you may be deleting one of the nodes that
is the current one in a lower level. The internal code takes care
of access to previous/next elements of the now defunct node. Here's
an example:

\begin{lyxcode}
for\_each\_data(l)~\{~
\begin{lyxcode}
for\_each\_data(l)~\{~
\begin{lyxcode}
list\_del(l,~header\_data);~

free(header\_data);~
\end{lyxcode}
\}~end\_for\_each(l);

\emph{tempnode~=~list\_cur\_next(l);~}
\end{lyxcode}
\}~end\_for\_each(l);
\end{lyxcode}
Although you have deleted the current node of the outer loop, the
line in italic will work as if nothing happened. But if it's replaced
with:

\begin{lyxcode}
tempnode~=~list\_next(l,~list\_get\_current(l));
\end{lyxcode}
the code will break, since \texttt{list\_get\_current} will return
either NULL or some garbage. The best way to avoid this problem is
not using \texttt{list\_del} in a big stack of loops, or test the
return value of \texttt{list\_get\_current()}. You can use \texttt{break}
and \texttt{continue}, just as if you were in a normal for loop, but
\emph{never} use a goto to somewhere outside the loop (theoretically
you can do it, using the \texttt{list\_lower} function explained below,
but if you do \textbf{take care}).

Note: if you have two elements with the same data, the functions will
assume that the first one is the wanted one. Not a bug, a feature.

Another note: avoid calling \texttt{list\_prev} and \texttt{list\_next}.
They are intensive and slow functions. Keep the result in a variable
or, if you need something more, use \texttt{list\_get\_element\_from\_data},
described below.


\subsection{Internal list functions}

There are some functions that are used internally, but may be used
by you to do some clever optimizations. Note that, if not used correctly,
you may break the code.

\begin{lyxcode}
Element~{*}list\_element\_from\_data~(~List~{*}l,~void~{*}data~);~
\end{lyxcode}
Given a data, returns the Element it's stored in. Element is a structure:

\begin{lyxcode}
struct~element~\{~
\begin{lyxcode}
struct~element~{*}next,~{*}previous;~

void~{*}data;~
\end{lyxcode}
\};~

typedef~struct~element~Element;
\end{lyxcode}
This may be interesting if you need to access the next and previous
nodes several times and you are not using a \texttt{for\_each\_data},
i.e., you need to use \texttt{list\_next} and \texttt{list\_prev}
heavily.

\begin{lyxcode}
int~list\_higher\_level~(~List~{*}l~);~

void~list\_lower\_level~(~List~{*}l~);~
\end{lyxcode}
These functions are used internally by \texttt{for\_each\_data} and
should not be directly called by the user.


\section{Hash tables}

Hash tables are used internally to access string arrays (which are
used to save attributes that are created in real time, for example),
and may be useful to you. The functions provided are not as flexible
as the linked list ones, but should suffice for most uses. Remember
to include \texttt{hash.h}.

\begin{lyxcode}
int~hash\_init~(~HashTable~{*}t,~int~size,~int~({*}hash\_func)(char~{*}));~
\end{lyxcode}
Initialize a hash table, with \texttt{size} entries, using \texttt{hash\_func}
as the hash generator func. If \texttt{t} is NULL, the function automatically
mallocs memory for it. If \texttt{hash\_func} is NULL, the default
internal hash generator is used. Returns -1 on error, 0 if OK.

\begin{lyxcode}
int~hash\_insert~(~HashTable~{*}t,~char~{*}key,~void~{*}data~);
\end{lyxcode}
Inserts a new entry in table \texttt{t}, with key \texttt{key}, which
will contain \texttt{data}. Returns -1 on error, -2 if the data already
exists, or the hash if everything was OK (although theoretically the
hash should be hidden from the user, etc, it's used internally by
GOCR to store character attributes. You can safely ignore the hash,
and use if (hash\_insert()) < 0 \{ error\}).

\begin{lyxcode}
void~{*}hash\_del~(~HashTable~{*}t,~char~{*}key~);
\end{lyxcode}
Deletes the entry associated with the \texttt{key}. Returns a pointer
to the data structure, which is not freed.

\begin{lyxcode}
void~{*}hash\_data~(~HashTable~{*}t,~char~{*}key~);~
\end{lyxcode}
Returns the a pointer to the data associated associated with \texttt{key.}

\begin{lyxcode}
int~hash\_free~(~HashTable~{*}t,~void~({*}free\_func)(void~{*}));~
\end{lyxcode}
Frees the hash table contents. If \texttt{free\_func} is not NULL,
it's called for every data stored in the table. Does not free the
hash table structure itself.

\begin{lyxcode}
char~{*}hash\_key~(~HashTable~{*}t,~void~{*}data~);
\end{lyxcode}
Searches the hash table for the first ocurrence of data, and returns
the corresponding key.


\chapter{Troubleshooting}

No matter how hard we developers work, writing perfect code, computers
stubbornly do not adapt to our code and insist in showing bugs and
problems. 

~

\textbf{Q: I'm having NetPBM problems.}

\textbf{Q: The compiler issues several warning about enum pm\_check.}

\textbf{Q: Image input or output is not working correctly.}

A: These are very likely to be result of a bad NetPBM install.

For some reason, many Linux distributions still come with old NetPBM
libraries. They lack functionality that GOCR could use, and probably
have bugs that were already fixed. That would not be so bad if it
were not for another problem: if you download the latest NetPBM package
(http://netpbm.sourceforge.net), and do a \texttt{make install}, (at
least in my computer) the install is not complete. Besides the usual
problem of things going to /usr, /usr/local/, /usr/local/share, etc,
possibly resulting in keeping the old libraries and executables, the
Makefile doesn't install the headers. This will lead to the \texttt{enum
pm\_check} warnings, which seem kind of harmless, but end up messing
everything. Solution: manually install the new headers (which are:
pnm.h, pam.h, pbm.h, pgm.h, ppm.h, pbmplus.h and shhopt.h), and make
sure that the old libraries are deleted (or at least that symbolic
links point to the new ones).

~

\textbf{Q: Why TRUE is defined as 0x22A8 (8872 in decimal)?}

A: Because UNICODE defines the symbol \( \models  \) as TRUE, as
code 0x22A8. If you need to use boolean values, use GOCR\_TRUE and
GOCR\_FALSE, which are what you want.

~


\chapter{Notes}

These chapter contains internal notes to remind myself. Disregard
them.


\section{image }

finish the IO functions (support non-pam lib)


\section{Blocks}

New architecture: instead of gocr\_addBlock, use the gocr\_beginBlock(
geometry type) paradigm. Probably only in next version.


\section{charFinder}

gocr\_endCharacter() may or may not automatically call charRecognizer.
Set a flag to do it.

How to save boxes? In a linked list in the gocrBlock structure? Otherwise,
it's reponsability of the user?


\section{Characters recognizer}

images Passed as copies, to improve speed with use of processor's
cache. They are called/stored by gocr\_endCharacter() (on flag, see
above) ???

Finish charSplit{[}Begin/End{]}

how to store the characters? A wchar\_t {*}data is very inconvenient.
Perhaps a linked list, paging the text. Probably wrapper functions.

Take care of the char attributes in unicode.c


\section{contextcorrection}

Let it access the characters without seeing internal codes (E0XX-EXXX).
Should it never see the attributes? I think that knowledge such as
{}``this is in italic'' may be helpful. But using ispell will require
conversion to text, which is not straight forward and should be done
by outputFormatter.


\section{outputformatter}

It should get the text preferably in one big chunk.

\index{recursive|see{recursive}}

\printindex{}
\end{document}