从V473版本开始，提供新版绿幕抠图算法。
新版绿幕抠图基于剪映最新版绿幕算法进行迭代优化，抠图效果在质量，智能化以及场景兼容性上均处于领先地位。SDK除了提供识别绿幕和绿色背景外，可以识别任何背景主色（如蓝色，红色等幕布）以进行抠图。此外，相比于老版本绿幕算法，在效果以及性能上也有较大优势，支持更多参数以进行精细调节，也支持一键自动化抠图方案。

详细接口说明查看头文件：bef_effect_ai_chroma_keying.h

1.创建绿幕抠图句柄

BEF_SDK_API bef_effect_result_t   
bef_effect_ai_chroma_keying_create(bef_effect_handle_t *handle);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

2.从文件初始化模型参数

// 当前版本暂不支持模型设置, model_path 设置成空字符串就好 
BEF_SDK_API bef_effect_result_t   
bef_effect_ai_chroma_keying_init(
    bef_effect_handle_t handle,    const char* model_path = "");

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

3.设置SDK参数

// 上一版本设置处理参数。
BEF_SDK_API 
void bef_effect_ai_chroma_keying_set_processParam(float similar, float smoothness, float correction, float clip_black, float clip_white);

// 新版本算法设置处理参数。
BEF_SDK_API
void bef_effect_ai_chroma_keying_set_processParam(bef_effect_handle_t handle, bef_ai_chroma_keying_uniform_type uniformType, float value);

参数说明

// 涉及参数及其含义
typedef enum{
    BEF_AI_CHROMA_KEYING_UNIFORM_COLOR = 0,         // COLOR：[0,360]，算法会自动调色，可以手动更改微调绿幕主色
    BEF_AI_CHROMA_KEYING_UNIFORM_INTENSITY = 1,     // INTENSITY：[0,1]，抠图强度，以COLOR为中心，影响抠除色域的范围
    BEF_AI_CHROMA_KEYING_UNIFORM_SPILL = 2,         // SPILL：[0,1]，去溢色能力，对于绿幕，会把前景里泛绿的颜色矫正
    BEF_AI_CHROMA_KEYING_UNIFORM_EDGE_SMOOTH = 3,   // EDGE_SMOOTH：[0,1]，边缘平滑能力，适当的值可以去锯齿，值过大可能会导致前景模糊
    BEF_AI_CHROMA_KEYING_UNIFORM_DETAIL = 4,        // DETAIL：[0,1]，细节增强能力，0为通用方案，1为精细方案，之间进行效果加权
    BEF_AI_CHROMA_KEYING_UNIFORM_SHADOW = 5         // SHADOW：[0,1]，阴影增强能力，可用于保留阴影
}bef_ai_chroma_keying_uniform_type;

// 设置float类型的参数接口 
BEF_SDK_API bef_effect_result_t 
bef_effect_ai_chroma_keying_set_paramF(
    bef_effect_handle_t handle,
    bef_ai_chroma_keying_param_type type,
    float value);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

// 设置int类型的参数接口 
BEF_SDK_API bef_effect_result_t 
bef_effect_ai_chroma_keying_set_paramI(
    bef_effect_handle_t handle,
    bef_ai_chroma_keying_param_type type,
    int value);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h
备注
bef_ai_chroma_keying_param_type 详细见bef_effect_ai_chroma_keying.h

/** 
 * @brief 参数枚举 
 * 
 */ 
