这是基于 Qt for Python（以前称为 PySide2）的新 VRED Python API v2 的文档。药查看 VRED Python API v1 文档，请单击此处。

类型

新接口的某些函数将 Qt 类型用于参数或用作返回值类型。这些类型将自动导入到 Python 名称空间中，并且无需从 PySide2 模块导入即可使用。

可以导入其他 Qt 类，如下所示：

from PySide2.QtCore import QLine
from PySide2.QtGui import QBrush

line = QLine(0,0,100,100)
brush = QBrush()

对象

新接口中的场景对象源自 vrdObject。这些对象的类名称以前缀 vrd 开头，例如，对于节点对象，为 vrdNode；对于材质对象，为 vrdMaterial。

每当从 API 函数或方法返回这些对象时，会动态确定其类类型。这意味着，它们将是由文档指定的基类类型或后代类。例如，通过 vrMaterialService.findMaterial(Environments) 检索默认环境切换时，返回的对象将为 vrdEnvironmentSwitchMaterial 类型，而不是记录的基础类型 vrdMaterial。

因此，用户不需要向上转换返回的对象，因为它们已经显示了其最具体的类型。但是，在访问特定类型的方法或属性之前，用户应通过 vrdObject.isType() 检查所返回对象的类型，以防止出现运行时错误。例如，当用户想要访问由上面调用 findMaterial() 而返回的材质的 choice 属性时，应在调用 material.getChoice() 之前通过 material.isType(vrdSwitchMaterial) 检查材质类型。如果仅访问记录的基本类型的方法或属性，这当然是不必要的。

服务

虽然对象具有许多用于查询和更改属性的函数，但主入口点是通过服务获取要使用的对象。

使用服务查找现有场景对象、创建新对象、删除对象或访问相关 VRED 模块中可用的其他函数。

• 标注：vrAnnotationService
• 烘焙灯光和阴影：vrBakeService
• 摄影机编辑器：vrCameraService
• 群集：vrClusterService、vrClusterManagerService
• 灯光编辑器：vrLightService
• 材质编辑器：vrMaterialService
• 参照编辑器：vrReferenceService
• 场景板编辑器：vrSceneplateService
• Collaboration:vrSessionService
• 虚拟现实：vrDeviceService、vrImmersiveInteractionService、vrImmersiveUiService、vrHMDService
• Constraints: vrConstraintService
• UV：vrUVService
• 加载和保存文件：vrFileIOService

通过与服务类同名的对象调用服务函数。例如：

camNode = vrCameraService.createCamera("new camera")

函数调用

在 VRED API V2 中，只能在调用函数时将可选参数作为关键字参数（命名参数）传递。可选参数会连同其默认值一起显示在本文档的函数签名中。

所有必需参数必须作为位置参数传递，即，不具有其名称，且按照签名中指定的顺序。

例如，vrNodeService.findNode 有一个必需参数 ((name))，其余参数是可选的。这意味着，此函数调用可以正常工作（忽略第二个和第三个参数）：

trackNode = vrNodeService.findNode("track1", root=vrCameraService.getCameraRoot())

然而，此函数调用将出错：

trackNode = vrNodeService.findNode(name="track1", root=vrCameraService.getCameraRoot())

安装第三方模块

由于 VRED 已移至 Python 3，因此您可以轻松安装第三方模块。您可以在 lib/python 下的安装文件夹中找到完整的 Python 安装。您可以使用 pip 从官方 Python 存储库进行安装。如果要安装“numpy”，可以执行如下操作：

python.exe -m pip install numpy

Pip 独立于 Python 开发。如果要将 pip 升级到更高版本，请使用以下命令：

python.exe -m pip install --upgrade pip

如果包含的 pip 应停止工作，则可以使用 Python boostrap 机制恢复它：

python.exe -m ensurepip

您也可以手动将模块安装到 Lib/site-packages。如果要使用 Python API 编译自己的 C 或 C++ 扩展，请确保使用兼容的编译器。我们在不重新编译的情况下针对 VRED 使用官方 Python 3 二进制文件。因此，可以对 python.org 上的 Python 发行版进行编译且版本号与 VRED 附带的版本相同的任何内容都应该起作用。

通过 Web 界面使用 Python API

可以通过 Python 或 Web 界面使用此接口。通过 JavaScript 进行访问。异步执行函数调用。以下示例显示了如何从网页进行此类调用。所有参数和返回值类型都映射到 JavaScript 类型。例如，QVector3D 和 QMatrix4x4 将映射到由 3 或 16 个数字组成的数组。

<script type="module">
  import {api} from '/api.js';

  // reacting on a signal
  api.vrClusterService.started.connect(() => {console.log('Started')});
  // calling a function
  api.vrClusterService.start();
  // changing the position of the camera
  api.vrNodeService.findNode("Perspective")
      .then((node) => node.setTranslation([10,20,30]));
</script&gt>

一起使用 API v1 和 v2

可以在同一脚本中同时使用 API v1 和 API v2 中的函数。

在 API v1 中，节点对象类型为 vrNodePtr。您可以在 API v1 中以 vrNodePtr 作为参数的函数中使用 vrdNode 对象，反之亦然，可以在 API v2 中以 vrdNode 作为参数的函数中使用 vrNodePtr 对象。系统会自动转换它们。

可以将 vrdNode 显式转换为 vrNodePtr 对象：

oldNodePtr = toNode(newVRDObject.getObjectId())

也可以将 vrNodePtr 转换为 vrdNode：

newVRDObject = vrNodeService.getNodeFromId(oldNodePtr.getID())

场景图形术语

有关如何在本文档中引用场景图形的介绍，请参见 VRED 中的场景图形。

Python 示例脚本

这是演示 VRED Python API 各种功能的示例脚本集合。

• VRED Python 示例
• VRED Python 教程示例脚本