Code Analysis: International City, Part 1

- Importing rule files to your base file;
- Using Annotations to add variable attribute controls to the Rules inspector panel.

Before we delve into our analysis of the International City rule file, let’s review the rule types and their definitions as described in ESRI documentation. ESRI describes a rule file as a “collection of attributes, functions and rules”.

Attributes apply values to rules.  The lot shape will be extruded 10 meters.

1  attr height = 10
2  Lot --> extrude(height)

Functions( ) are encapsulated and perform operations and return values, just as in VB or other object-oriented code languages.

Standard Rules take a shape named with a shape symbol and replaces it with a number of new shapes. The example code shows our initial symbol StartShape creates a primitive cube with x,y,z dimensions of 50 meters, then declares a successor rule called NextShape.  The successor rule splits the cube in quarters on its y-axis and assigns each to another successor rule, Floor.

1  StartShape --> primitiveCube(50,50,50) NextShape
2  NextShape --> split(y) { ~4 : Floor }

Parameterized Rules contain variables that can be changed as needed, adding flexibility to the model. In the code above, the primitiveCube operation creates a cube using the x,y,z parameters shown in the parenthesis (50,50,50).  These parameters can be changed as needed, adding flexibility to the model.

Conditional Rules use the words case and else:

1  In CASE the following condition exists : do this and NextRule
2  In CASE this other condition exists: do this and AnotherNextRule
3  ELSE (otherwise) : Do This and go to this OtherNextRule

4  NextRule -->
5  AnotherNextRule -->
6  OtherNextRule -->

Stochastic Rules use randomness to create variations according to declared proportions. Roof types assigned to selected structures will be apportioned according to the percentages

1  Roof -->  40% : Roof(“TerraCotta”)
2            30% : Roof(“AsphaltShingle”)
3            else : Roof(“Tile”)

Styles assign predefined parameters to individual components such as doors or windows. We will get to these in a later installment.

Import is used to make rules from one CGA files available in another. The code structure becomes modular.

Code Analysis

Let’s get started with the initial section of International City.cga.


1  import Street_Modern_Standard: "/ESRI.lib/rules/Streets/Street_Modern_Standard.cga" 
2  Crossing --> Street_Modern_Standard.Crossing

This code imports four other rule files:

  • Street_Modern_Standard.cga (shown)
  • Facade_Textures.cga
  • Roof_Textures.cga
  • Plant_Loader.cga

Noticce the Street_Modern_Standard.cga rule file is imported using a named pseudonym Street_Modern_Standard directly after the import command.  On Line 2, the Crossing rule within the imported file is assigned to our own Crossing rule with the pseudonym followed by the rule name.


1  @Group("Building",1)
2  @Order(1) @Range("Highrise Building","Office Building","Apartment Building",
3  "Residential","Open Space") 
4  attr Type            = getType
5  @Order(2) @Range(0.5,2)
6  attr HeightFactor    = 1

7  @Group("Trees",2)
8  @Order(1) @Range("None","Fan","Model","Analytical") 
9  @Description("Do not generate Models for whole city i.e. take care with polygon counts!")
10  attr ShowTrees       = "Fan"

11 @Order(2) @Range("Random Forest","Tropical","Zone 6 Trees")
12 attr Mix             = "Zone 6 Trees"

13 @Group("H:W Ratio",3)
14 @Order(1) @Range(1,20)
15 attr HRatio = 4 
16 @Order(2) @Range(1.0,2.0)
17 attr WRatio = 1

18 @Group("Colors", 4)
19 @Order(1) @Color
20 attr surfaceColor = "#FFFFFF"
21 @Order(2)@Range("#ff0000", "#00ff00", "#0000ff")
22 attr color = "#000000"

In the next code block, “control attributes” are set with annotations, which are used to add additional information to a rule or an attribute”.  Annotations begin with an Ampersand @ character.  Unless they are marked as @hidden, control attributes will appear in the Inspector panel (Alt+I) where they can be changed with dropdown menus, sliders or other GUI devices.

  • Select a High Rise Building by clicking on it, then click on and move the Height Factor control slider. As shown in the code, this control has a range of 0.5 to 2. You can move the slider for this control within this range, or enter your own value by manually changing the number.  While you have the building selected, change the type to Office Building or one of the other types and watch the result.

Compare the  hierarchy in the code with the illustration above.  The first @Group  named Building, appears first in the panel because of the ,1 after “Building”. The @Group  named “Trees” with ,2 after the name appears second.

Under the Building @Group on lines 2-6, there are two attributes (Type and Height Factor) named with the attr declaration. Their order of appearance on the panel is determined by the number in @Order(#).

The @Range annotations set either a list of values which will appear in a dropdown menu, or a range of numeric values which will appear with a slider control.

On lines 13-17, I have added my own control for a Height-to-Width Ratio group. The slider controls in the Inspector panel will not do anything, however, until I "connect" the attribute -- more on this in a future installment.  I can return to the default value for any control by clicking "Rule Default" at the bottom of the drop-down.

Finally, on lines 18-22, I have added two color controls. The first, called "surfaceColor", has a hex default value of #FFFFFF (white).  The @Color annotation causes the control to call up a color palate when clicked.  The second control called "color" has a default of black (#000000) and a range of three hexidecimal values that can be selected.

Leave a Reply

Your email address will not be published. Required fields are marked *