Work with rules

The tutorials and example projects that you can download from the CityEngine main menu (Help > Download Tutorials and Examples) as well as ESRI.lib contain versatile rules that you can use in your projects as is, or as starting points for your own customized rules. To start working with rules, you can create a simple rule file, apply it to initial shapes, and generate models.

Create a rule file

1. Select the rules folder of your project in the Navigator window.
2. Click New > CityEngine > CGA Rule File.

   Alternatively, right-click the rule folder in the Navigator window and choose New > CGA Rule File.

3. Define the name of the rule file.
4. Click Finish.

   A new CGA file is created and opened in the CGA Editor window. It is empty except for some header information.

Metadata

/**
 * File:    rule.cga
 * Created: 4 May 2008 23:27:29 GMT
 * Author:  xxxx
 */

version "2019.0"

The file starts with autogenerated metadata information for the user. It is marked as comments and is ignored by the compiler. The version tag specifies the CityEngine version for which this rule file was originally written.

Attributes

attr minheight 		= 10
attr maxheight 		= 300

You can start by defining two building parameters: minimum and maximum height. It is good practice to choose descriptive names. Additionally, the keyword attr is added to the front of each parameter definition. This way, these values become editable attributes in the Inspector window. The values set in the CGA file are default values.

Start rule

@StartRule
Lot --> extrude(rand(minheight,maxheight))

CityEngine recognizes the annotation @StartRule as the start rule, so it doesn't need to be specified manually when assigning the rule file to an initial shape.

The Lot rule extrudes the initial shape to a height that is defined by a randomly selected value between the values of the two attributes you defined before.

Note:

• Press Ctrl+S and click File > Save or right-click in the CGA Editor window and select Save to save your CGA file. You must save your changes for them to take effect for the model generation.
• To open CGA files, double-click the file in the Navigator window or click File > Open in the main menu.

Learn more about the CGA Editor window.

Assign rules and generate models

1. Create some shapes using the Polygonal Shape Creation tool (S) .
2. Select the shapes.
3. Click Shapes > Assign Rule Files and select the rule file you just created.
4. Click Open.
   • In the Inspector window, the Rule File and Start Rule fields are filled in now.
   • The maxHeight and minHeight attributes appear in the Inspector window.
5. Click the Generate models tool or press Ctrl+G.

   In the Viewport window, you now see extrusions to different heights.

Select some of the shapes and change one of the attributes in the Inspector window. This automatically triggers a regeneration of the selected shapes.

Note:

The changes in the Inspector window don't affect the values defined in the .cga file.

Repeatedly regenerating the rule without changing the attributes always yields to the same building heights. This behavior is intended because although you are using random values, you want the scene to look exactly the same as when closing and reopening the scene. To get new random values, you need to set a new seed on the shapes. You can do this by clicking the Update Seed tool (or pressing Ctrl+Shift+G) on the toolbar.

Learn more about CGA in Tutorial 6: Basic shape grammar.

Models from CGA without shapes

Some CGA rules, such as vegetation or furniture, can generate 3D models without assigning them to shapes. For example, you can customly place trees into a scene, by dragging the Plant_Loader.cga rule from the ESRI.lib library directly onto the terrain in the Viewport. A small shape (0.1m x 0.1m) is created at the position where you dragged the rule.

After, you can use the Inspector window to modify the rule attributes.

Set the start rule

In addition to the rule file, a shape requires a valid start rule to trigger model generation. If no valid start rule is found while a rule file is assigned, the Set Start Rule dialog box appears.

You can also type the start rule in the Inspector window, or set it on the Set Start Rule dialog box by clicking Select in the Inspector.

Set Start Rule dialog box

The Set Start Rule dialog box displays all rules that can be applied as start rules. Rules that are marked as start rules are displayed in bold in the following image (see also CGA annotations):

Start rules are selected on the Set Start Rule dialog box.

Select the rule that you want to assign as start rule. Additionally, you can choose the following:

• Apply to all selected shapes—Set the start rule to all selected shapes.
• Apply only to shapes with invalid Start Rule—Set the start rule to all shapes with an invalid or empty start rule. This option is only available if applicable.

Note:

CityEngine attempts to automatically detect and suggest start rules from a rule file. Use the annotation @StartRule to explicitly mark a rule as a start rule. See CGA annotations for more details.

Default start rules

• Shapes that are generated in CityEngine from a street network (by block subdivision or street shape creation) have their start rule set to a default value during creation (Lot, LotInner, Street, Sidewalk, and so on). You can reset these start rules to their initial value by clicking Graph > Reset Shape Attributes.
• Shapes that are imported from an .obj file (arbitrary geometries) have their start rule set to the obj group name by default.

Note:

See Rules to learn more about working with rules in Inspector.