SDK 示例
=================================

本章将介绍一些 DaoAI InspecTRA SDK 的常用功能示例代码，以帮助您更好地使用。

.. contents:: 
   :local:

前提条件
-----------

      - 安装DaoAI InspecTRA
      - 遵循环境配置中的步骤，确保环境正确配置


引入库
--------

在示例中，我们使用了以下几个头文件，其中daoai_camera_3d 开头的是用于引入DaoAI InspecTRA SDK的库。

.. code-block:: C++

    #include <daoai_camera_3d/application.h>
    #include <daoai_camera_3d/array2d.h>
    #include <daoai_camera_3d/camera.h>
    #include <daoai_camera_3d/camera_info.h>
    #include <daoai_camera_3d/connect_mode.h>
    #include <daoai_camera_3d/frame.h>
    #include <daoai_camera_3d/pointcloud.h>
    #include <daoai_camera_3d/settings.h>
    #include <opencv2/core/mat.hpp>
    #include <opencv2/imgcodecs.hpp>
    #include <cstdint>
    #include <exception>
    #include <filesystem>
    #include <iostream>
    #include <vector>

发现相机
-----------

这段代码展示了如何使用 DaoAI InspecTRA SDK 扫描指定子网内的相机。

首先，定义了两个常量：kInstanceId 表示应用实例的标识符，kCameraSubnet 表示要扫描的子网地址。然后，创建一个 DaoAI::Application 对象 app，并使用 kInstanceId 进行初始化。

接下来，通过调用 app.listCameras 方法，并传入子网地址 kCameraSubnet，扫描指定子网内的所有支持的设备，并将结果存储在 cameras 向量中。如果扫描过程中发生异常，会捕获并输出错误信息，并终止程序返回 -1。

.. code-block:: C++

    constexpr char kInstanceId[] = "NetworkCamera3dSample";
    constexpr char kCameraSubnet[] = "192.168.1.11";

    DaoAI::Application app(DaoAISample::kInstanceId);

    // Scans supported devices from the specified subnet.
    std::vector<DaoAI::Camera> cameras;
    try {
        cameras = app.listCameras(DaoAISample::kCameraSubnet);
    } catch (const std::exception& e) {
        std::cerr << "Error discovering network cameras. Cause: " << e.what() << std::endl;
        return -1;
    }



连接相机
--------------

这段代码展示了如何使用 DaoAI InspecTRA SDK 获取相机的信息，并连接到相机。

首先，通过循环遍历之前扫描到的 cameras 向量，获取每个相机的详细信息。每个相机的信息通过 camera.get3DCameraInfo().getCameraInfo() 方法获取，并输出以下字段：

- 序列号（Serial number）
- 型号（Model）
- IP 地址（IP）
- 主机设备（Host device）
- 网关版本（Gateway version）
- 固件版本（Firmware version）
- 投影仪固件版本（Projector firmware version）

接着，只使用扫描到的第一个相机进行演示。通过引用 cameras[0] 获取第一个相机对象 cam，并尝试以 DaoAI::ConnectMode::MODE_1 模式连接该设备。

连接模式分为：

- DEFAULT: 默认，USB 相机的连接方式
- MODE_1: 网口相机的连接方式
- FILE: 虚拟相机的连接方式

如果连接失败，会捕获并输出错误信息，并终止程序返回 -1。

以下是代码示例：

.. code-block:: C++

	// Camera information is readily available even prior to connection.
	for (const auto& camera : cameras) {
		DaoAI::CameraInfo::Info info = camera.get3DCameraInfo().getCameraInfo();
		std::cout << "Serial number:\t\t\t" << info.serial << std::endl;
		std::cout << "Model:\t\t\t\t" << info.model << std::endl;
		std::cout << "IP:\t\t\t\t" << info.ip << std::endl;
		std::cout << "Host device:\t\t\t" << info.host_device << std::endl;
		std::cout << "Gateway version:\t\t" << info.gateway_version << std::endl;
		std::cout << "Firmware version:\t\t" << info.firmware_version << std::endl;
		std::cout << "Projector firmware version:\t" << info.projector_firmware_version << std::endl;
	}

    // We will only use the first camera device for this demonstration.
	auto& cam = cameras[0];
	try {
		cam.connect(DaoAI::ConnectMode::MODE_1);
	} catch (const std::exception& e) {
		std::cerr << "Failed to connect the device. Cause: " << e.what() << std::endl;
		return -1;
	}



