PTZ Control

Pan-tilt-zoom (PTZ) control enables a camera to pan from left to right, tilt up and down, and zoom in and out of a scene.

Features

Development guide

Runtime environment

• Development framework

  The generic features provided by IPC Product Development Kit.

• Components

  • app_user_ptz
  • app_sys_ptz
  • app_user_event

How to

Configure the PTZ capabilities with motor.config and call the initialization API.

Initialization process

TY_SYS_PTZ_PARAM_T ptz_params;
...
// Configure the PTZ capabilities as needed.
...

// Initialize PTZ.
ty_user_ptz_start();

Data structure

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 description

Initialize the PTZ module

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

Initialize the PTZ system management module

/**
 * @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);

Get the current status of PTZ movement

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

Get the current coordinates of the PTZ preset point

/**
 * @fn OPERATE_RET ty_sys_ptz_linkpos_get(OUT INT_T *x, OUT INT_T *y)
 * @brief get the current target position coordinates.
 * @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);

Get the status of key control

/**
 * @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);

Stop the scheduling of PTZ threads

/**
 * @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);

Determine if the camera is moving

/**
 * @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);

Get the current coordinates

/**
 * @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);

Example

Here is an example of how to configure the montor.config file to implement a typical patrol feature.

Things to note

The PTZ component only provides business logic capabilities and does not include driver capabilities. Add the necessary driver resource if needed.

FAQs

Can the camera perform other operations during self-check?

No, it cannot.

Self-check has the highest priority and cannot be interrupted by other operations. The modules listed from highest to lowest priority:

1. Self-check
2. Panorama stitching
3. Key control
4. Preset points and site favorites
5. Patrol
6. Tracking

Will the camera still perform its scheduled patrol if it gets disconnected?

Yes, it will.

The camera receives the patrol schedule after the user creates it on the mobile app. Here is how the patrol schedule works:

1. The cloud sends the created patrol schedule to the camera.
2. The camera receives the patrol schedule and sets a timer accordingly.
3. The PTZ module gets notified when the timer expires and performs a patrol.