美摄SDK For Android  3.10.0
Master Keyer技术文档

Master Keyer技术文档

1.1版本

北京美摄网络科技有限公司

目录

[toc]

前置说明：

  美摄SDK抠像技术在拍摄和编辑时都可应用，本文档适用于拍摄。对于编辑应用，请参考美摄相关文档。

1、抠像

  “抠像”一词来源于早期电视制作，英文称作“Key”。吸取画面中的某一种颜色作为透明色，将透明色从画面中抠去，使背景透出来，形成二层画面的叠加合成。可以使拍摄的人物经抠像后与其它景物叠加在一起，形成神奇的艺术效果。

  美摄SDK非线性编辑软件，巧妙地应用其中的Key功能，并与其它特技配合，达到高质量的抠像效果。

2、素材要求

  所有的画面都可以抠像，如果实现比较好的抠像效果，最好流媒体前景与背景色差区别明显，色调不要过于接近，背景铺光要匀称。这样抠像效果最佳。

3、如何利用美摄SDK进行抠像开发

3.1、总体思想

  美摄SDK的很多功能实现是通过特效来进行实现的，抠像也不例外。抠像的实现是对流媒体添加特效。

  为了方便广大开发人员编程，抠像和AR Scene一样，都是通过字符串参数ID进行标记。通过Maseter Keyer参数ID构造特效对象，然后进行相关参数设定。

  抠像实现的本质是在当前流媒体界面上把一些相近颜色用其它颜色进行替代。用户在流媒体界面上发出事件，程序捕获用户点击范围，采集范围颜色，把界面上和范围相近的颜色用其它颜色来取代。

3.2、抠像分类

  抠像整体分为3种模式，Master Mode、Hsv Mode、RGB Mode。分别为色度抠像，HSV空间抠像和RGB抠像。

3.3、抠像参数ID

  通过字符串参数ID，方便开发者应用，Master Keyer整体代表抠像特技。在Master Keyer下有禁用预乘、靶色、收缩边界强度、柔软度修正、溢色去除、溢色去除强度等参数ID。根据实际需要，通过特效对象，进行相关参数设置。

  在美摄SDK种，参数ID按照抠像分类进行组织。即色度抠像参数ID，HSV空间抠像参数ID，RGB抠像参数ID，其次还有公共ID参数，公共参数ID可以被这三种模式调用。

  需要强调的是：模式内参数仅在模式选择为对应模式时生效。

3.3.1、公共参数ID

标号 名字     解释 类型 最大 最小 默认
01 Master Keyer 代表抠像
02 Keyer Mode 抠像类型：Master Mode；Hsv Mode；RGB Mode String Master Mode
03 Hsv Mode RGB Mode
04 Key Color 靶色 COLOR 0，0，0
05 Aperture 孔径范围，取色之后色度范围张角大小 FLOAT 360 0 90

3.3.2、Master模式

标号 名字 解释 类型 最大 最小 默认
01 Disable Premultiply 禁用预乘, 是否保留原图像alpha值 BOOL false
02 Shrink Intensity 收缩边界强度，处理抠像边界 FLOAT 1.0 0.0 0.0
03 Softeness Amendment 柔软度修正，可以调整选区中区域抠至半透明 FLOAT 1.0 -1.0 0.0
04 Spill Removal 溢色去除，抠像边界杂色称为溢色 BOOL false
05 Spill Removal Intensity 溢色去除强度 FLOAT 1.0 0.0 0.25

3.3.3、HSV模式

标号 名字     解释 类型 最大 最小 默认
01 Sat Width S空间宽度 FLOAT 1 0 0.2
02 Val Width V空间宽度，各个空间宽度相当于和孔径一起控制对应的颜色 FLOAT 1 0 0.2
03 Hue Roll Off H空间柔边 FLOAT 1 0 0
04 Sat Roll Off S空间柔边 FLOAT 1 0 0
05 Val Roll Off 柔边对应软边，控制选中区域的半透明程度,V空间柔边 FLOAT 1 0 0

3.3.4、RGB抠像参数ID

标号 名字 解释 类型 最大 最小 默认
01 RGB Softness 同软边 FLOAT 1 0 0.2

3.3.5、说明

  特别说明：在表格中，最大值与最小值是相对的，小的代表弱化，大的代表增强。

4、类与函数

  在本部分中，用到NvsColor和RectF类，对于特效编程其它类，参考前面相关文档。

4.1、NvsColor类

  美摄SDK封装的颜色类，是对r(红色)，g(绿色)，b(蓝色)以及a(透明度)的封装。

public 成员函数 

NvsColor (float r, float g, float b, float a)

public 属性 

float   r      红色
float   g     绿色
float   b     蓝色
float   a     透明度

SDK中，NvsColor类属性r,g,b,a取值范围是[0,1]，而非[0,255]。

构造及析构函数说明：

不带参数构造函数： 

NvsColor()

带参数构造函数： 

NvsColor
(
    float   r,
    float   g,
    float   b,
    float   a 
)

4.2、相关函数

  相同名字的函数参考前面文档。本文档仅列出前面没有讲述过的函数。

