声网提供透视校正 API,使老师将学生的视频进行失真矫正,自动将拍摄出来的梯形画纸调整成为长方形并使长宽比符合标准画纸比例。
你已经集成了声网 RTC v4.0.0 教育特殊版 SDK 并实现了基本的音视频功能。详见 Android 快速开始。
透视校正 API 存在两种调用场景。教师可以帮助学生进行透视校正,学生也可以自行进行透视校正。
教师端调用 enableRemoteTrapezoidCorrection
或 enableRemoteTrapezoidCorrectionEx
对指定的远端 uid 在教师端的渲染画面开启透视校正。这样教师可以看到校正后的学生画面。
// 对指定的远端 uid 开启透视校正功能
mRtcEngine.enableRemoteTrapezoidCorrection(uid, true);
教师端根据透视校正的实际效果,调用 setRemoteTrapezoidCorrectionOptions
或 setRemoteTrapezoidCorrectionOptionsEx
设置透视校正选项,进行调整。
// 设置透视校正选项,可以在手动校正和自动校正模式之间切换
TrapezoidCorrectionOptions options = new TrapezoidCorrectionOptions();
// 开启自动校正
options.setAutoCorrect(1);
// 或者开启手动校正
options.setAutoCorrect(0);
// 根据轨迹设置拖动起始点和终止点坐标
// 例如:从(0.8,0.2)开始,拖动经过(0.85,0.15),(0.87,0.12),在(0.9,0.1)结束。
options.setDragSrcPoint(0.8,0.2);
options.setDragDstPoint(0.85,0.15);
options.setDragFinished(0);
mRtcEngine.setRemoteTrapezoidCorrectionOptions(uid, options);
options.setDragSrcPoint(0.8,0.2);
options.setDragDstPoint(0.87,0.12);
options.setDragFinished(0);
mRtcEngine.setRemoteTrapezoidCorrectionOptions(uid, options);
// 拖动结束时要设置 setDragFinished(1)
options.setDragSrcPoint(0.8,0.2);
options.setDragDstPoint(0.9,0.1);
options.setDragFinished(1);
mRtcEngine.setRemoteTrapezoidCorrectionOptions(uid, options);
(可选)教师端可调用 applyTrapezoidCorrectionToRemote
或 applyTrapezoidCorrectionToRemoteEx
将透视校正参数应用到远端 uid 的本地预览画面上。这样学生也能在本地预览中看到校正后的本地画面。
// 将透视校正参数应用到远端 uid 的本地画面上
mRtcEngine.applyTrapezoidCorrectionToRemote(uid, true);
// 在不需要远端本地预览进行透视校正时,关闭远端uid的本地画面梯形校正
mRtcEngine.applyTrapezoidCorrectionToRemote(uid, false);
(可选)教师端在调用 applyTrapezoidCorrectionToRemote
或 applyTrapezoidCorrectionToRemoteEx
前后,可以调用 getRemoteTrapezoidCorrectionOptions
或 getRemoteTrapezoidCorrectionOptionsEx
获取透视校正参数,用于保存记忆参数。
// 获取透视校正参数
mRtcEngine.getRemoteTrapezoidCorrectionOptions(uid, options);
如果不再需要透视校正功能,教师端可调用 enableRemoteTrapezoidCorrection
或 enableRemoteTrapezoidCorrectionEx
关闭透视校正。
// 对指定的远端 uid 关闭透视校正功能
mRtcEngine.enableRemoteTrapezoidCorrection(uid, false);
学生端调用 enableLocalTrapezoidCorrection
在本地开启透视校正。
// 在本地开启透视校正
mRtcEngine.enableLocalTrapezoidCorrection(true, VIDEO_SOURCE_CAMERA_PRIMARY);
学生端根据透视校正的实际效果,调用 setLocalTrapezoidCorrectionOptions
设置透视校正选项,进行调整。本地设置梯形校正后,远端就能看到梯形校正后的画面。
// 设置透视校正选项,可以在手动校正和自动校正模式之间切换
TrapezoidCorrectionOptions options = new TrapezoidCorrectionOptions();
// 开启自动校正
options.setAutoCorrect(1);
// 或者开启手动校正
options.setAutoCorrect(0);
// 根据轨迹设置拖动起始点和终止点坐标
// 例如:从(0.8,0.2)开始,拖动经过(0.85,0.15),(0.87,0.12),在(0.9,0.1)结束。
options.setDragSrcPoint(0.8,0.2);
options.setDragDstPoint(0.85,0.15);
options.setDragFinished(0);
mRtcEngine.setLocalTrapezoidCorrectionOptions(options, VIDEO_SOURCE_CAMERA_PRIMARY);
options.setDragSrcPoint(0.8,0.2);
options.setDragDstPoint(0.87,0.12);
options.setDragFinished(0);
mRtcEngine.setLocalTrapezoidCorrectionOptions(options, VIDEO_SOURCE_CAMERA_PRIMARY);
// 拖动结束时要设置 setDragFinished(1)
options.setDragSrcPoint(0.8,0.2);
options.setDragDstPoint(0.9,0.1);
options.setDragFinished(1);
mRtcEngine.setLocalTrapezoidCorrectionOptions(options, VIDEO_SOURCE_CAMERA_PRIMARY);
(可选)学生端在调用 setLocalTrapezoidCorrectionOptions
前后,可以调用 getLocalTrapezoidCorrectionOptions
获取透视校正参数,用于保存记忆参数。
// 获取透视校正参数
mRtcEngine.getLocalTrapezoidCorrectionOptions(options, VIDEO_SOURCE_CAMERA_PRIMARY);
如果不再需要透视校正功能,教师端可调用 enableLocalTrapezoidCorrection
关闭透视校正。
// 对指定的远端 uid 关闭透视校正功能
mRtcEngine.enableLocalTrapezoidCorrection(false);
public abstract int enableRemoteTrapezoidCorrection(int uid, boolean enabled)
在本地启用或关闭远端 uid 在本地渲染画面的透视校正。远端 uid 自身的本地预览不会看到透视校正效果。
参数 | 说明 |
---|---|
uid | 需要开启或关闭透视校正的 uid。 |
enabled | 是否开启画面透视校正。
|
public abstract int enableRemoteTrapezoidCorrectionEx(int uid, boolean enabled, RtcConnection connection)
(适用于多频道)在本地启用或关闭远端 uid 在本地渲染画面的透视校正。远端 uid 自身的本地预览不会看到透视校正效果。
参数 | 说明 |
---|---|
uid | 需要开启或关闭透视校正的 uid。 |
enabled | 是否开启画面透视校正。
|
connection | Connection 信息。详见 RtcConnection。 |
public abstract int enableLocalTrapezoidCorrection(boolean enabled, Constants.VideoSourceType sourceType)
开启或关闭本地画面的透视校正。本地设置透视校正后,远端就能看到梯形校正后的画面。
参数 | 说明 |
---|---|
enabled | 是否开启本地画面透视校正。
|
sourceType | 画面视频源。
|
public abstract int setLocalTrapezoidCorrectionOptions(final TrapezoidCorrectionOptions options, Constants.VideoSourceType sourceType)
配置本地透视校正选项。
参数 | 说明 |
---|---|
options | 透视校正配置参数。详见 TrapezoidCorrectionOptions 。 |
sourceType | 画面视频源。
|
public abstract TrapezoidCorrectionOptions getLocalTrapezoidCorrectionOptions(Constants.VideoSourceType sourceType)
获取本地透视校正配置参数。
参数 | 说明 |
---|---|
sourceType | 画面视频源。
|
透视校正配置参数。如果之前多次调用过 setLocalTrapezoidCorrectionOptions
,获取的是之前多次设置的参数集合。详见 TrapezoidCorrectionOptions
。
public abstract int setRemoteTrapezoidCorrectionOptions(int uid, final TrapezoidCorrectionOptions options)
配置远端透视校正选项。
参数 | 说明 |
---|---|
uid | 远端用户 uid。 |
options | 透视校正配置参数。如果之前多次调用过 setRemoteTrapezoidCorrectionParams ,获取的是之前多次设置的参数集合。详见 TrapezoidCorrectionOptions 。 |
public abstract int setRemoteTrapezoidCorrectionOptionsEx(int uid, final TrapezoidCorrectionOptions options, RtcConnection connection)
(适用于多频道)配置远端透视校正选项。
参数 | 说明 |
---|---|
uid | 远端用户 uid。 |
options | 透视校正配置参数。如果之前多次调用过 setRemoteTrapezoidCorrectionParams ,获取的是之前多次设置的参数集合。详见 TrapezoidCorrectionOptions 。 |
connection | Connection 信息。详见 RtcConnection。 |
public abstract TrapezoidCorrectionOptions getRemoteTrapezoidCorrectionOptions(int uid)
获取远端透视校正配置参数。
参数 | 说明 |
---|---|
uid | 远端用户 uid。 |
透视校正配置参数。详见 TrapezoidCorrectionOptions
。
public abstract TrapezoidCorrectionOptions getRemoteTrapezoidCorrectionOptionsEx(int uid, RtcConnection connection)
(适用于多频道)获取远端透视校正配置参数。
参数 | 说明 |
---|---|
uid | 远端用户 uid。 |
options | 透视校正配置参数。详见 TrapezoidCorrectionOptions 。 |
connection | Connection 信息。详见 RtcConnection。 |
透视校正配置参数。详见 TrapezoidCorrectionOptions
。
public abstract int applyTrapezoidCorrectionToRemote(int uid, boolean enabled)
将透视校正参数应用到远端 uid 的本地预览画面或取消远端 uid 的本地预览画面的透视校正效果。
参数 | 说明 |
---|---|
uid | 远端用户 uid。 |
enabled | 是否将透视校正参数应用到远端 uid 的本地预览画面。
|
public abstract int applyTrapezoidCorrectionToRemoteEx(int uid, boolean enabled, RtcConnection connection)
(适用于多频道)将透视校正参数应用到远端 uid 的本地预览画面或取消远端 uid 的本地预览画面的透视校正效果。
参数 | 说明 |
---|---|
uid | 远端用户 uid。 |
enabled | 是否将透视校正参数应用到远端 uid 的本地预览画面。
|
connection | Connection 信息。详见 RtcConnection。 |
public void onTrapezoidAutoCorrectionFinished(
int uid, int result, int costTime, PointF[] dragSrcPoints, PointF[] dragDstPoints) {}
自动透视校正完成时触发。
参数 | 说明 |
---|---|
uid | 远程开启自动透视校正时的远端用户 uid。 |
result | 自动透视校正结果。
|
costTime | 透视校正花费的时间(ms)。 |
dragSrcPoints | 拖动起始点时的梯形四个顶点坐标。 |
dragDstPoints | 拖动结束点时的梯形四个顶点坐标。 |
public class TrapezoidCorrectionOptions {
private PointF dragSrcPoint;
private PointF dragDstPoint;
private Integer dragFinished;
private Integer assistLine;
private Integer autoCorrect;
private Integer mirror;
private Integer resetDragPoints;
private List<Float> dragSrcPoints;
private List<Float> dragDstPoints;
@CalledByNative
public TrapezoidCorrectionOptions() {
}
@CalledByNative
public PointF makePointF(float x, float y) {
return new PointF(x, y);
}
@CalledByNative
public void setDragSrcPoint(PointF pt) {
dragSrcPoint = pt;
}
@CalledByNative
public void setDragDstPoint(PointF pt) {
dragDstPoint = pt;
}
@CalledByNative
public void setDragFinished(int finished) {
dragFinished = finished;
}
@CalledByNative
public void showAssistLine(int show) {
assistLine = show;
}
@CalledByNative
public void setAutoCorrect(int autoCorr) {
autoCorrect = autoCorr;
}
@CalledByNative
public void setMirror(int mirr) {
mirror = mirr;
}
@CalledByNative
public void setResetDragPoints(int reset) {
resetDragPoints = reset;
}
@CalledByNative
public void setDragSrcPoints(
PointF topLeft, PointF bottomLeft, PointF topRight, PointF bottomRight) {
if (dragSrcPoints == null)
dragSrcPoints = new ArrayList<>();
dragSrcPoints.clear();
dragSrcPoints.add(topLeft.x);
dragSrcPoints.add(topLeft.y);
dragSrcPoints.add(bottomLeft.x);
dragSrcPoints.add(bottomLeft.y);
dragSrcPoints.add(topRight.x);
dragSrcPoints.add(topRight.y);
dragSrcPoints.add(bottomRight.x);
dragSrcPoints.add(bottomRight.y);
}
@CalledByNative
public void setDragDstPoints(
PointF topLeft, PointF bottomLeft, PointF topRight, PointF bottomRight) {
if (dragDstPoints == null)
dragDstPoints = new ArrayList<>();
dragDstPoints.clear();
dragDstPoints.add(topLeft.x);
dragDstPoints.add(topLeft.y);
dragDstPoints.add(bottomLeft.x);
dragDstPoints.add(bottomLeft.y);
dragDstPoints.add(topRight.x);
dragDstPoints.add(topRight.y);
dragDstPoints.add(bottomRight.x);
dragDstPoints.add(bottomRight.y);
}
@CalledByNative
public final float[] getDragSrcPoint() {
return dragSrcPoint != null ? new float[] {dragSrcPoint.x, dragSrcPoint.y} : null;
}
@CalledByNative
public final float[] getDragDstPoint() {
return dragDstPoint != null ? new float[] {dragDstPoint.x, dragDstPoint.y} : null;
}
@CalledByNative
public final Integer getDragFinished() {
return dragFinished;
}
@CalledByNative
public final Integer getAssistLine() {
return assistLine;
}
@CalledByNative
public final Integer getAutoCorrect() {
return autoCorrect;
}
@CalledByNative
public final Integer getMirror() {
return mirror;
}
@CalledByNative
public final Integer getResetDragPoints() {
return resetDragPoints;
}
private float[] listToArray(List<Float> list) {
float[] ret = new float[list.size()];
int i = 0;
for (Float f : list) {
ret[i++] = f;
}
return ret;
}
@CalledByNative
public final float[] getDragSrcPoints() {
return dragSrcPoints == null ? null : listToArray(dragSrcPoints);
}
@CalledByNative
public final float[] getDragDstPoints() {
return dragDstPoints == null ? null : listToArray(dragDstPoints);
}
@Override
public String toString() {
StringBuilder sb = new StringBuilder();
if (dragSrcPoint != null) {
sb.append("dragSrcPoint : ");
sb.append("x " + dragSrcPoint.x + " y " + dragSrcPoint.y);
}
if (dragDstPoint != null) {
sb.append("dragDstPoint : ");
sb.append("x " + dragDstPoint.x + " y " + dragDstPoint.y);
}
if (dragSrcPoints != null) {
sb.append("dragSrcPoints : ");
sb.append(dragSrcPoints.toString());
}
if (dragDstPoints != null) {
sb.append("dragDstPoints : ");
sb.append(dragDstPoints.toString());
}
return sb.toString();
}
}
透视校正参数配置,包含以下成员:
x:x 坐标,根据屏幕宽度归一化为 [0.0~1.0] 的浮点数。
y:y 坐标,根据屏幕高度归一化为 [0.0~1.0] 的浮点数。
设置拖动起始点坐标。
参数 | 说明 |
---|---|
pt | 拖动起始点坐标。详见 PointF 。 |
设置拖动终止点坐标。
如果同时调用 setDragSrcPoint
、setDragDstPoint
、setDragFinished
和 setDragSrcPoints
、setDragDstPoints
,则 setDragSrcPoints
、setDragDstPoints
的设置生效。
参数 | 说明 |
---|---|
pt | 拖动终止点坐标。详见 PointF 。 |
设置该次拖动调整是否结束。
参数 | 说明 |
---|---|
finished | 该次拖动调整是否结束。
|
同时设置 4 个点的拖动起始点坐标。
参数 | 说明 |
---|---|
topLeft | 左上角拖动起始点坐标。详见 PointF 。 |
bottomLeft | 左下角拖动起始点坐标。详见 PointF 。 |
topRight | 右上角拖动起始点坐标。详见 PointF 。 |
bottomRight | 右下角拖动起始点坐标。详见 PointF 。 |
同时设置 4 个点的拖动终止点坐标。
参数 | 说明 |
---|---|
topLeft | 左上角拖动终止点坐标。详见 PointF 。 |
bottomLeft | 左下角拖动终止点坐标。详见 PointF 。 |
topRight | 右上角拖动终止点坐标。详见 PointF 。 |
bottomRight | 右下角拖动终止点坐标。详见 PointF 。 |
开启或关闭辅助线。初始值为关闭。
参数 | 说明 |
---|---|
show | 开启或关闭辅助线。
|
开启或关闭自动透视校正。初始值为关闭。
参数 | 说明 |
---|---|
autoCorr | 开启或关闭自动透视校正。
|
启用或关闭镜像。初始值为关闭。
只有使用自定义渲染功能并且自定义渲染开启水平镜像时,才需要启用镜像参数。
参数 | 说明 |
---|---|
mirr | 启用或关闭镜像。
|
重置透视校正效果。初始值为不重置。
参数 | 说明 |
---|---|
reset | 重置透视校正效果。
|