帧值参数和预览
------------------

这段代码展示了如何使用 DaoAI InspecTRA SDK 检查相机当前的视野，并调整帧配置以获得理想的图像。

首先，定义了一个 DaoAI::Settings::FrameConfig 对象 candidate_frame_config，用于设置帧配置参数，其中包括：

- 曝光补偿（exposure_stop）：设置为 -1
- 亮度（brightness）：设置为 3
- 增益（gain）：设置为 0

接着，调用 cam.cameraPreview(candidate_frame_config) 方法，获取相机在当前配置下的预览图像，并将结果存储在 images 向量中。

然后，通过循环遍历 images 向量，将每个图像保存为 JPEG 文件。文件名格式为 "file_camera_preview_" + std::to_string(i) + ".jpg"，其中 i 表示图像的索引。

以下是代码示例：

.. code-block:: C++

	// Checks what the camera is currently seeing. Now, it's a good opportunity to tune a
	// desirable frame configuration for this scene.
	DaoAI::Settings::FrameConfig candidate_frame_config(
		/*exposure_stop=*/-1, /*brightness=*/3, /*gain=*/0);
	std::vector<DaoAI::Array2D<uint8_t>> images = cam.cameraPreview(candidate_frame_config);
	for (unsigned i = 0; i < images.size(); ++i) {
		DaoAISample::saveImage(images[i], "file_camera_preview_" + std::to_string(i) + ".jpg");
	}



拍照
-----------

这段代码展示了如何使用 DaoAI InspecTRA SDK 拍照并采集点云，并自定义算法配置以适应特定场景。

首先，定义了一个 DaoAI::Settings 对象 capture_settings，并将之前设置的帧配置 candidate_frame_config 添加到 capture_settings 中。

接着，创建了一个 DaoAI::Settings::CameraAlgorithmUserConfig::Median 对象 median_filter，用于设置中值滤波器的内核大小（median_kernel_size），这里设置为 5。然后，通过 capture_settings.algorithm_params\_.configureCameraAlgorithmParam(median_filter) 方法，将中值滤波器配置应用到采集设置中。

接下来，定义一个 DaoAI::Frame 对象 frame，用于存储采集到的点云。通过 cam.D3Capture(capture_settings) 方法，使用定义的采集设置进行点云采集。如果采集过程中发生异常，会捕获并输出错误信息，并终止程序返回 -2。

以下是代码示例：

.. code-block:: C++

    // Capture one frame of point cloud.
    DaoAI::Settings capture_settings;
    capture_settings.frame_settings_.addAll({ candidate_frame_config });

    // The default algorithm configuration is set to work for common scenarios. Here we show how
    // one might customize the configuration using the SDK.
    DaoAI::Settings::CameraAlgorithmUserConfig::Median median_filter(/*median_kernel_size=*/5);
    capture_settings.algorithm_params_.configureCameraAlgorithmParam(median_filter);

    DaoAI::Frame frame;
    try {
        frame = cam.D3Capture(capture_settings);
    } catch (const std::exception& e) {
        std::cerr << "Error capturing. Cause: " << e.what() << std::endl;
        return -2;
    }
        

保存
-----------

这段代码展示了如何从采集到的帧中获取点云数据，并将其保存为 PLY 文件。

首先，通过 frame.getPointCloud() 方法获取采集到的点云数据，并存储在 point_cloud 对象中。然后，输出点云的维度信息，包括点的数量（#points）、宽度（width）和高度（height）。

接着，定义保存帧的路径 frame_path，路径为当前工作目录下的 "file_camera_frame.ply" 文件。通过 std::filesystem::current_path() 方法获取当前工作目录，并拼接文件名 "file_camera_frame.ply"。

然后，输出保存帧的信息，并调用 frame.save(frame_path) 方法将帧保存到指定路径。

.. code-block:: C++

    // The resulting point cloud is kept organized.
    DaoAI::PointCloud point_cloud = frame.getPointCloud();
    std::cout
        << "Pointcloud dimension -- #points: " << point_cloud.getSize()
        << ", width: " << point_cloud.getWidth()
        << ", height: " << point_cloud.getHeight() << std::endl;

    std::filesystem::path frame_path = std::filesystem::current_path() / "file_camera_frame.ply";
    std::cout << "Saving frame " << frame_path.string() << std::endl;
    frame.save(frame_path);

    return 0;