VCGA (Visual CGA) 编辑器

Visual CGA 编辑器是一个基于节点的编程界面，可用于构建程序化设计。 ‌每项设计都通过将高级建筑组件连接为图形来构建‌。

ESRI.lib 提供了一套开箱即用的 VCGA 组件与材料库，可用于创建自己的 VCGA 设计‌。

示例 VCGA Playground 包含完整 VCGA 设计的示例。 打开 CityEngine 并单击主菜单中的帮助 > 下载教程和示例 > Example VCGA Playground。 将自动下载 Example VCGA Playground 工程并将其添加至您的 CityEngine 工作空间。

创建 Visual CGA 设计

通过执行以下操作之一打开向导对话框：

• 在导航器窗口中，右键单击任意文件夹并选择新建 > Visual CGA 设计。
• 在主菜单上，单击文件 > 新建 (Ctrl+N) > CityEngine > Visual CGA 设计。

选择目标文件夹和文件名，然后单击完成。

Visual CGA 编辑器

在 Visual CGA 编辑器窗口中，可以编写和修改由 .vcga 扩展标识的 VCGA 设计。 要编辑 VCGA 设计，请执行以下操作：

1. 打开 VCGA 设计文件：
   • 双击导航器窗口中的设计文件。
   • 如果所选对象已分配 VCGA 设计文件，请单击检查器窗口中的规则文件以将其打开。
2. 编辑设计。

   Visual CGA 编辑器会在每次更改后自动保存 VCGA 设计，并在将其分配给视口窗口中的所选形状时生成 3D 模型。 这意味着无需手动保存和生成 VCGA 设计。

Visual CGA 编辑器节点

Visual CGA 编辑器采用基于节点的系统，其中节点连接在一起以实现程序化设计。

节点浏览器

‌节点浏览器列出了可用的 VCGA 组件，这些组件可作为节点添加到 VCGA 设计中‌。

您可以通过以下方式打开节点浏览器：

• 单击编辑器工具栏中的切换节点浏览器按钮 。
• 双击画布上的任意位置。
• 按 A。

所有这些操作会打开节点浏览器，您可在其中搜索并选择节点，将其添加到设计中。 在新建的空白 VCGA 设计中，节点浏览器会自动打开‌。

节点浏览器将可用节点划分为三个类别‌：

• ‌ESRI.lib - 来自 ESRI.lib 的即用型组件‌。
• 工程 - 当前项目规则文件夹中的组件‌。
• 内置 - 编辑器图元，例如值、属性、扩展模块和条件节点。

在节点浏览器中，可以在列表视图和格网视图之间切换。 在格网视图下，节点与文件夹的缩略图尺寸更大；而列表视图则更为紧凑。 在格网视图或列表视图中单击任意组件，即可打开描述视图查看更多详细信息。

这些面板以不同视图展示：（左侧）格网视图；（中间）列表视图；（右侧）描述视图。

 

在节点浏览器中搜索节点

单击节点浏览器顶部的搜索按钮 ，或按下 S 键，即可打开搜索栏。 默认情况下，搜索将返回名称和路径均匹配的节点。

单击过滤器图标，将搜索范围扩展至其他字段：

• 节点（默认）- 节点名称，包括完整路径
• 输入形状 - 节点输入形状的名称
• 属性 - 节点属性的名称
• 扩展组件 - 节点扩展组件的名称

要了解不同字段的详细描述，请参阅组件节点。

添加节点

可以通过两种方式向 VCGA 图形中添加新的节点。 打开节点浏览器，然后导航至要添加的节点的目录。

• 单击 + 添加按钮，或
• 将节点从节点浏览器拖动到画布上。

还可以在描述视图下完成这些操作。

如果选中单个节点，并使用 + 添加 按钮添加节点，新节点将自动放置在选中节点的右侧。 如果选中的节点仅带有单个扩展模块，它还会自动连接至新添加的节点。

替换节点

可通过以下选项对现有节点进行就地替换‌：

选项 A

1. 在图形中选择现有节点。
2. 在节点浏览器中选择其他兼容组件，然后按 ⇋ 替换按钮。

   

选项 B

1. 将组件从节点浏览器拖动至 Visual CGA 编辑器窗口，然后将鼠标悬停在现有节点上方。 替换图标 ⇋ 随即显示。
2. 释放鼠标按钮以替换节点。

   

替换节点时，将尽可能保留‌所有兼容的连接。

