声网提供透视校正 API,使老师将学生的视频进行失真矫正,自动将拍摄出来的梯形画纸调整成为长方形并使长宽比符合标准画纸比例。
你已经集成了声网 RTC v4.0.0 教育特殊版 SDK 并实现了基本的音视频功能。详见 Windows 快速开始。
透视校正 API 存在两种调用场景。教师可以帮助学生进行透视校正,学生也可以自行进行透视校正。
教师端调用 enableRemoteTrapezoidCorrection
或 enableRemoteTrapezoidCorrectionEx
对指定的远端 uid 在教师端的渲染画面开启透视校正。这样教师可以看到校正后的学生画面。
// 对指定的远端 uid 开启透视校正功能
m_lpAgoraEngine->enableRemoteTrapezoidCorrection(uid, true);
教师端根据透视校正的实际效果,调用 setRemoteTrapezoidCorrectionOptions
或 setRemoteTrapezoidCorrectionOptionsEx
设置透视校正选项,进行调整。
// 设置透视校正选项,可以在手动校正和自动校正模式之间切换
TrapezoidCorrectionOptions options;
// 开启自动校正
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);
m_lpAgoraEngine->setRemoteTrapezoidCorrectionOptions(uid, options);
options.setDragSrcPoint(0.8,0.2);
options.setDragDstPoint(0.87,0.12);
options.setDragFinished(0);
m_lpAgoraEngine->setRemoteTrapezoidCorrectionOptions(uid, options);
// 鼠标左键抬起拖动结束时要设置 setDragFinished(1)
options.setDragSrcPoint(0.8,0.2);
options.setDragDstPoint(0.9,0.1);
options.setDragFinished(1);
m_lpAgoraEngine->setRemoteTrapezoidCorrectionOptions(uid, options);
(可选)教师端可调用 applyTrapezoidCorrectionToRemote
或 applyTrapezoidCorrectionToRemoteEx
将透视校正参数应用到远端 uid 的本地预览画面上。这样学生也能在本地预览中看到校正后的本地画面。
// 将透视校正参数应用到远端 uid 的本地画面上
m_lpAgoraEngine->applyTrapezoidCorrectionToRemote(uid, true);
// 在不需要远端本地预览进行透视校正时,关闭远端uid的本地画面梯形校正
m_lpAgoraEngine->applyTrapezoidCorrectionToRemote(uid, false);
(可选)教师端在调用 applyTrapezoidCorrectionToRemote
或 applyTrapezoidCorrectionToRemoteEx
前后,可以调用 getRemoteTrapezoidCorrectionOptions
或 getRemoteTrapezoidCorrectionOptionsEx
获取透视校正参数,用于保存记忆参数。
// 获取透视校正参数
m_lpAgoraEngine->getRemoteTrapezoidCorrectionOptions(uid, options);
如果不再需要透视校正功能,教师端可调用 enableRemoteTrapezoidCorrection
或 enableRemoteTrapezoidCorrectionEx
关闭透视校正。
// 对指定的远端 uid 关闭透视校正功能
m_lpAgoraEngine->enableRemoteTrapezoidCorrection(uid, false);
学生端调用 enableLocalTrapezoidCorrection
在本地开启透视校正。
// 在本地开启透视校正
m_lpAgoraEngine->enableLocalTrapezoidCorrection(true, VIDEO_SOURCE_CAMERA_PRIMARY);
学生端根据透视校正的实际效果,调用 setLocalTrapezoidCorrectionOptions
设置透视校正选项,进行调整。本地设置梯形校正后,远端就能看到梯形校正后的画面。
// 设置透视校正选项,可以在手动校正和自动校正模式之间切换
TrapezoidCorrectionOptions options;
// 开启自动校正
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);
m_lpAgoraEngine->setLocalTrapezoidCorrectionOptions(options, VIDEO_SOURCE_CAMERA_PRIMARY);
options.setDragSrcPoint(0.8,0.2);
options.setDragDstPoint(0.87,0.12);
options.setDragFinished(0);
m_lpAgoraEngine->setLocalTrapezoidCorrectionOptions(options, VIDEO_SOURCE_CAMERA_PRIMARY);
// 鼠标左键抬起拖动结束时要设置 setDragFinished(1)
options.setDragSrcPoint(0.8,0.2);
options.setDragDstPoint(0.9,0.1);
options.setDragFinished(1);
m_lpAgoraEngine->setLocalTrapezoidCorrectionOptions(options, VIDEO_SOURCE_CAMERA_PRIMARY);
(可选)学生端在调用 setLocalTrapezoidCorrectionOptions
前后,可以调用 getLocalTrapezoidCorrectionOptions
获取透视校正参数,用于保存记忆参数。
// 获取透视校正参数
m_lpAgoraEngine->getLocalTrapezoidCorrectionOptions(options, VIDEO_SOURCE_CAMERA_PRIMARY)
如果不再需要透视校正功能,教师端可调用 enableLocalTrapezoidCorrection
关闭透视校正。
// 对指定的远端 uid 关闭透视校正功能
m_lpAgoraEngine->enableLocalTrapezoidCorrection(false);
virtual int enableRemoteTrapezoidCorrection(uid_t uid, bool enabled) = 0;
在本地启用或关闭远端 uid 在本地渲染画面的透视校正。远端 uid 自身的本地预览不会看到透视校正效果。
参数 | 说明 |
---|---|
uid | 需要开启或关闭透视校正的 uid。 |
enabled | 是否开启透视校正。
|
virtual int enableRemoteTrapezoidCorrectionEx(uid_t uid, bool enabled, const RtcConnection& connection) = 0;
(适用于多频道)在本地启用或关闭远端 uid 在本地渲染画面的透视校正。远端 uid 自身的本地预览不会看到透视校正效果。
参数 | 说明 |
---|---|
uid | 需要开启或关闭透视校正的 uid。 |
enabled | 是否开启本地画面透视校正。
|
connection | Connection 信息。详见 RtcConnection。 |
virtual int enableLocalTrapezoidCorrection(bool enabled, VIDEO_SOURCE_TYPE sourceType = VIDEO_SOURCE_CAMERA_PRIMARY) = 0;
开启或关闭本地画面的透视校正。本地设置透视校正后,远端就能看到梯形校正后的画面。
参数 | 说明 |
---|---|
enabled | 是否开启本地画面透视校正。
|
sourceType | 画面视频源。
|
0:方法调用成功。
<0:方法调用失败。
virtual int setLocalTrapezoidCorrectionOptions(const TrapezoidCorrectionOptions& options, VIDEO_SOURCE_TYPE sourceType = VIDEO_SOURCE_CAMERA_PRIMARY) = 0;
配置本地透视校正选项。
参数 | 说明 |
---|---|
options | 透视校正配置参数。详见 TrapezoidCorrectionOptions 。 |
sourceType | 画面视频源。
|
virtual int getLocalTrapezoidCorrectionOptions(TrapezoidCorrectionOptions& options, VIDEO_SOURCE_TYPE sourceType = VIDEO_SOURCE_CAMERA_PRIMARY) = 0;
获取本地透视校正配置参数。
参数 | 说明 |
---|---|
options | 透视校正配置参数。如果之前多次调用过 setLocalTrapezoidCorrectionOptions ,获取的是之前多次设置的参数集合。详见 TrapezoidCorrectionOptions 。 |
sourceType | 画面视频源。
|
virtual int setRemoteTrapezoidCorrectionOptions(uid_t uid, const TrapezoidCorrectionOptions& options) = 0;
配置远端透视校正选项。
参数 | 说明 |
---|---|
uid | 远端用户 uid。 |
options | 透视校正配置参数。如果之前多次调用过 setRemoteTrapezoidCorrectionParams ,获取的是之前多次设置的参数集合。详见 TrapezoidCorrectionOptions 。 |
virtual int setRemoteTrapezoidCorrectionOptionsEx(uid_t uid, const TrapezoidCorrectionOptions& options, const RtcConnection& connection) = 0;
(适用于多频道)配置远端透视校正选项。
参数 | 说明 |
---|---|
uid | 远端用户 uid。 |
options | 透视校正配置参数。如果之前多次调用过 setRemoteTrapezoidCorrectionParams ,获取的是之前多次设置的参数集合。详见 TrapezoidCorrectionOptions 。 |
connection | Connection 信息。详见 RtcConnection。 |
virtual int getRemoteTrapezoidCorrectionOptions(uid_t uid, TrapezoidCorrectionOptions& options) = 0;
获取远端透视校正配置参数。
参数 | 说明 |
---|---|
uid | 远端用户 uid。 |
options | 透视校正配置参数。详见 TrapezoidCorrectionOptions 。 |
virtual int getRemoteTrapezoidCorrectionOptionsEx(uid_t uid, TrapezoidCorrectionOptions& options, const RtcConnection& connection) = 0;
(适用于多频道)获取远端透视校正配置参数。
参数 | 说明 |
---|---|
uid | 远端用户 uid。 |
options | 透视校正配置参数。详见 TrapezoidCorrectionOptions 。 |
connection | Connection 信息。详见 RtcConnection。 |
virtual int applyTrapezoidCorrectionToRemote(uid_t uid, bool enabled) = 0;
将透视校正参数应用到远端 uid 的本地预览画面或取消远端 uid 的本地预览画面的透视校正效果。
参数 | 说明 |
---|---|
uid | 远端用户 uid。 |
enabled | 是否将透视校正参数应用到远端 uid 的本地预览画面。
|
virtual int applyTrapezoidCorrectionToRemoteEx(uid_t uid, bool enabled, const RtcConnection& connection) = 0;
(适用于多频道)将透视校正参数应用到远端 uid 的本地预览画面或取消远端 uid 的本地预览画面的透视校正效果。
参数 | 说明 |
---|---|
uid | 远端用户 uid。 |
enabled | 是否将透视校正参数应用到远端 uid 的本地预览画面。
|
connection | Connection 信息。详见 RtcConnection。 |
virtual void onTrapezoidAutoCorrectionFinished(uid_t uid, TrapezoidAutoCorrectionResult result, int costTime,
const TrapezoidCorrectionOptions::Point* dragSrcPoints, int dragSrcPointsLen,
const TrapezoidCorrectionOptions::Point* dragDstPoints, int dragDstPointsLen) {
(void)uid;
(void)result;
(void)costTime;
(void)dragSrcPoints;
(void)dragSrcPointsLen;
(void)dragDstPoints;
(void)dragDstPointsLen;
}
自动透视校正完成时触发。
参数 | 说明 |
---|---|
uid | 远程开启自动透视校正时的远端用户 uid。 |
result | 自动透视校正结果。
|
costTime | 透视校正花费的时间(ms)。 |
dragSrcPoints | 拖动起始点时的梯形四个顶点坐标。 |
dragSrcPointsLen | dragSrcPoints 数组长度。 |
dragDstPoints | 拖动结束点时的梯形四个顶点坐标。 |
dragDstPointsLen | dragDstPointsLen 数组长度。 |
virtual void onTrapezoidAutoCorrectionFinished(const RtcConnection& connection, uid_t uid,
TrapezoidAutoCorrectionResult result, int costTime,
const TrapezoidCorrectionOptions::Point* dragSrcPoints, int dragSrcPointsLen,
const TrapezoidCorrectionOptions::Point* dragDstPoints, int dragDstPointsLen) {
(void)connection;
(void)uid;
(void)result;
(void)costTime;
(void)dragSrcPoints;
(void)dragSrcPointsLen;
(void)dragDstPoints;
(void)dragDstPointsLen;
}
自动透视校正完成时触发。
参数 | 说明 |
---|---|
connection | Connection 信息。详见 RtcConnection。 |
uid | 远程开启自动透视校正时的远端用户 uid。 |
result | 自动透视校正结果。
|
costTime | 透视校正花费的时间(ms)。 |
dragSrcPoints | 拖动起始点时的梯形四个顶点坐标。 |
dragSrcPointsLen | dragSrcPoints 数组长度。 |
dragDstPoints | 拖动结束点时的梯形四个顶点坐标。 |
dragDstPointsLen | dragDstPointsLen 数组长度。 |
struct TrapezoidCorrectionOptions {
enum {
POINT_ARRAY_LEN = 8,
};
struct Point {
float x; // value in [0.0 - 1.0]
float y; // value in [0.0 - 1.0]
};
TrapezoidCorrectionOptions():hasMultiPoints(false){}
void setDragSrcPoint(Point pt)
{
dragSrcPoint = pt;
}
void setDragDstPoint(Point pt)
{
dragDstPoint = pt;
}
void setDragFinished(int finished)
{
dragFinished = finished;
}
void setDragSrcPoints(Point topLeft, Point bottomLeft, Point topRight, Point bottomRight)
{
dragSrcPoints[0] = topLeft.x;
dragSrcPoints[1] = topLeft.y;
dragSrcPoints[2] = bottomLeft.x;
dragSrcPoints[3] = bottomLeft.y;
dragSrcPoints[4] = topRight.x;
dragSrcPoints[5] = topRight.y;
dragSrcPoints[6] = bottomRight.x;
dragSrcPoints[7] = bottomRight.y;
hasMultiPoints = true;
}
void setDragDstPoints(Point topLeft, Point bottomLeft, Point topRight, Point bottomRight)
{
dragDstPoints[0] = topLeft.x;
dragDstPoints[1] = topLeft.y;
dragDstPoints[2] = bottomLeft.x;
dragDstPoints[3] = bottomLeft.y;
dragDstPoints[4] = topRight.x;
dragDstPoints[5] = topRight.y;
dragDstPoints[6] = bottomRight.x;
dragDstPoints[7] = bottomRight.y;
hasMultiPoints = true;
}
void showAssistLine(int show)
{
assistLine = show;
}
void setAutoCorrect(int autoCorr)
{
autoCorrect = autoCorr;
}
void setMirror(int mirr)
{
mirror = mirr;
}
void setResetDragPoints(int reset)
{
resetDragPoints = reset;
}
Optional<Point> dragSrcPoint;
Optional<Point> dragDstPoint;
Optional<int> dragFinished; //value: 0 or 1
float dragSrcPoints[POINT_ARRAY_LEN];
float dragDstPoints[POINT_ARRAY_LEN];
bool hasMultiPoints; // if true, indicates dragSrcPoints and dragDstPoints have valid values
Optional<int> assistLine; //value: 0 or 1
Optional<int> autoCorrect; //value: 0 or 1
Optional<int> mirror; //value: 0 or 1, only set if not use sdk renderer, such as custom renderer
Optional<int> resetDragPoints; //value: 0 or 1
};
透视校正参数配置,包含以下成员:
x:x 坐标,根据屏幕宽度归一化为 [0.0~1.0] 的浮点数。
y:y 坐标,根据屏幕高度归一化为 [0.0~1.0] 的浮点数。
设置拖动起始点坐标。
参数 | 说明 |
---|---|
pt | 拖动起始点坐标。详见 Point 。 |
设置拖动终止点坐标。
如果同时调用 setDragSrcPoint
、setDragDstPoint
、setDragFinished
和 setDragSrcPoints
、setDragDstPoints
,则 setDragSrcPoints
、setDragDstPoints
的设置生效。
参数 | 说明 |
---|---|
pt | 拖动终止点坐标。详见 Point 。 |
设置该次拖动调整是否结束。
参数 | 说明 |
---|---|
finished | 该次拖动调整是否结束。
|
同时设置 4 个点的拖动起始点坐标。
参数 | 说明 |
---|---|
topLeft | 左上角拖动起始点坐标。详见 Point 。 |
bottomLeft | 左下角拖动起始点坐标。详见 Point 。 |
topRight | 右上角拖动起始点坐标。详见 Point 。 |
bottomRight | 右下角拖动起始点坐标。详见 Point 。 |
同时设置 4 个点的拖动终止点坐标。
参数 | 说明 |
---|---|
topLeft | 左上角拖动终止点坐标。详见 Point 。 |
bottomLeft | 左下角拖动终止点坐标。详见 Point 。 |
topRight | 右上角拖动终止点坐标。详见 Point 。 |
bottomRight | 右下角拖动终止点坐标。详见 Point 。 |
开启或关闭辅助线。初始值为关闭。
参数 | 说明 |
---|---|
show | 开启或关闭辅助线。
|
开启或关闭自动透视校正。初始值为关闭。
参数 | 说明 |
---|---|
autoCorr | 开启或关闭自动透视校正。
|
启用或关闭镜像。初始值为关闭。
只有使用自定义渲染功能并且自定义渲染开启水平镜像时,才需要启用镜像参数。
参数 | 说明 |
---|---|
mirr | 启用或关闭镜像。
|
重置透视校正效果。初始值为不重置。
参数 | 说明 |
---|---|
reset | 重置透视校正效果。
|