API 参考

PyViz3D 完整 API 文档。所有参数均为可选，位置参数数组格式为 NumPy ndarray。

Visualizer 类

可视化主入口。所有方法均返回实例本身，支持链式调用。

参数	类型	说明
name	str	浏览器窗口标题，默认为 "PyViz3D"
server_port	int	本地服务器端口，默认为 8000
window_size	tuple	(width, height)，设置画布像素尺寸

链式调用示例

add_points — 点云

参数	类型	说明
name	str	图层名称，用于控制面板标识
positions	np.ndarray (N,3)	N 个点的 xyz 坐标
colors	np.ndarray (N,3)	N 个点的 RGB 颜色，值范围 0~1
normals	np.ndarray (N,3)	可选，法向量用于 Phong 光照着色
normal_scale	float	法向量缩放，影响光照强度
point_size	float	点的像素大小，默认为 2
visible	bool	初始是否可见，默认为 True

add_mesh — 多边形网格

参数	类型	说明
name	str	图层名称
vertices	np.ndarray (V,3)	V 个顶点的 xyz 坐标
faces	np.ndarray (F,3)	F 个三角形的顶点索引（0-based）
colors	np.ndarray (3,) 或 (V,3)	RGB 颜色，单值则全局着色

add_boxes — 边界框

参数	类型	说明
positions	np.ndarray (N,3)	N 个框的中心点坐标
sizes	np.ndarray (N,3)	N 个框的 (width, height, depth)
colors	np.ndarray (N,3)	N 个框的颜色
rotations	np.ndarray (N,3)	绕 (x,y,z) 轴旋转角度（度），默认不旋转
alpha	float	透明度，0（完全透明）到 1（完全不透明）

add_arrows — 箭头

参数	类型	说明
positions	np.ndarray (N,3)	N 个箭头的起点坐标
vectors	np.ndarray (N,3)	N 个箭头的方向向量（决定方向和长度）
colors	np.ndarray (N,3)	N 个箭头的颜色

add_text — 标签

参数	类型	说明
text	str 或 list[str]	标签文字，列表则每个位置对应一条
positions	np.ndarray (N,3)	N 个标签的 3D 坐标
colors	np.ndarray (N,3)	N 个标签的文字颜色

add_polygon — 多段线

参数	类型	说明
vertices	np.ndarray (V,3)	按顺序排列的顶点数组，自动连接相邻点
colors	np.ndarray (3,)	线条 RGB 颜色
alpha	float	透明度（仅在闭合多边形时有填充效果）

add_superquadrics — 超二次曲面

参数	类型	说明
positions	np.ndarray (N,3)	N 个形状的中心位置
parameters	dict	参数字典，见下方说明

parameters 字典支持的键：

键	类型	说明
'epsilon'	list[2]	形状圆润度 [e1, e2]，越小越方
'size'	list[3]	各轴缩放 [sx, sy, sz]
'color'	list[3]	RGB 颜色
'taper'	list[2]	锥化系数 [tx, ty]，0~1
'bend'	float	弯曲系数
'wireframe'	bool	是否以线框模式渲染

add_motion_arrows — 运动箭头

与 add_arrows 参数相同，但多了两个控制箭头头部比例的参数：

参数	类型	说明
head_shaft_ratio	float	箭头头部占整体长度的比例，默认 0.9
head_width_ratio	float	箭头头部宽度与总长度的比，默认 0.3

相机控制

参数	类型	说明
position	list[3]	相机位置 [x, y, z]
look_at	list[3]	相机目标点 [x, y, z]
up	list[3]	世界空间中向上的方向向量

参数	类型	说明
mode	str	"circle"（圆形轨道）或 "spline"（贝塞尔样条）
radius	float	圆形轨道半径
height	float	相机高度
frames	int	动画总帧数
seconds	float	动画时长（秒）

输出方法