README.markdown 8.25 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.
4
That is, it helps using various OCR tools from a Python program.
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.
8 9


10 11
## Supported OCR tools

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

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
24
* PDF generation (libtesseract only)
Jerome Flesch's avatar
Jerome Flesch committed
25

26

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

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://gitlab.gnome.org/World/OpenPaperwork/pyocr.git
44
cd pyocr
45
make install  # will run '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
# 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)
#
Jerome Flesch's avatar
Jerome Flesch committed
110 111 112 113 114 115 116
# Each word box object has an attribute 'confidence' giving the confidence
# score provided by the OCR tool. Confidence score depends entirely on
# the OCR tool. Only supported with Tesseract and Libtesseract (always 0
# with Cuneiform).
#
# Beware that some OCR tools (Tesseract for instance) may return boxes
# with an empty content.
117

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

Jerome Flesch's avatar
Jerome Flesch committed
127
Argument 'lang' is optional. The default value depends of
128
the tool used.
129

Jerome Flesch's avatar
Jerome Flesch committed
130
Argument 'builder' is optional. Default value is
131 132
builders.TextBuilder().

133 134 135 136 137 138
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).

139 140 141 142 143 144 145

### Orientation detection

Currently only available with Tesseract or Libtesseract.

```Python
if tool.can_detect_orientation():
146 147 148 149 150 151 152 153 154
    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))
155 156 157 158
# Ex: Orientation: {
#   'angle': 90,
#   'confidence': 123.4,
# }
159
```
160

161 162 163 164 165 166 167 168 169 170
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.

171

Jerome Flesch's avatar
Jerome Flesch committed
172
### Writing and reading text files
173 174 175 176 177 178 179 180

Writing:

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

181
tool = pyocr.get_available_tools()[0]
182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207
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
208
### Writing and reading hOCR files
209 210 211 212 213 214 215 216

Writing:

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

217
tool = pyocr.get_available_tools()[0]
218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244
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)
```


245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262
### 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
263
## Dependencies
264

Jerome Flesch's avatar
Jerome Flesch committed
265
* PyOCR requires python 2.7 or later. Python 3 is supported.
266
* You will need [Pillow](https://github.com/python-imaging/Pillow)
267 268 269
  or Python Imaging Library (PIL). Under Debian/Ubuntu, Pillow is in
  the package ```python-pil``` (```python3-pil``` for the Python 3
  version).
270
* Install an OCR:
Jerome Flesch's avatar
Jerome Flesch committed
271 272 273
  * [libtesseract](http://code.google.com/p/tesseract-ocr/)
    ('libtesseract3' + 'tesseract-ocr-<lang>' in Debian).
  * or [tesseract-ocr](http://code.google.com/p/tesseract-ocr/)
274 275
    ('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
276
    PyOCR is tested with Tesseract >= 3.01 only.
277
  * or Cuneiform
278 279


Jerome Flesch's avatar
Jerome Flesch committed
280
## Tests
281

282
```sh
283
make check  # requires pyflake8
Thomas Perret's avatar
Thomas Perret committed
284
make test  # requires tox, pytest and python3
285
```
286

Thomas Perret's avatar
Thomas Perret committed
287
Tests are made to be run without external dependencies (no Tesseract or Cuneiform needed).
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 295
who gives the best results is [Stroke Width
Transform](https://gitlab.gnome.org/World/OpenPaperwork/libpillowfight#stroke-width-transformation).
296 297


298 299
## Contact

300 301
* [Mailing-list](https://gitlab.gnome.org/World/OpenPaperwork/paperwork/wikis/Contact#mailing-list)
* [Bug tracker](https://gitlab.gnome.org/World/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://gitlab.gnome.org/World/OpenPaperwork/paperwork#readme)
309 310

If you know of any other applications that use Pyocr, please
311
[tell us](https://gitlab.gnome.org/World/OpenPaperwork/paperwork/wikis/Contact#mailing-list) :-)
312

Jerome Flesch's avatar
Jerome Flesch committed
313
## Copyright
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).
319

320
https://gitlab.gnome.org/World/OpenPaperwork/pyocr