opencascade AIS_Manipulator源码学习

前言

AIS_Manipulator 是 OpenCASCADE 库中的一个类，用于在3D空间中对其他交互对象或一组对象进行局部变换。该类提供了直观的操控方式，使用户可以通过鼠标进行平移、缩放和旋转等操作。

详细功能

交互对象类，通过鼠标操控另一个交互对象或一组对象的局部变换。
它管理3D空间中的三种操作类型：

• 通过轴进行平移
• 轴内缩放
• 围绕轴旋转
  要启用这些模式之一，需要激活选择模式（从1到3）。
  操作器的位置信息定义了三个正交变换轴。可以为每个轴或所有轴禁用特定的变换模式。
  此外，每个轴可以被隐藏或显示。
  以下步骤演示了如何为交互对象附加、配置和使用操作器：
  步骤1. 创建操作器对象并调整其外观：

   Handle(AIS_Manipulator) aManipulator = new AIS_Manipulator();
  aManipulator->SetPart (0, AIS_Manipulator::Scaling, Standard_False);
  aManipulator->SetPart (1, AIS_Manipulator::Rotation, Standard_False);

// 将操作器附加到已显示的对象，并管理操作模式

 aManipulator->AttachToObject (anAISObject);
  aManipulator->EnableMode (AIS_Manipulator::Translation);
  aManipulator->EnableMode (AIS_Manipulator::Rotation);
  aManipulator->EnableMode (AIS_Manipulator::Scaling);

请注意，你可以只启用一种操作模式，但显示所有的可视部分。
这段代码允许你查看操作器并选择其操作部分。
请注意，操作器在部分选择时激活模式。
如果此模式已激活，则不会对操作器进行选择。
它可以通过高亮显示激活。启用此功能：

  aManipulator->SetModeActivationOnDetection (Standard_True);

步骤2. 在事件处理链中使用以下代码对对象进行变换：
// 捕捉鼠标按下事件

  if (aManipulator->HasActiveMode())
  {
    aManipulator->StartTransform (anXPix, anYPix, aV3dView);
  }

…
// 或者跟踪鼠标移动事件

  if (aManipulator->HasActiveMode())
  {
    aManipulator->Transform (anXPix, anYPix, aV3dView);
    aV3dView->Redraw();
  }

…
// 或者捕捉鼠标释放事件（应用）或逃逸事件（取消）

  aManipulator->StopTransform(/*Standard_Boolean toApply*/);

步骤3. 要停用当前操作模式使用：

  aManipulator->DeactivateCurrentMode();

步骤4. 要从对象上分离操作器使用：

  aManipulator->Detach();

最后一个方法会删除操作器对象。
AIS_Manipulator 是 OpenCASCADE 库中的一个类，用于在3D空间中对其他交互对象或一组对象进行局部变换。该类提供了直观的操控方式，使用户可以通过鼠标进行平移、缩放和旋转等操作。以下是 AIS_Manipulator 类的详细介绍：

主要功能

AIS_Manipulator 管理 3D 空间中的三种主要变换操作：

1. 平移：沿着指定的轴进行移动。
2. 缩放：沿着指定的轴进行缩放。
3. 旋转：围绕指定的轴进行旋转。

变换模式

要启用某种变换模式，需要激活对应的选择模式（从 1 到 3）。操作器的位置信息定义了三个正交变换轴。可以为每个轴或所有轴禁用特定的变换模式。此外，每个轴可以被隐藏或显示。

方法

使用步骤

步骤 1: 创建并配置操作器对象

Handle(AIS_Manipulator) aManipulator = new AIS_Manipulator();
aManipulator->SetPart (0, AIS_Manipulator::Scaling, Standard_False);
aManipulator->SetPart (1, AIS_Manipulator::Rotation, Standard_False);

步骤 2: 将操作器附加到对象并管理操作模式

aManipulator->AttachToObject (anAISObject);
aManipulator->EnableMode (AIS_Manipulator::Translation);
aManipulator->EnableMode (AIS_Manipulator::Rotation);
aManipulator->EnableMode (AIS_Manipulator::Scaling);

