基于iOS 16 vImage API计算10位HDR CVPixelBuffer的Y与RGB直方图

提问翻译 #

我从相机获取了YCbCr格式（422或420双平面10位视频范围）的CVPixelBuffer，了解到vImage框架可处理多种图像格式（包括各类YCbCr格式的像素缓冲区）。我希望计算Y（亮度）分量和RGB的直方图。针对8位YCbCr样本，我可通过以下代码计算Y分量的直方图：

var alphaBin = [vImagePixelCount](repeating: 0, count: Int(numBins))

CVPixelBufferLockBaseAddress(pixelBuffer, .readOnly)

let bytesPerRow = CVPixelBufferGetBytesPerRowOfPlane(pixelBuffer, 0)
let baseAddress = CVPixelBufferGetBaseAddressOfPlane(pixelBuffer, 0)
let height = CVPixelBufferGetHeightOfPlane(pixelBuffer, 0)
let width = CVPixelBufferGetWidthOfPlane(pixelBuffer, 0)

CVPixelBufferUnlockBaseAddress(pixelBuffer, .readOnly)

var buffer = vImage_Buffer(data: baseAddress, height: vImagePixelCount(height), width: vImagePixelCount(width), rowBytes: bytesPerRow)

alphaBin.withUnsafeMutableBufferPointer { alphaPtr in
    let error = vImageHistogramCalculation_Planar8(&buffer, alphaPtr.baseAddress!, UInt32(kvImageNoFlags))

    guard error == kvImageNoError else {
        fatalError("Error calculating histogram luma: \(error)")
    }
}

请问如何针对10位HDR像素缓冲区实现相同功能？最好使用iOS 16新增的vImage API（这类API灵活性更高，例如无需显式进行像素格式转换即可从YCbCr样本获取RGB直方图）。

一、先修正基础隐患：像素缓冲区锁定时机 #

你提供的8位代码存在内存安全问题：在创建vImage_Buffer前就解锁了CVPixelBuffer，这会导致baseAddress失效。正确做法是在直方图计算完成后再解锁，下文代码会用defer语句确保这一点。

二、计算10位Y分量直方图 #

针对双平面YCbCr的Y分量（第0平面），使用vImageHistogramCalculation_Planar10API处理10位单平面数据：

func calculate10BitLumaHistogram(from pixelBuffer: CVPixelBuffer, numBins: Int = 1024) throws -> [vImagePixelCount] {
    // 10位像素对应0~1023共1024个级别，建议numBins设为1024
    var lumaBins = [vImagePixelCount](repeating: 0, count: numBins)
    
    CVPixelBufferLockBaseAddress(pixelBuffer, .readOnly)
    defer { CVPixelBufferUnlockBaseAddress(pixelBuffer, .readOnly) }
    
    guard let yBaseAddress = CVPixelBufferGetBaseAddressOfPlane(pixelBuffer, 0) else {
        throw NSError(domain: "vImageError", code: -1, userInfo: [NSLocalizedDescriptionKey: "无法获取Y平面内存地址"])
    }
    
    let yWidth = CVPixelBufferGetWidthOfPlane(pixelBuffer, 0)
    let yHeight = CVPixelBufferGetHeightOfPlane(pixelBuffer, 0)
    let yBytesPerRow = CVPixelBufferGetBytesPerRowOfPlane(pixelBuffer, 0)
    
    var yBuffer = vImage_Buffer(data: yBaseAddress,
                                height: vImagePixelCount(yHeight),
                                width: vImagePixelCount(yWidth),
                                rowBytes: yBytesPerRow)
    
    let error = lumaBins.withUnsafeMutableBufferPointer { binsPtr in
        vImageHistogramCalculation_Planar10(&yBuffer, binsPtr.baseAddress!, UInt32(kvImageNoFlags))
    }
    
    guard error == kvImageNoError else {
        throw NSError(domain: "vImageError", code: Int(error), userInfo: [NSLocalizedDescriptionKey: "亮度直方图计算失败：\(error)"])
    }
    
    return lumaBins
}

三、iOS 16+：直接从YCbCr计算RGB直方图 #

iOS 16新增的vImageHistogramCalculation_YCbCrToRGBAPI支持直接从双平面10位YCbCr计算RGB直方图，无需提前转换格式：

