VCGA (Visual CGA) Editor

The Visual CGA Editor is a node-based programming interface that simplifies building procedural designs. It is based on a high-level set of architectural components and materials released with the ESRI.lib, designed to support a wide range of massing typologies usable across VCGA, CGA, and Urban environments.

Download the VCGA Playground example to have access to the following:

• Multiple examples for VCGA design.
• A rich CGA component library. CGA components are nodes in a VCGA design; you can use the library to create your own designs.

Open CityEngine and click Help > Download Tutorials and Examples > Example VCGA Playground in the main menu. The Example VCGA Playground project is automatically downloaded and added to your CityEngine workspace.

You can also access the VCGA Playground example on ArcGIS Online. There are accompanying video tutorials to help get you started.

Visual CGA Editor

In the Visual CGA Editor window, you can write and modify VCGA designs which are identified by the .vcga extension. To edit a VCGA design, do the following:

1. Open the VCGA design file:
   • Double-click the design file in the Navigator window.
   • If a selected object has a VCGA design file assigned, click Rule File in the Inspector window to open it.
2. Edit the design.

   The Visual CGA Editor automatically saves the VCGA design with every change and generates the 3D model if it is assigned to a selected shape in the Viewport window. This means there is no need to manually save and generate the VCGA design.

Visual CGA Editor nodes

The Visual CGA Editor utilizes a node-based system in which nodes are connected to implement procedural designs. Each node has input and output slots, in which circular slots represent values and square slots represent shapes.

To add nodes, double click anywhere in the Visual CGA Editor window, or right-click in the window and select Add Node. This opens the Add Node dialog box:

The Add Node dialog box has the following types of nodes:

• Library—Displays the architectural components provided by the ESRI.lib.
• Custom—Displays the custom components located in the rules folder of the current project.
• Built-in—Displays the built-in nodes provided by the editor, such as input, attribute, extension, and flow control nodes.

This layout helps you to quickly find and use different types of nodes to build your procedural designs efficiently.

Component nodes

Each component node in the Visual CGA Editor window corresponds to either a CGA or a VCGA file. You can directly open this file using the Open Component File option in the node context menu that displays when you right-click the node.

Body

The body of each component node includes the following three distinct slot sections:

• Input shape slot—This slot represents the component’s input shape.
• Extension slots—These slots represent the component’s extension point shapes.
• Attribute slots—These slots represent the component’s input parameters. Each slot allows you to set a value in two ways:
  • You can create a value or attribute node and connect it to the slot.
  • You can use the node mini-inspector pop-up that opens when you click Edit when hovering over the slot. Initially, every attribute slot uses the component’s default value, but you can choose to set new values.

    

Title bar

In the component node’s title bar, there are buttons that have the following functionalities:

• The square button toggles a node on or off. Turning a node off activates the NIL operation, which removes the input shapes from the shape tree.

  

• The circular button toggles the visibility of the component's attributes in the Inspector window where they are hidden by default.

  

  

• The triangular button enables visualization of the input shapes' scopes on the lead selection in the Viewport window.

  

  

Visualization

You can select a component node to highlight its extension points on the lead selection in the Viewport window:

It is also possible to highlight a single extension point by hovering over the corresponding output slot. This feature is useful for visually identifying specific extension points in the Viewport window.

Built-in nodes

In the Visual CGA Editor window, you can use built-in nodes such as shape, attribute, or value nodes to create VCGA designs.

Shape nodes

The shape node is the root of the visual graph and it cannot be deleted or cloned. It represents the shapes that the rule is assigned to (in the .cej scene).

Input nodes

You can use the following distinct types of input nodes:

• Value nodes:
  • These nodes exclusively provide a value.
• Attribute nodes:
  • These nodes define the attributes of the VCGA design and are displayed in the Inspector window.

    Note:

    Attribute nodes can be conveniently created automatically by dragging a connection from an attribute slot and dropping it into the canvas. This action opens up the on-drop context menu, offering the Link attribute in the Inspector option.

  • They can either adopt the default attribute value or specify a new value.

    Note:

    • The default values depend on the connected initial shapes and are evaluated at runtime. Therefore, they cannot be displayed in the attribute nodes. However, you can see the default value for a specific shape in the Rules section of the Inspector window.
    • When attribute nodes adopt a default attribute value, they also inherit its annotations. Conversely, when attributes nodes specify a new value, they allow for the configuration of custom annotations through the annotation editor.

    

Additional built-in nodes

You can also use the following additional built-in nodes:

• Extension nodes:
  • These nodes specify the extension points of the VCGA design.
  • They can either follow a default behavior implementation or define a new leaf shape.
• Switch nodes:
  • Switch nodes enable the activation and deactivation of different branches within the visual graph through custom properties.
• Conditional flow control nodes:
  • These nodes activate or deactivate different branches of the visual graph through conditional statements on attributes.

Visual CGA Editor toolbar

The Visual CGA Editor toolbar includes the following tools:

Select and frame	Select and frame objects in the Viewport window with the current VCGA design assigned.
Assign	Assign the current VCGA design to the selected objects in the Viewport window.
Export	Export the current Visual CGA design as CGA rule file.
Frame	Frame the selected nodes (F), or frame all if nothing is selected.
Zoom in	Zoom / Dolly in.
Zoom out	Zoom / Dolly out.
View mini-map	Toggle the mini-map in the editor.

Manage rule errors

Errors in the VCGA file are detected automatically and are marked differently based on the type of error.

Component node errors

Component nodes can show the following possible error states:

• Error: the file *** has changed—Reload the node to resolve: This error indicates that the CGA/VCGA file linked to the component node has been modified, altering its signature (e.g., attributes or extensions have been introduced, modified, or removed). The error can be fixed using the Reload Node option in the context menu.
• Error: the file *** contains errors—This error indicates that the CGA/VCGA file linked to the component node contains errors. This can be fixed by manually fixing the errors inside the respective CGA or VCGA file.
• Error: the file *** could not be found—This error occurs when the CGA/VCGA file linked to the component node has been deleted or renamed. It can be fixed by selecting Change Component File from the context menu.

Input node errors

Input nodes validate the entered values. If validation fails, an error is displayed based on the node's type. An explanatory pop-up provides details about why the validation failed.

VCGA file errors

When there are compilation errors within the VCGA file, a small red cross appears in the window tab:

More detailed information about the error can be found in the Problems window (Window > Problems). Errors must be resolved before applying the rules. It is not possible to generate models if the assigned rule file contains errors.

Shortcuts

In the Visual CGA Editor window, you can use navigation and keyboard shortcuts to work more efficiently.

You can configure the global navigation mouse scheme in the CityEngine preferences. This allows customizing nodes selection, panning (scrolling), and zooming shortcuts.

You can use the following keyboard shortcuts when working in the Visual CGA Editor window:

Ctrl+Z	Undo
Ctrl+Y	Redo
Ctrl+A	Select all nodes
Ctrl+C	Copy selection to clipboard
Ctrl+V	Paste clipboard to canvas
F	Frame the selected nodes, or frame all if nothing is selected
Space	Maximize or minimize the Visual CGA Editor window