README.md 13.9 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

HinGwenWoong's avatar
HinGwenWoong committed
11
12
13
14
15
16
17
18
19
20
- 2022.01:(by [PeterH0323](https://github.com/peterh0323)
  - Optimize multiple Chinese prompt messages
  - Optimize software startup
  - Change the shortcut key for deletion to [Alt + x]
  - New feature: Add the number of pictures and the number of currently displayed pictures in the [file list]
  - New feature: Add time display when [Auto Label]
  - New feature: use the shortcut keys [x] and [C] to rotate the box
  - Fixed: After automatic recognition, rotating the picture directly without clicking on the file list will cause an error: the array exceeds the index
  - Fixed: When zooming in and out with the shortcut keys, the zoom slider will not change
  - Fixed: When using paddlepaddle-gpu to automatically label, the CPU is still used for infer
21
22
23
24
- 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
25
26
  - 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))
27
- 2021.2.5: New batch processing and undo functions (by [Evezerest](https://github.com/Evezerest)):
Leif's avatar
Leif committed
28
29
  - **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.
30
  - 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)).
31
- 2021.1.11: Optimize the labeling experience (by [edencfc](https://github.com/edencfc)),
WenmuZhou's avatar
WenmuZhou committed
32
  - Users can choose whether to pop up the label input dialog after drawing the detection box in "View - Pop-up Label Input Dialog".
33
34
  - 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)
35
36
- 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
37

grasswolfs's avatar
grasswolfs committed
38

39
40
41
## 1. Installation and Run

### 1.1 Install PaddlePaddle
Leif's avatar
Leif committed
42
43
44
45
46

```bash
pip3 install --upgrade pip

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

# If you only have cpu on your machine, please run the following command to install
50
python3 -m pip install paddlepaddle -i https://mirror.baidu.com/pypi/simple
Leif's avatar
Leif committed
51
52
53
54
```

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

55
### 1.2 Install and Run PPOCRLabel
Leif's avatar
Leif committed
56

57
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
58

59
#### Windows
Leif's avatar
Leif committed
60
61

```bash
62
63
pip install PPOCRLabel  # install
PPOCRLabel  # run
Leif's avatar
Leif committed
64
65
```

66
67
68
69
> 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
70

71
#### Ubuntu Linux
Leif's avatar
Leif committed
72

73
74
75
76
77
```bash
pip3 install PPOCRLabel
pip3 install trash-cli
PPOCRLabel
```
grasswolfs's avatar
grasswolfs committed
78

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

86
#### 1.2.2 Build and Install the Whl Package Locally
Leif's avatar
Leif committed
87

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

94
95
#### 1.2.3 Run PPOCRLabel by Python Script

Leif's avatar
Leif committed
96
```bash
97
cd ./PPOCRLabel  # Switch to the PPOCRLabel directory
Leif's avatar
Leif committed
98
python PPOCRLabel.py
Leif's avatar
Leif committed
99
100
```

101
102


Leif's avatar
Leif committed
103
## 2. Usage
grasswolfs's avatar
grasswolfs committed
104

Leif's avatar
Leif committed
105
### 2.1 Steps
grasswolfs's avatar
grasswolfs committed
106
107
108
109
110
111
112
113
114
115

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
116

Leif's avatar
Leif committed
117
   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
118

grasswolfs's avatar
grasswolfs committed
119
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
120

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

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

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

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

Leif's avatar
Leif committed
129
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
130

131
### 2.2 Note
grasswolfs's avatar
grasswolfs committed
132
133
134
135
136

[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 "√".

137
[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
138
139
140
141

[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
142
| :-----------: | :----------------------------------------------------------: |
Leif's avatar
Leif committed
143
|   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
144
145
| 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
146
|  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
147
148
|   crop_img    | The recognition data, generated at the same time with *rec_gt.txt* |

149
150


Leif's avatar
Leif committed
151
## 3. Explanation
grasswolfs's avatar
grasswolfs committed
152

Leif's avatar
Leif committed
153
### 3.1 Shortcut keys
154

155
| Shortcut keys            | Description                                      |
HinGwenWoong's avatar
HinGwenWoong committed
156
|--------------------------|--------------------------------------------------|
157
158
159
| 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
160
161
| X                        | Rotate the box anti-clockwise                    |
| C                        | Rotate the box clockwise                         |
162
163
164
165
| Ctrl + E                 | Edit label of the selected box                   |
| Ctrl + R                 | Re-recognize the selected box                    |
| Ctrl + C                 | Copy and paste the selected box                  |
| Ctrl + Left Mouse Button | Multi select the label box                       |
166
| Ctrl + X                 | Delete the selected box                          |
167
168
169
170
171
172
173
| Ctrl + V                 | Check image                                      |
| Ctrl + Shift + d         | Delete image                                     |
| D                        | Next image                                       |
| A                        | Previous image                                   |
| Ctrl++                   | Zoom in                                          |
| Ctrl--                   | Zoom out                                         |
| ↑→↓←                     | Move selected box                                |
174

Leif's avatar
Leif committed
175
### 3.2 Built-in Model
grasswolfs's avatar
grasswolfs committed
176
177
178

- 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
179
- 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
180
  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
181

Leif's avatar
Leif committed
182
183
184
- **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/release/ 2.3/PPOCRLabel/PPOCRLabel.py#L116) :

  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
185

Leif's avatar
Leif committed
186
### 3.3 Export Label Result
Leif's avatar
Leif committed
187

Leif's avatar
Leif committed
188
PPOCRLabel supports three ways to export Label.txt
Leif's avatar
Leif committed
189

Leif's avatar
Leif committed
190
- 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
191
192
193

  > The automatically export mode is turned off by default

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

Leif's avatar
Leif committed
196
- Close application export
Leif's avatar
Leif committed
197
198


Leif's avatar
Leif committed
199
### 3.4 Export Partial Recognition Results
Leif's avatar
Leif committed
200

Leif's avatar
Leif committed
201
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
202

Leif's avatar
Leif committed
203
> *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
204

205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
### 3.5 Dataset division

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

  ```
  cd ./PPOCRLabel # Change the directory to the PPOCRLabel folder
  python gen_ocr_train_val_test.py --trainValTestRatio 6:2:2 --labelRootPath ../train_data/label --detRootPath ../train_data/det --recRootPath ../train_data/rec
  ```

  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`

  - `labelRootPath` is the storage path of the dataset labeled by PPOCRLabel, the default is `../train_data/label`

  - `detRootPath` is the path where the text detection dataset is divided according to the dataset marked by PPOCRLabel. The default is `../train_data/det`

  - `recRootPath` is the path where the character recognition dataset is divided according to the dataset marked by PPOCRLabel. The default is `../train_data/rec`

### 3.6 Error message
Leif's avatar
Leif committed
225

grasswolfs's avatar
grasswolfs committed
226
- 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
227

grasswolfs's avatar
grasswolfs committed
228
- 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
229

grasswolfs's avatar
grasswolfs committed
230
231
232
233
234
235
236
    ```
    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
237
- 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
238
    ```
WenmuZhou's avatar
WenmuZhou committed
239
    pip install opencv-contrib-python-headless==4.2.0.32
Leif's avatar
Leif committed
240
    ```
WenmuZhou's avatar
WenmuZhou committed
241

–MrCuiHao's avatar
MrCuiHao committed
242
243


244
### 4. Related
Leif's avatar
Leif committed
245

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