步骤 3: 启用检测时激活模式

aManipulator->SetModeActivationOnDetection (Standard_True);

步骤 4: 在事件处理链中使用操作器进行变换

// 捕捉鼠标按下事件
if (aManipulator->HasActiveMode())
{
  aManipulator->StartTransform (anXPix, anYPix, aV3dView);
}
// 跟踪鼠标移动事件
if (aManipulator->HasActiveMode())
{
  aManipulator->Transform (anXPix, anYPix, aV3dView);
  aV3dView->Redraw();
}
// 捕捉鼠标释放事件（应用）或逃逸事件（取消）
aManipulator->StopTransform(/*Standard_Boolean toApply*/);

步骤 5: 停用当前变换模式

aManipulator->DeactivateCurrentMode();

步骤 6: 从对象上分离操作器

aManipulator->Detach();

代码示例

下面是一个完整的示例，演示如何使用 AIS_Manipulator 来操控一个交互对象：

#include <AIS_Manipulator.hxx>
#include <AIS_Shape.hxx>
#include <V3d_View.hxx>
#include <Geom_CartesianPoint.hxx>
#include <TopoDS_Shape.hxx>
#include <BRepPrimAPI_MakeBox.hxx>

// 创建一个形状
TopoDS_Shape aBox = BRepPrimAPI_MakeBox(100, 100, 100).Shape();
Handle(AIS_Shape) anAISObject = new AIS_Shape(aBox);

// 创建并配置操作器
Handle(AIS_Manipulator) aManipulator = new AIS_Manipulator();
aManipulator->SetPart (0, AIS_Manipulator::Scaling, Standard_False);
aManipulator->SetPart (1, AIS_Manipulator::Rotation, Standard_False);

// 将操作器附加到对象并启用操作模式
aManipulator->AttachToObject(anAISObject);
aManipulator->EnableMode(AIS_Manipulator::Translation);
aManipulator->EnableMode(AIS_Manipulator::Rotation);
aManipulator->EnableMode(AIS_Manipulator::Scaling);

// 启用检测时激活模式
aManipulator->SetModeActivationOnDetection(Standard_True);

// 在事件处理中进行变换
// 捕捉鼠标按下事件
if (aManipulator->HasActiveMode())
{
  aManipulator->StartTransform(anXPix, anYPix, aV3dView);
}
// 跟踪鼠标移动事件
if (aManipulator->HasActiveMode())
{
  aManipulator->Transform(anXPix, anYPix, aV3dView);
  aV3dView->Redraw();
}
// 捕捉鼠标释放事件（应用）或逃逸事件（取消）
aManipulator->StopTransform(/*Standard_Boolean toApply*/);

// 停用当前变换模式
aManipulator->DeactivateCurrentMode();

// 从对象上分离操作器
aManipulator->Detach();

通过以上步骤和示例代码，用户可以在 OpenCASCADE 应用中使用 AIS_Manipulator 类来实现对三维对象的直观变换操作。

示例

1

构造一个具有默认位置并显示所有部分的操作器对象。
Standard_EXPORT AIS_Manipulator();

2

构造一个具有输入位置和轴位置并显示所有部分的操作器对象。
Standard_EXPORT AIS_Manipulator (const gp_Ax2& thePosition);

3

禁用或启用某个轴上的平移、旋转或缩放的可视部分。

3

默认情况下所有部分都是启用的（将显示）。
启用或禁用操作器的可视部分不会管理操作（选择）模式。
如果轴索引 < 0 或 > 2，则会引发程序错误。
Standard_EXPORT void SetPart (const Standard_Integer theAxisIndex, const AIS_ManipulatorMode theMode, const Standard_Boolean theIsEnabled);

4

禁用或启用所有轴上的平移、旋转或缩放的可视部分。
默认情况下所有部分都是启用的（将显示）。
启用或禁用操作器的可视部分不会管理操作（选择）模式。
如果轴索引 < 0 或 > 2，则会引发程序错误。
Standard_EXPORT void SetPart (const AIS_ManipulatorMode theMode, const Standard_Boolean theIsEnabled);

