README.md 14.2 KB
Newer Older
grasswolfs's avatar
grasswolfs committed
1
2
English | [简体中文](README_ch.md)

Leif's avatar
Leif committed
3
4
# PPOCRLabel

Leif's avatar
Leif committed
5
PPOCRLabel is a semi-automatic graphic annotation tool suitable for OCR field, with built-in PPOCR model to automatically detect and re-recognize data. It is written in python3 and pyqt5, supporting rectangular box annotation and four-point annotation modes. Annotations can be directly used for the training of PPOCR detection and recognition models.
Leif's avatar
Leif committed
6

grasswolfs's avatar
grasswolfs committed
7
<img src="./data/gif/steps_en.gif" width="100%"/>
Leif's avatar
Leif committed
8

9
10
### Recent Update

11
- 2022.02:(by [PeterH0323](https://github.com/peterh0323)
HinGwenWoong's avatar
HinGwenWoong committed
12
  - Add KIE Mode by using `--kie`, for [detection + identification + keyword extraction] labeling.
HinGwenWoong's avatar
HinGwenWoong committed
13
- 2022.01:(by [PeterH0323](https://github.com/peterh0323)
HinGwenWoong's avatar
HinGwenWoong committed
14
  - Improve user experience: prompt for the number of files and labels, optimize interaction, and fix bugs such as only use CPU when inference
15
16
17
18
- 2021.11.17:
  - Support install and start PPOCRLabel through the whl package (by [d2623587501](https://github.com/d2623587501))
  - Dataset segmentation: Divide the annotation file into training, verification and testing parts (refer to section 3.5 below, by [MrCuiHao](https://github.com/MrCuiHao))
- 2021.8.11:
Leif's avatar
Leif committed
19
20
  - New functions: Open the dataset folder, image rotation (Note: Please delete the label box before rotating the image) (by [Wei-JL](https://github.com/Wei-JL))
  - Added shortcut key description (Help-Shortcut Key), repaired the direction shortcut key movement function under batch processing (by [d2623587501](https://github.com/d2623587501))
21
- 2021.2.5: New batch processing and undo functions (by [Evezerest](https://github.com/Evezerest)):
Leif's avatar
Leif committed
22
23
  - **Batch processing function**: Press and hold the Ctrl key to select the box, you can move, copy, and delete in batches.
  - **Undo function**: In the process of drawing a four-point label box or after editing the box, press Ctrl+Z to undo the previous operation.
24
  - Fix image rotation and size problems, optimize the process of editing the mark frame (by [ninetailskim](https://github.com/ninetailskim)[edencfc](https://github.com/edencfc)).
25
- 2021.1.11: Optimize the labeling experience (by [edencfc](https://github.com/edencfc)),
WenmuZhou's avatar
WenmuZhou committed
26
  - Users can choose whether to pop up the label input dialog after drawing the detection box in "View - Pop-up Label Input Dialog".
27
28
  - The recognition result scrolls synchronously when users click related detection box.
  - Click to modify the recognition result.(If you can't change the result, please switch to the system default input method, or switch back to the original input method again)
29
30
- 2020.12.18: Support re-recognition of a single label box (by [ninetailskim](https://github.com/ninetailskim) ), perfect shortcut keys.

Leif's avatar
Leif committed
31

grasswolfs's avatar
grasswolfs committed
32

33
34
35
## 1. Installation and Run

### 1.1 Install PaddlePaddle
Leif's avatar
Leif committed
36
37
38
39
40

```bash
pip3 install --upgrade pip

# If you have cuda9 or cuda10 installed on your machine, please run the following command to install
41
python3 -m pip install paddlepaddle-gpu -i https://mirror.baidu.com/pypi/simple
Leif's avatar
Leif committed
42
43

# If you only have cpu on your machine, please run the following command to install
44
python3 -m pip install paddlepaddle -i https://mirror.baidu.com/pypi/simple
Leif's avatar
Leif committed
45
46
47
48
```

For more software version requirements, please refer to the instructions in [Installation Document](https://www.paddlepaddle.org.cn/install/quick) for operation.

49
### 1.2 Install and Run PPOCRLabel
Leif's avatar
Leif committed
50

51
PPOCRLabel can be started in two ways: whl package and Python script. The whl package form is more convenient to start, and the python script to start is convenient for secondary development.
Leif's avatar
Leif committed
52

53
#### Windows
Leif's avatar
Leif committed
54
55

```bash
56
pip install PPOCRLabel  # install
57
58

# Select label mode and run 
HinGwenWoong's avatar
Fix doc  
HinGwenWoong committed
59
60
PPOCRLabel  # [Normal mode] for [detection + recognition] labeling
PPOCRLabel --kie True # [KIE mode] for [detection + recognition + keyword extraction] labeling
Leif's avatar
Leif committed
61
62
```

63
64
65
66
> 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 using http://www.lfd.uci.edu/~gohlke/pythonlibs/#shapely.
>
> 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
67

68
#### Ubuntu Linux
Leif's avatar
Leif committed
69

70
71
72
```bash
pip3 install PPOCRLabel
pip3 install trash-cli
73
74

# Select label mode and run 
HinGwenWoong's avatar
Fix doc  
HinGwenWoong committed
75
76
PPOCRLabel  # [Normal mode] for [detection + recognition] labeling
PPOCRLabel --kie True # [KIE mode] for [detection + recognition + keyword extraction] labeling
77
```
grasswolfs's avatar
grasswolfs committed
78

79
#### MacOS
Leif's avatar
Leif committed
80
```bash
81
82
pip3 install PPOCRLabel
pip3 install opencv-contrib-python-headless==4.2.0.32
83
84

# Select label mode and run 
85
86
PPOCRLabel  # [Normal mode] for [detection + recognition] labeling
PPOCRLabel --kie True # [KIE mode] for [detection + recognition + keyword extraction] labeling
Leif's avatar
Leif committed
87
88
```

89
#### 1.2.2 Build and Install the Whl Package Locally
Leif's avatar
Leif committed
90

Leif's avatar
Leif committed
91
```bash
92
cd PaddleOCR/PPOCRLabel
93
python3 setup.py bdist_wheel
Leif's avatar
Leif committed
94
pip3 install dist/PPOCRLabel-1.0.2-py2.py3-none-any.whl
Leif's avatar
Leif committed
95
96
```

97
98
#### 1.2.3 Run PPOCRLabel by Python Script

Leif's avatar
Leif committed
99
```bash
100
cd ./PPOCRLabel  # Switch to the PPOCRLabel directory
101
102

# Select label mode and run 
103
104
python PPOCRLabel.py  # [Normal mode] for [detection + recognition] labeling
python PPOCRLabel.py --kie True # [KIE mode] for [detection + recognition + keyword extraction] labeling
Leif's avatar
Leif committed
105
106
```

107
108


Leif's avatar
Leif committed
109
## 2. Usage
grasswolfs's avatar
grasswolfs committed
110

Leif's avatar
Leif committed
111
### 2.1 Steps
grasswolfs's avatar
grasswolfs committed
112
113
114
115
116
117
118
119
120
121

1. Build and launch using the instructions above.

2. Click 'Open Dir' in Menu/File to select the folder of the picture.<sup>[1]</sup>

3. Click 'Auto recognition', use PPOCR model to automatically annotate images which marked with 'X' <sup>[2]</sup>before the file name.

4. Create Box:

   4.1 Click 'Create RectBox' or press 'W' in English keyboard mode to draw a new rectangle detection box. Click and release left mouse to select a region to annotate the text area.
Leif's avatar
Leif committed
122

Leif's avatar
Leif committed
123
   4.2 Press 'Q' to enter four-point labeling mode which enables you to create any four-point shape by clicking four points with the left mouse button in succession and DOUBLE CLICK the left mouse as the signal of labeling completion.
Leif's avatar
Leif committed
124

grasswolfs's avatar
grasswolfs committed
125
5. After the marking frame is drawn, the user clicks "OK", and the detection frame will be pre-assigned a "TEMPORARY" label.
Leif's avatar
Leif committed
126

grasswolfs's avatar
grasswolfs committed
127
6. Click 're-Recognition', model will rewrite ALL recognition results in ALL detection box<sup>[3]</sup>.
Leif's avatar
Leif committed
128

HinGwenWoong's avatar
HinGwenWoong committed
129
7. Single click the result in 'recognition result' list to manually change inaccurate recognition results.
Leif's avatar
Leif committed
130

Leif's avatar
Leif committed
131
8. **Click "Check", the image status will switch to "√",then the program automatically jump to the next.**
Leif's avatar
Leif committed
132

grasswolfs's avatar
grasswolfs committed
133
9. Click "Delete Image" and the image will be deleted to the recycle bin.
Leif's avatar
Leif committed
134

Leif's avatar
Leif committed
135
10. Labeling result: the user can export the label result manually through the menu "File - Export Label", while the program will also export automatically if "File - Auto export Label Mode" is selected. The manually checked label will be stored in *Label.txt* under the opened picture folder. Click "File"-"Export Recognition Results" in the menu bar, the recognition training data of such pictures will be saved in the *crop_img* folder, and the recognition label will be saved in *rec_gt.txt*<sup>[4]</sup>.
Leif's avatar
Leif committed
136

137
### 2.2 Note
grasswolfs's avatar
grasswolfs committed
138
139
140
141
142

[1] PPOCRLabel uses the opened folder as the project. After opening the image folder, the picture will not be displayed in the dialog. Instead, the pictures under the folder will be directly imported into the program after clicking "Open Dir".

[2] The image status indicates whether the user has saved the image manually. If it has not been saved manually it is "X", otherwise it is "√", PPOCRLabel will not relabel pictures with a status of "√".

143
[3] After clicking "Re-recognize", the model will overwrite ALL recognition results in the picture. Therefore, if the recognition result has been manually changed before, it may change after re-recognition.
grasswolfs's avatar
grasswolfs committed
144
145
146
147

[4] The files produced by PPOCRLabel can be found under the opened picture folder including the following, please do not manually change the contents, otherwise it will cause the program to be abnormal.

|   File name   |                         Description                          |
Leif's avatar
Leif committed
148
| :-----------: | :----------------------------------------------------------: |
Leif's avatar
Leif committed
149
|   Label.txt   | The detection label file can be directly used for PPOCR detection model training. After the user saves 5 label results, the file will be automatically exported. It will also be written when the user closes the application or changes the file folder. |
grasswolfs's avatar
grasswolfs committed
150
151
| fileState.txt | The picture status file save the image in the current folder that has been manually confirmed by the user. |
|  Cache.cach   |    Cache files to save the results of model recognition.     |
Leif's avatar
Leif committed
152
|  rec_gt.txt   | The recognition label file, which can be directly used for PPOCR identification model training, is generated after the user clicks on the menu bar "File"-"Export recognition result". |
grasswolfs's avatar
grasswolfs committed
153
154
|   crop_img    | The recognition data, generated at the same time with *rec_gt.txt* |

155
156


Leif's avatar
Leif committed
157
## 3. Explanation
grasswolfs's avatar
grasswolfs committed
158

Leif's avatar
Leif committed
159
### 3.1 Shortcut keys
160

161
| Shortcut keys            | Description                                      |
HinGwenWoong's avatar
HinGwenWoong committed
162
|--------------------------|--------------------------------------------------|
163
164
165
| Ctrl + Shift + R         | Re-recognize all the labels of the current image |
| W                        | Create a rect box                                |
| Q                        | Create a four-points box                         |
HinGwenWoong's avatar
HinGwenWoong committed
166
167
| X                        | Rotate the box anti-clockwise                    |
| C                        | Rotate the box clockwise                         |
168
| Ctrl + E                 | Edit label of the selected box                   |
169
| Ctrl + X                 | Change key class of the box when enable `--kie`  |
170
171
172
| Ctrl + R                 | Re-recognize the selected box                    |
| Ctrl + C                 | Copy and paste the selected box                  |
| Ctrl + Left Mouse Button | Multi select the label box                       |
HinGwenWoong's avatar
HinGwenWoong committed
173
| Alt + X                  | Delete the selected box                          |
174
175
176
177
178
179
180
| Ctrl + V                 | Check image                                      |
| Ctrl + Shift + d         | Delete image                                     |
| D                        | Next image                                       |
| A                        | Previous image                                   |
| Ctrl++                   | Zoom in                                          |
| Ctrl--                   | Zoom out                                         |
| ↑→↓←                     | Move selected box                                |
181

Leif's avatar
Leif committed
182
### 3.2 Built-in Model
grasswolfs's avatar
grasswolfs committed
183
184
185

- Default model: PPOCRLabel uses the Chinese and English ultra-lightweight OCR model in PaddleOCR by default, supports Chinese, English and number recognition, and multiple language detection.

WenmuZhou's avatar
WenmuZhou committed
186
- Model language switching: Changing the built-in model language is supportable by clicking "PaddleOCR"-"Choose OCR Model" in the menu bar. Currently supported languages​include French, German, Korean, and Japanese.
grasswolfs's avatar
grasswolfs committed
187
  For specific model download links, please refer to [PaddleOCR Model List](https://github.com/PaddlePaddle/PaddleOCR/blob/develop/doc/doc_en/models_list_en.md#multilingual-recognition-modelupdating)
Leif's avatar
Leif committed
188

189
- **Custom Model**: If users want to replace the built-in model with their own inference model, they can follow the [Custom Model Code Usage](https://github.com/PaddlePaddle/PaddleOCR/blob/release/2.3/doc/doc_en/whl_en.md#31-use-by-code) by modifying PPOCRLabel.py for [Instantiation of PaddleOCR class](https://github.com/PaddlePaddle/PaddleOCR/blob/dygraph/PPOCRLabel/PPOCRLabel.py#L86) :
Leif's avatar
Leif committed
190
191

  add parameter `det_model_dir`  in `self.ocr = PaddleOCR(use_pdserving=False, use_angle_cls=True, det=True, cls=True, use_gpu=gpu, lang=lang) `
Leif's avatar
Leif committed
192

Leif's avatar
Leif committed
193
### 3.3 Export Label Result
Leif's avatar
Leif committed
194

Leif's avatar
Leif committed
195
PPOCRLabel supports three ways to export Label.txt
Leif's avatar
Leif committed
196

Leif's avatar
Leif committed
197
- Automatically export: After selecting "File - Auto Export Label Mode", the program will automatically write the annotations into Label.txt every time the user confirms an image. If this option is not turned on, it will be automatically exported after detecting that the user has manually checked 5 images.
Leif's avatar
Leif committed
198
199
200

  > The automatically export mode is turned off by default

Leif's avatar
Leif committed
201
- Manual export: Click "File-Export Marking Results" to manually export the label.
Leif's avatar
Leif committed
202

Leif's avatar
Leif committed
203
- Close application export
Leif's avatar
Leif committed
204
205


Leif's avatar
Leif committed
206
### 3.4 Export Partial Recognition Results
Leif's avatar
Leif committed
207

Leif's avatar
Leif committed
208
For some data that are difficult to recognize, the recognition results will not be exported by **unchecking** the corresponding tags in the recognition results checkbox. The unchecked recognition result is saved as `True` in the `difficult` variable in the label file `label.txt`.
Leif's avatar
Leif committed
209

Leif's avatar
Leif committed
210
> *Note: The status of the checkboxes in the recognition results still needs to be saved manually by clicking Save Button.*
Leif's avatar
Leif committed
211

212
213
214
215
### 3.5 Dataset division

- Enter the following command in the terminal to execute the dataset division script:

216
    ```
217
  cd ./PPOCRLabel # Change the directory to the PPOCRLabel folder
218
  python gen_ocr_train_val_test.py --trainValTestRatio 6:2:2 --datasetRootPath ../train_data 
219
220
221
222
223
224
  ```

  Parameter Description:

  - `trainValTestRatio` is the division ratio of the number of images in the training set, validation set, and test set, set according to your actual situation, the default is `6:2:2`

225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
  - `datasetRootPath` is the storage path of the complete dataset labeled by PPOCRLabel. The default path is `PaddleOCR/train_data` .
  ```
  |-train_data
    |-crop_img
      |- word_001_crop_0.png
      |- word_002_crop_0.jpg
      |- word_003_crop_0.jpg
      | ...
    | Label.txt
    | rec_gt.txt
    |- word_001.png
    |- word_002.jpg
    |- word_003.jpg
    | ...
  ```
  
241
### 3.6 Error message
Leif's avatar
Leif committed
242

grasswolfs's avatar
grasswolfs committed
243
- If paddleocr is installed with whl, it has a higher priority than calling PaddleOCR class with paddleocr.py, which may cause an exception if whl package is not updated.
Leif's avatar
Leif committed
244

grasswolfs's avatar
grasswolfs committed
245
- For Linux users, if you get an error starting with **objc[XXXXX]** when opening the software, it proves that your opencv version is too high. It is recommended to install version 4.2:
Leif's avatar
Leif committed
246

grasswolfs's avatar
grasswolfs committed
247
248
249
250
251
252
253
    ```
    pip install opencv-python==4.2.0.32
    ```
- If you get an error starting with **Missing string id **,you need to recompile resources:
    ```
    pyrcc5 -o libs/resources.py resources.qrc
    ```
WenmuZhou's avatar
WenmuZhou committed
254
- If you get an error ``` module 'cv2' has no attribute 'INTER_NEAREST'```, you need to delete all opencv related packages first, and then reinstall the 4.2.0.32  version of headless opencv
Leif's avatar
Leif committed
255
    ```
WenmuZhou's avatar
WenmuZhou committed
256
    pip install opencv-contrib-python-headless==4.2.0.32
Leif's avatar
Leif committed
257
    ```
WenmuZhou's avatar
WenmuZhou committed
258

–MrCuiHao's avatar
MrCuiHao committed
259
260


261
### 4. Related
Leif's avatar
Leif committed
262

263
1.[Tzutalin. LabelImg. Git code (2015)](https://github.com/tzutalin/labelImg)