README.md 8.69 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
11
12
### Recent Update

- 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
13
14
15
16
### TODO:
- Lock box mode: For the same scene data, the size and position of the locked detection box can be transferred between different pictures.
- Experience optimization: Add undo, batch operation include move, copy, delete and so on, optimize the annotation process.

grasswolfs's avatar
grasswolfs committed
17
## Installation
Leif's avatar
Leif committed
18

grasswolfs's avatar
grasswolfs committed
19
20
### 1. Install PaddleOCR

Leif's avatar
Leif committed
21
PaddleOCR models has been built in PPOCRLabel, please refer to [PaddleOCR installation document](https://github.com/PaddlePaddle/PaddleOCR/blob/develop/doc/doc_ch/installation.md) to prepare PaddleOCR and make sure it works.
grasswolfs's avatar
grasswolfs committed
22
23

### 2. Install PPOCRLabel
Leif's avatar
Leif committed
24
25
26

#### Windows + Anaconda

grasswolfs's avatar
grasswolfs committed
27
28
Download and install [Anaconda](https://www.anaconda.com/download/#download) (Python 3+)

Leif's avatar
Leif committed
29
```
Leif's avatar
Leif committed
30
pip install pyqt5
grasswolfs's avatar
grasswolfs committed
31
32
cd ./PPOCRLabel # Change the directory to the PPOCRLabel folder
python PPOCRLabel.py
Leif's avatar
Leif committed
33
34
35
36
37
38
39
```

#### Ubuntu Linux

```
pip3 install pyqt5
pip3 install trash-cli
grasswolfs's avatar
grasswolfs committed
40
41
cd ./PPOCRLabel # Change the directory to the PPOCRLabel folder
python3 PPOCRLabel.py
Leif's avatar
Leif committed
42
43
44
45
46
```

#### macOS
```
pip3 install pyqt5
grasswolfs's avatar
grasswolfs committed
47
48
49
50
pip3 uninstall opencv-python # Uninstall opencv manually as it conflicts with pyqt
pip3 install opencv-contrib-python-headless # Install the headless version of opencv
cd ./PPOCRLabel # Change the directory to the PPOCRLabel folder
python3 PPOCRLabel.py
Leif's avatar
Leif committed
51
52
```

grasswolfs's avatar
grasswolfs committed
53
54
55
56
57
58
59
60
61
62
63
64
65
## Usage

### Steps

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
66

Leif's avatar
Leif committed
67
   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
68

grasswolfs's avatar
grasswolfs committed
69
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
70

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

grasswolfs's avatar
grasswolfs committed
73
7. Double click the result in 'recognition result' list to manually change inaccurate recognition results.
Leif's avatar
Leif committed
74

grasswolfs's avatar
grasswolfs committed
75
8. Click "Check", the image status will switch to "√",then the program automatically jump to the next(The results will not be written directly to the file at this time).
Leif's avatar
Leif committed
76

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

grasswolfs's avatar
grasswolfs committed
79
80
10. Labeling result: the user can save manually through the menu "File - Save Label", while the program will also save automatically after every 10 images confirmed by the user.the manually checked label will be stored in *Label.txt* under the opened picture folder.
    Click "PaddleOCR"-"Save 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
81

grasswolfs's avatar
grasswolfs committed
82
83
84
85
86
87
88
89
90
91
92
93
### Note

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

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

[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
94
| :-----------: | :----------------------------------------------------------: |
grasswolfs's avatar
grasswolfs committed
95
96
97
98
99
100
101
102
|   Label.txt   | The detection label file can be directly used for PPOCR detection model training. After the user saves 10 label results, the file will be automatically saved. It will also be written when the user closes the application or changes the file folder. |
| 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.     |
|  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"-"Save recognition result". |
|   crop_img    | The recognition data, generated at the same time with *rec_gt.txt* |

## Explanation

103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
### Shortcut keys

| Shortcut keys    | Description                                      |
| ---------------- | ------------------------------------------------ |
| Ctrl + shift + A | Automatically label all unchecked images         |
| Ctrl + shift + R | Re-recognize all the labels of the current image |
| W                | Create a rect box                                |
| Q                | Create a four-points box                         |
| Ctrl + E         | Edit label of the selected box                   |
| Ctrl + R         | Re-recognize the selected box                    |
| Backspace        | Delete the selected box                          |
| Ctrl + V         | Check image                                      |
| Ctrl + Shift + d | Delete image                                     |
| D                | Next image                                       |
| A                | Previous image                                   |
| Ctrl++           | Zoom in                                          |
| Ctrl--           | Zoom out                                         |
| ↑→↓←             | Move selected box                                |

grasswolfs's avatar
grasswolfs committed
122
123
124
125
### Built-in Model

- 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.

126
- 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
127
  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
128

grasswolfs's avatar
grasswolfs committed
129
- Custom model: The model trained by users can be replaced by modifying PPOCRLabel.py in [PaddleOCR class instantiation](https://github.com/PaddlePaddle/PaddleOCR/blob/develop/PPOCRLabel/PPOCRLabel.py#L110) referring [Custom Model Code](https://github.com/PaddlePaddle/PaddleOCR/blob/develop/doc/doc_en/whl_en.md#use-custom-model)
Leif's avatar
Leif committed
130

grasswolfs's avatar
grasswolfs committed
131
### Export partial recognition results
Leif's avatar
Leif committed
132

grasswolfs's avatar
grasswolfs committed
133
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.
Leif's avatar
Leif committed
134

grasswolfs's avatar
grasswolfs committed
135
*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
136

grasswolfs's avatar
grasswolfs committed
137
### Error message
Leif's avatar
Leif committed
138

grasswolfs's avatar
grasswolfs committed
139
- 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
140

grasswolfs's avatar
grasswolfs committed
141
- 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
142

grasswolfs's avatar
grasswolfs committed
143
144
145
146
147
148
149
    ```
    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
    ```
Leif's avatar
Leif committed
150
151
152
153
154
- 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 headless version of opencv
    ```
    pip install opencv-contrib-python-headless
    ```
    
grasswolfs's avatar
grasswolfs committed
155
### Related
Leif's avatar
Leif committed
156
157

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