Percipio Viewer 用户指南
Percipio Viewer 是图漾基于 Percipio Camport SDK 开发的一款看图软件，可实时预览相机输出的深度图、彩色图、红外图和点云图。
Percipio Viewer 分 Windows 版和 Linux 版，推荐使用 Windows 版。下文以 Percipio Viewer（Windows 版）为例，介绍其界面和功能。
Percipio Viewer 软件界面
Preferences 按钮：单击 Preferences 可调出下拉菜单。
视图切换区：用于切换 2D、3D、Registration 和 Color 3D 视图。
按钮：单击该按钮即跳转到 Percipio Viewer 用户指南页面。控制面板区：用于查看信息、设置工作模式、开启/关闭数据流、设置组件参数和录制视频。
表示数据流处于开启状态。
表示数据流处于关闭状态。
图像显示区：用于显示深度图、彩色图、红外图和点云图。
Log 显示区：用于显示 log 信息。
快速开始
该部分内容主要介绍 Percipio Viewer 的使用流程：
使用 Percipio Viewer 前，请先：
设置相机 IP
Percipio Viewer 支持修改网络相机的 IP 地址为静态或动态 IP。设置相机 IP 前，请确保上位机 IP 在目标网段上。
按照以下步骤，设置相机 IP：
点击 Preferences，在下拉菜单中点击 Device IP Settings。进入 Device IP Settings 页面。
在 Net interface list 一栏中选择目标网段的网络接口或者 All network interfaces。
在 Found device 一栏中选择目标相机序列号。
依次填写相机的 MAC 地址 Device mac address、 目标 IP 地址 Device target IP 、网关 Device target gate、子网掩码 Device target mask。
备注
Device target IP 一栏不填写表示将当前相机设置为动态 IP 地址，填写即表示设置为静态 IP 地址。
点击 Accept。
Log 区域提示 “Device IP setting is successful.” 表示设置 IP 成功。 Log 区域提示 “Device IP setting failed” 表示设置 IP 失败，请检查电脑网络配置、硬件接线、 Device IP Settings 页面参数填写是否正确。
选择相机
从 V1.2.3 版本开始，Percipio Viewer 启动后不会自动打开相机，您需手动选择并打开。
以序列号为 207000106916 的相机为例，按照以下步骤，选择相机：
双击打开可执行文件
percipio-viewer-X.X.X.exe。待相机初始化完成后，点击 Preferences，在下拉菜单中点击 Refresh Source 刷新设备列表。
在设备列表中选择目标相机的序列号 207000106916。
备注
若设备列表中的序列号后显示了相机状态码和固件错误码（如上图 -1014, 0x00000000），表明该相机无法正常打开，请在下图中查看相机状态码。若相机状态码为 -1024，需根据固件错误码判断相机的异常情况。
查看信息
点击 
，可查看相机信息，包括接口名称、序列号、型号、Mac/IP 地址（网络相机特有）、固件版本和配置版本。
网络相机信息
USB 相机信息
固件版本信息较长，当鼠标停留在 Firmware Version 信息上时即可显示完整的内容。
选中 Info 相机信息，使用“Ctrl C + Ctrl V”可复制粘贴。
设置工作模式
Percipio Viewer 支持设置相机的工作模式，相机根据设置采集图像。
在所有数据流处于 时，点击 
，并根据下表选择工作模式。
工作模式 |
相机工作状态 |
|---|---|
Trigger Mode Off 自由采集模式 |
开启数据流，相机以最高帧率连续采集图像。 |
Hardware Trigger Mode 硬触发模式 |
将外部硬触发信号源与相机连接，开启数据流，相机根据触发信号频率采集图像。 |
Software Trigger Mode (continue) 连续软触发模式 |
开启数据流，相机接收到软件触发信号后采集图像。 |
Software Trigger Mode (single) 单帧软触发模式 |
开启数据流，点击 |
，每点击一次，相机采集一帧图像。选中的工作模式右侧会带有图标 √。
选中的工作模式
预览图像
Percipio Viewer 支持预览深度图、彩色图、左右红外图、点云图以及调试组件参数。
按照以下步骤，预览图像：
打开数据流，即可在图像显示区实时预览相应的图像。
图像上方标题栏分别显示当前的数据流名称、图像分辨率以及帧率。
深度图、彩色图、左/右红外图
点击数据流左侧
展开页面，可根据实际情况调试参数。
备注
部分参数需在数据流处于
各个型号的相机支持设置的参数不同，Percipio Viewer 界面的显示随之改变。下表以 PS800-E1 相机为例介绍参数。
PS800-E1 相机的参数界面
点击视图切换区的 2D、 3D、 Registration 和 Color 3D，可切换视图。
备注
只有在 Depth Stream 和 Color Stream 同时打开时，才可切换至 Registration 或 Color 3D 视图。
将鼠标置于 2D/3D 图上并选择以下方式调整视图：
缩放图像：滚动鼠标滚轮
平移图像（仅 3D/Color 3D 视图支持）：按住鼠标滚轮并拖动
旋转图像（仅 3D/Color 3D 视图支持）：按住鼠标左键并拖动
复位视图（仅 3D/Color 3D 视图支持）：点击
保存图像
按照以下步骤，保存 2D/3D 图：
备注
图像文件默认保存在 C 盘，若无法保存到默认路径，请参考 无法保存文件至 C 盘，怎么办？
切换至 2D 视图，点击
，选择保存路径并点击保存。切换至 3D/Color 3D 视图，点击
，选择 3D 点云图导出的文件格式（支持 .xyz和.ply格式）和保存路径并点击保存。
录制视频
Percipio Viewer 支持录制相机采集图像时的视频。录制视频过程中，支持调整部分参数，不支持关闭/开启数据流。
按照以下步骤，录制视频：
点击
，并设置 .bag文件的保存路径。视频录制开始。备注
.bag文件默认保存在 C 盘，若无法保存到默认路径，请参考 无法保存文件至 C 盘，怎么办？
录制视频
点击
。视频录制结束。.bag文件保存路径会显示在图像显示区右上角和 Log 信息显示区。
若需回放录制视频，点击 Preferences，在下拉菜单中点击 Load Recorded Sequence，并选择目标 .bag 文件。
录像回放
保存/加载参数设置
Percipio Viewer 支持将各个组件的 Control 参数设置保存至 XXX.json 文件，以便后续通过加载该 XXX.json 文件来导入参数设置。
点击 Dump parameters，可将当前相机的 Control 参数设置保存至 XXX.json 文件。
点击 Load parameters，加载 XXX.json 文件，导入参数设置。
保存/加载参数设置
图像调试（软件）
该部分内容主要介绍 Percipio Viewer 软件支持的图像调试功能：
对齐功能
Percipio Viewer 支持 RGB-Depth 对齐和 RGB-3D 对齐。
在 Depth Stream 和 Color Stream 处于 时，点击以下按钮，切换到相应的对齐视图。
点击 Registration，可切换到彩色图与深度图对齐的视图。
点击 Color 3D，可切换到彩色图与 3D 点云图对齐的视图。
彩色图和深度图对齐
彩色图和 3D 点云图对齐
Fill Hole 填洞功能
该功能软件层面的后处理，可填补缺失的深度数据。该功能结合 Remove Outlier 降噪功能一起使用，能获得成图效果最佳的深度图。
在 Depth Stream 处于 时，选中 Fill Hole，并根据深度图调节参数 k Size 和 h Size。
Fill Hole 填洞功能
备注
若 k Size 和 h Size 的参数值设置太大，可能会出现深度图失真的现象。
Remove Outlier 降噪功能
该功能软件层面对于点云的后处理，可减少点云图中的飞点和错误匹配点。
在 Depth Stream 处于 时，选中 Remove Outlier，并根据深度图调节参数 spk size。
若区域中的点云个数小于 spk size 设定值，则将该区域的点云视为飞点并去除。
Remove Outlier 降噪功能
Time Domain Filtering 时域滤波功能
该功能是软件层面对于点云的后处理，将多帧数据均值化处理，以去除噪声和平滑点云。
在 Depth Stream 处于 时，选中 Time Domain Filtering，并根据点云图调节参数 time-domain frame count。
参数 time-domain frame count 设定值约大，得到的深度值抖动幅度越小，点云越平滑。
Time Domain Filtering 时域滤波功能
Median Filtering 中值滤波功能
该功能是软件层面对于点云的后处理，可消除孤立的噪声点，同时尽可能地保留图像的边缘信息。
在 Depth Stream 处于 时，选中 Median Filtering，并根据点云图调节参数 Ksize。
Auto ISP 功能
该功能是软件层面对于彩色图像的 ISP 后处理，可将存在偏色的 RAW BAYER 图像处理成正常色彩空间的彩色图。
备注
带有硬件 ISP 模块的相机可输出正常色彩空间的彩色图像，无需使用 Auto ISP 功能进行后处理。
在 Color Stream 处于 时，选中 Auto ISP，再打开数据流。
Auto ISP 功能
Undistort 畸变校正
该功能是软件层面对于彩色图像的后处理，可对输出的彩色图做畸变校正。
在 Color Stream 处于 时，选中 Undistort EN，即可得到畸变校正后的彩色图。
Undistort 畸变校正
Analytical Type 分析类型
该功能是软件层面对于深度图的数据分析。
在 Depth Stream 处于 时，设置 Analytical Type。
选择 single pixel，深度视图左下角实时显示以下信息：
Depth of center ：深度图中心点的深度值。
Depth of (X,Y) ：鼠标所指点的深度值。
single pixel
选择 rectangle area，鼠标左键在深度图上拖拉，框选出感兴趣的区域 ROI 后，深度视图左下角实时显示以下信息：
Mean distance of ROI（x1 y1 x2 y2）：ROI 区域内所有深度值的平均值。
Fit plane distance of ROI（x1 y1 x2 y2）：相机光心到ROI拟合平面的深度距离。
Planarity of ROI（x1 y1 x2 y2）：ROI 区域平面度。ROI 区域内的深度值越平整，planarity 值越小。
rectangle area
图像调试（相机）
该部分主要介绍如何通过 Percipio Viewer 设置相机特有的图像调试功能。
ToF 系列
以下是 ToF 系列特有的图像调试功能，只有用 Percipio Viewer 打开了该系列的相机，才可在界面中设置。
ToF 系列图像调试功能
Depth Quality 深度质量
该功能用于设置相机输出的深度图质量，为适应不同应用的需求。
在 Depth Stream 处于 时，根据实际需求设置 depth quality，再打开数据流。
basic：深度值抖动幅度大，输出帧率高。
medium：深度值抖动幅度中等，输出帧率中等。
high：深度值抖动幅度小，输出帧率低。
depth quality basic
depth quality medium
depth quality high
ToF Channel 调制频道
该功能用于设置 ToF 深度相机调制频道。不同调制频道的调制频率不同，互不干扰。
在 Depth Stream 处于 时，设置 tof channel，确保同一场景下同系列 ToF 相机的调制频道不同。
ToF Modulation Threshold 激光调制光强
该功能用于设置 ToF 深度相机接收激光调制光强的阈值，小于此阈值的像素点不参与计算深度，即像素点的深度值赋值为 0。
在 Depth Stream 处于 时，根据深度图实时调整 tof modulation threshold。
ToF Jitter Threshold 抖动过滤
该功能用于设置 ToF 深度相机的抖动过滤阈值。阈值设置值越大，深度图边缘抖动的深度数据过滤得越少。
在 Depth Stream 处于 时，根据深度图实时调整 tof jitter threshold，过滤边缘抖动的像素点。
Filter Threshold 飞点滤波
该功能用于设置 ToF 深度相机的飞点滤波阈值。滤波阈值设置越小，过滤的飞点越多。
在 Depth Stream 处于 时，根据深度图实时调整 filter threshold，过滤飞点。
HDR Ratio 高动态范围比
该功能用于优化高对比度场景的深度成像效果。ToF 系列中仅 TL460-S1-E1 支持 HDR Ratio 功能。
按照以下步骤，设置 HDR Ratio：
在所有数据流处于
时，点击 ，根据需求选择以下触发模式。Hardware Trigger Mode 硬触发模式
Software Trigger Mode (continue) 连续软触发模式
Software Trigger Mode (single) 单帧软触发模式
在 Depth Stream 处于
时，将 depth quality 设置为 high。在 Depth Stream 处于
时，根据深度图实时调整 HDR ratio。
ToF Anti-sunlight Index 抗阳光指数
该功能用于优化 ToF 相机在阳光下的深度成像效果。ToF 系列中仅 TM260-E2 支持 ToF Anti-sunlight Index 功能。
在所有数据流处于 时，调整 tof anti-sunlight index。
若在室内场景或阳光较弱时，建议将该指数设置为 0；在半室外场景或有一定阳光时，设置为 1；在室外场景或阳光强烈时，设置为 2。
PS 系列
以下是 PS 系列特有的图像调试功能，只有用 Percipio Viewer 打开了该系列的相机，才可在界面中设置。
Flash Light 泛光
该功能用于辅助相机在线动态标定。
在 Left IR Stream 和 Right IR Stream 处于 时，选中 flash light enable，并根据实际需求设置泛光灯亮度 flash light intensity。
设置泛光功能
HDR 高动态范围
该功能用于优化高对比度场景的深度成像效果，设置完 HDR 参数后需要调节 Left/Right IR 的曝光时间，以获得成像效果最佳的深度图。
按照以下步骤，设置 HDR 功能：
在 Left IR Stream 和 Right IR Stream 处于
时，选中 HDR，设置 参数 1 和 参数 2，并按 Enter 键确认设置。小技巧
参数 1 和参数 2 的设置范围 0，1，2。
设置参数1和参数2
设置 Left IR 和 Right IR 的曝光时间 exposure time，获得最佳的深度图。
使用 HDR 功能前后对比：
使用 HDR 功能前
使用 HDR 功能后
SGBM 参数
SGBM 参数用于调节相机的测距范围、精度、帧率以及深度图像后处理。部分相机支持 SGBM 参数。
在 Depth Stream 处于 时，展开 Depth Stream 的 Control 参数，根据深度图实时调整 SGBM 参数。
与测距范围、精度、帧率相关的 SGBM 参数
scale unit
设置深度图中像素值的单位。
深度数据可表示最大值 = 65536 * scale unit。
设定值越小，深度计算的精度越高，但设定值过小可能会导致深度计算出现误差。
disparity num
设置视差搜索范围。
设定值越大，相机 Z 方向的测量范围越大，但算力会增加。建议设置成 16 的整数倍。
disparity offset
设置开始搜索的视差值。
设定值越小，Z方向最大测量值（Zmax）越大，即测量范围越远，但设定值下限受景深影响。
match window height
设置视差匹配窗口的高。
设定值必须为奇数。
match window width
设置视差匹配窗口的宽。
设定值必须为奇数。
视差匹配窗口（match window height * match window width）越大，深度图更加平滑，但是精度会降低。视差匹配窗口越小，深度图显示更多细节，但是出现错误匹配的几率越大。
image number
设置用于深度计算的 IR 图像数量。
设定值越大，输出深度图像质量越好，帧率越小。
备注
受相机算力的影响，image number 和 match window height 之间存在一个约束，即 (image number+1) / 2 * match window height < 48。
与图像中边缘像素平滑处理相关的 SGBM 参数
semi global param p1
设置相邻像素 (+/-1) 约束惩罚参数 P1。
设定值越大，深度图越平滑。
防止出现不连续或不合理的深度值，有效抑制噪声和不连续性。
semi global param p1 scale
设置相邻像素 (+/-1) 约束惩罚参数 P1_scale。
设定值越小，深度图越平滑。
semi global param p2
设置周围像素约束惩罚参数 P2。
设定值越大，深度图越平滑。P2 > P1。
该参数可以有效地处理纹理丰富区域，减少误匹配的数量。
enable half window size
搜索滤波开关。
用于进一步优化深度图，去除噪声和不连续性，对物体边缘点云更友好。
与误匹配相关的 SGBM 参数
uniqueness factor param
设置唯一性检查参数 1，即最优匹配点与次优匹配点的百分比。
设定值越大，匹配代价越唯一，错误匹配点过滤掉的越多。
uniqueness min absolute diff
设置唯一性检查参数 2，即最优匹配点与次优匹配点差值的绝对值。
设定值越大，匹配代价越唯一，错误匹配点过滤掉的越多。
enable LRC
左右一致性检查开关。
开启 enable LRC 后，调节参数 max LRC diff。
在进行立体匹配时，对于同一物体表面上的像素，左图匹配右图的视差为 LR，右图匹配左图的视差为 RL。当 ABS(LR-RL) > max LRC diff 时，则认为该点是可信匹配点。
max LRC diff 设定值越小，匹配结果越可靠。
中值滤波
enable median filter
中值滤波开关。用于消除孤立的噪声点，同时尽可能地保留图像的边缘信息。
开启 enable median filter 后，调节参数 median filter thresh。
median filter thresh 设定值越大，过滤的噪点越多，但也可能会导致深度图的细节信息丢失。
常见问题
Percipio Viewer 支持哪些操作系统？
Percipio Viewer 支持以下操作系统：
Windows：7/10/11
Linux：Ubuntu 16.04/18.04/20.04
无法保存文件至 C 盘，怎么办？
问题描述
保存 2D 图、3D 图和录像文件至 C 盘时，出现报错。
报错信息
分析思路
电脑可能已开启了“勒索软件防护”，限制了部分应用程序对电脑上的文件、文件夹和内存区域进行未授权更改。
解决方法
在电脑上搜索 “ 勒索软件防护 ”，关闭 受控制文件夹的访问。
关闭受控制文件夹的访问