CityEngine Starter Project 2 - Rule file set up, attribute generation and reporting

At the very core of CityEngine is the shape grammar operations that take input 2D geometry and create 3D models. A CGA rule file is the code needed to string a list of operations together to create 3D content. I have been asked numerous times is it like such and such code. Yes, its a programming language so it has the same type of logic and structure as Python etc. However, the syntax is unique but thankfully pretty simple to understand.

By now I had seen and played with a number of rule files that were within the tutorials and sales material from Esri. These are fun but without coding my own rules I could never make CityEngine do what I wanted it to do. The starter project was a fun way to practise what I had learned and to try a few things to really get to grips with the software. I would advise that you make yourself familiar with the Basics of Rule-Based Modelling section of the Help (within CityEngine - if you have the software) if you are still are not aware what the Scope, Geometry and Pivot attributes are and how operations are applied to the shapes.

I will include the full rule file in the last post of the starter project, but for now I'll go through it in sections in more detail. 


Rule file set-up

The first thing that you'll notice when you create a rule file is the header section:

/**

 * File:    StarterProject.cga

 * Created: 01 Jan 2013 01:02:07 GMT

 * Author:  ellawayc

 */ 

version "2012.1"

This information is enclosed within the /** and */ characters which essentially tells CityEngine to ignore these lines and we can use them to make comments. This information just describes the name of the rule file (.cga), the creation date, the creator and the version. Note that the version is not within the comment section and must be a special use string.

From here the rule file was split into a few different sections:

## Hidden Attributes ##

## Attributes ##

## Functions ##

## Constants ##

## Assets ##

## Rules ##

The sections allow easy tracking and maintenance of parts of the code. Each section has a particular function but each rule file is different and so maybe all sections are used or maybe only the Rules section is used. Very simply, Hidden Attributes and Attributes are for reporting, storing and keeping values for rules. Functions and Constants are used to create values for rules, Assets are for importing data or models and Rules is used to create the 3D content using operations.

Attribute generation and reporting

To begin, I needed to create an attribute that can be used as a slider to differentiate between the residential and commercial zones. Within the Attributes section I generated an attribute called ZONETYPE and gave a list of attribute values that I wanted (Residential, Commercial) and provided a default value(Residential):

## Attributes ##

@Range("Residential","Commercial")

attr ZONETYPE = "Residential"

This creates a text field slider that allowed me to choose which zone selected shapes should be. The range allowed me to choose between the two zones with the default of "Residential". I now applied the rule file to the parcels and changed the slider on each parcel in the Commercial area - as per the zoning plan shown in part 1. 

Within the Rules section I created a startRule (Lot) which is used as the starting rule for the parcel shapes. An Align operation is applied to make sure that the shapes are aligned correctly and that the y scope is in the vertical direction. There are quite a few Align operations within CityEngine, all of which are used in different scenario's. For now I just used the most simple auto operation. 

## Rules

@startRule

Lot -->

     alignScopeToGeometry(yUp, auto)

Now I wanted to report out some figures that I could use in calculations such as to find the building coverage. Under Hidden Attributes I created an attribute that is ready to store the geometry area of each parcel shape. The default value (0) doesn't really matter -  as long as the value is a number:

## Hidden Attributes ##

@Hidden

attr ParcelArea = 0

Following the Align operation under the rules header, Set and Report operations were added to give geometry.area to the ParcelArea attribute. 

## Rules

@startRule

Lot -->

     alignScopeToGeometry(yUp, auto)

     set(ParcelArea, geometry.area
     report("A Parcel Area (m2)", ParcelArea)

I now regenerated models but obviously this did not produce any 3D content just yet but it does expose the ParcelArea, shown within the Reports tab of the Inspector window. The CityEngine scene now looked as per the image below:

That's the first small section of code written, showing how I generated a very simple report and stored the geometry.area value within a Hidden Attribute. In the next post I will show the coding of some basic operations, and calculations and demonstrate a basic loop to give a requested building coverage.