PTZ 控制

PTZ（Pan Tilt Zoom）控制在安防监控应用中，代表云台上下左右全方位移动及镜头变倍、变焦控制。

主要功能

主要功能	功能说明
基础功能	自检：PTZ 模块通过自行校准检查，实现 PTZ 坐标的校准。在 PTZ 的业务优先级别中，自检处于最高优先级别。 键控：响应用户下发的键控指令，设备按照指令方向进行转动。
高级功能	巡航： 简易巡航：用户制定巡航时间。设备在到达规定时间后，进行一次 360°巡航模式。 非简易巡航： 全景巡航：设备进行 360 度巡航。 收藏点巡航：设备用户的收藏点之间进行往复运动。 追踪：设备能根据物体的移动趋势在，自行进行电机运动，使物体一直处在画面中心。可以通过配置移动检测的相关参数来控制设备的检测范围。
扩展功能	收藏点：PTZ 提供了坐标的收藏功能，用户通过添加收藏点按键，可以单独的保存当前画面和当前 PTZ 坐标。并且可以对当前的收藏点进行个性化命名。 联动点（预设点）：可以理解为简化版本的收藏点，最大上限为四，无法个性化命名。 全景拼接：全景拼接是指通过 PTZ 的转动，对设备周围的环境进行拍摄。对获得的照片进行拼接最后获得一个设备周围的 360°全景图像。

开发指导

运行环境

• 开发框架

  IPC 产品开发包通用功能

• 关联组件

  • app_user_ptz
  • app_sys_ptz
  • app_user_event

使用方法

配置 motor.config 相关能力，调用初始化接口。

初始化流程

TY_SYS_PTZ_PARAM_T ptz_params;
...
//根据需求配置 PTZ 相关能力
...

//初始化 PTZ
ty_user_ptz_start();

数据结构

typedef struct {
    int max_pan_step;                   // maximal pan step
    int max_pan_angle;                  // maximal pan angle
    int max_tilt_step;                  // maximal tilt step
    int max_tilt_angle;                 // maximal tilt angle
    int horizon_tilt_step;              // horizontal tilt step
    int pan_speed;                      // default pan speed
    int tilt_speed;                     // default tilt speed
    int tilt_track;                     // tilt track support flag
    int sleep_pos_def;                  // sleep position support flag
    int defalut_patrol_tmode;           // default patrol type(non-/simple patrol)
    int pan_reverse;                    // pan motor reverse flag
    int tilt_reverse;                   // tilt motor reverse flag
    char struct_type;                                           // device structure type
    TY_GET_OBJECT_COORDINATE_CB get_object_coordinate_cb;       // determinate track source
    char drv_path[DRV_PATH_NAME_LEN];                           // path of PTZ driver
} TY_SYS_PTZ_PARAM_T;

API 说明

初始化 PTZ 模块

/**
 * @brief NONE
 *
 * @return OPERATE_RET
 */
OPERATE_RET ty_user_ptz_start(void);

初始化 PTZ sys 管理模块

/**
 * @fn OPERATE_RET ty_sys_ptz_init(TY_SYS_PTZ_PARAM_T* params)
 * @brief initialize PTZ component with user defined parameters.
 * @param[in] params: user defined parameters' srtuct pointer.
 * @param[out] None.
 * @retval OPRT_OK: action succeed; OPRT_INVALID_PARM: invaild parameter.
 * @attention None.
 */
OPERATE_RET ty_sys_ptz_init(IN CONST TY_SYS_PTZ_PARAM_T* params);

获取当前 PTZ 的运动状态

/**
 * @fn int ty_sys_ptz_get_check_state(void)
 * @brief check if device in self checking
 * @param[in] None
 * @param[out] None
 * @retval 0: is in self checking; 1: not in self checking.
 * @attention None
 */
int ty_sys_ptz_get_check_state(void);

获取当前 PTZ 预设点坐标

/**
 * @fn OPERATE_RET ty_sys_ptz_linkpos_get(OUT INT_T *x, OUT INT_T *y)
 * @brief get current target position coordinate.
 * @param[in] None.
 * @param[out] x: target pan pos.
 * @param[out] y: target tilt pos.
 * @retval OPRT_OK: succeed; OPRT_COM_ERROR: PTZ component is uninitialized.
 * @attention None.
 */
