entangledstate-isbn 1.4.0 → 1.4.1

data/src/gocr-0.48/configure.in

@@ -0,0 +1,71 @@
+# see /usr/share/info/standards.info,autoconf.info (autoconf 2.57)
+dnl Process this file with autoconf to produce a configure script.
+dnl obsolete: AC_INIT(src/pgm2asc.c)
+AC_INIT(gocr,0.48,,)
+AC_PREREQ(2.50)
+AC_CONFIG_HEADERS([include/config.h])
+dnl AC_EXEEXT is obsolete now
+
+dnl Checks for programs.
+AC_PROG_CC
+AC_PROG_INSTALL
+AC_PROG_MAKE_SET
+dnl only needed for libPgm2asc.a, not for the rpm/ebuild
+dnl AC_PROG_RANLIB
+dnl AC_CHECK_PROG(AR,ar,ar)
+dnl needed for developpers to make examples, not for the rpm/ebuild
+dnl AC_CHECK_PROG(FIG2DEV,fig2dev,fig2dev)
+
+dnl Check for optional debug mode
+dnl debug makes program slow, but is very useful for developper
+dnl ToDo: how to check that c-flags are available?
+AC_ARG_WITH(debug,
+ [  --with-debug            switching on debugging (more verbose output)],
+ [ CPPFLAGS="-Wall -g -fexceptions -DDO_DEBUG=1 $CPPFLAGS" ])
+if test "$with_debug"; then echo "debugging enabled"; fi
+
+dnl Check for optional netpbm PACKAGE: --with-netpbm=no == --without-netpbm
+dnl LDFLAGS+=-R$withval/lib compiles the search path into the file ???
+AC_ARG_WITH(netpbm,
+ [  --with-netpbm=PATH      enter the PATH to netpbm package],
+ [ if test "$withval" != "no"; then
+    LDFLAGS="-L$withval/lib $LDFLAGS";\
+    CPPFLAGS="-I$withval/include $CPPFLAGS";\
+   fi ])
+if test -n "$with_netpbm"; then echo "option: with_netpbm $with_netpbm"; fi
+
+dnl Checks for libraries.
+if test "$with_netpbm" != "no"; then
+# netpbm-10.26 + SuSE-10.0: netpbm needs mathlib -lm
+# netpbm-10    : libnetpbm + pam.h (+ p[bgpn]m.h, libp[bgpn]m.so as links)
+# netpbm-9     : libpnm    + pnm.h (+ p[bgp]m.h)
+# pnm_readpaminit (netpbm-10)
+# pnm_readpnminit (netpbm-9,10)
+# ToDo: how to check that -lm is needed?
+LDFLAGS="-lm $LDFLAGS"
+AC_SEARCH_LIBS(pnm_readpnminit,[netpbm pnm],[check_netpbm_h="pam.h pnm.h"],
+ [ echo " * * * try option --with-netpbm=PATH"])
+fi
+
+dnl Checks for header files.
+AC_HEADER_STDC
+AC_CHECK_HEADERS([unistd.h wchar.h ${check_netpbm_h}])
+
+dnl Checks for typedefs, structures, and compiler characteristics.
+AC_C_CONST
+dnl AC_CHECK_TYPE(wchar_t,unsigned)
+
+dnl Checks for library functions.
+dnl this macro produces a warning: AC_TRY_RUN called without default ...
+dnl The message can be ignored as long as you don't configure gOCR for 
+dnl cross-compiling.
+AC_FUNC_SETVBUF_REVERSED
+AC_CHECK_FUNCS(wcschr wcsdup gettimeofday popen)
+
+dnl Checks for system services
+
+dnl obsolete: AC_OUTPUT(Makefile src/Makefile doc/Makefile man/Makefile)
+dnl the light weight version of package comes without src/api
+AC_CONFIG_FILES([Makefile src/Makefile doc/Makefile man/Makefile])
+dnl AC_CONFIG_COMMANDS([default],,)
+AC_OUTPUT

data/src/gocr-0.48/doc/.#Makefile.1.6

@@ -0,0 +1,39 @@
+#
+# Makefile for ./doc path, used by configure
+#
+
+# these two lines are for cross-compiling, not tested
+#srcdir = .
+#VPATH = .
+
+# changed to html, tex is not used anymore
+#LATEX=@LATEX@
+#DVIPS=@DVIPS@
+
+OCRDOC=ocr
+# add other source file to documentation here
+# SRC=$(OCRDOC).tex
+
+.PHONY : all clean proper install uninstall
+default: all
+
+all:	# do nothing!
+
+#$(OCRDOC).ps: $(OCRDOC).dvi
+#	$(DVIPS) -o $(OCRDOC).ps $?
+#
+#$(OCRDOC).dvi: $(SRC)
+#	$(LATEX) $(OCRDOC).tex
+
+install: all
+	echo "Copy gocr.html to your document path."
+
+uninstall:
+	echo "Remove gocr.html from your document path."
+
+clean:
+	-rm -f *.bak *~ $(OCRDOC).{dvi,log,aux}
+
+proper: clean
+	-rm -f $(OCRDOC).ps 
+

