pctb/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 dictionary 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 dictionary
  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 dictionary - 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 dictionaries for upper case (Upper), lower case
  42 (Lower), and (initial portions of) mid-phrase words (Word).  At the
  43 beginning of each cell in the table, we expect uppercase; in the
  44 middle of a word we expect lowercase; and, unfortunately, after an
  45 inter-word gap, we are not sure.
  46
  47 This is troublesome because `l' and `I' look identical on the screen.
  48 So any time we see a word starting with `l' or `I', the program has to
  49 ask about it.
  50
  51 After an interword gap, we first search for a Word entry in the
  52 dictionary.  If there is a match we use it.  Otherwise we search both
  53 the uppercase and lowercase dictionaries; if one matches and the other
  54 doesn't, or one matches a wider character than the other, we use it.
  55 If that fails to resolve the ambiguity we must ask.
  56
  57 *Do not* make an entry in the character set dictionary mapping
  58 `vertical stick' to `l' or `I'.  Instead, select enough of the whole
  59 word in question that no word would start with the other letter, and
  60 enter the whole word or part of it as a new glyph as a new entry in
  61 the Word dictionary.
  62
  63 For example, in the supplied dictionary there is already a glyph for
  64 `Iron'; this is OK because there are no words which start `lron'.
  65
  66
  67 Short inter-word gaps
  68 ---------------------
  69
  70 It can happen that the problem you are being asked about is caused by
  71 the program failing to spot an inter-word gap and mistakenly thinks
  72 that the next word is necessarily in lowercase, so fails to recognise
  73 an uppercase letter.  The context in which each glyph was recognised
  74 is shown on the screen, underneath the text which shows what it was
  75 recognised as.
  76
  77 *You should check the alleged context before entering a character*.
  78 If it is wrong, you should fix it, rather that just making an entry
  79 for the uppercase letter in the lowercase dictionary.
  80
  81 Instead, make a new glyph for the last letter of the previous word
  82 plus the (unusually narrow) inter-word space, and end that entry with
  83 a literal space ` '.
  84
  85 For example, you might find that `y<space>G' is treated as
  86 `y<??lowercase>' and the G doesn't get matched.  Select the `y<space>'
  87 region of the bitmap and type `y ' into the string box.
  88
  89
  90 Overlapping characters - ligatures
  91 ----------------------------------
  92
  93 Some of the characters in the font used overlap with the next
  94 character.  When this happens, select both the characters and enter
  95 them together as one glyph with a multi-character definition, as a new
  96 entry in the Lower or Upper dictionary.
  97
  98 For example `yw' is rendered with the top right corner of the `y' and
  99 the top left corner of the `w' overlapping.  This is dealt with by
 100 matching the whole merged thing - select the region of the screen
 101 containing `yw' and define it as `yw'.
 102
 103
 104 Fixing mistakes
 105 ---------------
 106
 107 The OCR query UI allows you to delete things from the glyph
 108 dictionary.  However since you are not guaranteed to actually get an
 109 OCR query at all (and since it is not possible to override the
 110 presence of an entry in the master database with the absence of one in
 111 the local database), if the dictionary contains errors, you shouldn't
 112 rely on this.
 113
 114 If you think you have made mistakes answering OCR queries (for
 115 example, the recognised data is wrong), you should delete the file
 116 #local-char*#.txt, which contains your local updates.  It will then
 117 only use the centrally provided (and vetted) master file (which is
 118 automatically updated when you run the PCTB client, by default).
 119
 120
 121 Enabling interactive character set update
 122 -----------------------------------------
 123
 124 Now that you have read this document, you should rerun your OCR job
 125 with the --edit-charset option.  You probably want to supply --same as
 126 well, to avoid having to wait for it to page through and recapture all
 127 the screenshots.  So, this time,
 128    ./ypp-commodities --edit-charset --same
 129 and in future, just always run it with the --edit-charset option.
 130
 131 With --edit-charset, when the OCR finds characters it does not
 132 understand, it will put up an OCR resolution query window.  This will
 133 display the part of the text it is having trouble with, showing where
 134 it has got to, and allow you to edit the character set dictionary it
 135 uses for recognising the text.
 136
 137 The process is subtle and it is important to understand the way the
 138 machinery works, and the possible mistakes you can make, before
 139 answering the program.  So *Please read this documentation*, which
 140 explains the meaning of the entries you make.
 141
 142 Be sure to check or specify the dictionary to which the new glyph
 143 should be added.  Normally the default will be the Word dictionary
 144 which is right if the match failure is a new word starting with l or I
 145 (see above).  You will need to change this to the Upper or Lower
 146 dictionary for new ligatures.  You should not need to add new Digits.
 147
 148 Also, the character set updates you make will by default be submitted
 149 to my server so that they can be checked by me and shared with other
 150 users.  See README.privacy.
 151
 152 If you need help please ask me (ijackson@chiark.greenend.org.uk, or
 153 Aristarchus on Midnight in game if I'm on line, or ask any pirate of
 154 the crew Special Circumstances if they happen to know where I am
 155 and/or can get in touch).