SONY TOF

1. 概述

Xvisio SeerSense™ DS80 系列模组产品会使用到此类型 TOF Camera，其他产品可以参考对应的数据手册来确认 TOF Camera 类型。SONY 类型 TOF Camera 使用的也是 iTOF 算法 ，波长为940nm 。

2. 特性

2.1 工作模式

SONY 类型 TOF Camera 可以支持多种工作模式以应对不同的主机处理能力和应用场景：

工作模式类型定义:

enum class SonyTofLibMode { IQMIX_DF ,IQMIX_SF, LABELIZE_DF ,LABELIZE_SF ,M2MIX_DF ,M2MIX_SF };

2.2 调制频率

支持单频 60MHz 或者双频 20MHz/120MHz ，所有的工作模式都能支持这两种调制频率，通常工作距离2米内建议使用单频模式，工作距离大于2米建议使用双频模式。双频下距离更远精度更高，单频的数据带宽和负载更低，具体参数请参考产品数据手册。
调制频率定义:

enum class SonyTofLibMode { IQMIX_DF ,IQMIX_SF, LABELIZE_DF ,LABELIZE_SF ,M2MIX_DF ,M2MIX_SF };

调制频率模式和工作模式共用一个类型。

2.3 分辨率

支持两种分辨率:

• VGA：640*480
• QVGA：320*240

所有的工作模式都能支持这两种分辨率。

分辨率类型定义：

enum class Resolution{ Unknown = -1,VGA = 0 ,QVGA ,HQVGA};

注意：SONY 类型 TOF 不支持HQVGA。

2.4 帧率和数据带宽

可以设置帧率，范围在5-30 fps ,但是受限于不同工作模式下的算力带宽负载限制，只有对应帧率可以达到设置要求才设置生效，对应的帧率请查看表格：

用户根据使用场景和需求选择不同模式和设置。
帧率类型定义：

enum class Framerate{ FPS_5 ,FPS_10 ,FPS_15 ,FPS_20 ,FPS_25 ,FPS_30 };

2.5 设置 API

Xvisio SDK提供了一个API可以同时设置 “工作模式”、“调制频率模式”、“分辨率”、“帧率” :

device->tofCamera()->setSonyTofSetting(xv::TofCamera::SonyTofLibMode::IQMIX_DF,
            xv::TofCamera::Resolution::VGA,
            xv::TofCamera::Framerate::FPS_30);

具体code参考demo-api.cpp（case 11），demo-api 。

2.6 Filter 设置文件

Xvisio SDK 提供了一个可以替换当前 TOF 算法库所使用的 Filter 设置文件，如果您想使用此功能需要对 TOF 算法库的 Filter 格式及功能有一定的了解。
接口原型：
void setFilterFile(std::string filePath)
调用示例:

device->tofCamera()->setSonyTofSettingsetFilterFile("filterfile.bin");

3 深度数据和 IR 数据

SONY类型的 TOF 深度数据格式支持16位深度数据，单位毫米，并能够支持 IR 灰度数据。

3.1 DepthImage定义

/**
 * @brief An image provided by a TOF camera.
 * @note  There are two manufacturers of TOF camera, Pmd and sony.
 *        Pmd TOF depth type is Depth_32，sony TOF depth type is Depth_16.
 *        Cloud type just use for Pmd point cloud,the coordinate system of the point cloud is the camera coordinate system, and the data unit is meters.
 *        Length, width and depth are in meters use Pmd TOF.
 *        Length, width and depth are in metmillimeterers use sony TOF. 
 */
struct DepthImage {
    enum class Type { Depth_16 = 0, Depth_32, IR, Cloud, Raw, Eeprom, IQ };
    Type type = Type::Depth_32;
    std::size_t width = 0; //!< width of the image (in pixel)
    std::size_t height = 0; //!< height of the image (in pixel)
    double  confidence = 0.0; //!< confidence of depth [0.0,1.0]
    std::shared_ptr<const std::uint8_t> data = nullptr; //! image of depth
    unsigned int dataSize = 0;
    double hostTimestamp = std::numeric_limits<double>::infinity(); //!< host timestamp of the physical measurement (in second based on the `std::chrono::steady_clock`).
    std::int64_t edgeTimestampUs = (std::numeric_limits<std::int64_t>::min)(); //!< timestamp of the physical measurement (in microsecond based on edge clock).
    /**
     * @brief Convert to a #xv::RgbImage
     */
    RgbImage toRgb() const;
};

说明：

1. “type”值为 “Depth_16” 或 “IR” 。
2. “width” 和 “height” 和 TOF 分辨率对应。
3. “data” 为 depth image data ，单位毫米,每个像素16位的位宽，使用时根据应用场景进行对应的转换。
4. “data size” 等同于 “width” * “height” * 2（16位的位宽）。
5. “confidence” 只有工作模式在 IQ 模式时才有效。
6. “hostTimestamp” 经过 SDK 的时间戳同步转换为主机端相同基准的时间戳，单位秒，精度可达到微秒。
7. “edgeTimestampUs” ，Xvisio 设备端采样时间戳，单位微秒。
8. “toRgb()” 暂无效，保留。