@available(iOS 16.0, *)
func calculateRGBHistogramFrom10BitYCbCr(from pixelBuffer: CVPixelBuffer, numBins: Int = 1024) throws -> (red: [vImagePixelCount], green: [vImagePixelCount], blue: [vImagePixelCount]) {
    var redBins = [vImagePixelCount](repeating: 0, count: numBins)
    var greenBins = [vImagePixelCount](repeating: 0, count: numBins)
    var blueBins = [vImagePixelCount](repeating: 0, count: numBins)
    
    CVPixelBufferLockBaseAddress(pixelBuffer, .readOnly)
    defer { CVPixelBufferUnlockBaseAddress(pixelBuffer, .readOnly) }
    
    guard let yBaseAddress = CVPixelBufferGetBaseAddressOfPlane(pixelBuffer, 0),
          let cbCrBaseAddress = CVPixelBufferGetBaseAddressOfPlane(pixelBuffer, 1) else {
        throw NSError(domain: "vImageError", code: -1, userInfo: [NSLocalizedDescriptionKey: "无法获取YCbCr平面内存地址"])
    }
    
    let yWidth = CVPixelBufferGetWidthOfPlane(pixelBuffer, 0)
    let yHeight = CVPixelBufferGetHeightOfPlane(pixelBuffer, 0)
    let yBytesPerRow = CVPixelBufferGetBytesPerRowOfPlane(pixelBuffer, 0)
    
    let cbCrWidth = CVPixelBufferGetWidthOfPlane(pixelBuffer, 1)
    let cbCrHeight = CVPixelBufferGetHeightOfPlane(pixelBuffer, 1)
    let cbCrBytesPerRow = CVPixelBufferGetBytesPerRowOfPlane(pixelBuffer, 1)
    
    var yBuffer = vImage_Buffer(data: yBaseAddress,
                                height: vImagePixelCount(yHeight),
                                width: vImagePixelCount(yWidth),
                                rowBytes: yBytesPerRow)
    
    var cbCrBuffer = vImage_Buffer(data: cbCrBaseAddress,
                                   height: vImagePixelCount(cbCrHeight),
                                   width: vImagePixelCount(cbCrWidth),
                                   rowBytes: cbCrBytesPerRow)
    
    // 根据像素格式匹配转换参数
    let pixelFormat = CVPixelBufferGetPixelFormatType(pixelBuffer)
    let ycbcrFormat: vImage_YCbCrToRGBFormat
    switch pixelFormat {
    case kCVPixelFormatType_422YpCbCr10BiPlanarVideoRange:
        ycbcrFormat = vImage_YCbCrToRGBFormat(kvImageYCbCrToRGB_ITU_R_BT_709_422VideoRange)
    case kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange:
        ycbcrFormat = vImage_YCbCrToRGBFormat(kvImageYCbCrToRGB_ITU_R_BT_709_420VideoRange)
    default:
        throw NSError(domain: "vImageError", code: -2, userInfo: [NSLocalizedDescriptionKey: "不支持的YCbCr像素格式"])
    }
    
    // 调用iOS16新增API计算RGB直方图
    let error = redBins.withUnsafeMutableBufferPointer { redPtr in
        greenBins.withUnsafeMutableBufferPointer { greenPtr in
            blueBins.withUnsafeMutableBufferPointer { bluePtr in
                vImageHistogramCalculation_YCbCrToRGB(&yBuffer,
                                                      &cbCrBuffer,
                                                      redPtr.baseAddress!,
                                                      greenPtr.baseAddress!,
                                                      bluePtr.baseAddress!,
                                                      UInt32(numBins),
                                                      ycbcrFormat,
                                                      UInt32(kvImageNoFlags))
            }
        }
    }
    
    guard error == kvImageNoError else {
        throw NSError(domain: "vImageError", code: Int(error), userInfo: [NSLocalizedDescriptionKey: "RGB直方图计算失败：\(error)"])
    }
    
    return (red: redBins, green: greenBins, blue: blueBins)
}

关键注意事项 #

• 10位数据的bin数：10位像素有1024个亮度级别，建议numBins设为1024以保留完整精度；若需合并级别可调整为更小值，但会损失细节。
• 像素格式匹配：确保传入的CVPixelBuffer是相机输出的标准双平面10位YCbCr格式（如kCVPixelFormatType_422YpCbCr10BiPlanarVideoRange），否则API会返回错误。
• 内存安全：必须在使用完vImage缓冲区后再解锁CVPixelBuffer，defer语句可自动保证这一点，避免野指针问题。

内容的提问来源于stack exchange，提问作者Deepak Sharma