Web 可视化器与 Jupyter

简介

Open3D 的 web 可视化器（web visualizer）能够在现代浏览器中实现高级的 3D 模型渲染与可视化。你首先在本地或远程机器上启动可视化服务器，然后就可以从任何装有现代浏览器的设备查看 3D 模型。web 可视化器的服务器与客户端之间通过 WebRTC（Web Real-Time Communication，网页实时通信）协议进行通信。

在本教程中，我们将介绍两种常见用法：

独立模式（Standalone mode）：将 Open3D web 可视化器服务器作为独立应用运行，并在浏览器中查看 3D 模型。它同时支持 C++ 和 Python。只需在代码中添加一行即可启用该服务器。
Jupyter 模式（Jupyter mode）：将 Open3D web 可视化器作为嵌入式 Jupyter 单元运行。它同时支持 Python Jupyter notebook 和 Jupyter lab 环境。你需要修改代码以使用非阻塞 API 和相应的封装函数。

截至当前版本，Open3D web 可视化器在以下平台上受到支持：

平台	Ubuntu	macOS	Windows
独立模式服务器（C++/Python）	是	是	是
Jupyter 模式服务器（Python）	是	否	是
独立/Jupyter 模式客户端（web 浏览器）	是	是	是

关于兼容性的补充说明：

在 Ubuntu 上，web 可视化器服务器运行在 EGL 之上。只要机器具备图形能力（集显或独显即可），大多数机器都能支持。如果 CPU 不带集显，则需要一块独显。例如，AWS 云实例通常使用不带集显的 Intel XEON 处理器，你需要为实例添加独显并安装显卡驱动才能启用 web 可视化器。
web 可视化器服务器目前尚不支持 ARM 平台。要让 web 可视化器在 ARM 上工作，你需要为 ARM 从源码编译 WebRTC 库。详见 3rdparty/webrtc 文件夹。
不支持 Google Colab 和 Kaggle notebook。你需要运行自己的 Jupyter 或 JupyterLab 服务器。
如果你更喜欢使用原生窗口（阻塞式调用）而不是 Jupyter 单元中的嵌入式图形，可以在导入 Open3D 之前设置环境变量 OPEN3D_DISABLE_WEB_VISUALIZER=true。

独立模式

在独立模式下，Open3D web 可视化器服务器作为独立应用运行。它同时支持 C++ 和 Python。只需对代码做极少的改动即可启用该服务器。

C++ 服务器

确保在 CMake 配置步骤中设置了 -DBUILD_GUI=ON 和 -DBUILD_WEBRTC=ON（默认即为 ON）。在你的 C++ 代码中，通过调用以下函数来启用 WebRTC 服务器后端：

open3d::visualization::webrtc_server::WebRTCWindowSystem::GetInstance()->EnableWebRTC();

示例：

mkdir build && cd build
cmake ..
make DrawWebRTC -j$(nproc)
cd bin/example
./DrawWebRTC
google-chrome http://localhost:8888  # Or, open the address in your browser

完整源代码见 examples/cpp/DrawWebRTC.cpp。

Python 服务器

在你的 Python 代码中，通过调用以下函数来启用 WebRTC 服务器后端：

import open3d as o3d
o3d.visualization.webrtc_server.enable_webrtc()

示例：

python examples/python/visualization/draw_webrtc.py
google-chrome http://localhost:8888  # Or, open the address in your browser

完整源代码见 examples/python/visualization/draw_webrtc.py。

IP/端口绑定

与其他 web 服务器类似，Open3D web 可视化器服务器允许绑定自定义的 IP 地址和端口。这在搭建远程服务器时通常是必需的。

要设置自定义 IP 地址，请设置 WEBRTC_IP 环境变量。要设置自定义端口号，请设置 WEBRTC_PORT 环境变量。例如：

# Bind to localhost:8888 (default)
python examples/python/visualization/draw_webrtc.py

# Bind to 127.0.0.1:8889
WEBRTC_IP=127.0.0.1 WEBRTC_PORT=8889 python draw_webrtc.py

要启用远程可视化，我们通常会绑定服务器所看到的内部 IP 和内部端口。路由器可能会将内部 IP 和内部端口转换为外部 IP 和端口。例如，在 Google 云上，我们可以获取该实例的内部 IP 和外部 IP，然后将 WEBRTC_IP 和 WEBRTC_PORT 设置为内部 IP 和端口，在防火墙规则中开放相应端口，并启用 HTTP 流量。最后，我们启动 web 可视化器服务器，并从浏览器访问外部 IP 地址。

