RapidOcr-Java Documentation

When choosing how to implement OCR in a Java application, there are four primary approaches. RapidOcr-Java is the recommended method for most developers because it abstracts the complexity of OCR models through JNI (Java Native Interface).

Comparison of Methods

To use RapidOcr-Java, you must include the core rapidocr dependency and exactly one platform-specific inference engine dependency.

• Use rapidocr-onnx-platform for CPU-based environments.
• Use rapidocr-ncnn-platform for mobile environments.

The dependencies automatically select the correct JAR based on your operating system. Check the Version Description for supported systems.

<!-- Core dependency (required) -->
<dependency>
    <groupId>io.github.mymonstercat</groupId>
    <artifactId>rapidocr</artifactId>
    <version>0.0.7</version>
</dependency>

<!-- Choose ONE engine: ONNX for CPU, NCNN for mobile -->
<dependency>
    <groupId>io.github.mymonstercat</groupId>
    <artifactId>rapidocr-onnx-platform</artifactId>
    <version>0.0.7</version>
</dependency>

<!-- OR -->
<dependency>
    <groupId>io.github.mymonstercat</groupId>
    <artifactId>rapidocr-ncnn-platform</artifactId>
    <version>0.0.7</version>
</dependency>

To compile the JNI dynamic library using the ONNX backend, follow these steps to prepare the environment and build the project. This process involves cloning the core engine, downloading pre-built dependencies (OpenCV and ONNX Runtime), and running the build script.

1. Download Dependencies

• Project Source: Clone https://github.com/RapidAI/RapidOcrOnnx.
• OpenCV: Download from OpenCVBuilder releases. Extract to a directory named opencv-static. Ensure the directory contains OpenCVWrapperConfig.cmake and platform-specific folders (e.g., macos, windows-x64).
• ONNX Runtime: Download from OnnxruntimeBuilder releases. Use the static version. Extract to a directory named onnxruntime-static. Ensure the directory contains OnnxRuntimeWrapper.cmake and platform-specific folders.

2. MacOS Environment Setup

• Install Xcode >= 12 and Xcode Command Line Tools: xcode-select --install.
• Install Homebrew and CMake >= 3.19.
• Install libomp: brew install libomp.
• Ensure a Java environment is installed.

3. Code Modification (MacOS Only)

Before building on macOS, you must update the include paths in the following files: AngleNet.h, CrnnNet.h, DbNet.h, OcrLite.h, and OcrUtils.h.

Change: #include <onnxruntime/core/session/onnxruntime_cxx_api.h> To: #include <onnxruntime/onnxruntime_cxx_api.h>

4. Build and Test

1. Open a terminal in the project root.
2. Run ./build.sh and follow the prompts. Select 'JNI动态库' (JNI Dynamic Library) when prompted.
3. The resulting library (e.g., libRapidOcrOnnx.dylib on macOS) can be used in your project. Replace the existing library in your project's resource module with this new file.
4. To test the build, run ./run-test.sh (ensure you update the image path within the script).

# 1. Clone the engine
git clone https://github.com/RapidAI/RapidOcrOnnx

# 2. Build (after setting up opencv-static and onnxruntime-static)
./build.sh

# 3. Test
./run-test.sh

To use a custom model, you must convert it to the required format using the RapidOCR model conversion process. Follow these steps:

1. Convert the model: Use the PaddleOCRModelConverter on ModelScope to convert your chosen model.
   • Model Address: Select a model from the official PaddleOCR models list.
   • TXT Address: Obtain the ppocr_keys_v1.txt file from the official PaddleOCR repository (navigate to the specific branch -> utils -> ppocr_keys_v1.txt).
   • Click convert to perform the transformation.
2. Deploy the model: Place the converted model file into the directory: src\main\resources\onnx\models.
3. Update configuration: Modify the PathConstants.MODEL_REC_NAME constant in the source code to match the filename of your new model.

This guide provides instructions for building the Rapid OCR Onnx library on the Kylin (arm64) operating system (e.g., Kylin V10 SP1 on Phytium D2000/8 CPU).

Compilation Requirements

• gcc: > 7
• g++: > 7
• cmake: > 3.17

Environment Setup

1. Configure Kylin Software Sources

If the Kylin repository is missing, add the appropriate source to /etc/apt/sources.list. For example, for V10:

deb http://archive.kylinos.cn/kylin/KYLIN-ALL 10.0 main restricted universe multiverse

2. Install GCC and G++

You can download .deb packages for offline installation using apt:

# Download only
sudo apt install --download-only gcc
sudo apt install --download-only g++

# Packages are cached in /var/cache/apt/packages
cd /var/cache/apt/packages

# Install the downloaded packages
sudo dpkg -i *.deb

3. Install CMake (Manual Installation)

Since apt may provide an outdated version (e.g., 3.16), download the tar.gz for Linux aarch64 from the official CMake website.

# Extract to a directory, e.g., /home/some/soft/cmake
tar -xzvf cmake-3.29.2-linux-aarch64.tar.gz -C /home/some/soft/

# Add to PATH in ~/.bashrc
export PATH=$PATH:/home/some/soft/cmake/bin
source ~/.bashrc

4. Configure JVM (Required for JNI)

Download the aarch64 JDK from Oracle. You must set JAVA_HOME to build JNI components.

# Extract to a directory, e.g., /home/some/soft/jdk
export JAVA_HOME=/home/some/soft/jdk
export PATH=$PATH:$JAVA_HOME/bin
source ~/.bashrc

If ldd reports missing GLIBCXX symbols, you may need to upgrade GCC.

⚠️ WARNING: Upgrading GCC carries significant risks to system stability. Always create a system snapshot or backup before proceeding in production environments.

1. Download and Prepare

Download the source, extract it, and use the included script to fetch required dependencies (mpfr, mpc, gmp).

2. Compile and Install

Configure the build with --enable-languages=c,c++ and --disable-multilib. Note that compilation can take 1-3 hours.

3. Update System Symlinks

After installation, locate the new libstdc++.so.6.0.26 (or higher) in /usr/local/lib64/ and update the system link in /usr/lib64/ to point to it.

# 1. Download and dependencies
mkdir temp && cd /temp
wget http://ftp.gnu.org/gnu/gcc/gcc-9.1.0/gcc-9.1.0.tar.gz
tar -zxvf gcc-9.1.0.tar.gz
cd gcc-9.1.0
./contrib/download_prerequisites

# 2. Build
mkdir build && cd build
../configure --enable-checking=release --enable-languages=c,c++ --disable-multilib
make
make install

# 3. Re-link libstdc++
find / -name "libstdc++.so*"
# Assuming /usr/local/lib64/libstdc++.so.6.0.26 is found:
cd /usr/lib64
cp /usr/local/lib64/libstdc++.so.6.0.26 /usr/lib64/
rm libstdc++.so.6
ln -s libstdc++.so.6.0.26 libstdc++.so.6