# platerec
<p align="center">
<img src="https://raw.githubusercontent.com/pstwh/platerec/main/examples/example.jpg" width="768" />
</p>
`platerec` is a lightweight package for reading license plates using an ONNX model. It is designed to be part of a pipeline for detecting, cropping, and reading license plates. The underlying model is a mobilenetv2 as encoder and a light gpt for decoder. The training data comprises primarily Brazilian license plates, sourced from internet images, also synthetic data generated in the same font with transforms. The model repository can be found [here](https://github.com/pstwh/platerec-model).
Now it supports reading from different countries.
Currently:
- \[br]: Brazil
- \[us]: United States
- \[ue]: European Union
- \[ru]: Russia
The license plate recognition model is continuously being improved. However, accuracy can be significantly enhanced by fine-tuning the model with a dataset specific to your needs. We encourage you to explore the model training repository to learn how to build a customized model with increased accuracy for your format.
The first token after '<' will be the country plate type.
Example:
'<[br]ZZZ1Z11>'
[Video example](https://www.youtube.com/embed/8zyAIp5qGBA)
## Installation
To install the required dependencies, use the following command:
For cpu
```bash
pip install "platerec[cpu]"
```
For cuda
```bash
pip install "platerec[gpu]"
```
## Usage
### Command Line Interface
You can use the command line interface to detect license plates in an image:
```bash
platerec image_path [--encoder_path ENCODER_PATH] [--decoder_path DECODER_PATH] [--return_types RETURN_TYPE] [--providers PROVIDERS] [--no_platedet]
```
#### Arguments
- `image_path`: Path to the input image. Could be more than one image.
- `--encoder_path`: Path to the ONNX encoder model (default: `artifacts/encoder.onnx`).
- `--decoder_path`: Path to the ONNX decoder model (default: `artifacts/decoder.onnx`).
- `--tokenizer_path`: Path to the tokenizer json file (default: `artifacts/tokenizer.json`).
- `--return_type`: Output formats (choices: `word`, `char`). Word return the plate text and confidence detected, char return the plate chars detected with confidences for each char.
- `--providers`: ONNX Runtime providers (default: `CPUExecutionProvider`).
- `--no_platedet`: Not use platedet to detect plates first.
### Example
To just read an already cropped image:
```bash
python3 platerec/cli.py examples/1.jpg --return_type word
```
To detect license plates and read them:
```bash
python3 platerec/cli.py examples/1.jpg --return_type word
```
### Using in Code
To just read an already cropped image:
```python
from PIL import Image
from platerec import Platerec
platerec = Platerec()
image = Image.open('examples/1.jpg')
pred = platerec.read(image)
```
pred will be something like:
```
{'word': '[br]ZZZ1Z11', 'confidence': 0.98828125}
```
To detect license plates and read them:
```python
from PIL import Image
from platerec import Platerec
platerec = Platerec()
image = Image.open('examples/1.jpg')
crops = platerec.detect_read(image)
for idx, crop in enumerate(crops['pil']['images']):
crop.save(f'{idx}.jpg')
```
pred will be something like:
```
{'images': [<PIL.Image.Image image mode=RGB size=105x40 at 0x7FEE25B67AD0>], 'confidences': array([0.72949219]), 'words': ['[br]AAA1A11'], 'boxes': array([[ 393, 1188, 498, 1228]], dtype=int32), 'words_confidences': [0.95263671875]}
```
If you want to use CUDA:
```python
from platerec import Platerec
platerec = Platerec(providers=["CUDAExecutionProvider"])
```
Check all execution providers [here](https://onnxruntime.ai/docs/execution-providers/).
<hr>
Extra commands for quick testing:
```bash
platerec-video video_path [--font_size FONT_SIZE] [--save_output]
```
Run platerec on a video file.
```bash
platerec-image image_path
```
Run platerec on a image file.
Raw data
{
"_id": null,
"home_page": "https://github.com/pstwh/platerec",
"name": "platerec",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.5",
"maintainer_email": null,
"keywords": "plate, ocr, read, alpr",
"author": null,
"author_email": null,
"download_url": null,
"platform": null,
"description": "# platerec\n\n<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/pstwh/platerec/main/examples/example.jpg\" width=\"768\" />\n</p>\n\n`platerec` is a lightweight package for reading license plates using an ONNX model. It is designed to be part of a pipeline for detecting, cropping, and reading license plates. The underlying model is a mobilenetv2 as encoder and a light gpt for decoder. The training data comprises primarily Brazilian license plates, sourced from internet images, also synthetic data generated in the same font with transforms. The model repository can be found [here](https://github.com/pstwh/platerec-model).\n\nNow it supports reading from different countries.\nCurrently:\n- \\[br]: Brazil\n- \\[us]: United States\n- \\[ue]: European Union\n- \\[ru]: Russia\n\nThe license plate recognition model is continuously being improved. However, accuracy can be significantly enhanced by fine-tuning the model with a dataset specific to your needs. We encourage you to explore the model training repository to learn how to build a customized model with increased accuracy for your format.\n\nThe first token after '<' will be the country plate type.\n\nExample:\n'<[br]ZZZ1Z11>'\n\n[Video example](https://www.youtube.com/embed/8zyAIp5qGBA)\n\n## Installation\n\nTo install the required dependencies, use the following command:\n\nFor cpu\n\n```bash\npip install \"platerec[cpu]\"\n```\n\nFor cuda\n```bash\npip install \"platerec[gpu]\"\n```\n\n## Usage\n\n### Command Line Interface\n\nYou can use the command line interface to detect license plates in an image:\n\n```bash\nplaterec image_path [--encoder_path ENCODER_PATH] [--decoder_path DECODER_PATH] [--return_types RETURN_TYPE] [--providers PROVIDERS] [--no_platedet]\n```\n\n#### Arguments\n\n- `image_path`: Path to the input image. Could be more than one image.\n- `--encoder_path`: Path to the ONNX encoder model (default: `artifacts/encoder.onnx`).\n- `--decoder_path`: Path to the ONNX decoder model (default: `artifacts/decoder.onnx`).\n- `--tokenizer_path`: Path to the tokenizer json file (default: `artifacts/tokenizer.json`).\n- `--return_type`: Output formats (choices: `word`, `char`). Word return the plate text and confidence detected, char return the plate chars detected with confidences for each char.\n- `--providers`: ONNX Runtime providers (default: `CPUExecutionProvider`).\n- `--no_platedet`: Not use platedet to detect plates first.\n\n### Example\n\nTo just read an already cropped image:\n\n```bash\npython3 platerec/cli.py examples/1.jpg --return_type word\n```\n\nTo detect license plates and read them:\n\n```bash\npython3 platerec/cli.py examples/1.jpg --return_type word\n```\n\n### Using in Code\n\nTo just read an already cropped image:\n\n```python\nfrom PIL import Image\nfrom platerec import Platerec\n\nplaterec = Platerec()\nimage = Image.open('examples/1.jpg')\npred = platerec.read(image)\n```\npred will be something like:\n```\n{'word': '[br]ZZZ1Z11', 'confidence': 0.98828125}\n```\n\nTo detect license plates and read them:\n\n```python\nfrom PIL import Image\nfrom platerec import Platerec\n\nplaterec = Platerec()\nimage = Image.open('examples/1.jpg')\ncrops = platerec.detect_read(image)\nfor idx, crop in enumerate(crops['pil']['images']):\n crop.save(f'{idx}.jpg')\n```\n\npred will be something like:\n```\n{'images': [<PIL.Image.Image image mode=RGB size=105x40 at 0x7FEE25B67AD0>], 'confidences': array([0.72949219]), 'words': ['[br]AAA1A11'], 'boxes': array([[ 393, 1188, 498, 1228]], dtype=int32), 'words_confidences': [0.95263671875]}\n```\n\nIf you want to use CUDA:\n```python\nfrom platerec import Platerec\n\nplaterec = Platerec(providers=[\"CUDAExecutionProvider\"])\n```\n\nCheck all execution providers [here](https://onnxruntime.ai/docs/execution-providers/).\n\n<hr>\n\nExtra commands for quick testing:\n\n```bash\nplaterec-video video_path [--font_size FONT_SIZE] [--save_output]\n```\nRun platerec on a video file.\n\n```bash\nplaterec-image image_path\n```\nRun platerec on a image file.\n",
"bugtrack_url": null,
"license": null,
"summary": "Read license plates",
"version": "0.0.3",
"project_urls": {
"Homepage": "https://github.com/pstwh/platerec"
},
"split_keywords": [
"plate",
" ocr",
" read",
" alpr"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cd4d7868a7ee5e9351b71d64ccb75208443b7bf602c091373ce97890cddb4d57",
"md5": "76923b07942169fb746634d29d91b56a",
"sha256": "02afb0ff01d1e50194710f1a81a8de9f844f3c253ada21585cb6385500e54719"
},
"downloads": -1,
"filename": "platerec-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "76923b07942169fb746634d29d91b56a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.5",
"size": 8270613,
"upload_time": "2025-02-08T06:31:22",
"upload_time_iso_8601": "2025-02-08T06:31:22.664231Z",
"url": "https://files.pythonhosted.org/packages/cd/4d/7868a7ee5e9351b71d64ccb75208443b7bf602c091373ce97890cddb4d57/platerec-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-08 06:31:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pstwh",
"github_project": "platerec",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "platerec"
}