typedef enum { 
    BEF_AI_CHROMA_KEYING_METHOD = 0,    // 算法key, int。 
                                        // 可选值有：0: 移动端实时方案【推荐默认】 
                                        //         1: 服务端方案 
    BEF_AI_CHROMA_KEYING_CAL_COLOR = 1, // 算法背景色计算key, int。 
                                        // 可选值有：0：全图自动主色提取 
                                        //         1： 绿幕场景精细化主色提取【默认】 
                                        //         2：人工设置主色提取（说明：该选项下返回变量的背景色彩为人工设置色彩） 
    BEF_AI_CHROMA_KEYING_BG_R = 2,      // 背景色设置，红色，0～255【默认0】, int。 
    BEF_AI_CHROMA_KEYING_BG_G = 3,      // 背景色设置，绿色，0～255【默认255】, int。 
    BEF_AI_CHROMA_KEYING_BG_B = 4,      // 背景色设置，蓝色，0～255【默认0】, int。 
    BEF_AI_CHROMA_KEYING_BALP = 5,      // 强度调节，float。 
                                        // 色彩范围参数 case1: 小于0，自动模式，chroma_keying_cal_color为“1”时候推荐，如【默认-1】 
                                        //            case2: 0～1，手动模式，chroma_keying_cal_color为“2”时候推荐设置为0.6～0.7 
    BEF_AI_CHROMA_KEYING_KALP = 6,      // 强度调节：锐利度参数【推荐0.15】，建议不调节，float。 
    BEF_AI_CHROMA_KEYING_SMOOTH = 7,    // 平滑系数，float。 
                                        // case1:小于0时无平滑 
                                        // case2:0 仅启用mask时序平滑，估色无时序平滑【推荐0】 
                                        // case3:0～1 启用mask时序平滑，参数描述背景色估计平滑下强度（算法内部限制最大为1） 
    BEF_AI_CHROMA_KEYING_SHARPEN = 8,   // mask边界锐化key，int。 
                                        // 可选有： <=0: 不启用边界锐化 
                                        //         >=1: 启用边界锐化【推荐设置为1】 
    BEF_AI_CHROMA_KEYING_GET_MASK = 9,  // mask计算并返回，int。 
                                        // 可选有：<=0: 不返回mask（仅获得背景色彩估计） 
                                        //        >=1: 计算mask，同时获得背景色估计和背景色估值【默认请设1】 
} bef_ai_chroma_keying_param_type;

4.进行绿幕抠图操作

//原版
BEF_SDK_API bef_effect_result_t 
bef_effect_ai_chroma_keying_detect( 
    bef_effect_handle_t handle, 
    const unsigned char *image, 
    bef_ai_pixel_format pixel_format, 
    int image_width, 
    int image_height, 
    int image_stride, 
    bef_ai_rotate_type orientation, 
    bef_ai_chroma_keying_ret *result, 
    bool soft_process); //V450去绿处理

//新版
BEF_SDK_API bef_effect_result_t 
bef_effect_ai_chroma_keying_detect( 
    bef_effect_handle_t handle, 
    const unsigned char *image, 
    bef_ai_pixel_format pixel_format, 
    int image_width, 
    int image_height, 
    int image_stride, 
    bef_ai_rotate_type orientation, 
    bef_ai_chroma_keying_ret *result, 
    bool autoColor); // 本帧处理中是否运行自动主色提取，为true，则会自动主色提取并返回提取结果

新版算法除了保留原有的“bef_effect_ai_chroma_keying_detect”接口外，将该接口进行了拆分，以进行性能优化，支持仅纹理输入；拆分后的两个接口如下：

// 该接口根据传入的image buffer进行绿幕背景主色提取，通过入参返回算法提取的主色
BEF_SDK_API bef_effect_result_t 
bef_effect_ai_chroma_keying_algorithm_buffer(
    bef_effect_handle_t handle,
    const unsigned char *image,
    bef_ai_pixel_format pixel_format,
    int image_width,
    int image_height,
    int image_stride,
    bef_ai_rotate_type orientation,
    bef_ai_chroma_keying_algorithm_buffer_ret *result);
    
// 该接口通过传入纹理id以及主色提取结果，进行绿幕抠图
BEF_SDK_API bef_effect_result_t 
bef_effect_ai_chroma_keying_process_texture(
    bef_effect_handle_t handle,
    unsigned int srcTexture,
    int image_width,
    int image_height,
    bef_ai_chroma_keying_algorithm_buffer_ret algorithm_ret,
    bef_ai_chroma_keying_process_texture_ret *result);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h
