---

vedo是Python实现的一个用于辅助科学研究的3D可视化库。

vedo的visual子模块包含了管理对象及其属性的可视化和外观的基类。
其中VolumeVisual包含了体素对象Volume的可视化控制方法；
Actor2D是对vtkActor2D的封装，用于管理2D对象；
LightKit是一组光工具套件，用于控制3D场景中的光照效果。

参考：vedo官方文档

---

6. VolumeVisual

体素对象的可视化控制。

6.1 关于体素

像素是2D空间中不可分割的最小单位，而体素是像素在3D空间的扩展。体素不仅包含模型的表面信息，还包含模型的内部属性。

体素是量化为固定大小的可视化点云。点云可以在空间中任何位置有无数的点和浮点坐标，而体素具有固定的大小和整数坐标。
体素是规格化的，存储和解析都很方便。它不需要浮点运算，可以避免CPU浮点运算的瓶颈。

立体数据是3D空间中对物体的离散采样。3D笛卡尔标量表示立体数据的格式一般为(x, y, z, feature)，其中feature代表某个点的灰度或其它信息。
立体数据表示的是每个点的属性，无法可视化。为了使立体数据可视化，就以采样点为中心，把feature表示特征扩充到一个小立方体上，这个小立方体就表示体素。

创建体素对象：

# 创建10x10x10的矩阵
data_matrix = np.zeros([10, 10, 10], dtype=np.uint8)
# 从该矩阵创建体素对象
v = vedo.Volume(data_matrix)
# 体素对象的标量范围是[0. 0.]
print(v.scalar_range())
# 展示
vedo.show(v, axes=1)

后续使用的示例体素对象都用numpy的矩阵构建：

# 创建10x10x10的矩阵
data_matrix = np.zeros([10, 10, 10], dtype=np.uint8)
# 矩阵的值沿x坐标从0到9变化
for i in range(10):data_matrix[i:i+1, :, :] = i
v = vedo.Volume(data_matrix)
# 体素对象的标量范围是[0. 9.]
print(v.scalar_range())

6.2 显示效果

6.2.1 遮蔽

v.shade(status=None)
设置或获取体素对象的遮蔽状态，0为关闭，1为开启。默认是开启状态开启后图像显示的颜色会受背后体素的叠加。
遮蔽效果可以被volume.lighting()方法进一步控制。
启用遮蔽时，映射器会进行遮蔽计算。
有些情况下遮蔽不会应用。如在mode为1或2时。

# 从该矩阵创建体素对象
v1 = vedo.Volume(data_matrix).shade(0)
v2 = vedo.Volume(data_matrix).shade(1)
vedo.show([("shade=0", v1),("shade=0", v2),], axes=1, shape=(1, 2), size=(800, 400))

shade关闭和打开的效果。后面的一些示例为易于观察，显示时会关闭shade效果。

6.2.2 木纹或磨砂效果

v.jittering(status=None)
为真时，每个光线的途径方向都会用噪音纹理轻微干扰，以消除木纹效果。

# 消除木纹效果
v1 = vedo.Volume(data_matrix).jittering(True)
v2 = vedo.Volume(data_matrix).jittering(False)
vedo.show([(vedo.Text2D("jittering", s=2), v1),(vedo.Text2D("default", s=2), v2)], axes=1, shape=(1,2), size=(800, 400))

使用鼠标拖动时出现的木纹效果变为磨砂效果：

6.3 颜色和透明度

6.3.1 透明度衰减单位

v.alpha_unit(u=None)
定义每单位长度的光衰减量。默认值是1。
设置为0时，光不衰减，物体的任何位置都是完全不透明的。该值越大，渲染越趋于透明。

# 从该矩阵创建体素对象
v1 = vedo.Volume(data_matrix).cmap("r").alpha_unit(0)
v2 = vedo.Volume(data_matrix).cmap("r").alpha_unit(1)
v3 = vedo.Volume(data_matrix).cmap("r").alpha_unit(5)
vedo.show([("alpha_unit=0", v1),("alpha_unit=1", v2),("alpha_unit=5", v3),], axes=1, shape=(1, 3), size=(1200, 400))

6.3.2 划分透明度标量梯度

