chiark / gitweb /
f2bfc7dcef96a34c9d5f1dcff3ac00b96d6664a7
[ypp-sc-tools.db-test.git] / README.charset
1 Handing OCR failures
2 --------------------
3
4 Sometimes the OCR will not be able to recognise some text.  By
5 default, when this happens, the program will stop with a fatal error
6 and refer you to this document.
7
8 It is possible to fix this by editing the character set database used
9 by the OCR algorithm.  But, it is important to get these inputs right
10 or your client may misrecognise text in future.  You *must* read the
11 documentation here first.
12
13
14 Recognition algorithm
15 ---------------------
16
17 We recognise the text in the commodity screen by doing exact matching
18 of `glyph' bitmaps, against the bitmap in each cell in the commodity
19 table.  We match from left to right.
20
21 We do not insist that each glyph is followed by whitespace, and nor do
22 we insist that glyphs do not contain whitespace.  Our glyph database
23 can contain entries which are strict prefixes of other entries - that
24 is, a glyph for (say) `v' which is the leftmost part of another glyph
25 for (say) `w'.  We resolve these ambiguities by taking the longest
26 (widest) glyph which matches.
27
28 So you should not be surprised if the program has matched the
29 left-hand half of some letter and thinks it is a different letter.  If
30 the part that it did recognise does look like the letter in question,
31 that isn't wrong.  All you need to do is insert the whole of the
32 actual letter in the database - move the LH cursor to the start of the
33 letter, and the RH cursor to its end, and hit `return' and enter the
34 correct character.  The longest match rule will mean it will prefer
35 the entry you have just made.
36
37
38 Upper vs lower case - important note regarding `l' and `I'
39 ----------------------------------------------------------
40
41 We maintain separate databases for upper and lower case.  At the
42 beginning of each cell in the table, we expect uppercase; in the
43 middle of a word we expect lowercase; and, unfortunately, after an
44 inter-word gap, we are not sure.
45
46 This is troublesome because `l' and `I' look identical on the screen.
47 So any time we see a word starting with `l' or `I', the program has to
48 ask about it.
49
50 *Do not* make an entry in the character set database mapping `vertical
51 stick' to `l' or `I'.  Instead, select enough of the whole word in
52 question that no word would start with the other letter, and enter the
53 whole word or part of it as a new glyph.
54
55 For example, in the supplied database there is already a glyph for
56 `Iron'; this is OK because there are no words which start `lron'.
57
58 Do not make an entry for a string more than 7 characters long;
59 currently we cannot cope (and you'll have to remove it manually from
60 the charset-15.txt file).
61
62
63 Short inter-word gaps
64 ---------------------
65
66 It can happen that the problem you are being asked about is caused by
67 the program failing to spot an inter-word gap and mistakenly thinks
68 that the next word is necessarily in lowercase, so fails to recognise
69 an uppercase letter.  The context in which each glyph was recognised
70 is shown on the screen, underneath the text which shows what it was
71 recognised as.
72
73 *You should check the alleged context before entering a character*.
74 If it is wrong, you should fix it, rather that just making an entry
75 for the uppercase letter in the lowercase database.
76
77 Instead, make a new glyph for the last letter of the previous word
78 plus the (unusually narrow) inter-word space, and end that entry with
79 \x20 (yes, type \ x 20).
80
81 For example, you might find that `y<space>G' is treated as
82 `y<??lowercase>' and the G doesn't get matched.  Select the `y<space>'
83 region of the bitmap and type `y\x20' into the string box.
84 Sorry for this rather poor UI!
85
86
87 Overlapping characters - ligatures
88 ----------------------------------
89
90 Some of the characters in the font used overlap with the next
91 character.  When this happens, select both the characters and enter
92 them together as one glyph with a multi-character definition.
93
94 For example `yw' is rendered with the top right corner of the `y' and
95 the top left corner of the `w' overlapping.  This is dealt with by
96 matching the whole merged thing - select the region of the screen
97 containing `yw' and define it as `yw'.
98
99
100 Fixing mistakes
101 ---------------
102
103 The OCR query UI allows you to delete things from the glyph database.
104 However since you are not guaranteed to actually get an OCR query at
105 all if the database contains errors, you shouldn't rely on this.
106
107 If you think you have made mistakes answering OCR queries (for
108 example, the recognised data is wrong), you should download a fresh
109 copy of charset-15.txt from
110  http://www.chiark.greenend.org.uk/~ijackson/ypp-sc-tools/master/pctb/charset-15.txt
111
112
113 Enabling interactive character set update
114 -----------------------------------------
115
116 Now that you have read this document, you should rerun your OCR job
117 with the --edit-charset option.  You probably want to supply --same as
118 well, to avoid having to wait for it to page through and recapture all
119 the screenshots.  So, this time,
120    ./ypp-commodities --edit-charset --same
121 and in future, just always run it with the --edit-charset option.
122
123 With --edit-charset, when the OCR finds characters it does not
124 understand, it will put up an OCR resolution query window.  This will
125 display the part of the text it is having trouble with, showing where
126 it has got to, and allow you to edit the character set database it
127 uses for recognising the text.
128
129 *This is subtle* and it is important to understand the way the
130 machinery works, and the possible mistakes you can make, before
131 answering the program.  *Please read this documentation*, which
132 explains the meaning of the entries you make.
133
134 If you need help please ask me (ijackson@chiark.greenend.org.uk, or
135 Aristarchus on Midnight in game if I'm on line, or ask any pirate of
136 the crew Special Circumstances if they happen to know where I am
137 and/or can get in touch).
138
139
140 Send me your updates
141 --------------------
142
143 The character set is in the file `charset-15.txt'.  When you enter new
144 characters, they are added there.  If you do this, please email me
145 your charset file (ijackson@chiark.greenend.org.uk) so that I can
146 include your contributions in future versions.  This will also let me
147 check that they seem right :-).
148
149 In future I may have the program phone home automatically so that I
150 can double-check your answers and distribute them in the next version.