Speckle虚幻连接器教程

Speckle正式支持Windows、Mac和Linux平台上的虚幻引擎4.26、4.27和5.0，其他平台未经测试。

Speckle虚幻引擎连接器正处于测试开发阶段。目前仅支持接收几何图形。

1、从虚幻商城安装Speckle连接器

Speckle虚幻引擎连接器在虚幻商城中打包为代码插件。对于大多数用户，建议使用此安装方法。

安装后，有必要从“编辑→插件”菜单中为你的项目启用 Speckle 插件。启用后，应将引导你重新启动项目。

就是这样！你的项目现在可以使用 Speckle 插件了！

2、用git安装Speckle虚幻引擎连接器

对于想要修改源代码、试用正在进行的分支和/或将更改贡献回 speckle-unreal 存储库的开发人员，最好通过 git（打开新窗口）进行安装。

首先使用Git 将此存储库克隆到项目的插件目录（根据需要创建）。

git clone https://github.com/specklesystems/speckle-unreal

然后打开UE项目（如果已打开编辑器，则重新启动编辑器）。这将在你的环境中构建插件。

3、在虚幻编辑器里使用插件

该插件包含一个名为Speckle虚幻管理器的Actor类型，可用于从Speckle导入对象。

以下是使用它的方法：

在“放置Actor”侧边栏中，搜索“Speckle Unreal Manager”并将其添加到世界中。

在世界大纲视图侧边栏中选择 SpeckleUnrealManager 实例，然后使用“Speckle”类别中显示的选项。

有两种方法可以使用Speckle虚幻管理器Actor导入对象。

设置接收参数后，只需单击“接收”按钮。指定的对象及其所有子对象将作为Actor导入。

4、使用蓝图调用Speckle虚幻插件

蓝图可以是一个强大的工具，用于实现你自己的自定义行为来接收对象。

接收过程可以使用蓝图执行，这样做可以允许额外的灵活性来执行接收的数据/转换的参与者的其他操作。

使用蓝图来做到这一点需要对插件的工作原理有基本的了解。

• ServerTransport 用于向 Speckle 服务器发出对象（及其子对象）的 HTTP 请求。它从服务器获取 JSON 对象，然后将其存储在本地内存传输中。
• 节点处理收到的对象，并将它们反序列化为对象模型（继承 UBase 的对象）。
• SpeckleConverterComponent将这些对象转换为本机Actor/组件。

蓝图中有一个关于这个过程的示例，在插件speckle-unrealContentExample目录中提供了，如下所示：

此外，还提供了许多蓝图宏节点来获取有关流/分支/提交/用户的详细信息。

5、Speckle/UE Actor转换

SpeckleConverterComponent提供了转换功能，用于将Speckle对象转换为原生UE Actor。但是，此类不包含特定的转换逻辑。

相反，转换器逻辑是模块化的，因此特定类型的转换函数和设置封装在它们自己的实现 ISpeckleConverter 的类中。

注意，这里的ISpeckleConverter与.NET SDK中的Speckle.Core.Kits .ISpeckleConverter不同。

开箱即用，该插件为以下转换提供了转换器：

由于虚幻引擎的性质，有必要提供对象转换方式的选项/设置。因此，每个 ISpeckleConverter 还可以公开可以从编辑器或 BP/C++ 中设置的属性。此结构与其他连接器明显不同，后者通常具有一个包含许多转换的大型转换类，并且提供很少（如果有）设置。

以 StaticMeshConverter 为例，你可以看到它公开了多个设置，例如要创建的 actor 类型和网格构建设置。

开箱即用，SpeckleConverterComponents 将使用一组默认转换器进行设置。对于大多数用户，不需要进一步的配置。但是，你可以通过内容中的资产创建自己的特定 ISpeckleConverter 实例，然后将它们分配给转换器组件。这可以通过右键单击并创建指定类型的新转换器来完成。

你可以在 BP/C++ 中创建自己的自定义转换器（请参阅创建自定义转化文档）。

5.1 网格转换器

Speckle-Unreal提供了两种类型的网格体转换器：

ProceduralMeshConverter：

• 创建 UProceduralMeshComponent。
• 转换速度稍快，并允许在运行时编辑顶点/面。
• 渲染速度最慢，不能使用烘焙照明。

StaticMeshConverter：

• 创建一个 UStaticMeshComponent。
• 网格顶点/面/等无法轻松编辑（需要重建）。
• 渲染速度更快。
• 构建的网格体可以保存为资源，允许重新加载关卡。
• 附加的仅编辑器构建过程允许烘焙照明、额外的路径跟踪选项和优化照明。

