# keras-ocr [](https://keras-ocr.readthedocs.io/en/latest/?badge=latest)
This is a slightly polished and packaged version of the [Keras CRNN implementation](https://github.com/kurapan/CRNN) and the published [CRAFT text detection model](https://github.com/clovaai/CRAFT-pytorch). It provides a high level API for training a text detection and OCR pipeline.
Please see [the documentation](https://keras-ocr.readthedocs.io/) for more examples, including for training a custom model.
## Getting Started
### Installation
`keras-ocr` supports Python >= 3.6 and TensorFlow >= 2.0.0.
```bash
# To install from master
pip install git+https://github.com/faustomorales/keras-ocr.git#egg=keras-ocr
# To install from PyPi
pip install keras-ocr
```
### Using
The package ships with an easy-to-use implementation of the CRAFT text detection model from [this repository](https://github.com/clovaai/CRAFT-pytorch) and the CRNN recognition model from [this repository](https://github.com/kurapan/CRNN).
```python
import matplotlib.pyplot as plt
import keras_ocr
# keras-ocr will automatically download pretrained
# weights for the detector and recognizer.
pipeline = keras_ocr.pipeline.Pipeline()
# Get a set of three example images
images = [
keras_ocr.tools.read(url) for url in [
'https://upload.wikimedia.org/wikipedia/commons/b/bd/Army_Reserves_Recruitment_Banner_MOD_45156284.jpg',
'https://upload.wikimedia.org/wikipedia/commons/e/e8/FseeG2QeLXo.jpg',
'https://upload.wikimedia.org/wikipedia/commons/b/b4/EUBanana-500x112.jpg'
]
]
# Each list of predictions in prediction_groups is a list of
# (word, box) tuples.
prediction_groups = pipeline.recognize(images)
# Plot the predictions
fig, axs = plt.subplots(nrows=len(images), figsize=(20, 20))
for ax, image, predictions in zip(axs, images, prediction_groups):
keras_ocr.tools.drawAnnotations(image=image, predictions=predictions, ax=ax)
```
## Comparing keras-ocr and other OCR approaches
You may be wondering how the models in this package compare to existing cloud OCR APIs. We provide some metrics below and [the notebook](https://drive.google.com/file/d/1FMS3aUZnBU4Tc6bosBPnrjdMoSrjZXRp/view?usp=sharing) used to compute them using the first 1,000 images in the COCO-Text validation set. We limited it to 1,000 because the Google Cloud free tier is for 1,000 calls a month at the time of this writing. As always, caveats apply:
- No guarantees apply to these numbers -- please beware and compute your own metrics independently to verify them. As of this writing, they should be considered a very rough first draft. Please open an issue if you find a mistake. In particular, the cloud APIs have a variety of options that one can use to improve their performance and the responses can be parsed in different ways. It is possible that I made some error in configuration or parsing. Again, please open an issue if you find a mistake!
- We ignore punctuation and letter case because the out-of-the-box recognizer in keras-ocr (provided by [this independent repository](https://github.com/kurapan/CRNN)) does not support either. Note that both AWS Rekognition and Google Cloud Vision support punctuation as well as upper and lowercase characters.
- We ignore non-English text.
- We ignore illegible text.
| model | latency | precision | recall |
| ----------------------------------------------------------------------------------------------------------------------------- | ------- | --------- | ------ |
| [AWS](https://github.com/faustomorales/keras-ocr/releases/download/v0.8.4/aws_annotations.json) | 719ms | 0.45 | 0.48 |
| [GCP](https://github.com/faustomorales/keras-ocr/releases/download/v0.8.4/google_annotations.json) | 388ms | 0.53 | 0.58 |
| [keras-ocr](https://github.com/faustomorales/keras-ocr/releases/download/v0.8.4/keras_ocr_annotations_scale_2.json) (scale=2) | 417ms | 0.53 | 0.54 |
| [keras-ocr](https://github.com/faustomorales/keras-ocr/releases/download/v0.8.4/keras_ocr_annotations_scale_3.json) (scale=3) | 699ms | 0.5 | 0.59 |
- Precision and recall were computed based on an intersection over union of 50% or higher and a text similarity to ground truth of 50% or higher.
- `keras-ocr` latency values were computed using a Tesla P4 GPU on Google Colab. `scale` refers to the argument provided to `keras_ocr.pipelines.Pipeline()` which determines the upscaling applied to the image prior to inference.
- Latency for the cloud providers was measured with sequential requests, so you can obtain significant speed improvements by making multiple simultaneous API requests.
- Each of the entries provides a link to the JSON file containing the annotations made on each pass. You can use this with the notebook to compute metrics without having to make the API calls yourself (though you are encoraged to replicate it independently)!
_Why not compare to Tesseract?_ In every configuration I tried, Tesseract did very poorly on this test. Tesseract performs best on scans of books, not on incidental scene text like that in this dataset.
## Advanced Configuration
By default if a GPU is available Tensorflow tries to grab almost all of the available video memory, and this sucks if you're running multiple models with Tensorflow and Pytorch. Setting any value for the environment variable `MEMORY_GROWTH` will force Tensorflow to dynamically allocate only as much GPU memory as is needed.
You can also specify a limit per Tensorflow process by setting the environment variable `MEMORY_ALLOCATED` to any float, and this value is a float ratio of VRAM to the total amount present.
To apply these changes, call `keras_ocr.config.configure()` at the top of your file where you import `keras_ocr`.
## Contributing
To work on the project, start by doing the following. These instructions probably do not yet work for Windows but if a Windows user has some ideas for how to fix that it would be greatly appreciated (I don't have a Windows machine to test on at the moment).
```bash
# Install local dependencies for
# code completion, etc.
make init
# Build the Docker container to run
# tests and such.
make build
```
- You can get a JupyterLab server running to experiment with using `make lab`.
- To run checks before committing code, you can use `make format-check type-check lint-check test`.
- To view the documentation, use `make docs`.
To implement new features, please first file an issue proposing your change for discussion.
To report problems, please file an issue with sample code, expected results, actual results, and a complete traceback.
## Troubleshooting
- _This package is installing `opencv-python-headless` but I would prefer a different `opencv` flavor._ This is due to [aleju/imgaug#473](https://github.com/aleju/imgaug/issues/473). You can uninstall the unwanted OpenCV flavor after installing `keras-ocr`. We apologize for the inconvenience.
Raw data
{
"_id": null,
"home_page": "https://github.com/faustomorales/keras-ocr",
"name": "keras-ocr",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7.5",
"maintainer_email": "",
"keywords": "",
"author": "Fausto Morales",
"author_email": "faustomorales@gmail.com",
"download_url": "",
"platform": null,
"description": "# keras-ocr [](https://keras-ocr.readthedocs.io/en/latest/?badge=latest)\n\nThis is a slightly polished and packaged version of the [Keras CRNN implementation](https://github.com/kurapan/CRNN) and the published [CRAFT text detection model](https://github.com/clovaai/CRAFT-pytorch). It provides a high level API for training a text detection and OCR pipeline.\n\nPlease see [the documentation](https://keras-ocr.readthedocs.io/) for more examples, including for training a custom model.\n\n## Getting Started\n\n### Installation\n\n`keras-ocr` supports Python >= 3.6 and TensorFlow >= 2.0.0.\n\n```bash\n# To install from master\npip install git+https://github.com/faustomorales/keras-ocr.git#egg=keras-ocr\n\n# To install from PyPi\npip install keras-ocr\n```\n\n### Using\n\nThe package ships with an easy-to-use implementation of the CRAFT text detection model from [this repository](https://github.com/clovaai/CRAFT-pytorch) and the CRNN recognition model from [this repository](https://github.com/kurapan/CRNN).\n\n```python\nimport matplotlib.pyplot as plt\n\nimport keras_ocr\n\n# keras-ocr will automatically download pretrained\n# weights for the detector and recognizer.\npipeline = keras_ocr.pipeline.Pipeline()\n\n# Get a set of three example images\nimages = [\n keras_ocr.tools.read(url) for url in [\n 'https://upload.wikimedia.org/wikipedia/commons/b/bd/Army_Reserves_Recruitment_Banner_MOD_45156284.jpg',\n 'https://upload.wikimedia.org/wikipedia/commons/e/e8/FseeG2QeLXo.jpg',\n 'https://upload.wikimedia.org/wikipedia/commons/b/b4/EUBanana-500x112.jpg'\n ]\n]\n\n# Each list of predictions in prediction_groups is a list of\n# (word, box) tuples.\nprediction_groups = pipeline.recognize(images)\n\n# Plot the predictions\nfig, axs = plt.subplots(nrows=len(images), figsize=(20, 20))\nfor ax, image, predictions in zip(axs, images, prediction_groups):\n keras_ocr.tools.drawAnnotations(image=image, predictions=predictions, ax=ax)\n```\n\n\n\n## Comparing keras-ocr and other OCR approaches\n\nYou may be wondering how the models in this package compare to existing cloud OCR APIs. We provide some metrics below and [the notebook](https://drive.google.com/file/d/1FMS3aUZnBU4Tc6bosBPnrjdMoSrjZXRp/view?usp=sharing) used to compute them using the first 1,000 images in the COCO-Text validation set. We limited it to 1,000 because the Google Cloud free tier is for 1,000 calls a month at the time of this writing. As always, caveats apply:\n\n- No guarantees apply to these numbers -- please beware and compute your own metrics independently to verify them. As of this writing, they should be considered a very rough first draft. Please open an issue if you find a mistake. In particular, the cloud APIs have a variety of options that one can use to improve their performance and the responses can be parsed in different ways. It is possible that I made some error in configuration or parsing. Again, please open an issue if you find a mistake!\n- We ignore punctuation and letter case because the out-of-the-box recognizer in keras-ocr (provided by [this independent repository](https://github.com/kurapan/CRNN)) does not support either. Note that both AWS Rekognition and Google Cloud Vision support punctuation as well as upper and lowercase characters.\n- We ignore non-English text.\n- We ignore illegible text.\n\n| model | latency | precision | recall |\n| ----------------------------------------------------------------------------------------------------------------------------- | ------- | --------- | ------ |\n| [AWS](https://github.com/faustomorales/keras-ocr/releases/download/v0.8.4/aws_annotations.json) | 719ms | 0.45 | 0.48 |\n| [GCP](https://github.com/faustomorales/keras-ocr/releases/download/v0.8.4/google_annotations.json) | 388ms | 0.53 | 0.58 |\n| [keras-ocr](https://github.com/faustomorales/keras-ocr/releases/download/v0.8.4/keras_ocr_annotations_scale_2.json) (scale=2) | 417ms | 0.53 | 0.54 |\n| [keras-ocr](https://github.com/faustomorales/keras-ocr/releases/download/v0.8.4/keras_ocr_annotations_scale_3.json) (scale=3) | 699ms | 0.5 | 0.59 |\n\n- Precision and recall were computed based on an intersection over union of 50% or higher and a text similarity to ground truth of 50% or higher.\n- `keras-ocr` latency values were computed using a Tesla P4 GPU on Google Colab. `scale` refers to the argument provided to `keras_ocr.pipelines.Pipeline()` which determines the upscaling applied to the image prior to inference.\n- Latency for the cloud providers was measured with sequential requests, so you can obtain significant speed improvements by making multiple simultaneous API requests.\n- Each of the entries provides a link to the JSON file containing the annotations made on each pass. You can use this with the notebook to compute metrics without having to make the API calls yourself (though you are encoraged to replicate it independently)!\n\n_Why not compare to Tesseract?_ In every configuration I tried, Tesseract did very poorly on this test. Tesseract performs best on scans of books, not on incidental scene text like that in this dataset.\n\n## Advanced Configuration\nBy default if a GPU is available Tensorflow tries to grab almost all of the available video memory, and this sucks if you're running multiple models with Tensorflow and Pytorch. Setting any value for the environment variable `MEMORY_GROWTH` will force Tensorflow to dynamically allocate only as much GPU memory as is needed.\n\nYou can also specify a limit per Tensorflow process by setting the environment variable `MEMORY_ALLOCATED` to any float, and this value is a float ratio of VRAM to the total amount present.\n\nTo apply these changes, call `keras_ocr.config.configure()` at the top of your file where you import `keras_ocr`.\n\n## Contributing\n\nTo work on the project, start by doing the following. These instructions probably do not yet work for Windows but if a Windows user has some ideas for how to fix that it would be greatly appreciated (I don't have a Windows machine to test on at the moment).\n\n```bash\n# Install local dependencies for\n# code completion, etc.\nmake init\n\n# Build the Docker container to run\n# tests and such.\nmake build\n```\n\n- You can get a JupyterLab server running to experiment with using `make lab`.\n- To run checks before committing code, you can use `make format-check type-check lint-check test`.\n- To view the documentation, use `make docs`.\n\nTo implement new features, please first file an issue proposing your change for discussion.\n\nTo report problems, please file an issue with sample code, expected results, actual results, and a complete traceback.\n\n## Troubleshooting\n\n- _This package is installing `opencv-python-headless` but I would prefer a different `opencv` flavor._ This is due to [aleju/imgaug#473](https://github.com/aleju/imgaug/issues/473). You can uninstall the unwanted OpenCV flavor after installing `keras-ocr`. We apologize for the inconvenience.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A packaged and flexible version of the CRAFT text detector and Keras CRNN recognition model.",
"version": "0.9.3",
"project_urls": {
"Homepage": "https://github.com/faustomorales/keras-ocr",
"Repository": "https://github.com/faustomorales/keras-ocr"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "aff37ad1edb975c6c485d73146438dfff188f1c22b798d3a076e4f644e7bdce1",
"md5": "9f8b83c9c2154b8e1c9c77a416a8d338",
"sha256": "8fdbb9044a814910e86d3853f5e7f13085c98ac210f27204fe75f4f8c4ac6262"
},
"downloads": -1,
"filename": "keras_ocr-0.9.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9f8b83c9c2154b8e1c9c77a416a8d338",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7.5",
"size": 42313,
"upload_time": "2023-11-06T16:35:44",
"upload_time_iso_8601": "2023-11-06T16:35:44.215920Z",
"url": "https://files.pythonhosted.org/packages/af/f3/7ad1edb975c6c485d73146438dfff188f1c22b798d3a076e4f644e7bdce1/keras_ocr-0.9.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-06 16:35:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "faustomorales",
"github_project": "keras-ocr",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "keras-ocr"
}
JSON