节点快捷菜单

右键节点可打开快捷菜单。 可用选项如下：

• 剪切、复制、删除 - 修改或移除所选节点。
• 在节点浏览器中显示 - 打开节点位置目录。
• 打开组件文件 - 打开定义该节点的基础 VCGA 设计或 CGA 文件‌。

如果规则文件的更改导致连接断开（例如，含现有连接或自定义值的属性、扩展模块被删除或重命名），组件节点上将提供其他选项：

• 重新加载节点 - 重新加载节点，并移除所有无效（断开）连接。

组件节点

Visual CGA 编辑器窗口中的每个组件节点对应于 CGA 或 VCGA 文件。 可以使用右键单击节点时随即显示的节点快捷菜单中的打开组件文件选项直接打开此文件。

主体

每个节点都具有输入和输出空位，其中圆形空位表示值，方形空位表示形状。 可以进一步将其分为四种不同的空位类型：

• 输入形状空位 - 此空位表示组件的输入形状。
• 扩展空位 - 这些空位表示组件的扩展点形状。
  • 白色空位表示除非该扩展连接到另一个节点，否则不会为其生成任何几何；而已填充的黑色空位表示将默认为此扩展生成形状。

    

• 扩展参数空位 - 这些空位表示组件的扩展点参数。 这些参数会传递形状特定值。
• 属性空位 - 这些空位表示组件的输入参数。 每个空位允许以两种方式设置值：
  • 可以创建值或属性节点并将其连接到空位。
  • 可以使用在将鼠标悬停在空位上时单击编辑 时随即打开的迷你检查器弹出窗口。 最初，每个属性空位均使用组件的默认值，但您可以设置新值。 仅在运行时评估默认值，无法进行显示。 但是，可以在检查器窗口中查看默认属性值（请参阅下文）。

    

将鼠标悬停在空位上即可在工具提示中显示其描述。

标题栏

在组件节点的标题栏中，可以使用具有以下功能的按钮：

• 将显示组件的描述。

  

• 方形切换按钮用于打开或关闭组件。 关闭组件可阻止生成其形状。

  

• 圆形按钮用于在检查器窗口中显示属性。

  

• 三角形按钮用于在视口窗口中可视化输入形状在优先选择上的范围。

  

可视化

可以选择一个组件节点，以在视口窗口的优先选择上高亮显示其扩展点：

通过将鼠标悬停在相应输出空位上，您也可以高亮显示单个扩展点。 此功能对于在视口窗口中直观地识别特定的扩展点非常有用。

内置节点

可以在 Visual CGA 编辑器窗口中使用内置节点，例如属性节点、值节点和条件节点，以便更好地控制在 VCGA 设计中评估组件节点的方式。

InitialShapes 节点

此节点是可视图形的根，无法对其进行删除或克隆。 它表示场景中将规则分配到的形状。 节点标题栏中的 @ 按钮可打开注记编辑器，可以在其中提供 VCGA 设计的描述以及 InitialShapes 节点本身的描述。

值节点

这些节点将提供常量值作为输出。

属性节点

这些节点可定义 VCGA 设计的属性，并显示在检查器窗口中。

通过将连接从属性空位拖放到画布中，可以自动创建属性节点。 此操作将打开下拉快捷菜单，其中包含在检查器中链接属性选项。

属性节点将提供一个输出值，可以将其初始化为自定义值或者组件已连接属性空位的默认值。 但是，检查器窗口中的用户设置值始终具有较高的优先级。

将属性节点初始化为属性空位的默认值时，它们也会继承其注记。 相反，当属性节点指定自定义值时，它们允许通过注记编辑器配置自定义注记。

节点标题栏中的 @ 按钮可打开注记编辑器。 在此编辑器中，可以配置多个首选项，这些首选项会影响属性在检查器窗口和 Visual CGA 编辑器窗口中的显示方式。

扩展节点

这些节点用于指定 VCGA 设计的扩展点。 当 Visual CGA 设计在另一个 Visual CGA 设计中用作组件时，它们会显示为扩展空位。

将为扩展节点生成默认形状。

以下选项用于设置扩展节点的默认形状：

• 标识：将输入几何保持原样。
• NIL：默认不会生成任何几何。
• 扩展名称（默认）：生成与所选扩展相同的默认几何。

切换节点

开关节点可以通过自定义属性来激活和禁用可视图形内的不同分支。

