常见问题

安装、使用和性能相关的常见问题解答。

安装问题
使用问题
性能问题
分享与部署

安装问题

pip 安装失败，报错 "Microsoft Visual C++ 14.0 is required"

这是因为 open3d 需要编译。如果不需要读取 .pcd/.ply 文件，可以跳过 open3d：

pip install pyviz3d --no-deps # 跳过所有依赖 pip install numpy flask # 只装必要依赖

open3d 在 macOS Apple Silicon 上安装失败

Apple Silicon（M1/M2/M3）用户建议使用 conda 环境：

conda create -n pyviz3d python=3.11 -y conda activate pyviz3d pip install pyviz3d

如果 conda 也失败，参考上文的 --no-deps 方式，跳过 open3d 即可使用大部分功能。

Blender 集成检测不到

确保 Blender 已安装且在系统 PATH 中：

# 验证 Blender 命令是否可用 blender --version # 如果返回版本号，说明集成应该正常 python -c "from pyviz3d.blender_tools import blender_available; print(blender_available())"

使用问题

浏览器打不开 / 服务器没有自动启动

save() 启动的服务器默认地址是 http://localhost:8000。如果端口被占用，会自动尝试 8001~8010。如果浏览器没自动打开，手动访问对应端口即可。

# 指定端口 v = viz.Visualizer(server_port=9000) v.save("out", open_browser=False) # 禁止自动打开

颜色不显示，全部是白色

检查颜色数组的值范围，必须是 0~1（浮点数）而非 0~255。

# 错误：值范围 0-255 colors = np.random.randint(0, 256, (1000, 3)) # 正确：值范围 0-1 colors = np.random.rand(1000, 3) # 或转换 colors = colors_normalized / 255.0

多边形网格显示不正确

确保 faces 数组使用的是 0-based 索引，且每个面是有效的三角形。

# 验证 faces 索引范围是否正确 assert faces.max() < vertices.shape[0] - 1, "索引越界" assert faces.shape[1] == 3, "需要三角形面"

如何在 Jupyter Notebook 中使用？

PyViz3D 不支持直接在 Jupyter 中渲染，但可以在 Notebook 中调用 save() 或 publish()，然后在新标签页打开链接：

import pyviz3d as viz import numpy as np v = viz.Visualizer() v.add_points("cloud", np.random.rand(1000,3)*5, np.random.rand(1000,3)) url = v.save("nb_demo", open_browser=False) print("打开查看：", url)

性能问题

数百万点云加载很慢

几个优化建议：

使用 np.float32 而非 np.float64，内存占用减半
使用 normal_scale=0 关闭法向量计算
考虑降采样：points[::2] 每隔一个点采样
点云 > 1000 万点时建议用本地渲染（save），而非 publish

浏览器占用大量内存

WebGL 渲染大规模点云对显存要求较高。建议：

Chrome 比 Firefox 的 WebGL 性能更好
关闭其他浏览器标签页
使用高性能独显（NVIDIA/AMD），Chrome 中确认硬件加速已开启：chrome://settings/system

publish() 上传数据量限制是多少？

单次 publish 数据大小建议不超过 100MB（压缩前）。超大型点云请使用 save() 本地渲染。

如何生成永久分享链接？

使用 publish() 方法会自动生成以 session ID 标识的 URL，在服务器上保留 7 天。

url = v.publish("my_project") print(url) # https://3d.pointcloudviz.top/view/abc123

如何部署私有版本？

PyViz3D 服务器端基于 Flask，可自行部署：

# 克隆并启动 git clone https://github.com/francisengelmann/PyViz3D.git cd PyViz3D pip install -e . python pyviz3d/app.py

详细部署指南参考项目的 GitHub README。

如何嵌入到现有网页？

可以通过 iframe 嵌入 viewer 页面：