v.alpha_gradient(alpha_grad, vmin=None, vmax=None)
为沿着标量范围的体素梯度分配一系列的透明度。可以给单个常量值。
这个梯度函数用来减少体素的平坦区域的不透明性，不同类型的材料之间的界限的不透明性维持不变。
梯度是依据光强在单位距离上的变化量决定的。

alpha_grad的格式和传给函数volume.alpha()的格式一样。
填透明度序列时，如[0, 0.2, 1]，表示标量范围前半段的透明度从0到0.2变化，后半段从0.2到1变化。
填单个值时，表示设置统一的透明度。
也可以填二维的序列，如[(0, 0), (7, 0.2), (9, 1)]，表示标量值从0到7，透明度从0变到0.2，标量值从7到9，透明度从0.2变化到1。

沿用上面的体素对象，查看不同的alpha_grad值的效果：

6.3.3 设置颜色或渐变

v.cmap(c, alpha=None, vmin=None, vmax=None)
和CommonVisual.color()效果一样。
c可以填单个颜色或颜色映射。单个颜色必须使用colors.colors中给定的英文颜色名称或colors.color_nicks给出的颜色缩写。

使用不同的c值的效果：

6.3.4 标量的计算模式

v.mode(mode=None)
指定体素的渲染模式。可选的值如下：

基类CommonVisual的alpha方法可以通过输入二维序列来定义标量到实际透明度的转换方式。如alpha=[(-5, 0), (35, 0.4) (123,0.9)]，表示标量值在-5以下的都是透明的，标量值在35时，透明度为40%，标量值大于123时，透明度为90%。
0，composite。默认模式，标量值从体素中采样，并在渲染透明度时以从前到后的模式复合。取样的标量值经过alpha提供的转换方式，转为最终的颜色和透明度。
1，maximum projection。使用最大标量值渲染。该值会经过转换，成为颜色与透明度。
2，minimum projection。使用最小标量值。该值需要转换为颜色与透明度值。
3，average projection。标量值和透明度转换后的值相乘，然后累加，得到的结果再除以体素对象的样本数。结果图一般是灰度图。由于累加的值是计算值而不是取样方向上的真值，因此不会做转换。
4，additive mode。标量值和透明度转换的值相乘，然后累加。即标量值用给定的透明度来缩放，又相加来产生结果颜色。结果图一般是灰度图。

6.3.5 标量的插值方式

v.interpolation(itype)
设置标量的插值类型。0是最近邻插值，1是线性插值。

# 对上面的体素对象，使用不同的插值策略
v1 = vedo.Volume(data_matrix).shade(0).interpolation(0)
v2 = vedo.Volume(data_matrix).shade(0).interpolation(1)
vedo.show([("nearest neighbour", v1),("linear", v2),], axes=1, shape=(1, 2), size=(800, 400))

6.4 过滤

6.4.1 按单元格id隐藏单元格

v.hide_voxels(ids)
在可视化中隐藏体素单元格。填体素的单元格id列表。