4.2.1、getCaptureVideoFxByIndex

获取采集视频特效。

原型： 

NvsCaptureVideoFx NvsStreamingContext.getCaptureVideoFxByIndex(int captureVideoFxIndex)

参数： captureVideoFxIndex 视频特效索引 返回： 返回视频特效对象

4.2.2、setColorVal()

给相关特效设置参数值。

原型： 

void com.meicam.sdk.NvsFx.setColorVal(String fxParam,NvsColor val)

设置特效颜色值参数值

参数：

fxParam 特效的颜色参数的类型。请参见PARAM_TYPE_COLOR

val NvsColor自定义颜色对象

4.2.3、sampleColorFromCapturedVideoFrame

采集区域颜色值。

原型： 

NvsColor com.meicam.sdk.NvsStreamingContext.sampleColorFromCapturedVideoFrame(RectF sampleRect)

对采集设备的视频帧内容进行采样

参数： sampleRect：采样的矩形区域，坐标为实时预览窗口的自身坐标系

返回： 返回值为采样的颜色值，该颜色值是采样的矩形区域内所有像素颜色的平均值

5、开发内容

5.1、开发准备

  开发者首先申请摄像头权限，创建流媒体上下文（Streaming Context）对象，流媒体窗口显示NvsLiveWindow对象，并进行预览。

对象声明 

private NvsLiveWindow m_liveWindow;
public NvsStreamingContext m_streamingContext;

String licensePath = "assets:/meishesdk.lic";
//对象定义
m_streamingContext = NvsStreamingContext.init(getApplicationContext(), licensePath, NvsStreamingContext.STREAMING_CONTEXT_FLAG_SUPPORT_4K_EDIT);
m_liveWindow = (NvsLiveWindow) findViewById(R.id.liveWindow);
m_streamingContext.connectCapturePreviewWithLiveWindow(m_liveWindow);

5.2、画面颜色采样

  从点击位置采集背景画面的颜色值。封装为成员函数

  矩形区域定位算法比较简单，不做讲述。 

private NvsColor getColorFromLiveWindow(MotionEvent event) {
//矩形位置定位
    int sampleWidth = 20;
    int sampleHeight = 20;
    RectF sampleRect = new RectF();
    sampleRect.left = (int) (event.getX() - sampleWidth / 2);
    if (sampleRect.left < 0) {
        sampleRect.left = 0;
    } else if (sampleRect.left + sampleWidth > m_liveWindow.getWidth()) {
        sampleRect.left = m_liveWindow.getWidth() - sampleWidth;
    }

    sampleRect.top = (int) (event.getY() - sampleHeight / 2);
    if (sampleRect.top < 0) {
        sampleRect.top = 0;
    } else if (sampleRect.top + sampleHeight > m_liveWindow.getHeight()) {
        sampleRect.top = m_liveWindow.getHeight() - sampleHeight;
    }
    sampleRect.right = sampleRect.left + sampleWidth;
    sampleRect.bottom = sampleRect.top + sampleHeight;
//采集位置颜色，并返回
    return m_streamingContext.sampleColorFromCapturedVideoFrame(sampleRect);
}

5.3、事件处理

  抠像的参数ID 

private final String NAME = "Master Keyer";

m_liveWindow.setOnTouchListener(new View.OnTouchListener() {
    @Override
    public boolean onTouch(View v, MotionEvent event) {

//判断是否添加过抠像特技，如果没有添加，则添加.不要重复添加。
        if (!isContainCaptureVideoFxByName(NAME)) {
            appendBuiltinCaptureVideoFx();
        }
//调用上面函数
        NvsColor sampledColor = getColorFromLiveWindow(event);
        /*
        * 将吸取下来的背景画面颜色值设置给抠像特技
        * Set the extracted background color value to the keying effect
        * */
//判断是否有特效对象
        NvsCaptureVideoFx keyerFx = m_streamingContext.getCaptureVideoFxByIndex(0);
        if (keyerFx == null) {
            return false;
        }
//设置抠像颜色
        keyerFx.setColorVal("Key Color", sampledColor);
        return true;
    }
});

5.4、抠像特效设置

private final String NAME = "Master Keyer";

//生成抠像对象
NvsCaptureVideoFx keyerFx = m_streamingContext.appendBuiltinCaptureVideoFx(NAME);

//对抠像对象进行技术处理
if (keyerFx != null) {
        /*
        * 开启溢色去除
        * Turn on overflow color removal
        * */
        keyerFx.setBooleanVal("Spill Removal", true);
        /*
        * 将溢色去除强度设置为最低
        * Set the overflow color removal intensity to minimum
        * */
        keyerFx.setFloatVal("Spill Removal Intensity", 0);
        /*
        * 设置收缩边界强度
        * Set shrink border strength
        * */
        keyerFx.setFloatVal("Shrink Intensity", 0.4);

    //Aperture：一个可以调节的孔径，代表取色之后的色度范围张角大小
//参数30在0到90之间，可以调整，实例应用中，可以通过进度条控制

keyerFx.setFloatVal("Aperture", 30);
}

5.5、运行效果

制作者   doxygen 1.8.17