quickstart_en.md 11.5 KB
Newer Older
WenmuZhou's avatar
WenmuZhou committed
1
- [PaddleOCR Quick Start](#paddleocr-quick-start)
WenmuZhou's avatar
WenmuZhou committed
2
3
4
  - [1. Installation](#1-installation)
    - [1.1 Install PaddlePaddle](#11-install-paddlepaddle)
    - [1.2 Install PaddleOCR Whl Package](#12-install-paddleocr-whl-package)
WenmuZhou's avatar
WenmuZhou committed
5
6
7
8
9
10
11
12
  - [2. Easy-to-Use](#2-easy-to-use)
    - [2.1 Use by Command Line](#21-use-by-command-line)
      - [2.1.1 Chinese and English Model](#211-chinese-and-english-model)
      - [2.1.2 Multi-language Model](#212-multi-language-model)
      - [2.1.3 Layout Analysis](#213-layout-analysis)
    - [2.2 Use by Code](#22-use-by-code)
      - [2.2.1 Chinese & English Model and Multilingual Model](#221-chinese--english-model-and-multilingual-model)
      - [2.2.2 Layout Analysis](#222-layout-analysis)
WenmuZhou's avatar
WenmuZhou committed
13
  - [3. Summary](#3-summary)
littletomatodonkey's avatar
littletomatodonkey committed
14

Leif's avatar
Leif committed
15
# PaddleOCR Quick Start
littletomatodonkey's avatar
littletomatodonkey committed
16
17


Leif's avatar
Leif committed
18
<a name="1nstallation"></a>
littletomatodonkey's avatar
littletomatodonkey committed
19

Leif's avatar
Leif committed
20
## 1. Installation
littletomatodonkey's avatar
littletomatodonkey committed
21

Leif's avatar
Leif committed
22
<a name="11-install-paddlepaddle"></a>
WenmuZhou's avatar
WenmuZhou committed
23

Leif's avatar
Leif committed
24
25
26
### 1.1 Install PaddlePaddle

> If you do not have a Python environment, please refer to [Environment Preparation](./environment_en.md).
littletomatodonkey's avatar
littletomatodonkey committed
27

Leif's avatar
Leif committed
28
- If you have CUDA 9 or CUDA 10 installed on your machine, please run the following command to install
littletomatodonkey's avatar
littletomatodonkey committed
29

Leif's avatar
Leif committed
30
31
32
33
34
35
36
37
38
  ```bash
  python3 -m pip install paddlepaddle-gpu -i https://mirror.baidu.com/pypi/simple
  ```

- If you have no available GPU on your machine, please run the following command to install the CPU version

  ```bash
  python3 -m pip install paddlepaddle -i https://mirror.baidu.com/pypi/simple
  ```
littletomatodonkey's avatar
littletomatodonkey committed
39

Leif's avatar
Leif committed
40
For more software version requirements, please refer to the instructions in [Installation Document](https://www.paddlepaddle.org.cn/install/quick) for operation.
WenmuZhou's avatar
WenmuZhou committed
41

Leif's avatar
Leif committed
42
43
44
<a name="12-install-paddleocr-whl-package"></a>

### 1.2 Install PaddleOCR Whl Package
Leif's avatar
Leif committed
45
46
47

```bash
pip install "paddleocr>=2.0.1" # Recommend to use version 2.0.1+
littletomatodonkey's avatar
littletomatodonkey committed
48
49
```

Leif's avatar
Leif committed
50
- **For windows users:** If you getting this error `OSError: [WinError 126] The specified module could not be found` when you install shapely on windows. Please try to download Shapely whl file [here](http://www.lfd.uci.edu/~gohlke/pythonlibs/#shapely).
Leif's avatar
Leif committed
51

Leif's avatar
Leif committed
52
  Reference: [Solve shapely installation on windows](https://stackoverflow.com/questions/44398265/install-shapely-oserror-winerror-126-the-specified-module-could-not-be-found)
Leif's avatar
Leif committed
53

Leif's avatar
Leif committed
54
- **For layout analysis users**, run the following command to install **Layout-Parser**
littletomatodonkey's avatar
littletomatodonkey committed
55

Leif's avatar
Leif committed
56
57
58
59
60
61
62
63
64
65
  ```bash
  pip3 install -U https://paddleocr.bj.bcebos.com/whl/layoutparser-0.0.0-py3-none-any.whl
  ```

<a name="2-easy-to-use"></a>

## 2. Easy-to-Use

<a name="21-use-by-command-line"></a>

66
### 2.1 Use by Command Line
Leif's avatar
Leif committed
67

Leif's avatar
Leif committed
68
PaddleOCR provides a series of test images, click [here](https://paddleocr.bj.bcebos.com/dygraph_v2.1/ppocr_img.zip) to download, and then switch to the corresponding directory in the terminal
Leif's avatar
Leif committed
69
70

```bash
Leif's avatar
Leif committed
71
cd /path/to/ppocr_img
littletomatodonkey's avatar
littletomatodonkey committed
72
```
Leif's avatar
Leif committed
73

Leif's avatar
Leif committed
74
If you do not use the provided test image, you can replace the following `--image_dir` parameter with the corresponding test image path
Leif's avatar
Leif committed
75

Leif's avatar
Leif committed
76
<a name="211-english-and-chinese-model"></a>
Leif's avatar
Leif committed
77

Leif's avatar
Leif committed
78
#### 2.1.1 Chinese and English Model
Leif's avatar
Leif committed
79

80
* Detection, direction classification and recognition: set the parameter`--use_gpu false` to disable the gpu device
Leif's avatar
Leif committed
81

Leif's avatar
Leif committed
82
  ```bash
83
  paddleocr --image_dir ./imgs_en/img_12.jpg --use_angle_cls true --lang en --use_gpu false --rec_image_shape 3,48,320
Leif's avatar
Leif committed
84
  ```
littletomatodonkey's avatar
littletomatodonkey committed
85

Leif's avatar
Leif committed
86
  Output will be a list, each item contains bounding box, text and recognition confidence
littletomatodonkey's avatar
littletomatodonkey committed
87

Leif's avatar
Leif committed
88
  ```bash
89
90
91
  [[[441.0, 174.0], [1166.0, 176.0], [1165.0, 222.0], [441.0, 221.0]], ('ACKNOWLEDGEMENTS', 0.9971134662628174)]
  [[[403.0, 346.0], [1204.0, 348.0], [1204.0, 384.0], [402.0, 383.0]], ('We would like to thank all the designers and', 0.9761400818824768)]
  [[[403.0, 396.0], [1204.0, 398.0], [1204.0, 434.0], [402.0, 433.0]], ('contributors who have been involved in the', 0.9791957139968872)]
Leif's avatar
Leif committed
92
93
94
95
96
97
98
99
  ......
  ```

* Only detection: set `--rec` to `false`

  ```bash
  paddleocr --image_dir ./imgs_en/img_12.jpg --rec false
  ```
Leif's avatar
Leif committed
100

Leif's avatar
Leif committed
101
102
103
  Output will be a list, each item only contains bounding box

  ```bash
104
105
106
  [[397.0, 802.0], [1092.0, 802.0], [1092.0, 841.0], [397.0, 841.0]]
  [[397.0, 750.0], [1211.0, 750.0], [1211.0, 789.0], [397.0, 789.0]]
  [[397.0, 702.0], [1209.0, 698.0], [1209.0, 734.0], [397.0, 738.0]]
Leif's avatar
Leif committed
107
108
109
110
111
112
  ......
  ```

* Only recognition: set `--det` to `false`

  ```bash
113
  paddleocr --image_dir ./imgs_words_en/word_10.png --det false --lang en --rec_image_shape 3,48,320
Leif's avatar
Leif committed
114
115
116
117
118
  ```

  Output will be a list, each item contains text and recognition confidence

  ```bash
119
  ['PAIN', 0.9934559464454651]
Leif's avatar
Leif committed
120
121
  ```

122
If you need to use the 2.0 model, please specify the parameter `--version PP-OCR`, paddleocr uses the PP-OCRv3 model by default(`--versioin PP-OCRv3`). More whl package usage can be found in [whl package](./whl_en.md)
Leif's avatar
Leif committed
123
<a name="212-multi-language-model"></a>
Leif's avatar
Leif committed
124
125
126

#### 2.1.2 Multi-language Model

127
Paddleocr currently supports 80 languages, which can be switched by modifying the `--lang` parameter. PP-OCRv3 currently only supports Chinese and English models, and other multilingual models will be updated one after another.
Leif's avatar
Leif committed
128
129

``` bash
130
paddleocr --image_dir ./doc/imgs_en/254.jpg --lang=en --rec_image_shape 3,48,320
littletomatodonkey's avatar
littletomatodonkey committed
131
132
```

Leif's avatar
Leif committed
133
134
135
136
137
138
139
<div align="center">
    <img src="../imgs_en/254.jpg" width="300" height="600">
    <img src="../imgs_results/multi_lang/img_02.jpg" width="600" height="600">
</div>
The result is a list, each item contains a text box, text and recognition confidence

```text
140
141
142
[[[67.0, 51.0], [327.0, 46.0], [327.0, 74.0], [68.0, 80.0]], ('PHOCAPITAL', 0.9944712519645691)]
[[[72.0, 92.0], [453.0, 84.0], [454.0, 114.0], [73.0, 122.0]], ('107 State Street', 0.9744491577148438)]
[[[69.0, 135.0], [501.0, 125.0], [501.0, 156.0], [70.0, 165.0]], ('Montpelier Vermont', 0.9357033967971802)]
Leif's avatar
Leif committed
143
144
......
```
littletomatodonkey's avatar
littletomatodonkey committed
145

Leif's avatar
Leif committed
146
Commonly used multilingual abbreviations include
littletomatodonkey's avatar
littletomatodonkey committed
147

Leif's avatar
Leif committed
148
149
150
151
152
| Language            | Abbreviation |      | Language | Abbreviation |      | Language | Abbreviation |
| ------------------- | ------------ | ---- | -------- | ------------ | ---- | -------- | ------------ |
| Chinese & English   | ch           |      | French   | fr           |      | Japanese | japan        |
| English             | en           |      | German   | german       |      | Korean   | korean       |
| Chinese Traditional | chinese_cht  |      | Italian  | it           |      | Russian  | ru           |
littletomatodonkey's avatar
littletomatodonkey committed
153

Leif's avatar
Leif committed
154
A list of all languages and their corresponding abbreviations can be found in [Multi-Language Model Tutorial](./multi_languages_en.md)
Leif's avatar
Leif committed
155
<a name="213-layoutAnalysis"></a>
littletomatodonkey's avatar
littletomatodonkey committed
156

Leif's avatar
Leif committed
157
158
159
#### 2.1.3 Layout Analysis

Layout analysis refers to the division of 5 types of areas of the document, including text, title, list, picture and table. For the first three types of regions, directly use the OCR model to complete the text detection and recognition of the corresponding regions, and save the results in txt. For the table area, after the table structuring process, the table picture is converted into an Excel file of the same table style. The picture area will be individually cropped into an image.
littletomatodonkey's avatar
littletomatodonkey committed
160

Leif's avatar
Leif committed
161
162
163
164
To use the layout analysis function of PaddleOCR, you need to specify `--type=structure`

```bash
paddleocr --image_dir=../doc/table/1.png --type=structure
littletomatodonkey's avatar
littletomatodonkey committed
165
166
```

Leif's avatar
Leif committed
167
- **Results Format**
Leif's avatar
Leif committed
168

Leif's avatar
Leif committed
169
  The returned results of PP-Structure is a list composed of a dict, an example is as follows
Leif's avatar
Leif committed
170

Leif's avatar
Leif committed
171
172
173
174
175
176
177
178
179
  ```shell
  [
    {   'type': 'Text',
        'bbox': [34, 432, 345, 462],
        'res': ([[36.0, 437.0, 341.0, 437.0, 341.0, 446.0, 36.0, 447.0], [41.0, 454.0, 125.0, 453.0, 125.0, 459.0, 41.0, 460.0]],
                  [('Tigure-6. The performance of CNN and IPT models using difforen', 0.90060663), ('Tent  ', 0.465441)])
    }
  ]
  ```
Leif's avatar
Leif committed
180

Leif's avatar
Leif committed
181
  The description of each field in dict is as follows
Leif's avatar
Leif committed
182

Leif's avatar
Leif committed
183
184
185
186
187
  | Parameter | Description                                                  |
  | --------- | ------------------------------------------------------------ |
  | type      | Type of image area                                           |
  | bbox      | The coordinates of the image area in the original image, respectively [left upper x, left upper y, right bottom x, right bottom y] |
  | res       | OCR or table recognition result of image area。<br> Table: HTML string of the table; <br> OCR: A tuple containing the detection coordinates and recognition results of each single line of text |
littletomatodonkey's avatar
littletomatodonkey committed
188

Leif's avatar
Leif committed
189
- **Parameter Description:**
littletomatodonkey's avatar
littletomatodonkey committed
190

Leif's avatar
Leif committed
191
192
193
194
195
  | Parameter       | Description                                                  | Default value                                |
  | --------------- | ------------------------------------------------------------ | -------------------------------------------- |
  | output          | The path where excel and recognition results are saved       | ./output/table                               |
  | table_max_len   | The long side of the image is resized in table structure model | 488                                          |
  | table_model_dir | inference model path of table structure model                | None                                         |
WenmuZhou's avatar
WenmuZhou committed
196
  | table_char_dict_path | dict path of table structure model                           | ../ppocr/utils/dict/table_structure_dict.txt |
Leif's avatar
Leif committed
197

Leif's avatar
Leif committed
198
<a name="22-use-by-code"></a>
Leif's avatar
Leif committed
199

Leif's avatar
Leif committed
200
201
### 2.2 Use by Code
<a name="221-chinese---english-model-and-multilingual-model"></a>
Leif's avatar
Leif committed
202

Leif's avatar
Leif committed
203
#### 2.2.1 Chinese & English Model and Multilingual Model
Leif's avatar
Leif committed
204

Leif's avatar
Leif committed
205
* detection, angle classification and recognition:
Leif's avatar
Leif committed
206

Leif's avatar
Leif committed
207
208
209
210
211
212
213
```python
from paddleocr import PaddleOCR,draw_ocr
# Paddleocr supports Chinese, English, French, German, Korean and Japanese.
# You can set the parameter `lang` as `ch`, `en`, `fr`, `german`, `korean`, `japan`
# to switch the language model in order.
ocr = PaddleOCR(use_angle_cls=True, lang='en') # need to run only once to download and load model into memory
img_path = './imgs_en/img_12.jpg'
Leif's avatar
Leif committed
214
215
216
217
218
result = ocr.ocr(img_path, cls=True)
for line in result:
    print(line)


Leif's avatar
Leif committed
219
220
# draw result
from PIL import Image
Leif's avatar
Leif committed
221
222
223
224
image = Image.open(img_path).convert('RGB')
boxes = [line[0] for line in result]
txts = [line[1][0] for line in result]
scores = [line[1][1] for line in result]
Leif's avatar
Leif committed
225
im_show = draw_ocr(image, boxes, txts, scores, font_path='./fonts/simfang.ttf')
Leif's avatar
Leif committed
226
227
im_show = Image.fromarray(im_show)
im_show.save('result.jpg')
littletomatodonkey's avatar
littletomatodonkey committed
228
```
Leif's avatar
Leif committed
229

Leif's avatar
Leif committed
230
Output will be a list, each item contains bounding box, text and recognition confidence
Leif's avatar
Leif committed
231
232

```bash
233
234
235
236
[[[441.0, 174.0], [1166.0, 176.0], [1165.0, 222.0], [441.0, 221.0]], ('ACKNOWLEDGEMENTS', 0.9971134662628174)]
  [[[403.0, 346.0], [1204.0, 348.0], [1204.0, 384.0], [402.0, 383.0]], ('We would like to thank all the designers and', 0.9761400818824768)]
  [[[403.0, 396.0], [1204.0, 398.0], [1204.0, 434.0], [402.0, 433.0]], ('contributors who have been involved in the', 0.9791957139968872)]
  ......
littletomatodonkey's avatar
littletomatodonkey committed
237
238
```

Leif's avatar
Leif committed
239
Visualization of results
littletomatodonkey's avatar
littletomatodonkey committed
240

Leif's avatar
Leif committed
241
<div align="center">
Leif's avatar
Leif committed
242
    <img src="../imgs_results/whl/12_det_rec.jpg" width="800">
Leif's avatar
Leif committed
243
</div>
Leif's avatar
Leif committed
244
<a name="222-layoutAnalysis"></a>
littletomatodonkey's avatar
littletomatodonkey committed
245

Leif's avatar
Leif committed
246
#### 2.2.2 Layout Analysis
Leif's avatar
Leif committed
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272

```python
import os
import cv2
from paddleocr import PPStructure,draw_structure_result,save_structure_res

table_engine = PPStructure(show_log=True)

save_folder = './output/table'
img_path = './table/1.png'
img = cv2.imread(img_path)
result = table_engine(img)
save_structure_res(result, save_folder,os.path.basename(img_path).split('.')[0])

for line in result:
    line.pop('img')
    print(line)

from PIL import Image

font_path = './fonts/simfang.ttf'
image = Image.open(img_path).convert('RGB')
im_show = draw_structure_result(image, result,font_path=font_path)
im_show = Image.fromarray(im_show)
im_show.save('result.jpg')
```
Leif's avatar
Leif committed
273
274
275
276
277
278
279
280

<a name="3"></a>

## 3. Summary

In this section, you have mastered the use of PaddleOCR whl packages and obtained results.

PaddleOCR is a rich and practical OCR tool library that opens up the whole process of data, model training, compression and inference deployment, so in the [next section](./paddleOCR_overview_en.md) we will first introduce you to the overview of PaddleOCR, and then clone the PaddleOCR project to start the application journey of PaddleOCR.