如何将ZKTECO-SLK20R生成的regTemp字节数组转为BMP文件

问题背景 #

在Java项目中使用ZKTECO-SLK20R扫描仪，调用DBMerge(long dbHandle , byte[] temp1, byte[] temp2, byte[] temp3, byte[] regTemp, int[] regTempLen)合并已注册指纹模板后，得到的regTemp字节数组无法转为BMP文件。尝试两种通用BMP转换方案均失败：

• 方案1抛出java.lang.ArrayIndexOutOfBoundsException: Index 2048 out of bounds for length 2048
• 方案2抛出java.lang.IllegalArgumentException: image == null!

相关Java代码片段：

public class ZKFPDemo extends JFrame{
    private JTextArea textArea;
    // 预注册模板数组
    private byte[][] regtemparray = new byte[3][2048];
    private long mhDB = 0;

    private void OnExtractOK(byte[] template, int len){
           int[] _retLen = new int[1];
           _retLen[0] = 2048;
           byte[] regTemp = new byte[_retLen[0]];

           if(0 == (ret = FingerprintSensorEx.DBMerge(mhDB, 
              regtemparray[0], regtemparray[1], regtemparray[2], 
              regTemp, _retLen)){
                   // 此处需将regTemp转为BMP文件
                   textArea.setText("Merged successfully.");

    }else{

                   textArea.setText("Failed to merge.");

    }
  }
}

而C#中使用对应SDK可通过以下代码成功转换：

public static BitmapSource ToBitmapSource(byte[] buffer)
    {
        BitmapSource bitmap = null;

        if (buffer != null && !(buffer.Length < 10))
        {
            using (var stream = new MemoryStream(buffer))
            {
                bitmap = BitmapFrame.Create(
                    stream, BitmapCreateOptions.None, BitmapCacheOption.OnLoad);
            }
        }

        return bitmap;
    }

问题根源 #

C#版本的ZK SDK内部对指纹模板字节数组做了模板到图像的隐式转换处理，而Java SDK的DBMerge返回的regTemp是原始指纹模板数据（并非标准BMP文件字节流），直接用通用BMP转换方法自然会失败。

可行解决方案 #

方案1：使用ZKTECO Java SDK原生转换API #

检查ZKTECO官方Java SDK文档，查找是否提供TemplateToImage或类似功能的方法——这类方法会直接将指纹模板字节数组转换为图像数据。

假设SDK提供如下方法，调用后可直接生成BMP格式数据：

// 示例：SDK提供的模板转图像方法
int imageWidth = 256;
int imageHeight = 360;
byte[] imageBuffer = new byte[imageWidth * imageHeight];
int result = FingerprintSensorEx.TemplateToImage(mhDB, regTemp, _retLen[0], imageBuffer, imageWidth, imageHeight);

// 将imageBuffer写入BMP文件（需补充BMP头构建逻辑）

方案2：手动解析模板生成BMP #

若SDK无原生转换API，需根据ZKTECO指纹模板格式（通常遵循ISO/IEC 19794-2标准或厂商自定义格式）手动解析并构建BMP文件：

private void convertTemplateToBmp(byte[] regTemp, int tempLen, String outputPath) throws IOException {
    // 1. 从模板中提取图像参数（需参考ZK官方文档确认实际值）
    int width = 256;
    int height = 360;
    int bitsPerPixel = 8; // 灰度图像
    int rowSize = (width * bitsPerPixel + 31) / 32 * 4; // BMP行字节数对齐到4字节

    // 2. 构建BMP文件头（14字节）
    byte[] fileHeader = new byte[14];
    fileHeader[0] = 'B';
    fileHeader[1] = 'M';
    int fileSize = 14 + 40 + rowSize * height;
    System.arraycopy(intToLittleEndian(fileSize), 0, fileHeader, 2, 4);
    fileHeader[10] = (byte)(14 + 40); // 像素数据偏移量

    // 3. 构建BMP信息头（40字节）
    byte[] infoHeader = new byte[40];
    infoHeader[0] = 40; // 信息头长度
    System.arraycopy(intToLittleEndian(width), 0, infoHeader, 4, 4);
    System.arraycopy(intToLittleEndian(height), 0, infoHeader, 8, 4);
    infoHeader[12] = 1; // 平面数
    infoHeader[14] = (byte)bitsPerPixel;
    System.arraycopy(intToLittleEndian(rowSize * height), 0, infoHeader, 20, 4);

    // 4. 从模板中提取像素数据（需根据模板格式调整头部偏移）
    int templateHeaderOffset = 128; // 假设模板前128字节为头部
    byte[] pixelData = new byte[rowSize * height];
    System.arraycopy(regTemp, templateHeaderOffset, pixelData, 0, width * height);
    // BMP像素数据需从下到上排列，此处需反转行顺序
    reversePixelRows(pixelData, width, height, rowSize);

    // 5. 写入BMP文件
    try (FileOutputStream fos = new FileOutputStream(outputPath)) {
        fos.write(fileHeader);
        fos.write(infoHeader);
        fos.write(pixelData);
    }
}

// 辅助方法：int转小端字节数组
private byte[] intToLittleEndian(int value) {
    return new byte[]{
        (byte)(value & 0xFF),
        (byte)((value >> 8) & 0xFF),
        (byte)((value >> 16) & 0xFF),
        (byte)((value >> 24) & 0xFF)
    };
}

// 反转像素行顺序以适配BMP格式
private void reversePixelRows(byte[] pixelData, int width, int height, int rowSize) {
    byte[] tempRow = new byte[rowSize];
    for (int i = 0; i < height / 2; i++) {
        int topRowIndex = i * rowSize;
        int bottomRowIndex = (height - 1 - i) * rowSize;
        System.arraycopy(pixelData, topRowIndex, tempRow, 0, rowSize);
        System.arraycopy(pixelData, bottomRowIndex, pixelData, topRowIndex, rowSize);
        System.arraycopy(tempRow, 0, pixelData, bottomRowIndex, rowSize);
    }
}

方案3：跨语言调用C#转换逻辑 #

若上述方案均无法实现，可通过JNI或进程调用方式，让Java调用C#编写的转换程序，传入regTemp字节数组，由C#处理后返回BMP文件路径或字节流。

注意事项 #

• 优先参考ZKTECO SLK20R官方SDK文档，确认模板格式和可用API，这是解决问题的核心依据。
• 手动解析时需注意BMP文件的字节序（小端）和像素存储顺序（从下到上）。

内容的提问来源于stack exchange，提问作者Said Naweed