English | 中文

HikVision Camera Package in ROS2 Humble

Purpose & Functionalities

This package provides the functionality of using Hikvision cameras in ROS2 Humble. This includes reading and setting exposure time, gain, frame rate, pixel format, etc. from the ROS2 parameter system, as well as reading sequence numbers, frame rates, and other parameters from the camera and publishing them to the parameter system, and the most basic function of obtaining images from the camera and publishing them to the '/image_raw' topic, supporting offline reconnection and hardware frame rate output. The commandline echo and the frame rate shown in rviz2 both reached >160FPS.

Usage

Prerequisite:

• Ubuntu 22.04, with the latest gcc/g++ and make have been installed.

Place the root directory of the package hik_comamera in your ROS2 workspace, change to the workspace directory, and after running rosdep install --from-paths src -y --ignore-src, (change execution permissions and) run hik_comamera/build.zsh and source hik_comamera/launch.zsh in sequence to build the workspace and start the node. (Recommended)

When you use rviz2 to view the images, do not forget to set client-side QoS to "Best Effort", and modify the frame rate to a proper value.

Code description/explanation

The definition part of HikCameraNode contains:

• Functional #defines, used to output logs. #undefs has been done orderly at the end of the node definition.
• The constructor and destructor of public attribute.
• Member variables of protected attribute.
  • Small variables: including MVS SDK-oriented and ROS2-oriented variables, some of which are cache variables (can also be implemented with static at where they are used).
  • Auxiliary functions of some of these small variables.
  • Several lookup tables: implemented with std::map. They are used to elegantly communicate the parameter names and setting methods between the ROS2 parameter side and the SDK camera side, and act as a list for traversal. See the note at the definition for details.
  • Ancillary function of lookup table: used to traverse these lookup tables conveniently.
• Member functions of protected attribute.
  • Initialization functions encapsulated by each layer, anti-initialization function encapsulated by each layer, and connection check function.
  • this management part: responsible for the initialization and de-initialization (there is no such requirement at present) of the HikCameraNode.
  • Image transmission section. The core functionality.
    • Since the pixel format has been changed through the SDK when the camera starts (including the initial startup and restart when changing some parameters), it is unnecessary and not recommended to change the pixel format here through MV_CC_ConvertPixelTypeEx.
    • The frame fetching function MV_CC_GetOneFrameTimeout, which is managed by the user according to the official document, meeting the requirement of loading frames into the member data of the message struct.
    • Among this function, timing functionalities are mixed within, which can output the time consumption of each internal functionality at runtime by uncommenting the TIMING_ON macro at the beginning of the code file.

---

海康威视相机ROS2 Humble包

目的

本包提供了在ROS2 Humble中使用海康相机的功能。包括从ROS2参数系统中读取并设置曝光时间（Exposure Time）、增益（Gain）、帧率（Frame Rate）、图像格式（Pixel Format，目前支持cpp代码中image_encodings_2_MvGvspPixelType所包含的像素格式）等，以及从相机读取序列号、帧率等参数并发布到参数系统，和最基本的从相机获取图片并发布到/image_raw话题的功能。

支持断线重连和实时相机（硬件）帧率输出。实测命令行回显帧率和rviz2上显示的帧率在默认分辨率下均达到了>160FPS。

使用

前提条件：

• Ubuntu 22.04，已安装最新gcc/g++和make。

将包的根目录hik_camera放置到你的ROS2工作区中，切换到工作区目录下，运行rosdep install --from-paths src -y --ignore-src后，（增加执行权限并）依次运行src/hik_camera/build.zsh,source src/hik_camera/launch.zsh即可构建工作区并启动节点。（推荐）

通过rviz2查看时，注意将接收端的话题服务策略设置到"Best Effort"模式，并更改rviz2中的帧率。

代码说明

HikCameraNode的定义部分，代码中依次包含：

• 功能性#define，用于输出日志。已在节点末尾按序#undef。
• public属性的节点构造函数和析构函数。
• protected属性的成员变量。
  • 小型变量：包括面向MVS SDK的和面向ROS2的，其中有些是缓存变量（也可在使用处用static实现）。
  • 某些小型变量的附属功能函数。
  • 几个查找表：用std::map实现，用于优雅地沟通ROS2参数端与SDK相机端的参数名称和设置方法，同时起到列表的作用，以便遍历。详见定义处注释。
  • 查找表的附属功能函数：用于方便地遍历这些查找表。
• protected属性的成员函数。
  • 各层封装的初始化函数、各层封装的反初始化函数、连接检查函数。
  • this管理部分，负责管理HikCameraNode的初始化和反初始化（暂无此需求）。
  • 图像发送部分。核心功能。
    • 由于已在相机启动（包括初次启动和更改某些参数时的重新启动）时通过SDK更改了像素格式，故无需且不应通过MV_CC_ConvertPixelTypeEx在此处更改像素格式。
    • 采用官方文档中说的由用户自行管理的取帧函数MV_CC_GetOneFrameTimeout，符合将帧加载到消息的data成员中的需求。
    • 其中穿插计时功能。打开代码文件开头的TIMING_ON宏，可在运行时输出每次调用内部各功能的时间消耗。

Bibliography

• Enable Multicast for lo in order to pass the test case on the website tutorial of ROS2

Problems encountered and reflections

• Decided not to use try...catch to handle errors. https://learn.microsoft.com/en-us/cpp/cpp/errors-and-exception-handling-modern-cpp?view=msvc-170
• 引入某些头文件后，需要在包的根目录下建立空文件夹config才能通过构建流程并正常运行，且Git默认忽略空目录。改进方法：在build.zsh脚本中加上新建文件夹功能。
• 理论上，也可以通过主动断线重连（如代码中原先更改pixel format的做法）的方法来修改帧率，以避免运行时无法更改帧率的问题。但此方法可能对画面的连续性造成一定的伤害，故仅用此方法设置了hardware级的PixelFormat因为此做法导致硬件帧率太低（~80FPS），故仅放进注释里供参考。