int ty_sys_ptz_linkpos_get(int *x, int *y);

获取设备的键控状态

/**
 * @fn int ty_sys_ptz_get_key_status(void)
 * @brief get keying task state.
 * @param[in] None.
 * @retval 0: not in keying; 1: in keying.
 * @attention None.
 */
int ty_sys_ptz_get_key_status(void);

停止 PTZ 相关线程调度

/**
 * @fn void ty_sys_ptz_stop(void)
 * @brief stop PTZ component.
 * @param[in] None.
 * @param[out] None.
 * @retval None.
 * @attention None.
 */
void ty_sys_ptz_stop(void);

判断设备是否在运动过程中

/**
 * @fn OPERATE_RET ty_sys_ptz_get_motion_state(OUT UINT_T *is_move)
 * @brief check if PTZ is moving(if md event is caused by PTZ moving).
 * @param[in] None.
 * @param[out] is_move to store result, 0: still(md event to upload); 1: in move(md event to ignore).
 * @retval OPRT_OK: action succeed; OPRT_INVALID_PARM: invaild parameter.
 * @attention None.
 */
OPERATE_RET ty_sys_ptz_get_motion_state(OUT UINT_T *is_move);

获取设备当前坐标

/**
 * @fn OPERATE_RET ty_sys_ptz_pos(int *pan, int *tilt)
 * @brief get PTZ position
 * @param[in] None.
 * @param[out] pan: current pan step.
 * @param[out] tilt: current tilt step.
 * @retval OPRT_OK: action succeed; OPRT_INVALID_PARM: invaild parameter.
 * @attention None.
 */
OPERATE_RET ty_sys_ptz_pos(int *pan, int *tilt);

使用示例

典型的简易巡航 montor.config 配置如下

配置名	值	说明
ENV_MOTOR_PTZ_ENABLE	0 或 1	是否使能 PTZ 0：不使能 1：使能
ENV_MOTOR_STRUCT_TYPE	0 或 1	PTZ 结构类型 1：无限位结构 2：有限位结构
ENV_MOTOR_DRV_PATH	字符类型	设备路径：默认为 /dev/tymotor
ENV_MOTOR_MAX_PAN_STEP	整型	水平运动最大步长
ENV_MOTOR_MAX_PAN_ANGLE	整型	水平方向最大运动角度
ENV_MOTOR_MAX_TILT_STEP	整型	垂直方向最大步长
ENV_MOTOR_MAX_TILT_ANGLE	整型	垂直方向最大运动角度
ENV_MOTOR_TILT_ZERO_STEP	整型	垂直方向水平位置时的垂直方向步长
ENV_MOTOR_PAN_SPEED_MAX	整型	水平方向的最大速度
ENV_MOTOR_TILT_SPEED_MAX	整型	垂直方向的最大速度
ENV_MOTOR_TILT_TRACK_SUPPORT	0 或 1	是否支持垂直追踪
ENV_MOTOR_PATROL_TYPE	0 或 2	巡航模式 0 ：非简易巡航 2 ：简易巡航
ENV_MOTOR_TILT_INVERSE	0 或 1	垂直电机电机运动方向控制 0：正向 1：反向
ENV_MOTOR_PAN_INVERSE	0 或 1	水平电机电机运动方向控制 0：正向 1：反向
ENV_MOTOR_MOTOR_SUP_SLEEP_POS	0 或 1	物理遮罩（隐私位置）支持 0：禁用 1：支持

注意事项

PTZ 组件仅包含业务能力，不包括驱动能力，使用需添加驱动资源。

常见问题

设备在自检的时候可以执行其他操作吗？

不可以。

在逻辑规划中自检属于最高优先级，不可被其他操作打断。模块优先级关系，从高到低依次为：

1. 自检
2. 全景拼接
3. 按键
4. 联动点、收藏点
5. 巡航
6. 追踪

设备断网后还会执行定时巡航任务吗？

会。

实际上在用户下发任务的那一刻，设备就已经收到了定时巡航任务消息。具体流程为：

1. （云端）用户下定时任务。
2. （设备）收到任务，按照规定时间设置定时器。
3. （设备）PTZ 模块收到定时提醒，执行巡航任务。