libwechat-zxing-cpp-wrapper

Fast QR code decoding for Java backed by the Tencent/WeChat ZXing-C++ fork with OpenCV’s wechat_qrcode neural network pipeline. Ships as a tiny JNI bridge + Linux native binaries, no external executables required.

---

Features

• WeChat QR accuracy – wraps Tencent’s optimized ZXing fork with the neural-network finder from OpenCV’s wechat_qrcode.
• Drop-in Java API – interact via byte[] grayscale frames; no BufferedImage ceremony and no extra copies.
• OpenCV-free sources – all OpenCV code was stripped; the repo only links against the public wechat_qrcode headers/ABI when building the native artefacts.
• Bundled native libs – 64-bit Linux .so compiled with OpenCV 4.5.5 is included; only Java 17+ is needed at runtime.
• Packaging ready – Maven module with resources configured for publishing to GitHub Packages/Maven Central.
• Extensible – rebuild the JNI layer for other platforms by re-running the documented GCC commands.
• Threading bugfix – includes a concurrency fix for multi-decoder workloads that is still missing upstream in OpenCV’s distribution.

Quick start

1. Declare the dependency

<dependency>
    <groupId>org.zxingcpp</groupId>
    <artifactId>libzxing-java-wrapper</artifactId>
    <version>opencv455-SNAPSHOT</version>
</dependency>

2. Load the JNI + decode

import org.zxingcpp.ZxingCppDecoder;
import org.zxingcpp.ZxingCppLoader;

public class Demo {
    public static void main(String[] args) {
        ZxingCppLoader.loadLibrary();                    // extract + load libzxing.so
        try (ZxingCppDecoder decoder = new ZxingCppDecoder()) {
            byte[] grayscale = ...;                      // width*height bytes
            String result = decoder.decode(grayscale, 640, 480, true);
            System.out.println("Decoded: " + result);
        }
    }
}

Build from source

Requires JDK 17+, OpenCV 4.5.5 toolchain headers, and a modern GCC/Clang on Linux.

The Java classes live under src/main/java and the native sources under src/main/cpp. To refresh the bundled .so:

Manual native build

1. cd src/main
2. Build the static ZXing/OpenCV objects:

   g++ -std=c++17 -O3 -fPIC -pthread $(find cpp/ -name '*.cpp') -c
   ar rcs resources/native/linux/libzxing.a *.o

3. Build the JNI bridge (adjust JDK include paths if needed):

   g++ -c -fPIC \
       -I"$JAVA_HOME/include" \
       -I"$JAVA_HOME/include/linux" \
       jni/org_zxingcpp_ZxingCppDecoder.cpp \
       -o resources/jni/linux/org_zxingcpp_ZxingCppDecoder.o \
       -Iresources/native/linux/
   
   g++ -shared -fPIC \
       -o resources/jni/linux/libzxing.so \
       resources/jni/linux/org_zxingcpp_ZxingCppDecoder.o \
       resources/native/linux/libzxing.a \
       -lc

4. From the project root run mvn clean package (or install/deploy).

Automated Maven build

mvn clean package

This compiles Java sources, bundles the JNI objects, and drops the shaded JAR + native libs into target/.

Rebuilding for other platforms

1. Compile OpenCV + ZXing sources into a platform-specific shared library.
2. Drop the results under src/main/resources/native/<os>/ and src/main/resources/jni/<os>/.
3. Extend ZxingCppLoader search paths if your directory naming differs.

Project layout

libwechat-zxing-cpp-wrapper/
 ├── src/main/java              # Java wrapper (Apache-2.0)
 │   └── org/zxingcpp/*
 ├── src/main/cpp               # Tencent/WeChat ZXing fork + OpenCV glue
 ├── src/main/jni               # JNI shim
 ├── src/main/resources/
 │   ├── native/linux           # Pre-built libzxing.a
 │   └── jni/linux              # libzxing.so + objects
 ├── pom.xml                    # Maven metadata
 ├── LICENSE                    # Apache-2.0 licence for this wrapper
 ├── NOTICE                     # Third-party notices (Tencent, ZXing, OpenCV)
 └── README.md                  # You are here

Contributing

Pull requests and platform ports are welcome! Please run mvn -q clean verify and update the README if you adjust the build.

Credits

• Tencent / THL A29 Limited – original wechat_qrcode detector implementation.
• ZXing contributors – foundation barcode decoding algorithms.
• Matteo Riva – JNI wrapper, packaging, tooling, and the concurrency bugfix beyond upstream OpenCV.

Licence

Released under the Apache License, Version 2.0. See LICENSE for the wrapper and NOTICE for bundled third-party attributions.