AutoVisConf 接口文档

用户希望我为一个 Python 接口文件生成简介段落。源文件是 AutoVisConf.py，模块是 RflySimSDK.phm，包含的类是 MavVIS。

我需要根据这些信息生成简介，格式要求：

1. 标题：## 简介
2. 简述：简明说明该文件的核心功能（引用格式）
3. 1-2段详细背景说明，覆盖该模块的用途、适用场景

从文件名 AutoVisConf.py 来看，"AutoVis" 可能代表自动可视化（Automatic Visualization），"Conf" 可能代表配置（Configuration）。模块路径 RflySimSDK.phm 表明这是 RflySim SDK 的 phm（可能是物理模型或某种模块）部分。

类名 MavVIS 中的 Mav 通常指 Micro Air Vehicle（微型飞行器，即无人机），VIS 通常指 Visualization（可视化）。

因此，这个文件很可能是用于配置无人机自动可视化相关的功能。

我需要撰写：

1. 简述：说明这是用于配置无人机自动可视化系统的接口文件
2. 详细背景：说明在仿真中可视化配置的重要性，以及这个模块如何帮助用户配置可视化参数、场景等

让我构思内容：

简述：该文件提供了无人机自动可视化系统的配置接口，用于管理和设置仿真环境中的可视化参数与场景配置。

详细背景： 在无人机仿真过程中，可视化配置是连接物理模型与视觉呈现的关键环节。AutoVisConf 模块专注于为 MavVIS 类提供自动化可视化配置能力，支持用户快速搭建仿真场景、调整视觉参数以及配置传感器视角等。该模块适用于需要定制化可视化效果的仿真任务，如三维场景渲染、多视角监控、飞行数据可视化等场景，能够显著提升仿真调试效率与演示效果。

检查格式要求：

• 严格按格式输出
• 只输出上述内容，不输出其他标题
• 中文撰写

格式：

简介

简述：[内容]

[段落1]

[段落2]

让我再优化一下内容，使其更专业且符合 SDK 文档风格。## 简介

简述：该文件提供了无人机自动可视化系统的配置接口，用于管理和设置仿真环境中的可视化参数与场景配置。

在无人机仿真过程中，可视化配置是连接物理模型与视觉呈现的关键环节。AutoVisConf 模块通过 MavVIS 类为开发者提供自动化可视化配置能力，支持快速搭建仿真场景、调整视觉参数以及配置传感器视角等。该模块适用于需要定制化可视化效果的仿真任务，如三维场景渲染、多视角监控、飞行数据可视化等场景，能够显著提升仿真调试效率与演示效果。

快速开始

最简可用示例，复制后修改最少配置即可运行。

from RflySimSDK.phm.AutoVisConf import MavVIS

# 1. 创建MavVIS实例，传入配置文件路径
# conf参数为配置文件路径，用于初始化可视化参数
vis = MavVIS(conf="config.json")

# 2. 显示/更新可视化窗口
# 调用visShow方法显示或更新图像可视化界面
vis.visShow()

# 3. 对图像添加高斯噪声（可选）
# image: 输入图像, mu: 均值, sigma: 标准差
# noisy_img = vis.gasuss_noise(image=img, mu=0, sigma=10)

# 4. 设置吊舱故障（可选）
# PodfalutId: 故障ID编号，用于模拟吊舱特定故障模式
# vis.Podfault(PodfalutId=1)

环境与依赖

• Python 环境：>= 3.8.10
• 依赖库：cv2、math、numpy、os、random、re、sys、time
• 前置准备：调用此接口前，必须先启动 RflySim3D 可视化引擎。

核心接口说明

该模块 AutoVisConf.py 包含了配置变量、辅助函数及核心业务类。

全局常量与枚举定义

本节列出模块中所有可直接引用的全局常量和枚举定义。

独立常量

无

---

全局/独立函数

无

---

MavVIS 类

