VTK 入门系列之二：为三维场景添加坐标轴

一、引言

在进行三维可视化开发时，我们常常希望能够清晰了解模型在空间中的位置、方向与比例关系。而最直观的辅助工具就是三维坐标轴（Axes）。在 VTK 中，vtkAxesActor 提供了一种开箱即用的方式来将 X、Y、Z 三个方向的坐标轴渲染到场景中，增强空间感知。

本篇我们将通过一个完整的 C++ 示例，逐步分析如何使用 VTK 构建一个包含：

• 一个球体模型；
• 一组平移后的三维坐标轴；
• 基本的摄像机旋转与视图设置；
  
  的基础渲染场景。

---

二、工程代码一览

以下是完整的 C++ 示例代码，使用 VTK 官方推荐的 vtkNew<> 智能指针风格：

#include <vtkActor.h>
#include <vtkAxesActor.h>
#include <vtkCamera.h>
#include <vtkCaptionActor2D.h>
#include <vtkNamedColors.h>
#include <vtkNew.h>
#include <vtkPolyDataMapper.h>
#include <vtkRenderWindow.h>
#include <vtkRenderWindowInteractor.h>
#include <vtkRenderer.h>
#include <vtkSphereSource.h>
#include <vtkTextProperty.h>
#include <vtkTransform.h>

主函数部分：

int main()
{
    // 1. 配色工具
    vtkNew<vtkNamedColors> colors;

    // 2. 球体模型源
    vtkNew<vtkSphereSource> sphereSource;
    sphereSource->SetRadius(0.5);
    sphereSource->SetCenter(0.0, 0.0, 0.0);

    // 3. 几何映射器
    vtkNew<vtkPolyDataMapper> sphereMapper;
    sphereMapper->SetInputConnection(sphereSource->GetOutputPort());

    // 4. 渲染实体（Actor）
    vtkNew<vtkActor> sphereActor;
    sphereActor->SetMapper(sphereMapper);

    // 5. 渲染器设置
    vtkNew<vtkRenderer> renderer;

    // 6. 渲染窗口
    vtkNew<vtkRenderWindow> renderWindow;
    renderWindow->SetWindowName("Axes");
    renderWindow->AddRenderer(renderer);
    renderWindow->SetSize(600, 600);

    // 7. 交互器
    vtkNew<vtkRenderWindowInteractor> renderWindowInteractor;
    renderWindowInteractor->SetRenderWindow(renderWindow);

    // 8. 添加球体到场景
    renderer->AddActor(sphereActor);
    renderer->SetBackground(colors->GetColor3d("CadetBlue").GetData());

    // 9. 添加三维坐标轴 + 位移
    vtkNew<vtkTransform> transform;
    transform->Translate(1.0, 0.0, 0.0);  // 坐标轴右移 1 个单位

    vtkNew<vtkAxesActor> axes;
    axes->SetUserTransform(transform);  // 应用变换
    renderer->AddActor(axes);

    // 10. 调整相机角度
    renderer->GetActiveCamera()->Azimuth(50);
    renderer->GetActiveCamera()->Elevation(-30);
    renderer->ResetCamera();

    // 11. 启动渲染
    renderWindow->Render();
    renderWindowInteractor->Start();

    return 0;
}

---

三、关键组件详解

1️⃣ vtkSphereSource：几何体数据源

vtkSphereSource 用于生成球体模型，它是 VTK 所有可视化的起点之一，输出一个标准的 vtkPolyData 数据集。

• SetRadius(double) 设置球的半径；
• SetCenter(x, y, z) 设置球心位置。

sphereSource->SetRadius(0.5);
sphereSource->SetCenter(0.0, 0.0, 0.0);

---

2️⃣ vtkAxesActor：三维坐标轴

vtkAxesActor 是 VTK 中专门用于展示三维坐标轴的 Actor，它默认显示：

• 红色 X 轴、绿色 Y 轴、蓝色 Z 轴；
• 带箭头；
• 自动加粗与缩放；
• 显示 X/Y/Z 标签。

vtkNew<vtkAxesActor> axes;
axes->SetUserTransform(transform); // 应用平移变换

如果不使用 SetUserTransform()，坐标轴将默认出现在场景原点。

可选配置项包括：

axes->SetTotalLength(1.0, 1.0, 1.0);     // 设置轴长
axes->SetShaftTypeToCylinder();         // 轴样式：Cylinder / Line / Tube
axes->SetAxisLabels(1);                 // 是否显示 X/Y/Z 标签
axes->SetCylinderRadius(0.02);          // 粗细设置

---

3️⃣ vtkTransform：变换控制

VTK 中通过 vtkTransform 控制 Actor 的位置、旋转与缩放。它支持：

• 平移：Translate(x, y, z)
• 旋转：RotateX(angle) / RotateY(angle) / RotateZ(angle)
• 缩放：Scale(x, y, z)

这些变换可以用来控制 vtkAxesActor、vtkActor 等在场景中的最终位置。

---

4️⃣ 渲染管线简介

这是一个典型的 VTK 可视化管线结构：

[数据源] → [Mapper] → [Actor] → [Renderer] → [RenderWindow]

在本例中：

• vtkSphereSource 是数据源；
• vtkPolyDataMapper 负责几何数据 → 图元 → GPU；
• vtkActor 作为场景中的实体节点；
• vtkRenderer 管理场景和相机；
• vtkRenderWindow 是输出窗口；
• vtkRenderWindowInteractor 提供交互能力。

---

四、运行效果示意图（概念图）

你将在窗口中看到一个淡蓝背景下的球体和一组 RGB 三维坐标轴，坐标轴出现在球体右侧，并有箭头和字母标识方向。

---

五、进阶拓展建议

功能	类名	简介
显示多个模型	vtkAppendPolyData	合并多个几何对象
场景交互标尺	vtkOrientationMarkerWidget	显示一个固定角落坐标轴
精细轴控制	vtkAnnotatedCubeActor	创建可标注的方向方块
GUI 集成	Qt + VTK	可嵌入 Qt 窗口构建完整应用

---

六、总结

在本文中，我们构建了一个基础的 VTK 可视化程序，展示了以下核心技能：

• 使用 vtkSphereSource 构建几何体；
• 使用 vtkAxesActor 添加坐标轴辅助信息；
• 使用 vtkTransform 控制坐标轴位置；
• 使用摄像机控制展示角度；
• 构建完整的 VTK 渲染管线。

坐标轴是三维场景中不可或缺的空间参考工具，也是后续可视化操作（如配准、交互、测量）的基础。

---