Python on Rockchip Linux

Python calls the same native SDK as a C application. To use the NPU, pair the Python wrapper with the Rockchip build of libInspireFace.so, its runtime dependencies and the correct Gundam_* resource pack.

This guide covers RK356x/RK3588 devices running aarch64 Linux with glibc. It uses INSPIREFACE_LIBRARY_PATH in the 1.2.4 wrapper to select the Rockchip native SDK. For a CPU comparison, use a compatible general CPU wheel in a separate environment.

The 1.2.4 Linux RK356x/RK3588 SDK provides the native library. Extract it and use its lib/libInspireFace.so with the matching headers and version file. Prepare the board's runtime dependencies and the SoC-specific model pack separately; build the SDK if you need a different toolchain or configuration.

Prepare the device

First get the native Rockchip detection example working. Then check that the Python interpreter, native library and root filesystem agree on architecture and libc.

An aarch64 glibc SDK needs an aarch64 Python process on a compatible glibc system. The current Python packaging scripts do not support ARMv7/uClibc targets such as RV1106; the installation steps below do not apply to those boards. Use the C/C++ deployment guide for them.

Organize application files in a predictable layout:

my-app/
  native/          # libInspireFace.so and matching runtime dependencies
  models/
    Gundam_RK3588  # choose the pack for your actual device
  detect.py

Keep the runtime libraries supplied for the board/build together. Check loader errors before trying to import the wrapper.

Install the matching wrapper

On the device, use the Python source from the same revision as the native SDK. CMake generates python/version.txt when configuring the SDK. If the library was built on another machine, copy the version.txt shipped with that exact SDK into the Python source directory before installing it. Without this file, the package version falls back to 0.0.0.

Replace the paths below with your SDK and source directories. Skip the copy only if this checkout already contains the version file generated by the matching SDK build:

cp /absolute/path/to/sdk/version.txt /path/to/InspireFace/python/version.txt
cat /path/to/InspireFace/python/version.txt
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e /path/to/InspireFace/python

Set these variables before starting Python:

export INSPIREFACE_LIBRARY_PATH=/absolute/path/to/my-app/native/libInspireFace.so
export LD_LIBRARY_PATH="/absolute/path/to/my-app/native${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
python -c 'import inspireface as isf; print("Wrapper:", isf.__version__, "Native:", isf.version())'

INSPIREFACE_LIBRARY_PATH selects the SDK library, and LD_LIBRARY_PATH supplies its dependency directories. Use the same library path in the application and deployment scripts.

With the current source, the Python package version is 1.2.4.post3 and the native version is 1.2.4. The .post3 suffix comes from python/post. Keep the source revision and native build matched as well; a shared version number alone does not identify the exact commit. See Python packaging when preparing a wheel for other devices.

Load a local pack

Pass the local model file to launch:

import inspireface as isf

isf.launch(resource_path="/absolute/path/to/my-app/models/Gundam_RK3588")
try:
    with isf.InspireFaceSession(
        isf.HF_ENABLE_NONE,
        isf.HF_DETECT_MODE_ALWAYS_DETECT,
        max_detect_num=5,
        detect_pixel_level=320,
        auto_launch=False,
    ) as session:
        # image is a tightly packed BGR uint8 NumPy array.
        faces = session.face_detection(image)
        print(len(faces))
finally:
    isf.terminate()

Use Gundam_RK356X for RK3566/RK3568 and Gundam_RK3588 for RK3588. Get started shows image loading and detection-box drawing. For other Rockchip SoCs, follow the native deployment guide.

For a headless board, an available opencv-python-headless build can read images without a GUI dependency. If no compatible wheel exists, use the image-loading facilities supplied by the board environment and pass a correctly formatted NumPy array or ImageStream.

Deploy to more than one device

Package the Python source revision, native SDK build, model pack and board runtime as one deployment set. Keep that set consistent across devices with the same board configuration.

Before rolling out, run a fixed still-image check and a short camera sequence on each board configuration. Record native diagnostics where supported, then measure processing time with the intended RGA choice and enabled features. See troubleshooting for library-loading and model errors.