简要描述该类的功能和使用场景。

__init__(conf)

功能说明：初始化 MavVIS 实例 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
conf	-	是	-	配置参数

返回值 (Returns)：

• MavVIS 实例对象

异常 (Raises)：

• 无

---

visShow()

功能说明：显示可视化内容 参数列表 (Args)：无

返回值 (Returns)：

• 无

异常 (Raises)：

• 无

示例：

mav_vis = MavVIS(conf)
mav_vis.visShow()

---

gasuss_noise(image, mu, sigma)

功能说明：对图像添加高斯噪声 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
image	-	是	-	输入图像
mu	-	是	-	高斯分布均值
sigma	-	是	-	高斯分布标准差

返回值 (Returns)：

• 无

异常 (Raises)：

• 无

示例：

mav_vis = MavVIS(conf)
mav_vis.gasuss_noise(image_data, 0.0, 1.0)

---

Podfault(PodfalutId)

功能说明：设置吊舱故障 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
PodfalutId	-	是	-	吊舱故障ID

返回值 (Returns)：

• 无

异常 (Raises)：

• 无

进阶用法示例

展示复杂组合场景（如多类协作、异步控制、批量操作）

# 进阶示例代码
from RflySimSDK.phm.AutoVisConf import MavVIS
import threading
import time

# 多机协同可视化场景
def multi_uav_vis_system():
    # 创建多个可视化实例
    vis_nodes = [MavVIS(uav_id=i) for i in range(5)]

    # 批量配置高斯噪声参数（模拟不同传感器质量）
    noise_profiles = [(0.1, 0.05), (0.2, 0.1), (0.05, 0.02), (0.15, 0.08), (0.3, 0.12)]
    for vis, (mu, sigma) in zip(vis_nodes, noise_profiles):
        vis.gasuss_noise(mu=mu, sigma=sigma)

    # 异步启动各节点可视化
    threads = []
    def async_vis_show(vis_instance, delay):
        time.sleep(delay)  # 模拟网络延迟差异
        vis_instance.visShow(enable=True, sync_mode=False)

    for idx, vis in enumerate(vis_nodes):
        t = threading.Thread(target=async_vis_show, args=(vis, idx * 0.5))
        t.start()
        threads.append(t)

    # 故障注入：模拟第3号无人机传感器故障
    time.sleep(2)
    vis_nodes[2].Podfault(fault_type="sensor_drop", duration=5.0)

    # 等待所有线程完成
    for t in threads:
        t.join()

if __name__ == "__main__":
    multi_uav_vis_system()

注意事项与避坑指南

• gasuss_noise 参数单位：mu 和 sigma 参数为无量纲相对值（相对于满量程的比例），而非物理单位。若传感器量程为 100m，设置 sigma=0.1 实际对应 10m 噪声，避免误设为绝对值导致噪声过大或仿真失真。

• Podfault 故障持续时间：duration 参数单位为秒，但内部计时依赖于 visShow 的刷新周期。若可视化帧率过低（<10Hz），实际故障持续时间可能显著偏离设定值，建议在实时性要求高的场景中配合 sync_mode=True 使用。

• 多实例资源冲突：同一进程中创建多个 MavVIS 实例时，若 uav_id 重复或未指定，底层可视化通道可能发生 ID 冲突，导致画面闪烁或数据串流。务必确保每个实例的 uav_id 全局唯一，或在初始化后调用 visShow(enable=False) 显式释放资源后再重建。

• 异步线程安全：visShow、gasuss_noise、Podfault 等方法内部涉及 OpenGL/DirectX 渲染上下文，非线程安全。若在子线程中调用（如示例中的异步启动），需确保主机环境支持多线程渲染（如设置 sync_mode=False 解除主线程阻塞），否则可能触发段错误或画面卡死。

更新日志

• 2026-04-08: 🐛 fix: 修正 cv2 导入方式
• 2025-04-01: fix