Jupyter 模式

使用以下命令安装 Jupyter：

pip install jupyter
jupyter notebook

或者，你也可以安装 JupyterLab：

pip install jupyterlab
jupyter-lab

然后运行示例 notebook docs/jupyter/visualization/jupyter_visualization.ipynb。与独立模式不同，Jupyter 模式下不使用 WEBRTC_IP 和 WEBRTC_PORT。不过，你可能需要为 Jupyter 指定 IP 和端口。

非阻塞函数

在 Jupyter 模式下，我们需要避免阻塞式的可视化 API 调用。否则，在一个单元中运行可视化会阻塞下一个单元的执行。我们提供了 Jupyter 专用的辅助函数来实现非阻塞可视化。例如，在上面的示例 notebook 中，使用 open3d.web_visualizer.draw 来代替常规的 open3d.visualization.draw。除了 draw 之外，你还可以借助 _AsyncEventLoop 类创建自己的非阻塞可视化辅助函数。以 python/open3d/web_visualizer.py 中的 _AsyncEventLoop 类以及 open3d.web_visualizer.draw 的实现为例进行参考。

从源码构建 Jupyter 包

Open3D 官方 Python wheel 已附带 Jupyter web 可视化器支持。若要从源码构建带 Jupyter web 可视化器的 Open3D Python 包，你需要：

安装 npm 和 yarn。例如，可以通过包管理器安装 npm，再用 npm install -g yarn 安装 yarn。确保它们能够在终端中被调用。
安装 Jupyter 构建依赖：

pip install -r python/requirements_jupyter_build.txt

构建 Open3D Python 包：

mkdir build && cd build
cmake -DBUILD_JUPYTER_EXTENSION ..
make install-pip-package -j$(nproc)

进阶主题：飞行模式下的本地服务器

当计算机没有任何活动的网络接口时（例如关闭了 Wi-Fi 且拔掉了网线，机器只有 loopback lo 接口），WebRTC 可能无法工作。在这种情况下，我们需要创建一个虚拟接口。该变通方法已在 Ubuntu 上测试过。

# Setup
sudo ip link add dummy0 type dummy
sudo ip addr add 1.1.1.1/24 dev dummy0
sudo ip link set dummy0 up

# Check interfaces
ip addr

# Do WebRTC things here
python examples/python/visualization/draw_webrtc.py
google-chrome http://localhost:8888  # Or, open the address in your browser

# Clean up
sudo ip link set dummy0 down
sudo ip link delete dummy0

进阶主题：TURN 服务器

WebRTC 的 ICE（Interactive Connectivity Establishment，交互式连接建立）框架通过 STUN 或 TURN 服务器来解析客户端与服务器的连接。在大多数场景下，一个 STUN 服务器就足以确定流量路由。在某些网络配置下（例如位于 NAT 或防火墙之后），则需要 TURN 服务器来转发 WebRTC 流量。你可以通过设置 WEBRTC_STUN_SERVER 环境变量来添加自定义的 TURN 服务器（视频流量中继）。如果有多个 TURN 服务器，用 ; 分隔。例如：

# UDP only
WEBRTC_STUN_SERVER="turn:user:password@my_turn_server.com:3478"
# TCP only
WEBRTC_STUN_SERVER="turn:user:password@my_tcp_turn_server.com:3478?transport=tcp"
# UDP and TCP (more than one TURN servers)
WEBRTC_STUN_SERVER="turn:user:password@my_turn_server.com:3478;turn:user:password@my_tcp_turn_server.com:3478?transport=tcp"

进阶主题：调试网络问题

在某些特定的网络配置下（例如 NAT、网络代理、VPN 配置），你可能会遇到连接失败、卡顿或可视化质量低下等问题。以下是一些调试网络问题的思路：

在尝试托管远程服务器之前，先确保 localhost 能正常工作。在尝试 Jupyter 模式之前，先确保独立模式能正常工作。
在 https://test.webrtc.org/ 上测试客户端和服务器机器的连通性和吞吐量。
如果遇到控制卡顿，尝试从 TCP 切换到 UDP 连接，或者切换到距离更近的 TURN（视频流量中继）服务器。
如果可视化视频出现压缩伪影，可能是你所使用的 TURN 服务器带宽不足。尝试切换到带宽更高或距离你位置更近的 TURN 服务器。