3.2 获取 DepthImage

使用注册回调方式获取 DepthImage,接口调用流程如下所示：

1. 注册tofCamera的callback；
2. 调用start()，启动 TOF streaming；
3. 触发回调，在回调里做数据处理；
4. 反注册回调后调用 stop()，停止 TOF Streaming。
   具体code参考demo-api.cpp（case 11）,demo-api 。

4 点云数据

Xvisio SDK 提供了 API 可以把深度数据转换为点云数据格式。

4.1 PointCloud定义

/**
 * @brief A point cloud of 3D points.
 */
struct PointCloud {
    double hostTimestamp = std::numeric_limits<double>::infinity(); //!< host timestamp of ? (in second based on the `std::chrono::steady_clock`).
    std::int64_t edgeTimestampUs = (std::numeric_limits<std::int64_t>::min)(); //!< timestamp of ? (in microsecond based on edge clock).
    std::vector<Vector3f> points;
};

说明：

1. “hostTimestamp” 经过 SDK 的时间戳同步转换为主机端相同基准的时间戳，单位秒，精度可达到微妙。
2. “edgeTimestampUs” ，Xvisio 设备端采样时间戳，单位微妙。
3. “points”,点云数据，每一个像素有3个 float 类型组成,代表 x , y ,z 轴向的深度数据，单位毫米。

4.2 获取 PointCloud

获取 PointCloud 必须要先获取 DepthImage，然后再调用接口做转换，流程如下：

1. 注册tofCamera的callback；
2. 调用start()，启动 TOF streaming；
3. 触发回调，在回调里做点云转换处里，使用的 API：
   device->tofCamera()->depthImageToPointCloud(tofDepthImage)
4. 反注册回调后调用 stop()，停止 TOF Streaming。
   具体code参考demo-api.cpp（case 11）,demo-api 。

5 代码

• 定义 Xvisio Device
  std::shared_ptr<xv::Device> device = nullptr;
• 读取 device_list,超时 10 秒(推荐值，也可以缩短)
  auto device_list = xv::getDevices(10., "");
• 判断获取的 devices 是否为空，为空则失败

  if (device_list.empty())`
  {
          LOG(LOG_Function,"initDevice faiiled:Timeout for device detection.");
          return false;
  }
  
  

• 获取 device （这里只针对单设备，多设备请参考相应文档描述）
  device = device_list.begin()->second;
• 设置 “工作模式”、“帧率”、“分辨率”，这里设置的是 "IQ 单频"、“VGA 分辨率”、“30fps” ：

  bool ret = m_xvDevice->tofCamera()->setSonyTofSetting(xv::TofCamera::SonyTofLibMode::IQMIX_SF,
                                          xv::TofCamera::Resolution::VGA,
                                          xv::TofCamera::Framerate::FPS_30);
      if(!ret)
      {
          std::cout<<"set TOF Setting failed"<<std::endl;
      }
  
  

• 注册回调，回调定义里获取深度数据或者 IR 数据 、点云数据

  int tofId = -1;
  tofId = device->tofCamera()->registerCallback([&](xv::DepthImage const & tofDepthImage){
          if (tof.type == xv::DepthImage::Type::Depth_16 ) {
              //Operation on tofDepthImage
              //...
  
              //point cloud process
              if(enableDevMap["tof_point_cloud"])
              {
                  auto points = device->tofCamera()->depthImageToPointCloud(tofDepthImage)->points;
          
                  for (auto iter = points.begin(); iter != points.end();iter++)
                  {
                      auto point = *iter;
                      printf(buff, "x=%f ,y=%f ,z=%f\n", point[0], point[1], point[2]);
                      //...
                  }
          
              }
          }
          else if(tof.type == xv::DepthImage::Type::IR )
          {
              //Operation on tofDepthImage
              //...
          }
      });
  
  

• TOF 启动

  //start tof
  device->tofCamera()->start();
  

• TOF 停止
  此处用到的 tofId 是注册callback时赋值。

  device->tofCamera()->unregisterCallback(tofId);
  device->tofCamera()->stop();
  

6 注意事项

1. TOF 的功耗需求 ，使能TOF后，因为TOF 相机具有红外投射器会周期性的发射红外波而带来周期性的负载峰值，所以设备的电流峰值对主机的 USB 供电负载能力有一定要求，具体可查看Xvisio 设备和使用注意事项。
2. PMD TOF 和 SONY TOF 深度数据格式的不同，单位不同 ：PMD 32位 单位米，SONY 16位 单位毫米。

←  Xvisio SDK 深度
←  Xvisio 功能介绍和快速启动
←  Xvisio SDK 文档主页