备注
bef_ai_chroma_keying_ret 详细见bef_effect_ai_chroma_keying.h
版本4.4.0及以上输出结果：

/** 
 * @brief 输出结果 
 */ 
typedef struct 
{ 
    int width;             // 返回宽 
    int height;            // 返回高 
    unsigned char color_b; // 背景色识别：蓝色 
    unsigned char color_g; // 背景色识别：绿色 
    unsigned char color_r; // 背景色识别：红色 
    float color_h;
    float color_s;
    float color_v;
    int outputTexture; // 输出的纹理rgb为原图大小纹理， alpha 通道为原图和目标图的混合系数 
} bef_ai_chroma_keying_ret;

5.释放句柄

BEF_SDK_API bef_effect_result_t 
bef_effect_ai_chroma_keying_release(bef_effect_handle_t handle);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

6.绿幕抠图授权

// 离线license检测方式 
BEF_SDK_API bef_effect_result_t 
bef_effect_ai_chroma_keying_check_license( 
    bef_effect_handle_t handle, 
    const char *licensePath); 
 
// 在线license检测方式 
BEF_SDK_API bef_effect_result_t 
bef_effect_ai_chroma_keying_check_online_license( 
    bef_effect_handle_t handle, 
    const char *licensePath);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

接口说明
详细接口说明查看文件：com.bytedance.labcv.effectsdk.ChromaKeying.java

1.初始化绿幕抠图句柄

public int init( 
    Context context, 
    String modelPath, 
    String licensePath, 
    boolean onlineLicense)

参数说明

返回值
成功返回BEF_RESULT_SUC，否则返回对应的错误码

2.设置SDK参数

// 老版本绿幕
public int setProcessParam(float similar, float smoothness, float correction, float clip_black, float clip_white)

// 当前版本
mDetector.setProcessParam(ChromaKeyingUniformType.BEF_AI_CHROMA_KEYING_UNIFORM_INTENSITY,0.3f);

涉及参数及含义：

public enum ChromaKeyingUniformType {
    BEF_AI_CHROMA_KEYING_UNIFORM_COLOR(0),      // COLOR：[0,360]，算法会自动调色，可以手动更改微调绿幕主色
    BEF_AI_CHROMA_KEYING_UNIFORM_INTENSITY(1),  // INTENSITY：[0,1]，抠图强度，以COLOR为中心，影响抠除色域的范围
    BEF_AI_CHROMA_KEYING_UNIFORM_SPILL(2),      // SPILL：[0,1]，去溢色能力，对于绿幕，会把前景里泛绿的颜色矫正
    BEF_AI_CHROMA_KEYING_UNIFORM_EDGE_SMOOTH(3),// EDGE_SMOOTH：[0,1]，边缘平滑能力，适当的值可以去锯齿，值过大可能会导致前景模糊
    BEF_AI_CHROMA_KEYING_UNIFORM_DETAIL(4),     // DETAIL：[0,1]，细节增强能力，0为通用方案，1为精细方案，之间进行效果加权
    BEF_AI_CHROMA_KEYING_UNIFORM_SHADOW(5);     // SHADOW：[0,1]，阴影增强能力，可用于保留阴影
}

参数效果：

可以在demo中使用下图对每个参数进行调整，了解每个参数的效果。

// 设置float类型的参数接口 
public int setParamF( 
    BytedEffectConstants.ChromaKeyingParamType paramType, 
    float value)

参数说明

// 设置int类型的参数接口 
public int setParamI( 
    BytedEffectConstants.ChromaKeyingParamType paramType, 
    int value)

参数说明

返回值
成功返回BEF_RESULT_SUC，否则返回对应的错误码
备注
关于BytedEffectConstants.ChromaKeyingParamType可参考com.bytedance.labcv.effectsdk.BytedEffectConstants.java，并且其定义与C接口bef_ai_chroma_keying_param_type保持一致。

3.绿幕抠图