data_matrix = np.zeros([100, 100, 100], dtype=np.uint8)
v1 = vedo.Volume(data_matrix).shade(0)
# 隐藏一半单元格
v1.hide_voxels(range(v1.ncells // 2))
v1.show()

6.4.2 按二进制矩阵设置隐藏

v.mask(data)
使用二进制值屏蔽体素的可视化。需指定volume.mapper = "gpu"。

from vedo import np, Volume, show
data_matrix = np.zeros([75, 75, 75], dtype=np.uint8)
# 设置值
data_matrix[ 0:35,  0:35,  0:35] = 1
data_matrix[35:55, 35:55, 35:55] = 2
data_matrix[55:74, 55:74, 55:74] = 3
vol = Volume(data_matrix).cmap('Blues')
vol.mapper = "gpu"
# 创建二进制矩阵，要显示的部分标记为1
data_mask = np.zeros_like(data_matrix)
data_mask[10:65, 10:60, 20:70] = 1
vol.mask(data_mask)
show(vol, axes=1).close()

这个方法使用后，一直显示失败，未找到调整方法。

---

7 Actor2D

管理2D对象。是对vtkActor2D的封装。
Actor2D封装的方法有的存在BUG，有的在子类中被重写。

7.1 可用的方法

t.mapper
获取内部的vtkMapper对象。

t.on()
使对象可见
t.off()
使对象不可见
t.toogle()
切换对象可见性

t.pickable(value=True)
设置对象的可选取性。

t.add_observer(event_name, func, priority=0)
为事件绑定回调函数。

t.layer(value=None)
设置或获取在多个渲染层中的图层编号。

t.coordiante_system(value=None)
设置或获取对象的坐标所在的坐标系。
value可选整型数值0到6：
0，Display。x、y取值为渲染窗口的像素值，坐标原点在窗口的左下角。
1，Normalized Display。和Display一样基于渲染窗口，不过x、y的取值范围为[0,1]。
2，Viewport。x、y的坐标值定义在视口或渲染器里。
3，Normalized Viewport。默认值。x、y的坐标值定义在视口或渲染器里，取值范围[0,1]。
4，View。x、y、z坐标值定义在相机所在的坐标系统里，取值范围[-1,1]，Z表示深度信息。
5，Pose。
6，World。x、y、z坐标值定义在世界坐标系统。世界坐标系是放置Actor的三维空间坐标系。

7.2 被子类重写的方法

t.pos(px=None, py=None)
设置或获取在屏幕坐标中的位置。
仅有的子类Text2D对这个方法做了重写。

t.color(value=None) c.c(value=None)
设置或获取对象颜色。
Text2D只能设置，不能获取颜色。

t.alpha(value=None)
设置或获取对象透明度。
Text2D只能设置，不能获取透明度。

7.3 存在错误的方法

t.ps(point_size=None)
设置构成对象的点的大小。

t.lw(line_width=None)
设置构成对象的线条的宽度。

t.ontop(value=True)
置顶或置底对象。

---

8. LightKit

光工具套件，包括3种光源，主光灯、补光灯、头灯。

8.1 关于灯光

主光灯一般是出现在头顶的光源(类似太阳、吊灯等)。它通常和垂直方向成45度夹角，会略微的左右偏移，向下照射。主光的亮度一般至少是其它光总亮度的两倍，以进行更好的对象特征建模。

套件中的其它光源是较弱的光源，可以提供额外的照明，补充主光源错过的点。

补光灯一般位于主光灯的对面(和相机都位于对象的同一侧)，用来模拟场景中其他对象的漫反射。照亮主光灯照不到的地方，同时维持对比度。

头灯总是位于相机位置，降低主光灯和补光灯照射的区域之间的对比度。

两个背光灯，一个位于观察者看到的对象左侧，一个位于右侧，填补了对象背后的高对比度区域。

为了加强不同灯光之间的联系，补光灯、背光灯和头灯的强度值被设置为与主光灯亮度的比率。因此场景中所有光源的亮度都能通过改变主光灯的强度来改变。

所有光都有方向，照射无限远并且不衰减。光会随着相机移动。

8.2 在显示时设置灯光

初始化参数LightKit(key=(), fill=(), back=(), head=(), maintain_luminance=False)
key、fill、back、head分别填主光、补光、背光和头光的控制参数，均为字典格式。
参数字典允许的键如下：
warmth，色温，范围[0,1]。0是蓝色冷光，1是红色热光，0.5是自然光。
intensity，主光光强。主光光强默认为1。
ratio，非主光的光强，填比例值。
elevation，灯位置上下提升的角度。
azimuth，灯位置的转动的角度。

灯光默认是关闭的，打开灯效：

s = vedo.Sphere()
lit = vedo.LightKit()
vedo.show(s, lit)

LightKit是单例的对象，每次窗口展示，即使分了不同的框，使用的仍然是同一个LightKit实例。
因此，上面的图是两次程序运行合并后的图。后续的灯光测试也都是多次运行合并的结果。

测试主光的不同参数的效果：

s = vedo.Sphere()
lit = vedo.LightKit(key={"warmth": 0})
vedo.show(s, lit)

不同色温：

不同elevation高度。默认灯光高度是45度左右。

不同azimuth转角：

c.update()
更新场景中的光照状态。

---

以上整理了visual的三个类VolumeVisual、Actor2D、LightKit的用法。

更多关于数据可视化的内容参考：Python数据可视化笔记