9.标注、坐标轴、辅助渲染

第八部分：标注、坐标轴、辅助渲染

VTK本身三维几何只管面片、线、点；工程软件里的坐标轴、标尺、文字标注、颜色条、辅助网格，都属于场景辅助对象，不参与几何计算，只做视觉展示。 注意：这些辅助Actor和零件Actor是平级，都加到Renderer里面；不属于模型PolyData，不会被拾取当成零件。

1. 坐标轴 vtkAxesActor（世界坐标系）

作用：场景原点处显示X/Y/Z三色坐标轴：X红、Y绿、Z蓝。 常用于帮助用户分辨三维方向。

#include <vtkAxesActor.h>

vtkSmartPointer<vtkAxesActor> axes = vtkSmartPointer<vtkAxesActor>::New();
axes->SetTotalLength(50,50,50); //三轴长度
axes->SetShaftType(0);
axes->SetCylinderRadius(0.8);

renderer->AddActor(axes); //直接加到渲染器

⚠️坑：

1. 坐标轴大小是世界空间尺寸，如果你的零件尺寸很大/很小，坐标轴会看不见或者占满屏幕，需要调SetTotalLength。
2. vtkAxesActor继承vtkActor2D，不受普通Actor的变换矩阵控制；它永远显示世界原点。

小需求：角落迷你坐标轴（很多CAD软件右下角小坐标系）

vtkOrientationMarkerWidget，把坐标轴固定渲染在窗口右下角，不会跟随相机旋转缩放而跑掉。

#include <vtkOrientationMarkerWidget.h>

vtkSmartPointer<vtkOrientationMarkerWidget> markerWidget = vtkSmartPointer<vtkOrientationMarkerWidget>::New();
markerWidget->SetOrientationMarker(axes);
markerWidget->SetInteractor(interactor);
markerWidget->SetViewport(0.8,0.0,1.0,0.2); //窗口右下角[xmin,ymin,xmax,ymax]
markerWidget->SetEnabled(true);
markerWidget->InteractiveOff(); //关闭鼠标拖拽坐标轴

工业软件几乎都用这个，右下角固定方位坐标轴，非常常用。

2. 文字标注 vtkTextActor3D（三维空间文字）

三维文字：文字贴在三维世界某个坐标点，模型旋转，文字跟着一起旋转。 适合给零件上某个位置打上尺寸标签、ID标记。

#include <vtkTextActor3D.h>

vtkSmartPointer<vtkTextActor3D> text3d = vtkSmartPointer<vtkTextActor3D>::New();
text3d->SetInput("标记点A");
text3d->SetPosition(10,20,0); //三维世界坐标
text3d->GetTextProperty()->SetFontSize(14);
text3d->GetTextProperty()->SetColor(1,1,0); //黄色

renderer->AddActor(text3d);

还有一种：vtkTextActor，屏幕2D文字，固定在窗口像素位置，不会跟着模型旋转，适合做UI提示、状态栏文字。

#include <vtkTextActor.h>
vtkSmartPointer<vtkTextActor> screenText = vtkSmartPointer<vtkTextActor>::New();
screenText->SetInput("屏幕提示文字");
screenText->SetPosition(10,10); //屏幕像素坐标
screenText->GetTextProperty()->SetColor(1,1,1);
renderer->AddActor2D(screenText);

区分记忆

• vtkTextActor3D：三维空间文字，随模型旋转缩放；用于零件标注。
• vtkTextActor：屏幕2D文字，固定窗口位置；用于UI提示。

3. 参考网格（地面网格 vtkGridActor）

给场景增加XY平面辅助网格，像CAD软件的工作平面栅格。

VTK没有直接叫GridActor，用vtkPlaneSource生成平面 + vtkExtractEdges提取边线，只渲染网格线，不渲染面片。

#include <vtkPlaneSource.h>
#include <vtkExtractEdges.h>
#include <vtkPolyDataMapper.h>
#include <vtkActor.h>

//生成平面
vtkSmartPointer<vtkPlaneSource> gridPlane = vtkSmartPointer<vtkPlaneSource>::New();
gridPlane->SetOrigin(-100,-100,0);
gridPlane->SetPoint1(200,0,0);
gridPlane->SetPoint2(0,200,0);
gridPlane->SetXResolution(20);
gridPlane->SetYResolution(20);
gridPlane->Update();