5

附加到输入的交互对象并在相同的上下文中显示。
它被放置在对象边界框的中心，其大小调整为对象边界框。
Standard_EXPORT void Attach (const Handle(AIS_InteractiveObject)& theObject, const OptionsForAttach& theOptions = OptionsForAttach());

6

附加到输入的交互对象组并在相同的上下文中显示。
它附加到第一个对象，但管理整个组的操作。
它被放置在对象边界框的中心，其大小调整为对象边界框。
Standard_EXPORT void Attach (const Handle(AIS_ManipulatorObjectSequence)& theObject, const OptionsForAttach& theOptions = OptionsForAttach());

7启用操作模式。

它在当前上下文中激活选择模式。
如果操作器未显示，则不会激活任何模式。
Standard_EXPORT void EnableMode (const AIS_ManipulatorMode theMode);

8

启用检测时激活模式（高亮显示）。
默认情况下，模式在选择操作器部分时激活。
如果启用此模式，选择部分将不起作用。
void SetModeActivationOnDetection (const Standard_Boolean theToEnable)

9

如果手动模式激活已启用，则返回 true。
Standard_Boolean IsModeActivationOnDetection() const

10

在查看器中拖动对象。

theCtx [in] 交互上下文

theView [in] 活动视图

heOwner [in] 检测到的实体所有者

theDragFrom [in] 拖动起点

theDragTo [in] 拖动终点

theAction [in] 拖动操作

如果对象拒绝拖动操作（例如 AIS_DragAction_Start），则返回 FALSE

Standard_EXPORT virtual Standard_Boolean ProcessDragging (const Handle(AIS_InteractiveContext)& theCtx,
const Handle(V3d_View)& theView,
const Handle(SelectMgr_EntityOwner)& theOwner,
const Graphic3d_Vec2i& theDragFrom,
const Graphic3d_Vec2i& theDragTo,
const AIS_DragAction theAction) Standard_OVERRIDE;

11

初始化起始（参考）变换。
它在链中与 StartTransform-Transform(gp_Trsf)-StopTransform 一起使用，
仅用于自定义变换集。如果使用 Transform(const Standard_Integer, const Standard_Integer)，
初始数据会自动设置，并在 DeactivateCurrentMode 调用时重置（如果尚未重置）。
Standard_EXPORT void StartTransform (const Standard_Integer theX, const Standard_Integer theY, const Handle(V3d_View)& theView);

12

将输入变换应用于拥有对象。
@remark 变换是使用 SetLocalTransformation 为拥有对象设置的。
操作器的位置也存储在本地变换中，因此无需重新显示对象。
它在链中与 StartTransform-Transform(gp_Trsf)-StopTransform 一起使用，
仅用于自定义变换集。
如果未初始化变换（通过 StartTransform() 调用），则不执行任何操作。
Standard_EXPORT void Transform (const gp_Trsf& aTrsf);

12

重置起始（参考）变换。

theToApply [in] 选择是否应用或取消已开始的变换。

它在链中与 StartTransform-Transform(gp_Trsf)-StopTransform 一起使用，

仅用于自定义变换集。

Standard_EXPORT void StopTransform (const Standard_Boolean theToApply = Standard_True);

13

应用从鼠标起始位置（在第一次 Transform() 调用时保存并在 DeactivateCurrentMode() 调用时重置）

14

到输入/输出鼠标位置（theX，theY）的变换。
Standard_EXPORT gp_Trsf Transform (const Standard_Integer theX, const Standard_Integer theY,
const Handle(V3d_View)& theView);

15

根据活动模式和输入运动矢量计算父对象的变换。
您可以使用此方法根据当前模式获取对象变换，或使用自己的算法为模式实现任何其他变换。
@return 父对象的变换。
Standard_EXPORT Standard_Boolean ObjectTransformation (const Standard_Integer theX, const Standard_Integer theY,
const Handle(V3d_View)& theView, gp_Trsf& theTrsf);

