手部异常多分类算法 SDK · 客户对接手册

一、概述与交付物

本算法用于晨检 / 工牌核验场景下的手部异常检测：检测戒指、指甲油、伤口、创可贴、手镯手链等佩戴物， 并判读手掌 / 手背的放置是否合规。模型为 RK3568 专用 INT8 统一模型，由 RKNN NPU 推理。

您拿到的文件

二、两步接入

三、工程配置（一次性，3 处）

3.1 引入 AAR（app/build.gradle）

android {
    compileSdk 34
    defaultConfig {
        minSdk 24                          // ≥ 23（Android Keystore 要求）
        ndk { abiFilters 'arm64-v8a' }     // RK3568 只需 arm64
    }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
}
dependencies {
    // ★ 唯一依赖，无需再声明其它库
    implementation files('libs/handanomaly-sdk-rknn-3.0.0.aar')
}

3.2 权限

<uses-permission android:name="android.permission.INTERNET" />

3.3 混淆

AAR 自带混淆规则，开启 minifyEnabled 无需额外配置。

四、激活（公网，仅首次）

4.1 四种激活方式（任选其一，与我方运营确认即可）

4.2 Java 代码

import com.company.handanomaly.sdk.HandAnomalySdk;

// 无参构造：激活地址 / 指纹 / 密文包 / 公钥已全部内置，只传 Context
HandAnomalySdk sdk = new HandAnomalySdk(context.getApplicationContext());

// 仅首次；之后启动自动复用本机授权
if (!sdk.isActivated()) {
    sdk.activate("ACT-XXXX-XXXX-XXXX");   // ① 激活码
    // sdk.activateByDevice();            // ② 云端激活
}

五、识别（传摄像头画面）

// bytes：摄像头一帧（JPEG/PNG 字节）
List<Map<String,Object>> results = sdk.recognizeImageBytes(bytes);

for (Map<String,Object> r : results) {
    String label = (String) r.get("label");                 // 类别名，如 "wound"
    float  score = ((Number) r.get("score")).floatValue();  // 置信度 0~1
    float[] bbox  = (float[]) r.get("bbox");                // [x, y, 宽, 高]（原图像素）
}

// 要 JSON：String json = sdk.recognizeToJson(bytes);

// 与 CameraX 配合：ImageAnalysis 回调里把帧编码为 JPEG 后交给 SDK 即可
// 释放：sdk.release();  （Activity/Application 退出时调用，下次识别自动重建）

六、结果语义（10 类，重要）

模型同时输出整手框与异常框两类目标，请区分处理：

推荐判定逻辑

boolean hasHand = false;
List<String> anomalies = new ArrayList<>();
for (Map<String,Object> r : results) {
    String label = (String) r.get("label");
    if ("palm".equals(label) || "back".equals(label)) {
        hasHand = true;                       // 整手框：手已正确放置
    } else {
        anomalies.add(label);                 // 异常框：佩戴物/伤患
    }
}
// 无整手框 → 未检测到手 / 放置不合规；anomalies 非空 → 存在需提示的异常

七、授权说明

算法包以密文形式内置在 SDK 中，SDK 内不含任何解密密钥。密钥只在激活成功时由授权平台用本机密钥加密下发：

• 未激活 = 无法解密算法包（密码学保证，非软件开关）。
• 激活一次后离线可用：授权缓存在本机，断网识别不受影响。
• 激活码一次性绑定设备，不能在第二台设备重复使用。
• 授权到期 / 被吊销后，设备下次联网激活即被拒。

八、错误排查

九、FAQ

Q：每次运行都要激活吗？
A：不需要。仅首次；之后自动复用本机授权，断网可用。

Q：支持哪些设备？
A：RK3568 主板（Android，arm64）。其它平台（Flutter / Python / 其它芯片）另有交付形态，联系我方。

Q：可以多线程并发识别吗？
A：不建议。请依次调用（可放同一后台线程/队列）。

Q：一帧传多大图？
A：建议 ≤ 1280×720，SDK 内部自动缩放。

附录 · Java 完整示例

完整可编译示例见随包文件 HandAnomalyClient.java，要点如下：

public class HandAnomalyClient {
    private final HandAnomalySdk sdk;
    public HandAnomalyClient(android.content.Context ctx) {
        sdk = new HandAnomalySdk(ctx.getApplicationContext());
    }
    public void ensureActivated(String activationCode) {
        if (!sdk.isActivated()) sdk.activate(activationCode);
    }
    public void inspect(byte[] jpegBytes) {
        List<Map<String,Object>> results = sdk.recognizeImageBytes(jpegBytes);
        boolean hasHand = false;
        List<String> anomalies = new ArrayList<>();
        for (Map<String,Object> r : results) {
            String label = (String) r.get("label");
            if ("palm".equals(label) || "back".equals(label)) hasHand = true;
            else anomalies.add(label);
        }
        // 业务逻辑：hasHand / anomalies
    }
}