//提取边线，只保留网格线
vtkSmartPointer<vtkExtractEdges> edgeFilter = vtkSmartPointer<vtkExtractEdges>::New();
edgeFilter->SetInputData(gridPlane->GetOutput());
edgeFilter->Update();

vtkSmartPointer<vtkPolyDataMapper> gridMapper = vtkSmartPointer<vtkPolyDataMapper>::New();
gridMapper->SetInputData(edgeFilter->GetOutput());

vtkSmartPointer<vtkActor> gridActor = vtkSmartPointer<vtkActor>::New();
gridActor->SetMapper(gridMapper);
gridActor->GetProperty()->SetColor(0.4,0.4,0.4);
gridActor->GetProperty()->SetOpacity(0.4); //半透明

renderer->AddActor(gridActor);

4. 标尺/测量标注（vtkDistanceWidget）

交互式测量两点距离，鼠标点两个点，自动生成线段+距离文字。 属于Widget系列，Widget = 交互组件，不止渲染，还接收鼠标交互。

#include <vtkDistanceWidget.h>
#include <vtkDistanceRepresentation.h>

vtkSmartPointer<vtkDistanceWidget> distanceWidget = vtkSmartPointer<vtkDistanceWidget>::New();
distanceWidget->SetInteractor(interactor);
distanceWidget->CreateDefaultRepresentation();

auto* rep = static_cast<vtkDistanceRepresentation*>(distanceWidget->GetRepresentation());
rep->SetLabelFormat("%.3f mm"); //格式化距离文字
distanceWidget->SetEnabled(true);

Widget系列特点：直接绑定interactor，自带鼠标交互，不需要自己写Pick回调。 类似还有角度测量vtkAngleWidget。

⚠️工程注意：

• vtkDistanceWidget算出来的距离，是三角网格上的三维空间距离；
• 如果要做CAD级精确测量，不能用这个结果，只是视图预览；真正尺寸计算交给OCCT对BRep做。

和前面Clip同一个道理：VTK Widget测量值是视图层的，业务真值交给OCCT。

5. 颜色标尺（ColorBar，云图色条 vtkScalarBarActor）

仿真应力云图旁边的颜色图例条，后面讲属性数组云图会大量用到。

#include <vtkScalarBarActor.h>

vtkSmartPointer<vtkScalarBarActor> scalarBar = vtkSmartPointer<vtkScalarBarActor>::New();
scalarBar->SetTitle("应力 MPa");
scalarBar->SetNumberOfLabels(6);
scalarBar->SetPosition(0.85,0.1); //归一化窗口坐标0~1
scalarBar->SetPosition2(0.1,0.8);

renderer->AddActor2D(scalarBar);

Actor / Actor2D / Widget 概念区分（非常容易混淆）

1. vtkActor：三维Actor，跟随相机旋转缩放，用于零件、网格、地面网格。
2. vtkActor2D：屏幕空间，窗口坐标，不受相机影响；屏幕文字、颜色条。
3. vtkWidget（OrientationMarkerWidget、DistanceWidget）：交互组件，自带渲染+鼠标事件，绑定interactor。

注意：AddActor()加三维对象；AddActor2D()加2D屏幕对象，不要混用。

工业软件常见坑

1. vtkAxesActor大小是世界坐标，模型尺寸变化坐标轴看不见，需要动态适配长度。
2. 三维文字vtkTextActor3D字体分辨率低，远距离会糊；CAD软件真正标注很多会自己做2D屏幕贴标签。
3. vtkDistanceWidget、vtkAngleWidget测量结果仅视图预览，不要拿这个数值作为业务计算结果，不要保存到文件，精确测量回退OCCT。
4. 辅助Actor会被拾取器拾取到；如果不想坐标轴、网格被点击选中，需要在拾取时过滤掉这些Actor。

//拾取的时候判断，如果是辅助Actor，直接跳过
if(picker->GetActor() == axes.Get())
{
    //命中辅助对象，忽略
}

本节小结

1. vtkAxesActor + vtkOrientationMarkerWidget：右下角固定方位坐标轴，工业软件标配。
2. vtkTextActor3D三维文字；vtkTextActor屏幕2D文字，按需选择。
3. 辅助网格：PlaneSource + ExtractEdges，生成栅格。
4. Widget组件：DistanceWidget、AngleWidget，交互式测量，仅视图预览。
5. ScalarBarActor：云图颜色图例条。
6. 所有辅助渲染对象，都只是视觉效果，不参与CAD业务计算。

---