Metadata-Version: 2.4
Name: rapidocrlite
Version: 5.0.0a7
Summary: RapidOCRLite: lightweight, fast PP-OCRv6 native engine, API-compatible with RapidOCR; import name rapidocr
Keywords: ocr,ppocr,ppocrv6,rapidocr
Author-Email: SWHL <liekkaskono@163.com>
License-Expression: Apache-2.0
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: C++
Project-URL: Documentation, https://rapidai.github.io/RapidOCRDocs
Project-URL: Repository, https://github.com/RapidAI/RapidOCRLite
Requires-Python: >=3.9
Requires-Dist: numpy>=1.21
Requires-Dist: Pillow>=9.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: requests
Requires-Dist: tqdm
Description-Content-Type: text/markdown

# RapidOCRLite

`RapidOCRLite` (RapidOCRLite) is published on PyPI as
[RapidOCRLite](https://pypi.org/project/RapidOCRLite/), separate from the official
[rapidocr](https://pypi.org/project/rapidocr/). The import name is still
`rapidocr`: `pip install rapidocrlite`, then `from rapidocr import RapidOCR`.
Both projects install the same `rapidocr` package directory, so do not install
them in one environment (run `pip uninstall rapidocr` first). RapidOCRLite is the lightweight native PP-OCRv6 engine with a RapidOCR-compatible API.
The ONNX Runtime 3.x line (latest tag `v3.9.2`) stays in RapidAI/RapidOCR.

```python
from rapidocr import RapidOCR, __version__

engine = RapidOCR(params={
    "Det.model_path": "PP-OCRv6_det_tiny.onnx",
    "Rec.model_path": "PP-OCRv6_rec_tiny.onnx",
    "Rec.rec_keys_path": "ppocrv6_tiny_dict.txt",
    "Global.use_cls": False,
})
result = engine("page.png")
print(__version__)
print(result.txts, result.scores)
print(result.to_json())
```

If model paths are omitted, `RapidOCR()` downloads the same files as 3.x:
`default_models.yaml` selects the URL, the file is saved under
`Global.model_root_dir` (the package `models/` directory when that is null)
using the URL filename, and the SHA256 is checked. `download_models()` and
`download_models(config_yaml)` follow 3.x and return `None`. PP-OCRv6 ONNX
recognizers also download the dictionary published next to the MNN bundles
(`ppocrv6_tiny_dict.txt` / `ppocrv6_dict.txt`).

Build from a checkout (CMake and a C++20 compiler required). The repository
root is the installable project, so the sdist contains the native sources:

```bash
pip install .
```

`pip install ./python` also works from a checkout, because that project
points CMake at the parent tree. It does not produce a self-contained sdist.

The binding is ctypes over the C ABI (`include/ppocr/ppocr.h`), so the wheel
ships `libppocr` and does not add a second C++ wrapper.

## Vulkan

Wheels are built with `-DPPOCR_ENABLE_VULKAN=OFF`. They do not contain the
compute shaders and do not need `libvulkan`. A checkout that has the
Vulkan-Headers submodule and `glslangValidator` can build a Vulkan-enabled
package with:

```bash
CMAKE_ARGS="-DPPOCR_ENABLE_VULKAN=ON -DPPOCR_BUILD_STATIC=OFF" pip install .
```

The runtime opens `libvulkan.so.1` with `dlopen`. It is not linked into the
library. Enable it per engine, in the same style as 3.x `use_cuda`:

```python
engine = RapidOCR(params={
    "EngineConfig.ppocr_cpp.use_vulkan": True,
    "EngineConfig.ppocr_cpp.device_index": 0,
})
```

`device_index` `-1` skips CPU Vulkan devices such as lavapipe. Set it to the
lavapipe index (`0` when it is the only device) together with
`VK_ICD_FILENAMES` pointing at `lvp_icd.json`. If no compute device exists,
the call logs a warning and runs on CPU. `backend: vulkan` is the same
attempt. `backend: hybrid` matches the C++ hybrid path. See `docs/API.md`.

## Migrating from rapidocr 3.x

`RapidOCR(config_path=..., params={"Section.key": value})` and
`engine(img, use_det=..., use_cls=..., use_rec=..., text_score=..., box_thresh=..., unclip_ratio=...)`
keep the same names. `result.txts`, `result.scores`, `result.boxes`,
`result.elapse`, `to_json()`, `to_markdown()`, and `vis()` are still there.
File paths, URLs, bytes, and PIL images are RGB. A numpy array is treated as
BGR, then swapped, which is what 3.x does for OpenCV images.

What does not carry over from 3.x:

| 3.x (`main`) | rapidocr 5 |
| --- | --- |
| ONNX Runtime, OpenVINO, Paddle, PyTorch, TensorRT, MNN | Built-in PP-OCRv6 interpreter. `EngineType.ONNXRUNTIME` and `EngineType.PPOCR_CPP` both select it. The other engine names raise `NotImplementedError`. |
| PP-OCRv4 and PP-OCRv5 model zoo | PP-OCRv6 ONNX detector and recognizer only. |
| Angle classifier (`use_cls=True` by default) | The cls file is downloaded like 3.x. The native engine does not run it, and logs one warning. |
| `use_det=False` or `use_rec=False` | Supported as on 3.x: `use_rec=False` returns `TextDetOutput`, `use_det=False` returns `TextRecOutput`. Both False raises `RapidOCRError`. |
| Word and character boxes | `return_word_box` / `return_single_char_box` warn. `word_results` is empty. |
| `elapse_list` is `[det, cls, rec]` | `[None, None, total]`. The native call is one timed region. An empty page is `RapidOCROutput()` (`boxes`/`txts`/`img` are `None`), same as 3.x. |
| `vis()` draws with OpenCV in BGR | `vis()` draws with Pillow and returns RGB. |
| `EngineConfig` (CUDA, OpenVINO, TensorRT, MNN, …) | Those keys load and can be read. They are not applied. `EngineConfig.ppocr_cpp.use_vulkan`, `backend` (`cpu`, `hybrid`, `vulkan`), and `device_index` are applied. |
| Detector `mean`/`std`, `limit_type`, `limit_side_len`, `use_dilation` | Passed through the C ABI and applied. `mean`/`std` are B, G, R, the same order as an OpenCV image. Recognizer normalization defaults to 0.5/0.5, matching 3.x. |
| `Global.min_height`, vertical padding, `max_side_len` | Applied before the native call, and boxes are mapped back. |

A call that only reads `txts`, `scores`, and `boxes` from a PP-OCRv6 model
can switch by installing this package and leaving `use_cls` at its default.
Set `use_cls=False` to skip the warning. Do not pass an older OCR version.

## Wheels and publishing

`.github/workflows/build-wheels.yml` builds the manylinux2014 wheels and the
sdist. It runs on pushes and pull requests to `main`, on tags named `v5*`,
and from the Actions “Run workflow” button. A normal push does not upload
anything to PyPI. Publishing happens only when a `v5*` tag is pushed.

`5.0.0a6` is a pre-release: `pip install --pre RapidOCRLite` or
`pip install rapidocrlite==5.0.0a6`. `pip install rapidocr` installs the
official 3.x package instead.

How to turn on PyPI Trusted Publishing (or the API-token fallback) and which
tag to push are in
[`docs/RELEASING.md`](../docs/RELEASING.md).

### Ported from `main` (#755)

- `RawMemoryImage(address, length, width, height, pixel_format="BGRA", stride=None, bottom_up=False)`
  reads an uncompressed pixel buffer (GRAY/BGR/RGB/BGRA/BGRX/RGBA/RGBX) by address.
- `bytes`, `bytearray`, `MemoryImage` and PIL inputs honor the EXIF orientation, like paths.
- Model routing lives in `default_models.yaml` under `model_routes`.
  `RapidOCR.list_supported_langs("rec", "PP-OCRv6", "tiny")` and
  `rapidocr --list-langs --task rec --ocr_version PP-OCRv6 --model_type tiny` list the languages.
- `Global.model_root_dir` accepts `str` or `Path`; the recognizer dictionary is stored there too.
- No OpenCV dependency or extra.
