README.markdown 8.04 KB
Newer Older
Jerome Flesch's avatar
Jerome Flesch committed
1 2
# PyOCR

3
PyOCR is an optical character recognition (OCR) tool wrapper for python.
Jerome Flesch's avatar
Jerome Flesch committed
4
That is, it helps using various OCR tools from a Python program.
Jerome Flesch's avatar
Jerome Flesch committed
5 6

It has been tested only on GNU/Linux systems. It should also work on similar
7
systems (*BSD, etc). It may or may not work on Windows, MacOSX, etc.
Jerome Flesch's avatar
Jerome Flesch committed
8 9


10 11
## Supported OCR tools

Jerome Flesch's avatar
Jerome Flesch committed
12 13 14
* Libtesseract (Python bindings for the C API)
* Tesseract (wrapper: fork + exec)
* Cuneiform (wrapper: fork + exec)
15

Jerome Flesch's avatar
Jerome Flesch committed
16 17
## Features

Jerome Flesch's avatar
Jerome Flesch committed
18 19 20 21 22
* Supports all the image formats supported by [Pillow](https://github.com/python-imaging/Pillow),
  including jpeg, png, gif, bmp, tiff and others
* Various output types: text only, bounding boxes, etc.
* Orientation detection (Tesseract and libtesseract only)
* Can focus on digits only (Tesseract and libtesseract only)
Jerome Flesch's avatar
Jerome Flesch committed
23
* Can save and reload boxes in hOCR format
Jerome Flesch's avatar
Jerome Flesch committed
24
* PDF generation (libtesseract only)
Jerome Flesch's avatar
Jerome Flesch committed
25

26

Jerome Flesch's avatar
Jerome Flesch committed
27 28
## Limitations

Jerome Flesch's avatar
Jerome Flesch committed
29 30
* hOCR: Only a subset of the specification is supported. For instance, pages and
  paragraph positions are not stored.
31

32 33 34 35

## Installation

```sh
36 37
sudo pip install pyocr  # Python 2.7
sudo pip3 install pyocr  # Python 3.X
38 39 40 41
```

or the manual way:
```sh
42
mkdir -p ~/git ; cd git
43
git clone https://github.com/openpaperwork/pyocr.git
44 45
cd pyocr
sudo python ./setup.py install
46 47 48
```


Jerome Flesch's avatar
Jerome Flesch committed
49
## Usage
50 51 52

### Initialization

53 54 55 56 57 58 59 60 61 62 63
```Python
from PIL import Image
import sys

import pyocr
import pyocr.builders

tools = pyocr.get_available_tools()
if len(tools) == 0:
    print("No OCR tool found")
    sys.exit(1)
Jerome Flesch's avatar
Jerome Flesch committed
64
# The tools are returned in the recommended order of usage
65 66
tool = tools[0]
print("Will use tool '%s'" % (tool.get_name()))
Jerome Flesch's avatar
Jerome Flesch committed
67
# Ex: Will use tool 'libtesseract'
68 69 70 71 72 73

langs = tool.get_available_languages()
print("Available languages: %s" % ", ".join(langs))
lang = langs[0]
print("Will use lang '%s'" % (lang))
# Ex: Will use lang 'fra'
74 75 76 77
# Note that languages are NOT sorted in any way. Please refer
# to the system locale settings for the default language
# to use.
```
78

79 80 81
### Image to text

```Python
82 83 84 85 86
txt = tool.image_to_string(
    Image.open('test.png'),
    lang=lang,
    builder=pyocr.builders.TextBuilder()
)
87
# txt is a Python string
88

89 90
word_boxes = tool.image_to_string(
    Image.open('test.png'),
Yada's avatar
Yada committed
91
    lang="eng",
92 93
    builder=pyocr.builders.WordBoxBuilder()
)
94 95 96 97 98 99
# list of box objects. For each box object:
#   box.content is the word in the box
#   box.position is its position on the page (in pixels)
#
# Beware that some OCR tools (Tesseract for instance)
# may return empty boxes
100

101
line_and_word_boxes = tool.image_to_string(
102
    Image.open('test.png'), lang="fra",
103 104
    builder=pyocr.builders.LineBoxBuilder()
)
105 106 107 108 109 110 111
# list of line objects. For each line object:
#   line.word_boxes is a list of word boxes (the individual words in the line)
#   line.content is the whole text of the line
#   line.position is the position of the whole line on the page (in pixels)
#
# Beware that some OCR tools (Tesseract for instance)
# may return empty boxes
Jerome Flesch's avatar
Jerome Flesch committed
112

Jerome Flesch's avatar
Jerome Flesch committed
113
# Digits - Only Tesseract (not 'libtesseract' yet !)
114 115 116 117 118
digits = tool.image_to_string(
    Image.open('test-digits.png'),
    lang=lang,
    builder=pyocr.tesseract.DigitBuilder()
)
119
# digits is a python string
120 121
```

Jerome Flesch's avatar
Jerome Flesch committed
122
Argument 'lang' is optional. The default value depends of
123
the tool used.
Jerome Flesch's avatar
Jerome Flesch committed
124

Jerome Flesch's avatar
Jerome Flesch committed
125
Argument 'builder' is optional. Default value is
126 127
builders.TextBuilder().

Jerome Flesch's avatar
Jerome Flesch committed
128 129 130 131 132 133
If the OCR fails, an exception ```pyocr.PyocrException```
will be raised.

An exception MAY be raised if the input image contains no
text at all (depends on the OCR tool behavior).

134 135 136 137 138 139 140

### Orientation detection

Currently only available with Tesseract or Libtesseract.

```Python
if tool.can_detect_orientation():
Jerome Flesch's avatar
Jerome Flesch committed
141 142 143 144 145 146 147 148 149
    try:
        orientation = tool.detect_orientation(
            Image.open('test.png'),
            lang='fra'
        )
    except pyocr.PyocrException as exc:
        print("Orientation detection failed: {}".format(exc))
        return
    print("Orientation: {}".format(orientation))
150 151 152 153
# Ex: Orientation: {
#   'angle': 90,
#   'confidence': 123.4,
# }
154
```
155

156 157 158 159 160 161 162 163 164 165
Angles are given in degrees (range: [0-360[). Exact possible
values depend of the tool used. Tesseract only returns angles =
0, 90, 180, 270.

Confidence is a score arbitrarily defined by the tool. It MAY not
be returned.

detect_orientation() MAY raise an exception if there is no text
detected in the image.

166

Jerome Flesch's avatar
Jerome Flesch committed
167
### Writing and reading text files
168 169 170 171 172 173 174 175

Writing:

```Python
import codecs
import pyocr
import pyocr.builders

176
tool = pyocr.get_available_tools()[0]
177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202
builder = pyocr.builders.TextBuilder()

txt = tool.image_to_string(
    Image.open('test.png'),
    lang=lang,
    builder=builder
)
# txt is a Python string

with codecs.open("toto.txt", 'w', encoding='utf-8') as file_descriptor:
    builder.write_file(file_descriptor, txt)
# toto.txt is a simple text file, encoded in utf-8
```

Reading:

```Python
import codecs
import pyocr.builders

builder = pyocr.builders.TextBuilder()
with codecs.open("toto.txt", 'r', encoding='utf-8') as file_descriptor:
    txt = builder.read_file(file_descriptor)
# txt is a Python string
```

Jerome Flesch's avatar
Jerome Flesch committed
203
### Writing and reading hOCR files
204 205 206 207 208 209 210 211

Writing:

```Python
import codecs
import pyocr
import pyocr.builders

212
tool = pyocr.get_available_tools()[0]
213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239
builder = pyocr.builders.LineBoxBuilder()

line_boxes = tool.image_to_string(
    Image.open('test.png'),
    lang=lang,
    builder=builder
)
# list of LineBox (each box points to a list of word boxes)

with codecs.open("toto.html", 'w', encoding='utf-8') as file_descriptor:
    builder.write_file(file_descriptor, line_boxes)
# toto.html is a valid XHTML file
```

Reading:

```Python
import codecs
import pyocr.builders

builder = pyocr.builders.LineBoxBuilder()
with codecs.open("toto.html", 'r', encoding='utf-8') as file_descriptor:
    line_boxes = builder.read_file(file_descriptor)
# list of LineBox (each box points to a list of word boxes)
```


240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257
### Generating PDF file from an image

With libtesseract >= 4, it's possible to generate a PDF from an image:

```Python
import PIL.Image
import pyocr

pyocr.libtesseract.image_to_pdf(
    PIL.Image.open("image.jpg"),
    "output_filename"  # .pdf will be appended
)

```

Beware this code hasn't been adapted to libtesseract 3 yet.


Jerome Flesch's avatar
Jerome Flesch committed
258
## Dependencies
Jerome Flesch's avatar
Jerome Flesch committed
259

Jerome Flesch's avatar
Jerome Flesch committed
260
* PyOCR requires python 2.7 or later. Python 3 is supported.
Jerome Flesch's avatar
Jerome Flesch committed
261
* You will need [Pillow](https://github.com/python-imaging/Pillow)
262 263 264
  or Python Imaging Library (PIL). Under Debian/Ubuntu, Pillow is in
  the package ```python-pil``` (```python3-pil``` for the Python 3
  version).
Jerome Flesch's avatar
Jerome Flesch committed
265
* Install an OCR:
Jerome Flesch's avatar
Jerome Flesch committed
266 267 268
  * [libtesseract](http://code.google.com/p/tesseract-ocr/)
    ('libtesseract3' + 'tesseract-ocr-<lang>' in Debian).
  * or [tesseract-ocr](http://code.google.com/p/tesseract-ocr/)
Jerome Flesch's avatar
Jerome Flesch committed
269 270
    ('tesseract-ocr' + 'tesseract-ocr-<lang>' in Debian).
    You must be able to invoke the tesseract command as "tesseract".
Jerome Flesch's avatar
Jerome Flesch committed
271
    PyOCR is tested with Tesseract >= 3.01 only.
272
  * or Cuneiform
Jerome Flesch's avatar
Jerome Flesch committed
273 274


Jerome Flesch's avatar
Jerome Flesch committed
275
## Tests
Jerome Flesch's avatar
Jerome Flesch committed
276

277 278 279
```sh
python ./run_tests.py
```
280

Jerome Flesch's avatar
Jerome Flesch committed
281
Tests are made to be run with the latest versions of Tesseract and Cuneiform.
282 283
the first tests verify that you're using the expected version.

Jerome Flesch's avatar
Jerome Flesch committed
284
To run the tesseract tests, you will need the following lang data files:
285 286 287
- English (tesseract-ocr-eng)
- French (tesseract-ocr-fra)
- Japanese (tesseract-ocr-jpn)
Jerome Flesch's avatar
Jerome Flesch committed
288 289


290 291 292 293
## OCR on natural scenes

If you want to run OCR on natural scenes (photos, etc), you will have to filter
the image first. There are many algorithms possible to do that. One of those
294
who gives the best results is
295
[Stroke Width Transform](https://github.com/openpaperwork/libpillowfight#stroke-width-transformation).
296 297


298 299
## Contact

300 301
* [Mailing-list](https://github.com/openpaperwork/paperwork/wiki/Contact#mailing-list)
* [Bug tracker](https://github.com/openpaperwork/pyocr/issues/)
302 303


304 305
## Applications that use PyOCR

306
* [Mayan EDMS](http://mayan-edms.com/)
307
* [Paperless](https://github.com/danielquinn/paperless#readme)
308
* [Paperwork](https://github.com/openpaperwork/paperwork#readme)
309 310

If you know of any other applications that use Pyocr, please
311
[tell us](https://github.com/openpaperwork/paperwork/wiki/Contact#mailing-list) :-)
312

Jerome Flesch's avatar
Jerome Flesch committed
313
## Copyright
Jerome Flesch's avatar
Jerome Flesch committed
314

315
PyOCR is released under the GPL v3+.
316 317 318
Copyright belongs to the authors of each piece of code
(see the file AUTHORS for the contributors list, and
```git blame``` to know which lines belong to which author).
Jerome Flesch's avatar
Jerome Flesch committed
319

320
https://github.com/openpaperwork/pyocr