//老版本接口：
public BefChromaKeyingInfo detect( 
    ByteBuffer buffer, 
    BytedEffectConstants.PixlFormat pixelFormat, 
    int imageWidth, 
    int imageHeight, 
    int imageStride, 
    BytedEffectConstants.Rotation orientation, 
    boolean soft_process)  //V450去绿处理

//最新版本：
public BefChromaKeyingInfo detect( 
    ByteBuffer buffer, 
    BytedEffectConstants.PixlFormat pixelFormat, 
    int imageWidth, 
    int imageHeight, 
    int imageStride, 
    BytedEffectConstants.Rotation orientation, 
    boolean autoColor)  //本帧处理中是否运行自动主色提取，为true，则会自动主色提取并返回提取结果

新版算法除了保留原有的“detect”接口外，将该接口进行了拆分，以进行性能优化，支持仅纹理输入；拆分后的两个接口如下：

// 该接口根据传入的image buffer进行绿幕背景主色提取，通过入参返回算法提取的主色
// 输出algorithmInfo为背景主色提取的算法结果
algorithmInfo = mDetector.detectColor(buffer, pixlFormat, width, height, stride, rotation, false);

// 对应上面的IOS C接口为：
bef_effect_ai_chroma_keying_algorithm_buffer
    
// 该接口通过传入纹理id以及主色提取结果，进行绿幕抠图
// 输出textureInfo为根据上面算法主色提取结果或者由外界给定的主色 进行抠图处理后的最终结果
textureInfo = mDetector.processTexture(TextureId, width, height, algorithmInfo);

// 对应上面的IOS C接口为：
bef_effect_ai_chroma_keying_process_texture

参数说明

备注
类BefChromaKeyingInfo详细情况可以参考com.bytedance.labcv.effectsdk.BefChromaKeyingInfo.java，并且其定义与C接口bef_ai_chroma_keying_ret保持一致。
版本4.4.0及以上输出结果：

/** 
 * 绿幕抠图结果 
 */ 
public class BefChromaKeyingInfo { 
    private int width; 
    private int height; 
    private int color_b; 
    private int color_g; 
    private int color_r; 
    private int color_h;//上面的b,g,r为自动提取主色的三通道颜色，
    //color_h为转换而来的HSV颜色空间的Hue，与上面setProcessParam中的COLOR属性含义相同
    private int outputTexture;  // 输出的纹理rgb为原图大小纹理， alpha 通道为原图和目标图的混合系数 
    ...
}

返回值
成功返回 类BefChromaKeyingInfo-绿幕抠图结果

4.释放绿幕抠图句柄

public void release()

可以指定输入视频中的某个矩形区域，对该区域不进行抠图处理，应用场景，例如可以用于在直播带货中，对绿色产品指定安全区域进行保护，不进行抠图。

1. 对于绝大多数场景，进行场景细分，如绿幕，蓝幕，红幕，复杂场景，精细场景（如发丝）等根据实际业务分别设置一套参数，进行一键自动化，使用体验更佳。

2. 对于复杂场景，具体地：

• 对于色彩多、复杂的场景，建议结合各个参数微调效果

• 场景中存在与绿幕十分接近的前景色，建议spill去溢色参数调低

3. 参数对于性能的影响，设置建议：

   参数	对于性能的影响，设置建议
   INTENSITY	[0,1]，默认建议0.4，抠图强度，影响抠除色域的范围
   EDGE_SMOOTH	[0,1]，默认建议0.2，边缘平滑系数越高，对于性能影响越大，越小，则越低
   DETAIL	[0,1]，为0，走通用方案，为1，走精细方案，中间值为两者方案加权，同时生效，建议只设置为0或1，提升性能
   SHADOW	[0,1]，如果场景中阴影较少，可以默认设置为0

1.如果出现任何异常，请查看是否有以下类型日志

答：建议首先查看以下tag输出Error类型的日志：bef_effect_ai 和SMASH_E_LOG 以及 EffectSDK

错误码请参考错误码表