对于大多数用户，我们建议使用静态网格体，因为它们针对渲染进行了更多优化，并且可以保存到某个级别。静态网格体可以在运行时或编辑器模式下使用，但仅编辑器构建过程仅适用于编辑器访问权限。

5.2 材质转换器

作为一种工具，虚幻引擎在制作精美、逼真的场景渲染方面大放异彩。这对于 Speckle 用户来说具有重要价值，因为它是制作高质量和实时演示、动画和 XR 体验的工具。

对于某些用户来说，使用对象的渲染材料（打开新窗口）转换的简单平面着色 PBR 材质将是他们想要的。

然而，许多用户都希望使用纹理材质，毕竟虚幻引擎擅长写实感，而高质量的材质是其中的重要组成部分。

MaterialConverter 的“材质覆盖”功能满足了这一需求，因为它支持将纹理材质应用于接收几何体的半自动工作流程。

Speckle's Objects kit 通过 Speckle 网格的 RenderMaterial 属性支持 PBR 材质。当使用渲染材质接收网格时，MaterialConverter 将创建一个应用于转换网格的材质实例。

• 材质转换原理

材质转换器公开了一些属性，用于定义所创建材质的基础/父材质。不透明材质将转换为 BaseMeshOpaqueMaterial 的实例。透明材质将转换为 BaseMeshTransparentMaterial 的实例。

默认情况下，这些基础材质分别是具有不透明/半透明着色器模型的简单材质。两者都公开了多个属性（请参见屏幕截图），并且在转换过程中，这些属性是使用 RenderMaterial 中的值设置的。

默认的不透明材质“SpeckleMaterial”如下所示：

默认的半透明材质“SpeckleGlassMaterial”看起来像这样：

这些基础材质作为转换器的属性公开，并且可以从编辑器中（或从 BP/C++）更改为自定义材质。

• 替换转换的材质

Speckle目前不支持发送/接收纹理材质。但是，我们确实提供了一种在接收来自Speckle的对象时自动应用原生虚幻材质的方法。

可以通过两种方式用自定义材质覆盖转换后的材质。

• 按名称 - RenderMaterial.name 将与 MaterialsOverridesByName 数组中的材料进行匹配。
• 按 ID - RenderMaterial.id 将按键与 MaterailOverridesById 地图中的材质一起使用。

默认材质转换器实例的详细信息面板中的材质覆盖“按 ID ”的屏幕截图。ID 为 f5f7ebd4a...将使用此材质，而不是从对象的渲染材质转换材质。

默认材质转换器实例的详细信息面板中的材质覆盖“按名称”的屏幕截图。名称为 Mossy_Grass 的材质将使用此材质，而不是从对象的渲染材质转换材质。

• 材质处理优先级

材质处理优先级从高到低排列如下：

• OverridesById 中按 Id 匹配的材质。
• OverridesByName中按名称匹配的材质。
• 从上一个接收操作缓存的材质。
• /Game/Speckle/Materials/{id} 包中的材质资源，即来自先前的接收，但未缓存，或来自战略放置的资产。
• 从网格的渲染材质转换而来的材质。
• 最后，如果所有其他方法都失败了，则将使用MaterialConverter中设置的DefaultMaterial。

注意：如果对象上没有材质，则我们不会像此连接器的先前版本那样回退到父项的材质。我们知道这可能会导致意外行为。这个问题将得到解决。

• 材质处理已知的局限

为了使用纹理材质，网格需要具有纹理坐标（UV 坐标）。目前，纹理坐标仅从 Rhino、Blender 和 Sketchup 连接器输出。虚幻连接器不会为你生成纹理坐标。具有UV坐标对于烘焙照明还有其他优势。

纹理不能通过Speckle发送/接收，只能通过平面颜色和简单的PBR属性发送/接收。纹理支持在我们的路线图上，但在此之前，有几个技术问题需要克服。

5.3 开发自定义转换

如前所述，ISpeckleConverter 类可以公开属性，例如要创建的 Actor 类型、是否创建资产或构建设置等。

如果这不能满足你的需求，有几种方法可以进一步自定义转化。

• 可以扩展现有转换器，并重新实现特定功能。
• 可以编写一个完全自定义的 ISpeckleConverter 类，并将一个实例添加到 SpeckleConverterComponent
• 可以扩展 SpeckleConverterComponent，以更普遍地自定义对象的转换方式和附加的执行组件。

可以在C++或蓝图中创建转换器。

5.4 自定义对象模型

虚幻插件中的对象模型的功能与.NET中的对象模型相同。