16

使当前选择的操作器部分变为非活动状态并重置当前轴索引和当前模式。
在调用后 HasActiveMode() 返回 false。
@sa HasActiveMode()
Standard_EXPORT void DeactivateCurrentMode();

17

从拥有对象中分离，并从上下文中移除自身。
Standard_EXPORT void Detach();

18

@return 所有拥有对象。
Standard_EXPORT Handle(AIS_ManipulatorObjectSequence) Objects() const;

19

@return 第一个（主导）拥有对象。
Standard_EXPORT Handle(AIS_InteractiveObject) Object() const;

20

@return 一个拥有对象。

21

@warning 如果 theIndex 大于拥有对象计数或小于 1，则引发程序错误。
Standard_EXPORT Handle(AIS_InteractiveObject) Object (const Standard_Integer theIndex) const;

22

@return 如果操作器附加到某个交互对象（有拥有对象），则返回 true。
Standard_Boolean IsAttached() const { return HasOwner(); }

23

@return 如果选择了操作器的某部分（变换模式处于活动状态，拥有对象可以变换），则返回 true。
Standard_Boolean HasActiveMode() const { return IsAttached() && myCurrentMode != AIS_MM_None; }

24

启用或禁用操作器的缩放持久模式。启用此模式后，演示将保持固定的屏幕大小。

启用此选项后，将覆盖变换持久性属性和局部变换以实现必要的视觉效果。

在启用缩放持久性时，修改 AttachToObjects 方法的 AdjustSize 参数的使用。

Standard_EXPORT void SetZoomPersistence (const Standard_Boolean theToEnable);

25

返回缩放持久模式的状态（启用或禁用）。
Standard_Boolean ZoomPersistence() const { return myIsZoomPersistentMode; }

26

返回缩放持久模式的状态（是否启用）。
Standard_Boolean ZoomPersistence() const { return myIsZoomPersistentMode; }

27

重新定义变换持久性管理以设置轴子演示的变换。

使用 ZoomPersistence 模式时，此交互对象不支持自定义变换持久性。在此模式下，此类会覆盖演示的变换持久性标志。

调试模式下，调用调试断言以捕获与 ZoomPersistence 模式的不兼容使用，在发布模式下默默无闻地不执行任何操作。

28

在启用缩放持久性时，重新考虑使用 AttachToObjects 方法中的 AdjustSize 参数。
Standard_EXPORT virtual void SetTransformPersistence (const Handle(Graphic3d_TransformPers)& theTrsfPers) Standard_OVERRIDE;

29

返回当前操作模式。
AIS_ManipulatorMode ActiveMode() const { return myCurrentMode; }

30

返回当前活动轴的索引。
Standard_Integer ActiveAxisIndex() const { return myCurrentIndex; }

31

返回操控器交互对象的位置。
const gp_Ax2& Position() const { return myPosition; }

32

设置操控器对象的位置。
Standard_EXPORT void SetPosition (const gp_Ax2& thePosition);

33

返回操控器的尺寸。
Standard_ShortReal Size() const { return myAxes[0].Size(); }

34

设置操控器立方体边界框的边长。
Standard_EXPORT void SetSize (const Standard_ShortReal theSideLength);

35

设置平移器、缩放器和旋转器子显示部分之间的间隔。
Standard_EXPORT void SetGap (const Standard_ShortReal theValue);

36

设置操控器执行变换动作的行为设置，无论它是否与被变换对象一起平移或旋转。
void SetTransformBehavior (const BehaviorOnTransform& theSettings) { myBehaviorOnTransform = theSettings; }

37

返回操控器变换动作的行为设置。
BehaviorOnTransform& ChangeTransformBehavior() { return myBehaviorOnTransform; }

38

返回操控器变换动作的行为设置。
const BehaviorOnTransform& TransformBehavior() const { return myBehaviorOnTransform; }

参考