图片色彩空间转换
========

调用者可以调用本模块提供的[C API接口](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-imageprocessing)，实现HDR2SDR、SDR2HDR、SDR2SDR的图片色彩空间转换。

该能力常用于图片编辑中，如下图所示：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/ed/v3/R-B81QM_T66HBGorhqffrw/zh-cn_image_0000002625188223.png?HW-CC-KV=V1&HW-CC-Date=20260612T073520Z&HW-CC-Expire=86400&HW-CC-Sign=CAF7374A2C1E2B0D08B80DA91F275EB07F20CF561825FAE296BB29BDD37EC591)

#### 规格说明

**支持的数据输入格式：**

*   图片色彩空间转换算法为HDR2SDR：
    
    | 输入[ColorSpaceName](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-native-color-space-manager-h#colorspacename) | 输入[HdrMetadataType](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-pixelmap-native-h#oh_pixelmap_hdrmetadatatype) | 输入[PIXEL\_FORMAT](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-pixelmap-native-h#pixel_format) | **输出[ColorSpaceName](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-native-color-space-manager-h#colorspacename)** | 
    **输出**
    
    [HdrMetadataType](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-pixelmap-native-h#oh_pixelmap_hdrmetadatatype)
    
     | **输出[PIXEL\_FORMAT](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-pixelmap-native-h#pixel_format)** |
    | :-- | :-- | :-- | :-- | :-- | :-- |
    | BT2020\_HLG\_LIMIT / BT2020\_HLG | HDR\_METADATA\_TYPE\_ALTERNATE | PIXEL\_FORMAT\_YCBCR\_P010 / PIXEL\_FORMAT\_YCRCB\_P010 / PIXEL\_FORMAT\_RGBA\_1010102 | SRGB\_LIMIT/SRGB | HDR\_METADATA\_TYPE\_BASE | PIXEL\_FORMAT\_RGBA\_8888 / PIXEL\_FORMAT\_BGRA\_8888 |
    | BT2020\_PQ\_LIMIT / BT2020\_PQ | HDR\_METADATA\_TYPE\_ALTERNATE | 
    
    YCBCR\_P010
    
    YCRCB\_P010
    
    RGBA\_1010102
    
     | SRGB\_LIMIT/SRGB | HDR\_METADATA\_TYPE\_BASE | PIXEL\_FORMAT\_RGBA\_8888 / PIXEL\_FORMAT\_BGRA\_8888 |
    | BT2020\_HLG\_LIMIT / BT2020\_HLG | HDR\_METADATA\_TYPE\_NONE | 
    
    YCBCR\_P010
    
    YCRCB\_P010
    
    RGBA\_1010102
    
     | SRGB\_LIMIT/SRGB | HDR\_METADATA\_TYPE\_BASE | PIXEL\_FORMAT\_RGBA\_8888 / PIXEL\_FORMAT\_BGRA\_8888 |
    | BT2020\_PQ\_LIMIT / BT2020\_PQ | HDR\_METADATA\_TYPE\_NONE | 
    
    YCBCR\_P010
    
    YCRCB\_P010
    
    RGBA\_1010102
    
     | SRGB\_LIMIT/SRGB | HDR\_METADATA\_TYPE\_BASE | PIXEL\_FORMAT\_RGBA\_8888 / PIXEL\_FORMAT\_BGRA\_8888 |
    | BT2020\_HLG\_LIMIT / BT2020\_HLG | HDR\_METADATA\_TYPE\_ALTERNATE | 
    
    YCBCR\_P010
    
    YCRCB\_P010
    
    RGBA\_1010102
    
     | DISPLAY\_P3\_LIMIT/DISPLAY\_P3 | HDR\_METADATA\_TYPE\_BASE | PIXEL\_FORMAT\_RGBA\_8888 / PIXEL\_FORMAT\_BGRA\_8888 |
    | BT2020\_PQ\_LIMIT / BT2020\_PQ | HDR\_METADATA\_TYPE\_ALTERNATE | 
    
    YCBCR\_P010
    
    YCRCB\_P010
    
    RGBA\_1010102
    
     | DISPLAY\_P3\_LIMIT/DISPLAY\_P3 | HDR\_METADATA\_TYPE\_BASE | PIXEL\_FORMAT\_RGBA\_8888 / PIXEL\_FORMAT\_BGRA\_8888 |
    | BT2020\_HLG\_LIMIT / BT2020\_HLG | HDR\_METADATA\_TYPE\_NONE | 
    
    YCBCR\_P010
    
    YCRCB\_P010
    
    RGBA\_1010102
    
     | DISPLAY\_P3\_LIMIT/DISPLAY\_P3 | HDR\_METADATA\_TYPE\_BASE | PIXEL\_FORMAT\_RGBA\_8888 / PIXEL\_FORMAT\_BGRA\_8888 |
    | BT2020\_PQ\_LIMIT / BT2020\_PQ | HDR\_METADATA\_TYPE\_NONE | 
    
    YCBCR\_P010
    
    YCRCB\_P010
    
    RGBA\_1010102
    
     | DISPLAY\_P3\_LIMIT/DISPLAY\_P3 | HDR\_METADATA\_TYPE\_BASE | PIXEL\_FORMAT\_RGBA\_8888 / PIXEL\_FORMAT\_BGRA\_8888 |
    | BT2020\_HLG\_LIMIT / BT2020\_HLG | HDR\_METADATA\_TYPE\_ALTERNATE | 
    
    YCBCR\_P010
    
    YCRCB\_P010
    
    RGBA\_1010102
    
     | SRGB\_LIMIT/SRGB | HDR\_METADATA\_TYPE\_NONE | PIXEL\_FORMAT\_RGBA\_8888 / PIXEL\_FORMAT\_BGRA\_8888 |
    | BT2020\_PQ\_LIMIT / BT2020\_PQ | HDR\_METADATA\_TYPE\_ALTERNATE | 
    
    YCBCR\_P010
    
    YCRCB\_P010
    
    RGBA\_1010102
    
     | SRGB\_LIMIT/SRGB | HDR\_METADATA\_TYPE\_NONE | PIXEL\_FORMAT\_RGBA\_8888 / PIXEL\_FORMAT\_BGRA\_8888 |
    | BT2020\_HLG\_LIMIT / BT2020\_HLG | HDR\_METADATA\_TYPE\_NONE | 
    
    YCBCR\_P010
    
    YCRCB\_P010
    
    RGBA\_1010102
    
     | SRGB\_LIMIT/SRGB | HDR\_METADATA\_TYPE\_NONE | PIXEL\_FORMAT\_RGBA\_8888 / PIXEL\_FORMAT\_BGRA\_8888 |
    | BT2020\_PQ\_LIMIT / BT2020\_PQ | HDR\_METADATA\_TYPE\_NONE | 
    
    YCBCR\_P010
    
    YCRCB\_P010
    
    RGBA\_1010102
    
     | SRGB\_LIMIT/SRGB | HDR\_METADATA\_TYPE\_NONE | PIXEL\_FORMAT\_RGBA\_8888 / PIXEL\_FORMAT\_BGRA\_8888 |
    | BT2020\_HLG\_LIMIT / BT2020\_HLG | HDR\_METADATA\_TYPE\_ALTERNATE | 
    
    YCBCR\_P010
    
    YCRCB\_P010
    
    RGBA\_1010102
    
     | DISPLAY\_P3\_LIMIT/DISPLAY\_P3 | HDR\_METADATA\_TYPE\_NONE | PIXEL\_FORMAT\_RGBA\_8888 / PIXEL\_FORMAT\_BGRA\_8888 |
    | BT2020\_PQ\_LIMIT / BT2020\_PQ | HDR\_METADATA\_TYPE\_ALTERNATE | 
    
    YCBCR\_P010
    
    YCRCB\_P010
    
    RGBA\_1010102
    
     | DISPLAY\_P3\_LIMIT/DISPLAY\_P3 | HDR\_METADATA\_TYPE\_NONE | PIXEL\_FORMAT\_RGBA\_8888 / PIXEL\_FORMAT\_BGRA\_8888 |
    | BT2020\_HLG\_LIMIT / BT2020\_HLG | HDR\_METADATA\_TYPE\_NONE | 
    
    YCBCR\_P010
    
    YCRCB\_P010
    
    RGBA\_1010102
    
     | DISPLAY\_P3\_LIMIT/DISPLAY\_P3 | HDR\_METADATA\_TYPE\_NONE | PIXEL\_FORMAT\_RGBA\_8888 / PIXEL\_FORMAT\_BGRA\_8888 |
    | BT2020\_PQ\_LIMIT / BT2020\_PQ | HDR\_METADATA\_TYPE\_NONE | 
    
    YCBCR\_P010
    
    YCRCB\_P010
    
    RGBA\_1010102
    
     | DISPLAY\_P3\_LIMIT/DISPLAY\_P3 | HDR\_METADATA\_TYPE\_NONE | PIXEL\_FORMAT\_RGBA\_8888 / PIXEL\_FORMAT\_BGRA\_8888 |
    
*   图片色彩空间转换算法为SDR2HDR：
    
    | 输入[ColorSpaceName](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-native-color-space-manager-h#colorspacename) | 输入[HdrMetadataType](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-pixelmap-native-h#oh_pixelmap_hdrmetadatatype) | 输入[PIXEL\_FORMAT](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-pixelmap-native-h#pixel_format) | **输出[ColorSpaceName](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-native-color-space-manager-h#colorspacename)** | 
    **输出**
    
    [HdrMetadataType](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-pixelmap-native-h#oh_pixelmap_hdrmetadatatype)
    
     | **输出[PIXEL\_FORMAT](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-pixelmap-native-h#pixel_format)** |
    | :-- | :-- | :-- | :-- | :-- | :-- |
    | SRGB\_LIMIT | HDR\_METADATA\_TYPE\_NONE | RGBA\_8888 | BT2020\_HLG | HDR\_METADATA\_TYPE\_ALTERNATE | YCBCR\_P010 / RGBA\_1010102 |
    | DISPLAY\_P3\_LIMIT | HDR\_METADATA\_TYPE\_NONE | RGBA\_8888 | BT2020\_HLG | HDR\_METADATA\_TYPE\_ALTERNATE | YCBCR\_P010 / RGBA\_1010102 |
    | SRGB | HDR\_METADATA\_TYPE\_NONE | RGBA\_8888 | BT2020\_HLG | HDR\_METADATA\_TYPE\_ALTERNATE | YCBCR\_P010 / RGBA\_1010102 |
    | DISPLAY\_P3 | HDR\_METADATA\_TYPE\_NONE | RGBA\_8888 | BT2020\_HLG | HDR\_METADATA\_TYPE\_ALTERNATE | YCBCR\_P010 / RGBA\_1010102 |
    | SRGB | HDR\_METADATA\_TYPE\_NONE | RGBA\_8888 | BT2020\_HLG | HDR\_METADATA\_TYPE\_NONE | YCBCR\_P010 / RGBA\_1010102 |
    | DISPLAY\_P3 | HDR\_METADATA\_TYPE\_NONE | RGBA\_8888 | BT2020\_HLG | HDR\_METADATA\_TYPE\_NONE | YCBCR\_P010 / RGBA\_1010102 |
    | ADOBE\_RGB\_1998 | HDR\_METADATA\_TYPE\_NONE | 
    
    RGBA\_8888
    
    BGRA\_8888
    
     | BT2020\_HLG | HDR\_METADATA\_TYPE\_NONE | YCBCR\_P010 / RGBA\_1010102 |
    | SRGB | HDR\_METADATA\_TYPE\_NONE | 
    
    RGBA\_8888
    
    BGRA\_8888
    
     | BT2020\_PQ | HDR\_METADATA\_TYPE\_NONE | YCBCR\_P010 / RGBA\_1010102 |
    | DISPLAY\_P3 | HDR\_METADATA\_TYPE\_NONE | 
    
    RGBA\_8888
    
    BGRA\_8888
    
     | BT2020\_PQ | HDR\_METADATA\_TYPE\_NONE | YCBCR\_P010 / RGBA\_1010102 |
    | ADOBE\_RGB\_1998 | HDR\_METADATA\_TYPE\_NONE | 
    
    RGBA\_8888
    
    BGRA\_8888
    
     | BT2020\_PQ | HDR\_METADATA\_TYPE\_NONE | YCBCR\_P010 / RGBA\_1010102 |
    
*   图片色彩空间转换算法为SDR2SDR：
    
    | 输入[ColorSpaceName](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-native-color-space-manager-h#colorspacename) | 输入[HdrMetadataType](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-pixelmap-native-h#oh_pixelmap_hdrmetadatatype) | 输入[PIXEL\_FORMAT](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-pixelmap-native-h#pixel_format) | **输出[ColorSpaceName](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-native-color-space-manager-h#colorspacename)** | 
    **输出**
    
    [HdrMetadataType](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-pixelmap-native-h#oh_pixelmap_hdrmetadatatype)
    
     | **输出[PIXEL\_FORMAT](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-pixelmap-native-h#pixel_format)** |
    | :-- | :-- | :-- | :-- | :-- | :-- |
    | SRGB | HDR\_METADATA\_TYPE\_NONE | 
    
    RGBA\_8888,
    
    BGRA\_8888
    
     | SRGB | HDR\_METADATA\_TYPE\_NONE | RGBA\_8888 |
    | DISPLAY\_P3 | HDR\_METADATA\_TYPE\_NONE | 
    
    RGBA\_8888,
    
    BGRA\_8888
    
     | SRGB | HDR\_METADATA\_TYPE\_NONE | RGBA\_8888 |
    | ADOBE\_RGB\_1998 | HDR\_METADATA\_TYPE\_NONE | 
    
    RGBA\_8888,
    
    BGRA\_8888
    
     | SRGB | HDR\_METADATA\_TYPE\_NONE | RGBA\_8888 |
    | SRGB | HDR\_METADATA\_TYPE\_NONE | 
    
    RGBA\_8888,
    
    BGRA\_8888
    
     | DISPLAY\_P3 | HDR\_METADATA\_TYPE\_NONE | RGBA\_8888 |
    | DISPLAY\_P3 | HDR\_METADATA\_TYPE\_NONE | 
    
    RGBA\_8888,
    
    BGRA\_8888
    
     | DISPLAY\_P3 | HDR\_METADATA\_TYPE\_NONE | RGBA\_8888 |
    | ADOBE\_RGB\_1998 | HDR\_METADATA\_TYPE\_NONE | 
    
    RGBA\_8888,
    
    BGRA\_8888
    
     | DISPLAY\_P3 | HDR\_METADATA\_TYPE\_NONE | RGBA\_8888 |
    

**分辨率规格：**

| 最小分辨率（单位：像素） | 最大分辨率（单位：像素） |
| :-- | :-- |
| 32\*32 | 8880\*8880 |

**内存规格：**

处理的PixelMap对象需为[DMA内存](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/image-allocator-type-c#内存类型介绍)。

#### 开发指导

具体实现可参考[示例工程](https://gitcode.com/HarmonyOS_Samples/DocsSample_MultiMedia/tree/master/UsingImageProcessingToProcessImages)。

#### \[h2\]在 CMake 脚本中链接动态库

add\_library(entry SHARED napi\_init.cpp ImageProcessing/ImageProcessing.cpp)
target\_link\_libraries(entry PUBLIC ${BASE\_LIBRARY})

#### \[h2\]ArkTS侧调用的开发步骤

1.  创建8 bit的PixelMap。
    
    let srcPixelMap = nativePix.createPixelMap(this.inputHeight, this.inputWidth);
    let outPutPixelMap = nativePix.createPixelMap(this.inputHeight, this.inputWidth);
    
2.  配置色彩空间和元数据信息。
    
    let colorSpaceDISPLAY\_P3 : colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceManager.ColorSpace.DISPLAY\_P3);
    let colorSpaceSrgb : colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceManager.ColorSpace.SRGB);
    inputpixelMap.setColorSpace(colorSpaceDISPLAY\_P3);
    inputpixelMap.setMetadata(image.HdrMetadataKey.HDR\_METADATA\_TYPE, image.HdrMetadataType.NONE);
    outputpixelMap.setColorSpace(colorSpaceSrgb);
    outputpixelMap.setMetadata(image.HdrMetadataKey.HDR\_METADATA\_TYPE, image.HdrMetadataType.NONE);
    

#### \[h2\]Native侧调用的开发步骤

1.  添加头文件。
    
    #include <multimedia/image\_framework/image\_mdk\_common.h>
    #include <multimedia/image\_framework/image\_pixel\_map\_mdk.h>
    #include <multimedia/image\_framework/image/pixelmap\_native.h>
    #include <multimedia/video\_processing\_engine/image\_processing.h>
    #include <multimedia/video\_processing\_engine/image\_processing\_types.h>
    #include <native\_color\_space\_manager/native\_color\_space\_manager.h>
    
2.  （可选）初始化环境。
    
    一般在进程内第一次使用时调用，可提前完成部分耗时操作。
    
    ImageProcessing\_ErrorCode ret =  OH\_ImageProcessing\_InitializeEnvironment();
    
3.  （可选）查询能力支持。建议在使用对应能力前调用。
    
    //输入格式
    ImageProcessing\_ColorSpaceInfo SRC\_INFO;
    ImageProcessing\_ColorSpaceInfo DST\_GAIN\_INFO;
    ImageProcessing\_ColorSpaceInfo DST\_INFO;
    SRC\_INFO.colorSpace = DISPLAY\_P3;
    SRC\_INFO.metadataType = HDR\_METADATA\_TYPE\_NONE;
    SRC\_INFO.pixelFormat = PIXEL\_FORMAT\_RGBA\_8888;
    DST\_INFO.colorSpace = SRGB;
    DST\_INFO.metadataType = HDR\_METADATA\_TYPE\_NONE;
    DST\_INFO.pixelFormat = PIXEL\_FORMAT\_RGBA\_8888;
    //能力查询
    bool flag = OH\_ImageProcessing\_IsColorSpaceConversionSupported(&SRC\_INFO, &DST\_INFO);
    
4.  创建8 bit的PixelMap。
    
    napi\_value ImageProcessing::CreatePixelMap(napi\_env env, napi\_callback\_info info)
    {
        napi\_value udfVar = nullptr;
        napi\_value pixelMap = nullptr;
        napi\_value thisVar = nullptr;
        napi\_value argValue\[2\] = {0};
        size\_t argCount = 2;
        size\_t count = 2;
        if (napi\_get\_cb\_info(env, info, &argCount, argValue, &thisVar, nullptr) != napi\_ok || argCount < count ||
            argValue\[0\] == nullptr || argValue\[1\] == nullptr) {
            return nullptr;
        }
        int32\_t width = 0;
        int32\_t height = 0;
        napi\_get\_value\_int32(env, argValue\[1\], &width);
        napi\_get\_value\_int32(env, argValue\[0\], &height);
        struct OhosPixelMapCreateOps createOps;
        createOps.width = width;
        createOps.height = height;
        int32\_t rgba8888 = 3;
        createOps.pixelFormat = rgba8888;
        createOps.alphaType = 0;
        
        size\_t bufferSize = createOps.width \* createOps.height \* 4;
        void \*buff = malloc(bufferSize);
        int32\_t res = OH\_PixelMap\_CreatePixelMapWithStride(env, createOps, (uint8\_t \*)buff, bufferSize, createOps.width \* 4,
            &pixelMap);
        free(buff);
        OH\_LOG\_Print(LOG\_APP, LOG\_INFO, LOG\_PRINT\_DOMAIN, "createPixelMap",
            "OH\_PixelMap\_CreatePixelMapWithStride %{public}d", res);
        if (res != IMAGE\_RESULT\_SUCCESS || pixelMap == nullptr) {
            return udfVar;
        }
        return pixelMap;
    }
    
5.  将ArkTS中的PixelMap转换为C++的PixelMap。
    
    OH\_PixelmapNative\* srcImg = nullptr;
    OH\_PixelmapNative\_ConvertPixelmapNativeFromNapi(env, argValue\[0\], &srcImg);
    OH\_PixelmapNative\* dstImg= nullptr;
    OH\_PixelmapNative\_ConvertPixelmapNativeFromNapi(env, argValue\[1\], &dstImg);
    
6.  创建图片色彩空间转换模块。
    
    应用可以通过图片处理引擎模块类型来创建图片色彩空间转换模块。示例中的变量说明如下：
    
    *   instance：图片处理模块实例。
    *   IMAGE\_PROCESSING\_TYPE\_COLOR\_SPACE\_CONVERSION：图片色彩空间转换。
    *   预期返回值：IMAGE\_PROCESSING\_SUCCESS
    
    OH\_ImageProcessing\* instance = nullptr;
    ret = OH\_ImageProcessing\_Create(&instance, IMAGE\_PROCESSING\_TYPE\_COLOR\_SPACE\_CONVERSION);
    
7.  执行算法。
    
    ret = OH\_ImageProcessing\_ConvertColorSpace(instance, srcImg, dstImg);
    
8.  释放实例资源。
    
    ret = OH\_ImageProcessing\_Destroy(instance);
    instance = nullptr;
    
9.  释放初始化环境资源。
    
    ret = OH\_ImageProcessing\_DeinitializeEnvironment();
    

#### 完整示例代码

ArkTS示例代码：

*   [ImageColorSpaceConversion.ets示例代码](https://gitcode.com/HarmonyOS_Samples/DocsSample_MultiMedia/blob/master/UsingImageProcessingToProcessImages/entry/src/main/ets/view/ImageColorSpaceConversionComponent.ets)

C++相关示例代码：

*   [CMakeLists.txt示例代码](https://gitcode.com/HarmonyOS_Samples/DocsSample_MultiMedia/blob/master/UsingImageProcessingToProcessImages/entry/src/main/cpp/CMakeLists.txt)
    
*   [ImageProcessing.h示例代码](https://gitcode.com/HarmonyOS_Samples/DocsSample_MultiMedia/blob/master/UsingImageProcessingToProcessImages/entry/src/main/cpp/ImageProcessing/ImageProcessing.h)
    
*   [ImageProcessing.cpp示例代码](https://gitcode.com/HarmonyOS_Samples/DocsSample_MultiMedia/blob/master/UsingImageProcessingToProcessImages/entry/src/main/cpp/ImageProcessing/ImageProcessing.cpp)