开箱即用的虚幻Speckle插件提供了多个对象模型。这些类可以在 speckle-unreal\Source\SpeckleUnreal\Public\Objects 中找到，并且都是 UBase 类型的子类。在大多数情况下，这些类是对象工具包中相应 .NET 类的直接端口。例如 Mesh 和 BlockInstance。

需要对象模型才能转换 Speckle 对象。如果要转换我们未提供对象模型的类型，则创建一个对象模型非常简单。

此过程与在 .NET 和 PY SDK 中定义对象模型非常相似，但请注意某些限制：

• UE 插件不提供基于反射的（反）序列化程序。对象模型以手动分析 JSON 属性的形式实现自己的（反）序列化逻辑。
• 只有某些对象模型是开箱即用的，而大多数是对象工具包的直接端口，有些不是！
• Speckle 类型在对象模型的构造函数中定义，而不是像 .NET 中那样由其命名空间定义。
• 单位在解析时应用（而不是 ToNative 转换 - 可能会发生变化）

要实现自己的虚幻对象模型，只需创建一个继承自UBase的新类即可。添加属性，并实现 Parse 方法以从 JSON 对象设置这些属性。

bool UMyObjectModel::Parse(const TSharedPtr<FJsonObject> Obj, const TScriptInterface<ITransport> ReadTransport)
{
	if(!Super::Parse(Obj, ReadTransport)) return false;

	// Add your own JSON parsing here!
	// Remove explicit properties from DynamicProperties array
	
	// Simple example of parsing an optional number property:
	if(Obj->TryGetNumberField("myProperty", MyProperty)) DynamicProperties.Remove("myProperty");
	
	// Simple example of parsing an required number property:
	if(!Obj->TryGetNumberField("myProperty", MyProperty)) return false; // Return false on error, rather than fatal assertions
	DynamicProperties.Remove("myProperty");
	
	//Return true if parsed successfully
	return true;
}

有关进一步的参考，请参阅 URenderMaterial 以获取示例，有关更高级的示例，请参阅 UMesh。UConversionUtils提供了用于分块/取消引用Speckle对象的帮助程序方法。

目前，单位缩放在解析（而非转换）期间应用。这可能会发生变化！

将来，我们可能会考虑创建一个使用反射的适当反序列化程序，这意味着对象模型可以反序列化，而无需开发人员编写这些 Parse 方法。在此之前，我们有几个技术挑战需要解决。

5.5 创建C++转换器

可以通过创建实现 ISpeckleConverter 的 UObject 类来定义自定义转换器。你必须实现 ConvertToNative 和 CanConverToNative 方法。

UCLASS(BlueprintType, Blueprintable)
class SPECKLEUNREAL_API UMyConverter : public UObject, public ISpeckleConverter
{
	GENERATED_BODY()

public:
	virtual UObject* ConvertToNative_Implementation(const UBase* SpeckleBase, UWorld*, TScriptInterface<ISpeckleConverter>&) override;
	
	virtual bool CanConvertToNative_Implementation(TSubclassOf<UBase> BaseType) override;

}

最有可能的是，与其在 ConvertToNative 函数中干扰实际的转换代码，不如将其包含在单独的函数中。但是这个类可以随心所欲地实现！AvailableConverters 参数对象是对主聚合转换器的引用，如果需要转换其他 Speckle 对象，并希望重用另一个转换器的转换逻辑，我们可以使用它。例如，StaticMeshConverter将使用AvailableConverters来转换RenderMaterial。

UObject* UMyConverter::ConvertToNative_Implementation(const UBase* SpeckleBase, UWorld* World, TScriptInterface<ISpeckleConverter>& AvailableConverters)
{
	const UMyObjectModel* m = Cast<UMyObjectModel>(SpeckleBase);
	
	if(m == nullptr) return nullptr;
	
	return MyObjectToNative(m);
}

AActor* UMyConverter::MyObjectToNative(const UMyObjectModel* MyObject, UWorld* World)
{
	// Conversion logic here!!
	// Convert MyObject into an Actor that we return
}

可以实现可选的 CleanUp 方法，该方法用于清除任何缓存对象/需要在接收操作之间完成的任何其他清理。

5.6 创建蓝图转换器

与C++一样，转换器也可以使用蓝图实现。首先创建一个继承 UObject 的新蓝图：

在“类设置”下，将 ISpeckleConverter 添加到“实现的接口”列表中。

最后，在所需的函数中实现转换逻辑。

原文链接：Unreal  Connector| Speckle Docs

BimAnt翻译整理，转载请标明出处