data/src/gocr-0.48/doc/.cvsignore

@@ -0,0 +1,2 @@
+.cvsignore
+Makefile

data/src/gocr-0.48/doc/Makefile

@@ -0,0 +1,39 @@
+#
+# Makefile for ./doc path, used by configure
+#
+
+# these two lines are for cross-compiling, not tested
+#srcdir = .
+#VPATH = .
+
+# changed to html, tex is not used anymore
+#LATEX=@LATEX@
+#DVIPS=@DVIPS@
+
+OCRDOC=ocr
+# add other source file to documentation here
+# SRC=$(OCRDOC).tex
+
+.PHONY : all clean proper install uninstall
+default: all
+
+all:	# do nothing!
+
+#$(OCRDOC).ps: $(OCRDOC).dvi
+#	$(DVIPS) -o $(OCRDOC).ps $?
+#
+#$(OCRDOC).dvi: $(SRC)
+#	$(LATEX) $(OCRDOC).tex
+
+install: all
+	echo "Copy gocr.html to your document path."
+
+uninstall:
+	echo "Remove gocr.html from your document path."
+
+clean:
+	-rm -f *.bak *~ $(OCRDOC).{dvi,log,aux}
+
+proper: clean
+	-rm -f $(OCRDOC).ps 
+

data/src/gocr-0.48/doc/Makefile.in

@@ -0,0 +1,39 @@
+#
+# Makefile for ./doc path, used by configure
+#
+
+# these two lines are for cross-compiling, not tested
+#srcdir = @srcdir@
+#VPATH = @srcdir@
+
+# changed to html, tex is not used anymore
+#LATEX=@LATEX@
+#DVIPS=@DVIPS@
+
+OCRDOC=ocr
+# add other source file to documentation here
+# SRC=$(OCRDOC).tex
+
+.PHONY : all clean proper install uninstall
+default: all
+
+all:	# do nothing!
+
+#$(OCRDOC).ps: $(OCRDOC).dvi
+#	$(DVIPS) -o $(OCRDOC).ps $?
+#
+#$(OCRDOC).dvi: $(SRC)
+#	$(LATEX) $(OCRDOC).tex
+
+install: all
+	echo "Copy gocr.html to your document path."
+
+uninstall:
+	echo "Remove gocr.html from your document path."
+
+clean:
+	-rm -f *.bak *~ $(OCRDOC).{dvi,log,aux}
+
+proper: clean
+	-rm -f $(OCRDOC).ps 
+

data/src/gocr-0.48/doc/example.dtd

