声网提供透视校正 API,使老师将学生的视频进行失真矫正,自动将拍摄出来的梯形画纸调整成为长方形并使长宽比符合标准画纸比例。
你已经集成了声网 RTC v4.0.0 教育特殊版 SDK 并实现了基本的音视频功能。详见快速开始。
透视校正 API 存在两种调用场景。教师可以帮助学生进行透视校正,学生也可以自行进行透视校正。
教师端调用 enableRemoteTrapezoidCorrection
或 enableRemoteTrapezoidCorrectionEx
对指定的远端 uid 在教师端的渲染画面开启透视校正。这样教师可以看到校正后的学生画面。
// swift
// 对指定的远端 uid 开启透视校正功能
agoraKit.enableRemoteTrapezoidCorrection(uid, true)
教师端根据透视校正的实际效果,调用 setRemoteTrapezoidCorrectionOptions
或 setRemoteTrapezoidCorrectionOptionsEx
设置透视校正选项,进行调整。
// 设置透视校正选项,可以在手动校正和自动校正模式之间切换
let options = 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)
agoraKit.setRemoteTrapezoidCorrectionOptions(uid, options)
options.setDragSrcPoint(0.8,0.2)
options.setDragDstPoint(0.87,0.12)
options.setDragFinished(0)
agoraKit.setRemoteTrapezoidCorrectionOptions(uid, options)
// 拖动结束时要设置 setDragFinished(1)
options.setDragSrcPoint(0.8,0.2)
options.setDragDstPoint(0.9,0.1)
options.setDragFinished(1)
agoraKit.setRemoteTrapezoidCorrectionOptions(uid, options)
(可选)教师端可调用 applyTrapezoidCorrectionToRemote
或 applyTrapezoidCorrectionToRemoteEx
将透视校正参数应用到远端 uid 的本地预览画面上。这样学生也能在本地预览中看到校正后的本地画面。
// 将透视校正参数应用到远端 uid 的本地画面上
agoraKit.applyTrapezoidCorrectionToRemote(uid, true)
// 在不需要远端本地预览进行透视校正时,关闭远端 uid 的本地画面梯形校正
agoraKit.applyTrapezoidCorrectionToRemote(uid, false)
(可选)教师端在调用 applyTrapezoidCorrectionToRemote
或 applyTrapezoidCorrectionToRemoteEx
前后,可以调用 getRemoteTrapezoidCorrectionOptions
或 getRemoteTrapezoidCorrectionOptionsEx
获取透视校正参数,用于保存记忆参数。
// 获取透视校正参数
agoraKit.getRemoteTrapezoidCorrectionOptions(uid, options)
如果不再需要透视校正功能,教师端可调用 enableRemoteTrapezoidCorrection
或 enableRemoteTrapezoidCorrectionEx
关闭透视校正。
// 对指定的远端 uid 关闭透视校正功能
agoraKit.enableRemoteTrapezoidCorrection(uid, false)
学生端调用 enableLocalTrapezoidCorrection
在本地开启透视校正。
// 在本地开启透视校正
agoraKit.enableLocalTrapezoidCorrection(true, AgoraVideoSourceType.camera)
学生端根据透视校正的实际效果,调用 setLocalTrapezoidCorrectionOptions
设置透视校正选项,进行调整。本地设置梯形校正后,远端就能看到梯形校正后的画面。
// 设置透视校正选项,可以在手动校正和自动校正模式之间切换
let options = 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)
agoraKit.setLocalTrapezoidCorrectionOptions(options, AgoraVideoSourceType.camera)
options.setDragSrcPoint(0.8,0.2)
options.setDragDstPoint(0.87,0.12)
options.setDragFinished(0)
agoraKit.setLocalTrapezoidCorrectionOptions(options, AgoraVideoSourceType.camera)
// 拖动结束时要设置 setDragFinished(1)
options.setDragSrcPoint(0.8,0.2)
options.setDragDstPoint(0.9,0.1)
options.setDragFinished(1)
agoraKit.setLocalTrapezoidCorrectionOptions(options, AgoraVideoSourceType.camera)
(可选)学生端在调用 setLocalTrapezoidCorrectionOptions
前后,可以调用 getLocalTrapezoidCorrectionOptions
获取透视校正参数,用于保存记忆参数。
// 获取透视校正参数
agoraKit.getLocalTrapezoidCorrectionOptions(options, AgoraVideoSourceType.camera)
如果不再需要透视校正功能,教师端可调用 enableLocalTrapezoidCorrection
关闭透视校正。
// 对指定的远端 uid 关闭透视校正功能
agoraKit.enableLocalTrapezoidCorrection(false)
- (int)enableRemoteTrapezoidCorrection:(NSUInteger)uid
enable:(BOOL)enabled;
在本地启用或关闭远端 uid 在本地渲染画面的透视校正。远端 uid 自身的本地预览不会看到透视校正效果。
参数 | 说明 |
---|---|
uid | 需要开启或关闭透视校正的 uid。 |
enabled | 是否开启画面透视校正。
|
- (int)enableRemoteTrapezoidCorrectionEx:(NSUInteger)uid
enable:(BOOL)enabled
connection:(AgoraRtcConnection * _Nonnull)connection;
(适用于多频道)在本地启用或关闭远端 uid 在本地渲染画面的透视校正。远端 uid 自身的本地预览不会看到透视校正效果。
参数 | 说明 |
---|---|
uid | 需要开启或关闭透视校正的 uid。 |
enabled | 是否开启画面透视校正。
|
connection | Connection 信息。详见 AgoraRtcConnection。 |
- (int)enableLocalTrapezoidCorrection:(BOOL)enabled
sourceType:(AgoraVideoSourceType)sourceType;
开启或关闭本地画面的透视校正。本地设置透视校正后,远端就能看到梯形校正后的画面。
参数 | 说明 |
---|---|
enabled | 是否开启本地画面透视校正。
|
sourceType | 画面视频源。
|
- (int)setLocalTrapezoidCorrectionOptions:(AgoraTrapezoidCorrectionOptions * _Nonnull)options
sourceType:(AgoraVideoSourceType)sourceType;
配置本地透视校正选项。
参数 | 说明 |
---|---|
options | 透视校正配置参数。详见 TrapezoidCorrectionOptions 。 |
sourceType | 画面视频源。
|
- (AgoraTrapezoidCorrectionOptions *_Nullable)getLocalTrapezoidCorrectionOptions:(AgoraVideoSourceType)sourceType;
获取本地透视校正配置参数。
参数 | 说明 |
---|---|
sourceType | 画面视频源。
|
透视校正配置参数。如果之前多次调用过 setLocalTrapezoidCorrectionOptions
,获取的是之前多次设置的参数集合。详见 AgoraTrapezoidCorrectionOptions
。
- (int)setRemoteTrapezoidCorrection:(NSUInteger)uid
options:(AgoraTrapezoidCorrectionOptions * _Nonnull)options;
配置远端透视校正选项。
参数 | 说明 |
---|---|
uid | 远端用户 uid。 |
options | 透视校正配置参数。如果之前多次调用过 setRemoteTrapezoidCorrectionParams ,获取的是之前多次设置的参数集合。详见 AgoraTrapezoidCorrectionOptions 。 |
- (int)setRemoteTrapezoidCorrectionEx:(NSUInteger)uid
options:(AgoraTrapezoidCorrectionOptions * _Nonnull)options
connection:(AgoraRtcConnection * _Nonnull)connection;
(适用于多频道)配置远端透视校正选项。
参数 | 说明 |
---|---|
uid | 远端用户 uid。 |
options | 透视校正配置参数。如果之前多次调用过 setRemoteTrapezoidCorrectionParams ,获取的是之前多次设置的参数集合。详见 AgoraTrapezoidCorrectionOptions 。 |
connection | Connection 信息。详见 AgoraRtcConnection。 |
- (AgoraTrapezoidCorrectionOptions *_Nullable)getRemoteTrapezoidCorrectionOptions:(NSUInteger)uid;
获取远端透视校正配置参数。
参数 | 说明 |
---|---|
uid | 远端用户 uid。 |
透视校正配置参数。详见 AgoraTrapezoidCorrectionOptions
。
- (AgoraTrapezoidCorrectionOptions *_Nullable)getRemoteTrapezoidCorrectionOptionsEx:(NSUInteger)uid
connection:(AgoraRtcConnection * _Nonnull)connection;
(适用于多频道)获取远端透视校正配置参数。
参数 | 说明 |
---|---|
uid | 远端用户 uid。 |
connection | Connection 信息。详见 AgoraRtcConnection。 |
透视校正配置参数。详见 AgoraTrapezoidCorrectionOptions
。
- (int)applyTrapezoidCorrectionToRemote:(NSUInteger)uid
enable:(BOOL)enabled;
将透视校正参数应用到远端 uid 的本地预览画面或取消远端 uid 的本地预览画面的透视校正效果。
参数 | 说明 |
---|---|
uid | 远端用户 uid。 |
enabled | 是否将透视校正参数应用到远端 uid 的本地预览画面。
|
- (int)applyTrapezoidCorrectionToRemoteEx:(NSUInteger)uid
enable:(BOOL)enabled
connection:(AgoraRtcConnection * _Nonnull)connection;
(适用于多频道)将透视校正参数应用到远端 uid 的本地预览画面或取消远端 uid 的本地预览画面的透视校正效果。
参数 | 说明 |
---|---|
uid | 远端用户 uid。 |
enabled | 是否将透视校正参数应用到远端 uid 的本地预览画面。
|
connection | Connection 信息。详见 AgoraRtcConnection。 |
- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine trapezoidAutoCorrectionFinish:(NSUInteger)uid
result:(AgoraTrapezoidAutoCorrectionResult)result
costTime:(NSUInteger)costTime
srcPoints:(NSArray<NSValue *> * _Nonnull)srcPoints
dstPoints:(NSArray<NSValue *> * _Nonnull)dstPoints;
自动透视校正完成时触发。
参数 | 说明 |
---|---|
uid | 远程开启自动透视校正时的远端用户 uid。 |
result | 自动透视校正结果。
|
costTime | 透视校正花费的时间(ms)。 |
srcPoints | 拖动起始点时的梯形四个顶点坐标。 |
dstPoints | 拖动结束点时的梯形四个顶点坐标。 |
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 | 重置透视校正效果。
|