条件节点

条件节点允许用户通过比较属性、值或参数连接来引导形状流。

Visual CGA 编辑器节点

Visual CGA 编辑器采用基于节点的系统，其中节点连接在一起以实现程序化设计。

此布局可帮助您快速找到并使用不同类型的节点来高效构建程序化设计。

Visual CGA 编辑器工具栏

Visual CGA 编辑器工具栏包含以下工具：

切换节点浏览器	打开和关闭节点浏览器。
选择并框选	在视口窗口中选择并框选已分配当前 VCGA 设计的对象。
分配	将当前 VCGA 设计分配给视口窗口中的所选对象。
导出	导出当前 Visual CGA 设计作为 CGA 规则文件。
框选	框选所选节点 (F)，如果未选择任何节点，则框选所有节点。
放大	放大/前推。
缩小	缩小/后推。
查找节点	打开搜索对话框以按节点的标题查找节点 (Ctrl+F)。 单击节点标题将视图框选至所选节点。
切换迷你地图	在编辑器中切换迷你地图。

创建自定义组件

可以将任何 Visual CGA 设计作为自定义组件集成到另一个 Visual CGA 设计中，其中 InitialShapes 节点将成为输入形状空位，属性节点将成为属性空位，扩展节点将成为扩展空位。

此外，可以将 CGA 规则文件本身配置为自定义组件。 CGA 组件必须包含一个起始规则，该规则将用作输入形状空位。 属性将用作属性空位，扩展规则将用作扩展空位。 其参数将显示为扩展参数空位。 可以使用 @RuleFileDescription 注记来记录组件。 可以使用 @Description 注记来记录起始规则、属性和扩展规则。

@RuleFileDescription("
This text describes the function of the component.
It will be displayed when pressing the (i) button on a component node.
- this text will automatically be formatted using markdown
")

@Description("This will be displayed when hovering the extension slot in VCGA")
extension My_Extension(My_Extension_Parameter) --> My_Extension.

@Description("This will be displayed in the inspector 
and when hovering the attribute slot in VCGA")
attr My_Attribute = 0

@Description("This will be displayed when hovering the start shape slot in VCGA")
start My_Start_Rule_Name -->
    My_Extension(My_Attribute)

管理规则错误

将自动检测 VCGA 文件中的错误，并根据错误类型进行不同的标记。

组件节点错误

组件节点可以显示以下可能的错误状态：

• 错误：文件 *** 已更改 - 请重新加载该节点以解决此错误：此错误指示链接到组件节点的 CGA/VCGA 文件已被修改，从而改变了其签名（例如，已引入、修改或移除属性或扩展）。 可以使用快捷菜单中的重新加载节点选项来修复该错误。
• 错误：文件 *** 包含错误 - 此错误指示链接到组件节点的 CGA/VCGA 文件包含错误。 可以通过手动修复相应 CGA 或 VCGA 文件内的错误来解决此问题。
• 错误：未找到文件 *** - 当已删除或重命名链接到组件节点的 CGA/VCGA 文件时，会出现此错误。 可使用节点浏览器通过替换组件修复。

输入节点错误

输入节点将验证输入的值。 如果验证失败，则将根据节点的类型显示错误。 解释性弹出窗口将提供有关验证失败原因的详细信息。

VCGA 文件错误

当 VCGA 文件内存在编译错误时，窗口选项卡中将显示一个红色十字：

可以在问题窗口（窗口 > 问题）中找到有关该错误的更多详细信息。 应用规则之前，必须先解决错误。 如果分配的规则文件包含错误，则无法生成模型。

快速链接

在 Visual CGA 编辑器窗口中，可以使用导航和键盘快捷键以更加高效地工作。

可以在 CityEngine 首选项中配置全局导航鼠标方案。 由此可自定义节点选择、平移（滚动）和缩放快捷键。

在 Visual CGA 编辑器窗口中工作时，可以使用以下键盘快捷键：

Ctrl+Z	撤消
Ctrl+Y	恢复
Ctrl+A	选择所有节点
Ctrl+C	将选择内容复制到剪贴板
Ctrl+V	将剪贴板粘贴到画布
Ctrl+F	打开“查找节点”对话框
F	框选所选节点，如果未选择任何节点，则框选所有节点。
空格	最大化或最小化 Visual CGA 编辑器窗口
A	打开节点浏览器
S	打开节点浏览器中的搜索