@@ -0,0 +1,53 @@
+<?xml version="1.0"?>
+<!--
+    first draft by Volker Simonis, reviewed by Joerg Schulenburg
+                 Its not ready for use!
+     ToDo:
+       - lynx/links/w3c should show xml like a html file 
+           value as <character ...>CharText</character>
+           or  <word><character ...></character><...>WordText</word>
+           or as line or as block? whats more useful?
+       - how to code table of alternative chars/words and its probability?
+       - how to handle images (as image tags?)
+       - xmllint -\-htmlout -\-loaddtd jocr/doc/example.dtd o.xml
+  -->
+<!ENTITY % default.attributes "x  CDATA #REQUIRED
+                               y  CDATA #REQUIRED
+                               dx CDATA #REQUIRED
+                               dy CDATA #REQUIRED">
+
+<!ELEMENT box EMPTY>
+<!ATTLIST box %default.attributes;
+              value CDATA #REQUIRED;>
+
+<!ELEMENT barcode EMPTY>
+<!ATTLIST barcode %default.attributes;
+                value CDATA #REQUIRED;>
+
+<!ELEMENT img EMPTY>
+<!ATTLIST img %default.attributes;>
+
+<!ELEMENT page (block*)>
+<!ATTLIST page %default.attributes;>
+
+<!ELEMENT block (line*)>
+<!ATTLIST block %default.attributes;>
+
+<!ELEMENT line ((word | space | punctuation-mark)*)>
+<!ATTLIST line %default.attributes;>
+
+<!ELEMENT word (character*)>
+<!ATTLIST word %default.attributes;>
+
+<!ELEMENT char EMPTY>
+<!ATTLIST char %default.attributes;
+               value CDATA #REQUIRED;
+               (#CDATA)>   <!-- is that correct? -->
+
+<!ELEMENT space EMPTY>
+<!ATTLIST space %default.attributes;
+                value CDATA #REQUIRED;>
+
+<!ELEMENT punctuation-mark EMPTY>
+<!ATTLIST punctuation-mark %default.attributes;
+                           value CDATA #REQUIRED;>

data/src/gocr-0.48/doc/example.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0"?>
+<!DOCTYPE gocr SYSTEM "example.dtd">
+<!-- example file for example.dtd -->
+<page>
+ <block x="123" y="11" dx="500" dy="800">
+  <line x="130" y="11" dx="480" dy="30">
+    <word x="130" y="11" dx="80" dy="30"> 
+      <character x="130" y="11" dx="80" dy="30" value="A"/>
+      <character ... />
+      ...
+    </word>
+    <punctuation-mark .. />
+    <space .. />
+    <word ..>
+    ...
+    </word>
+  </line>
+  <box ... />
+  ...
+ </block>
+</page>

data/src/gocr-0.48/doc/examples.txt

@@ -0,0 +1,67 @@
+Note: this info is related to example files, used to test gOCR. As of this 
+writing, these files are not available to non-developers. So, if you aren't
+a developer, forget about this file.
+
+				EXAMPLE FILES
+
+1. Scanning
+The examples can be scanned from anything; when looking for something, try to
+have in mind the kind of tests you are expecting to do: if you're testing
+accents recognition, look for texts in portuguese, french, etc. (pretty obvious,
+but keeping this in mind will help to have a large gamma of files covering
+different kinds of tests).
+
+If you're not interested in testing DPIs, scan at 150 or 300dpi.
+
+If you're not interested in testing the dust removal, cleaning, etc, functions,
+do the best scan you can. Usually increasing brightness and contrast will
+provide a sharper, cleaner image.
+
+Save the image in a supported format: for example, pgm or jpg. If a compression
+will result in a significant reduction of size, compress the image. BZIP2
+usually is the best compressor around, but gzip is more popular in the unix
+world. In the wintel world, people use ZIP, and usually will have to search for
+an application capable of opening .gz or .bz2 (though WinZIP opens at least the
+former).
+
+2. Sorting
+To help others to find the files they are looking for, the examples/ directory
+is divided in several other directories, which may be subdivided. When
+uploading a new example, look for the most suitable location. Depending of the
+directory, you probably will name your file with interesting info: for example,
+when uploading a image with all the characters of the foo font, the best thing
+to do is to place it at examples/fonts/foo.jpg.
+
+3. "Translation"
+Along with the image file, upload a text file with the expected output. Be
+careful with this file: it must resemble the original text as much as possible.
+Don't add extra new lines (\n), keep hyphenized words, etc. Name this file with
+the same name of the image file.
+
+In the beginning of the text file, you should provide comments, to help
+searches. Use the following sample:
+
+# Comments
+# DPI: 
+# Colors: 
+# Image size (colsXrows): 
+# Fonts: 
+# Font sizes: 
+# Layout form: 
+# Number of pictures: 
+# Language: 
+# Quality of scan: 
+# Non-ASCII characters: 
+# Extra: 
+
+Check existing examples to see what people have been doing. 
+
+Any lines that begin with # will be considered comments, so you may use several
+lines for comments or add new fields. Though gOCR itself doesn't depend on, and
+won't use, this file, it will be used by scripts.
+
+4. Other sources (WEB)
+ 
+  - http://www.clerkweb.house.gov/elections/elections.htm  (Nov2002)
+      PDF-files with lot of tables
+

data/src/gocr-0.48/doc/gocr.html

@@ -0,0 +1,578 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+
+<HTML>
+<HEAD>
+<TITLE>GOCR-documentation</TITLE>
+<META NAME="description" CONTENT="GOCR-documentation">
+<META NAME="keywords" CONTENT="ocr">
+<META NAME="resource-type" CONTENT="document">
+<META NAME="distribution" CONTENT="global">
+
+<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
+<META NAME="Generator" CONTENT="Joerg">
+</HEAD>
+
+<BODY >
+<H1 ALIGN="CENTER">GOCR-documentation</H1>
+<P ALIGN="CENTER"><STRONG>J&ouml;rg Schulenburg</STRONG></P>
+<P ALIGN="CENTER"><STRONG>Magdeburg, June 3, 2002</STRONG></P>
+
+<H3>Abstract:</H3>
+<DIV>
+In this documentation I describe some ideas for my OCR-program.
+It contains algorithms and examples and gives you
+ an impression of what the program can (or could) do.
+</DIV>
+<P>
+
+
+<P>
+<BR><HR>
+<!--Table of Child-Links-->
+<A NAME="CHILD_LINKS"></A>
+
+<UL>
+<LI><A HREF="#SEC1">Introduction</A>
+<LI><A HREF="#SEC2">Segmentation of textual regions / Layout analysis</A>
+<LI><A HREF="#SEC3">Line detection</A>
+<LI><A HREF="#SEC4">Cluster detection</A>
+<LI><A HREF="#SEC5">Engines</A>
+<LI><A HREF="#SEC6">Remove pixels</A>
+<LI><A HREF="#SEC7">Add pixels</A>
+<LI><A HREF="#SEC8">Similarity analyzer</A>
+<LI><A HREF="#SEC9">Overlapping characters</A>
+<LI><A HREF="#SEC10">Black/White, Gray and Colors</A>
+<LI><A HREF="#SEC11">Pictures on scanned pages</A>
+<LI><A HREF="#SEC12">Tools</A>
+<LI><A HREF="#SEC13">glossary</A>
+<LI><A HREF="#SEC14">More information?</A>
+<LI><A HREF="#SEC15">About this document</A>
+</UL>
+<!--End of Table of Child-Links-->
+
+<H1><A NAME="SEC1"> Introduction</A>
+</H1>
+First I have to say that I am not a expert in pattern recognition 
+or similar things. My knowledge is based mostly on experiments with my
+program.
+Therefore do not worry about stupid algorithms I put in this document. 
+In this documentation I describe some ideas for my OCR-program.
+The examples give you an impression of how the program handles 
+your images. 
+If you have comments regarding contents or spelling please
+write to the author.
+
+<H1><A NAME="SEC2">Segmentation of textual regions / Layout analysis</A></H1>
+
+This is implemented as a recursive division in two parts.
+
+<UL>
+ <LI>look for the thickest horizontal or vertical gap through the box</LI>
+ <LI>if the gap is less than five times longer than thick do not divide  </LI>
+ <LI>do the same with the two new parts</LI>
+</UL>
+I know that this algorithm is not as good as you wish,
+but I do not know a better one.
+
+<P>
+It would be very helpful to know about a function which is able to
+ decide whether the box represents a single text line or a more complex object. 
+
+<H1><A NAME="SEC3">Line detection</A></H1> 
+<P>
+Line detection is very importand for good recognition.
+ For example it is difficult to distinguish between lowercase letter <B>p</B>
+ and uppercase letter <B>P</B> without having a baseline (same total height).
+ The lowercase version of <B>p</B> has a depht (the lower end is below the
+ baseline) and therefore its easy to distinguish from the uppercase version
+ if the baseline is known. The line detection is responsible for finding the
+ baseline of every text line.
+
+<P>
+Lines of characters are detected by looking for interline spaces.
+ These are characterized by a large number of non-black pixels in a
+ row.  Image rotation (skewing) presents a problem, therefore the program
+ first looks only at the left half of the image.  When a line is
+ found, the left half of the right side is scanned, because lines
+ are often short.  The variation in height gives an indication of
+ the rotation angle.  Using this angle, a second run detects lines
+ more accurately.  Line detection may fail if there is dust on the
+ image. 
+
+<P>
+In version v0.2.3 this behaviour is slightly changed.
+ To detect the rotation angle, the line through the most
+ characters is detected.
+
+<H1><A NAME="SEC4">Cluster detection</A></H1>
+
+A cluster is a group of pixels which are connected with each other.
+The simplest way to detect a cluster is to look for a pixel.
+If you find one, look to the neighbouring pixels. This can be done recursively.
+
+<P>
+This method needs a lot of stack space if a cluster is very large,
+and can cause problems with the memory.
+
+<P>
+Do you remember the algorithm for leaving a maze?
+Go along the right (or left) wall. This seems to be a good approach
+for detecting clusters without recursion.
+The following picture shows a trace of the maze algorithm.
+
+<P>
+<TABLE  WIDTH="680">
+<TR><TD>
+<PRE>
+first 35 steps     next 36 steps     
+..@@@@@..@@@@&lt;..   ..v&lt;&lt;&lt;&lt;..v&lt;&lt;&lt;@..   * = starting point
+..@@@@@@@@@.@^&lt;.   ..&gt;&gt;v@^&lt;&lt;&lt;@.@@@.   &gt;^&lt;v = go right,up,left,down
+....@@@@@...@@^.   ....v@@@@...@@@.   @ = black pixel
+....@@@@....@@^.   ....v@@@....@@@.
+....@@@.....@@^.   ....v@@.....@@@.
+....@@@.....@@^.   ....v@@.....@@@.
+...@@@@.....@@^.   ...v&lt;@@.....@@@.
+...@@@......@@^.   ...v@@......@@@.
+...@@@......@@^.   ...v@@......@@@.
+...@@@.....@@@^.   ...v@@.....@@@@.
+...@@@.....@@&gt;^.   ...v@@.....@@@@.
+...@@@.....@@^..   ...v@@.....@@@..
+..@@@@.....@@^..   ..v&lt;@@.....@@@..
+..@@@@....@@@^..   ..v@@@....@@@@..
+*&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;^&lt;&lt;   @@@@@@@@@@@@@@@@
+</PRE></TD></TR>
+</TABLE>
+
+<P>
+The minimum and maximum coordinates can be used to create a box around the
+cluster. But does this algorithm work with diagonally connected pixels?
+
+<H1><A NAME="SEC5">Engines</A></H1>
+
+GOCR is able to work with different recognition engines.
+Since version 0.37 engines have to return a probability value together
+with the recognized character or a table of values to a table of characters.
+If the probability value is 100, the engine is 100% sure to have found the
+right character otherwise the value is less. This gives GOCR the possibility
+to compare results of different engines or in case of a not recognized character
+to inform the user or another
+application (spell checker) which characters probably could be there.
+
+<H2>Base-Engine</H2>
+The base engine (src/ocrX.c) is the original engine used in the first implementation
+of GOCR by J&ouml;rg. The idea was to get a fast and acceptable result
+without learning theoretical background. Later it should be replaced or completed
+by a better engine.
+The base engine is a rule based engine. 
+The engine was written without theoretical
+background and is improved by try and error method but is is still far from
+perfect. The algorithm is very tolerant to size and form af characters
+(omnifont).
+How does the engine identify a character? For the explanation look at the
+following pattern.
+
+<P>
+<TABLE  WIDTH="680">
+<TR><TD>
+<PRE>
+vvvv         vv- white regions
+......@@......  &lt;- crossing one line
+......@@......  
+.....@@@@.....
+.....@@@@.....
+.....@@@@.....
+....@..@@@....  &lt;- white hole / crossing two lines
+....@..@@@....  &lt;- crossing two lines
+....@..@@@....
+...@....@@@...
+...@....@@@...
+...@....@@@...
+..@@@@@@@@@@..  &lt;- horizontal line near center
+..@......@@@..
+..@......@@@..  
+.@........@@@.  v- increasing width of pattern
+.@........@@@.  v
+.@........@@@.  v
+@@@......@@@@@
+    ^^^-- gap
+</PRE></TD></TR>
+</TABLE>
+
+<P>
+In the future the program
+should detect edges, vertices, gaps, angles and so on.
+This is called feature extraction (as far as I know).
+With such data the engine could make a cluster analysis.
+But this is a difficult task, if the scanned image is noisy.
+
+<H2>Database-Engine</H2>
+The database  engine (src/database.c) was the second engine added to GOCR.
+It was primary written to give users a simple tool to recognize
+special language-specific characters. The program generates a list
+(text file db.lst of image filenames and character codes)
+and image samples (pnm-files) in a database path (./db/).
+The database can be created by hand or extern programs or by GOCR itself
+using option (-m 130). In the last case GOCR prompts the user 
+for not recognized characters. If he enters the character the pattern
+is saved in the database path as pnm-file and its file name is added 
+to the database list (db.lst) together with the text string the pattern
+should be replaced by.
+For recognition GOCR first loads the database into memory (option -m 2).
+The main algorithm compares not recognized characters with stored images
+and calculates a distance value. If the distance value is small enough,
+the character is treated as recognized.
+
+<H1><A NAME="SEC6">Remove pixels</A></H1>
+
+The following picture shows an <I>n</I> which has additional pixels at the
+bottom. Therefore it can not be detected as <I>n</I>. What can be done?
+
+<UL>
+<LI>classify horizontal (<TT>=</TT>) and vertical (<TT>I</TT>) pixels by
+ comparing the distance between the next vertical and next horizontal white
+ pixels (.)
+</LI>
+<LI>measure mean thickness of vertical and horizontal clusters
+</LI>
+<LI>erase unusually thin horizontal pixels at the bottom line
+</LI>
+</UL>
+
+<P>
+<TABLE  WIDTH="680">
+<TR><TD>
+<PRE>
+..@@@@@..@@@@@..     ..==III..===II.. dx=16 dy=15
+..@@@@@@@@@.@@@.     ..==III====.III. thickness 2 to 3
+....@@@@@...@@@.     ....III==...III.
+....@@@@....@@@.     ....III=....III.
+....@@@.....@@@.     ....III.....III.
+....@@@.....@@@.     ....III.....III.
+...@@@@.....@@@.     ...IIII.....III.
+...@@@......@@@.     ...III......III.
+...@@@......@@@.     ...III......III.
+...@@@.....@@@@.     ...III.....IIII.
+...@@@.....@@@@.     ...III.....IIII.
+...@@@.....@@@..     ...III.....III..
+..@@@@.....@@@..     ..IIII.....III..
+..@@@@....@@@@..     ..IIII....IIII..
+@@@@@@@@@@@@@@@@     ================
+      ^^^ 
+      this causes the problem
+</PRE></TD></TR>
+</TABLE>
+
+<P>
+A better way is to find serifs (horizontal lines glued on the lower end 
+of vertical lines) which touch together (v0.2.5).
+
+<P>
+The next picture shows blind pixels which are caused by dust on the paper.
+The upper right dots are not connected with the rest of the character.
+This can be detected via fill-algorithms. Currently the program
+assumes that dots near the upper end of a character are ``i''-dots
+or diaereses (umlaut dots).
+
+<P>
+<TABLE  WIDTH="680">
+<TR><TD>
+<PRE>
+..........................O...     ..........................O...
+..........................O...     ..........................O...
+..............................     ..............................
+..............................     ..............................
+..........@@@.......@@@@......     ..........@@@.......@@@@......
+..@@@@..@@@@@@@...@@@@@@@.....     ..@@@@..@@@@@@@...@@@@@@@.....
+@@@@@@@@@@@@@@@@.@@@@@@@@@....     @@@@@@@@@@@@@@@@.@@@@@@@@@....
+..@@@@@@....@@@@@@.....@@@@...     ..@@@@@@....@@@@@@.....@@@@...
+..@@@@.......@@@@......@@@@...     ..@@@@.......@@@@......@@@@...
+..@@@@.......@@@.......@@@@...     ..@@@@.......@@@.......@@@@...
+..@@@@.......@@@.......@@@@...     ..@@@@.......@@@.......@@@@...
+..@@@@.......@@@.......@@@@...     ..@@@@.......@@@.......@@@@...
+..@@@@.......@@@@......@@@@...     ..@@@@.......@@@@......@@@@...
+..@@@@.......@@@.......@@@@...     ..@@@@.......@@@.......@@@@...
+..@@@@.......@@@@......@@@@...     ..@@@@.......@@@@......@@@@...
+..@@@@.......@@@.......@@@@...     ..@@@@.......@@@.......@@@@...
+..@@@@.......@@@.......@@@@...     ..@@@@.......@@@.......@@@@...
+..@@@@.......@@@.......@@@@...     ..@@@@.......@@@.......@@@@...
+..@@@@.......@@@.......@@@@...     ..@@@@.......@@@.......@@@@...
+..@@@@.......@@@.......@@@@...     ..@@@@.......@@@.......@@@@...
+..@@@@.......@@@@......@@@@...     ..@@@@.......@@@@......@@@@...
+..@@@@......@@@@@......@@@@@..     ..@@@@......@@@@@......@@@@@..
+@@@@@@@@..@@@@@@@@@..@@@@@@@@@     @@@@@@@@..@@@@@@@@@..@@@@@@@@@
+</PRE></TD></TR>
+</TABLE>
+
+<H1><A NAME="SEC7">
+Add pixels</A>
+</H1>
+The following picture shows an <I>m</I>. The legs are only barely connected.
+How do we handle this?
+
+<UL>
+<LI>if the engine has failed, a filter is switched on and the engine
+ starts over
+</LI>
+<LI>the 2x2 filter sets pixels to (<I>O</I>) near barely connected pixels
+</LI>
+</UL>
+
+<P>
+<TABLE  WIDTH="680">
+<TR><TD>
+<PRE>
+   vv   vv
+@@@.@@@..@@@...     @@@.@@@..@@@...
+.@@.@@@@.@@@@..&lt;    .@@O@@@@O@@@@..  filter: .@ =&gt; O@     @. =&gt; @O
+.@@@..@@@..@@..&lt;    .@@@..@@@..@@..          @. =&gt; @.     .@ =&gt; .@
+.@@@..@@@..@@@.     .@@@..@@@..@@@.
+.@@@..@@@..@@@.     .@@@..@@@..@@@.     
+.@@@..@@@..@@@.     .@@@..@@@..@@@.     
+.@@@..@@@..@@@.     .@@@..@@@..@@@.
+.@@@..@@@..@@@.     .@@@..@@@..@@@.
+.@@@..@@@..@@@.     .@@@..@@@..@@@.
+.@@@..@@@..@@@.     .@@@..@@@..@@@.
+.@@@..@@@..@@@.     .@@@..@@@..@@@.
+.@@@..@@@..@@@.     .@@@..@@@..@@@.
+.@@@..@@@..@@@.     .@@@..@@@..@@@.
+@@@@@.@@@@.@@@@     @@@@@.@@@@.@@@@
+</PRE></TD></TR>
+</TABLE>
+
+<H1><A NAME="SEC8">
+Similarity analyzer</A>
+</H1>
+Some characters are a little bit noisy. These characters can be identified by
+comparison with other, already recognized characters. This can be done
+via a good distance function. May be 
+the distance function in the actual version of GOCR is not very good.
+Feel free to send me your ideas, but be sure it does not waste my time. 
+
+<H1><A NAME="SEC9">
+Overlapping characters</A>
+</H1>
+The following picture shows an overlapping <I>ru</I>.
+How do we handle this?
+
+<UL>
+<LI>look for 3 weak connections (sum over y is small, start in the middle)
+</LI>
+<LI>test if the right and left part can be detected by the engine
+</LI>
+<LI>correction of surrounding box
+</LI>
+</UL>
+
+<P>
+<TABLE  WIDTH="680">
+<TR><TD>
+<PRE>
+....@@...@@@@@@@@@@....@@@@@@@..     ....@@...@@@@@@@@@@....@@@@@@@..
+..@@@@..@@@@@..@@@@......@@@@@..     ..@@@@..@@@@@..@@@@......@@@@@..
+@@@@@@@@@@@@@.,.@@@.......@@@@..     @@@@@@@@@@@@@...@@@.......@@@@..
+..@@@@@@..@@@...@@@.......@@@@..     ..@@@@@@..@@@...@@@.......@@@@..
+...@@@@.......,.@@@@......@@@@..     ...@@@@.........@@@@......@@@@..
+...@@@@.........@@@@......@@@@..     ...@@@@.........@@@@......@@@@..
+...@@@@.......,.@@@.......@@@@..     ...@@@@.........@@@.......@@@@..
+...@@@@.........@@@.......@@@@..     ...@@@@.........@@@.......@@@@..
+...@@@........,.@@@@......@@@@..     ...@@@..........@@@@......@@@@..
+...@@@..........@@@@......@@@@..     ...@@@..........@@@@......@@@@..
+...@@@........,.@@@@......@@@@..     ...@@@..........@@@@......@@@@..
+...@@@..........@@@.......@@@@..     ...@@@..........@@@.......@@@@..
+...@@@........,.@@@@......@@@@..     ...@@@..........@@@@......@@@@..
+...@@@..........@@@@......@@@@..     ...@@@..........@@@@......@@@@..
+...@@@........,.@@@@......@@@@..     ...@@@..........@@@@......@@@@..
+...@@@..........@@@@@...@@@@@@@.     ...@@@..........@@@@@...@@@@@@@.
+..@@@@@.......,..@@@@@@@@@.@@@@@     ..@@@@@..........@@@@@@@@@.@@@@@
+@@@@@@@@@.........@@@@@@@..@@@..     @@@@@@@@@.........@@@@@@@..@@@..
+..............,....@@@..........     ...................@@@..........
+             ^^^
+             213 weak vertical lines
+</PRE></TD></TR>
+</TABLE>
+
+<P>
+Of course the situation is more difficult with slanted characters.
+
+<P>
+The following example shows, how to deal with larger clusters.
+To get a fast program a first test should select the possible positions of
+division. That can be done by following upper and lower bows to a crease or a break. Than try to break on all detected creases, start at most
+important one (not implemented yet v0.2.4).
+
+<P>
+<TABLE  WIDTH="766">
+<TR><TD>
+<PRE>
+             &gt;&gt;&gt;&gt;vvv&lt;&lt;&lt;&lt;&lt;       &gt;&gt;vv&lt;&lt;&lt;&lt;         &gt;&gt;&gt;vvv&lt;&lt;&lt;&lt;
+......@@@@@@@..................@@.........@@@@@@@..........@@@@@@@.....
+....@@@@@@@@@@@...............@@@.......@@@@@@@@@@@......@@@@@@@@@@@...
+...@@@@@@@@@@@@@.............@@@@......@@@@@@@@@@@@@....@@@@@@@@@@@@@..
+..@@@@.......@@@@...........@@@@@.....@@@@.......@@@@..@@@@.......@@@@.
+..@@@........@@@@..........@@@@@@@....@@@........@@@@@@@@@........@@@@.
+.@@@@..........@@.........@@@@@@@@...@@@@..........@@@@@@@.........@@@@
+.@@@.....................@@@@.@@@@...@@@..............@@...........@@@@
+.@@@....................@@@@@.@@@@...@@@...........................@@@@
+@@@...@@@@@@@...........@@@@..@@@...@@@...@@@@@@...................@@@.
+@@@@.@@@@@@@@@@........@@@@...@@@@..@@@@.@@@@@@@@@@...............@@@@.
+@@@@@@@@@@@@@@@.......@@@@....@@@@..@@@@@@@@@@@@@@@...............@@@..
+@@@@@@@.....@@@@@.....@@@.....@@@@..@@@@@@......@@@@@............@@@@..
+@@@@.........@@@@...@@@@......@@@@..@@@@@........@@@@...........@@@....
+@@@@..........@@@@.@@@@.......@@@@..@@@@..........@@@..........@@@@....
+@@@@..........@@@@@@@@@.......@@@@.@@@@@..........@@@.........@@@@.....
+@@@@..........@@@@@@@@@@@@@@@@@@@@@@@@@@..........@@@@.......@@@@......
+@@@@..........@@@@@@@@@@@@@@@@@@@@@@@@@@..........@@@@......@@@........
+.@@@..........@@@@@@@@@@@@@@@@@@@@@@.@@@..........@@@@....@@@@@........
+.@@@@........@@@@.............@@@@...@@@@........@@@@....@@@@..........
+..@@@@.......@@@@.............@@@@....@@@@.......@@@@...@@@@...........
+..@@@@@....@@@@@..............@@@@.....@@@@....@@@@@...@@@@@@..........
+....@@@@@@@@@@@...............@@@@......@@@@@@@@@@@...@@@@@@@@@@@@@@@@@
+.....@@@@@@@@@................@@@@........@@@@@@@@....@@@@@@@@@@@@@@@@@
+........@@@@...................@@..........@@@@@........@@@@@@@..@.@@@.
+            &gt;&gt;&gt;&gt;^            ^&lt;&lt;&gt;&gt;^ ^&lt;&lt;&lt;&lt;&lt;        &gt;&gt;&gt;^&lt;&lt;&lt;      ^^ ^
+
+&gt;,&lt; show the path of the detection algorithm
+</PRE></TD></TR>
+</TABLE>
+
+<P>
+The latest version of GOCR may use different algorithms.
+You have to look at the sources learn more.
+
+<H1><A NAME="SEC10">
+Black/White, Gray and Colors</A>
+</H1>
+For simplicity colored images are converted to gray internally.
+That means a red text on green background will not be detected.
+You should use your own filter for this purpose.
+
+<P>
+If the original image is gray, a critical value is calculated to
+extract characters from the background. This can fail, if images are
+on the scanned page or tha scan is bad (dark edges or borders).
+It is difficult to overcome this problem because graylevels are mostly
+restricted to the 8 bit limit (16 bit would help to overcome this problem).  
+
+<P>
+Black/White images are internally converted to gray with two levels (0 and
+255).
+
+<P>
+The lowest 4 bits are not used, because they are used by internal functions
+(this can be changed in future).
+
+<P>
+After calculation of the threshold value (otsu.c) the brightness of
+every pixel is recalculated to a new internal threshold value
+of 160 (128+32).
+This is a bit above the middle of the 8 bit range. The idea is to
+make the live easier for the other routines. Pixels which does not sure 
+belong to the white or black ones get a value near the threshold value.
+Some routines can use this bit of more information to ignore outriders.
+Second point is, that this is necessary for using lowest for bits
+without destroying image informations.
+
+<H1><A NAME="SEC11">Pictures on scanned pages</A>
+</H1>
+At first all objects on the scanned page are detected.
+Objects are clusters of black pixels.
+Pictures are detected if they are larger than 4 times the mean size of
+all objects. This rule is very simple and can fail some times.
+But it works fast and mostly the result is ok.
+
+<H1><A NAME="SEC12">Tools</A></H1>
+
+<P>
+<DL COMPACT>
+<DT>pbmclean:</DT>
+<DD>This program is written by Angus Duggan and Jef Poskanzer.
+ It cleans up ``snow'' on bitmap images.
+</DD>
+<DT>pnmtools:</DT>
+<DD>This tools are used to convert different image-formats to
+ easy readable PNM (PBM,PGM,PPM) format.
+ GOCR uses the popen-routine to call this programs if the
+ suffix of the filename matches to a list in pnm.c.
+ This will fail if pnmtools are missing.
+</DD>
+</DL>
+
+<H1><A NAME="SEC12b">related projects (to learn from)</A></H1>
+
+<P>
+<DL COMPACT>
+ <DT>unpaper:</DT> <!-- Dec05 JS -->
+ <DD> <a href="http://unpaper.berlios.de/">unpaper</a> -
+      post-processing scanned and photocopied book pages, 
+      written by Jens Gulden 2005, GPL 
+ </DD>
+</DL>
+
+<H1><A NAME="SEC13">glossary</A> </H1> <DL COMPACT>
+<DT>font series:</DT> <DD>bold, condensed</DD>
+<DT>font shape: </DT> <DD>normal, italic, slanted, sc... </DD>
+<DT>points:</DT>
+ <DD>length unit used for font size, 1/72 inch,
+    but I do not know its exact relation to the font size (height?
+    totalheight? width? 10pt and 300dpi results in 40 pixel heigh font?)
+ </DD>
+<DT>sans serif:</DT>
+ <DD>font without the (often thin) lines on the ends
+   of the character
+ </DD>
+<DT>descewing:</DT>
+ <DD>compensation of (slightly) rotated text
+ </DD>
+</DL>
+
+<H1><A NAME="SEC14"> More information?</A> </H1>
+<DL COMPACT>
+<DT>&middot;</DT>
+   <DD>see "/usr/share/doc/package/tetex/texmf/.../fntguide.dvi"
+       in the documentation of the tetex package 
+ 
+   </DD>
+<DT>&middot;</DT>
+   <DD>the fonts-HOWTO file is helpfully too
+                  ("www.faqs.org/faqs/fonts-faq/")
+ 
+  </DD>
+<DT>RTF:</DT>
+   <DD> RichTextFormat - does someone have a good documontation?
+  </DD>
+</DL>
+
+<H1><A NAME="SEC15"> About this document</A> </H1>
+This Document was originaly written in LaTeX.
+In May 2002 Joerg has convertet it to HTML. The reason is, that
+you can read it now directly and you does not need to have LaTeX and
+Ghostscript installed on your computer to read it.
+As a side effect you do not need tetex package to build the gocr.rpm-package.
+A good viewer to read this document is lynx, links or w3m.
+
+<BR>
+<HR>
+<ADDRESS> jNOschulen-at-gSmPAMx.de (remove NO+S+PAM) </ADDRESS>
+</BODY>
+</HTML>
+<!---
+%
+% -----------------------------------------------------------------
+%       #   v
+%       #   v     mark connected points via fifo-stack
+%       ### *<<   and 3bit direction code per pixel,
+%       # # ^ ^   should be better for overlapping letters
+%       ### ^<<
+% --------------------- point connections ----------------------
+% searching next nearest point  
+%     /----\
+%     |    |
+%   ^ | ## |
+%   | | ## |
+%   | |  | |
+%   | \--/ |
+%   \------/
+%-------------------------------------------------------------
+%
+
+--->