Working with rules

The tutorials and example projects you can download within the CityEngine main menu (Help > Download Tutorials and Examples...) as well as ESRI.lib are full of versatile rules that you can use in your projects as is or as starting points for your own customized rules. To get started with 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.
2. Click New > CityEngine > CGA Rule File....

   Alternatively, right-click in the Navigator the rule folder 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. 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 auto-generated meta 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 has originally been 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 put in front of each parameter definition. This way, these values become editable attributes in the Inspector. 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 a 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 we defined before.

Note:

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

Learn more about the CGA Editor.

Assigning rules and generating models

1. Create a couple of 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 the fields "Rule File" and "Start Rule" are filled out now.
   • The attributes maxHeight and minHeight appear in the Inspector.
5. Click Generate models tool (Ctrl+G) .

   In the Viewport you now see extrusions to different heights.

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

Note:

The changes in the Inspector 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 such as when closing and reopening the scene. To "shuffle the dice" and get new random values you need to set a new seed on the shapes. You can do this by clicking the Update Seed tool (Ctrl+Shift+G) in the toolbar.

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

Setting the Start Rule

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

A Start Rule is required for rule file model generation. The start rule can also be manually typed in the Inspector or set from using the Start Rule dialog by clicking Select... in the Inspector .

Set Start Rule dialog

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

Setting the start rule

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

• Apply to all selected shapes: Set selected start rule to all shapes.
• Apply only to shapes with invalid Start Rule: Set selected start rule to all shapes with invalid or empty start rule. This option is only active if applicable.

Note:

CityEngine tries 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 detail.

Default Start Rules

• Shapes generated inside 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, ...). These start rules can be reset to their initial value with Graph > Reset Shape Attributes
• Shapes which are imported from a .obj file (arbitrary geometries) have their start rule set to the obj group name by default.