Tutorial 11: Reporting

To access the tutorials in CityEngine, click Help > Download Tutorials and Examples. When you choose a tutorial or example, the project is automatically downloaded and added to your workspace.

The reporting feature augments CityEngine beyond the generation of geometry; it permits rule-based calculation and accumulation of a model's parameters. This means that you can not only visualize your urban master plans but also augment them by generating numerical reports (for example, Excel tables via .csv files). As with 3D models, you can generate the reports with the CGA shape grammar. Either the report operations can be included in the corresponding rules that generate the geometry, or CGA shape grammar rule sets only for reporting can be created.

The report operation allows for the reporting of arbitrary properties of the building design or master plan. This makes reporting completely generic and customizable. For example, it can include numbers, such as gross floor areas (GFA), number of units, or land-use mixes. In addition, by changing the urban design (that is, regenerating the models), the reports are updated automatically and instantaneously. This tutorial shows an example scenario in which a master plan is built from the beginning, and the reporting functionalities are used to analyze existing geospatial data.

Area reports

This section of the tutorial shows how to embed reporting actions in CGA files and how resulting reports are generated.

Set up

Open the Tutorial_11_Reporting/scenes/reporting_01.cej scene.

The scene is based on the following street network, which was generated with the CityEngine street grow feature using a spiral pattern:

By applying simple extrusion rules with some green space percentage, you can generate a city model.

Greenspace and BuildUp area reports

1. In the Navigator window, double-click the rules/reporting_01.cga file to open the CGA Editor window to see the rules for your facade.
2. Locate the Lot rule, and find the two lines with report() commands.
   @StartRule
   Lot --> 
   	case p(greenspacePercentage/100):
   		report("Area.Greenspace",geometry.area)
   		GreenSpace
   	else:
   		report("Area.BuildUp",geometry.area)
   		BuildingLot

By using the geometry.area property as the reported value, both report commands report the current geometries area (the area of the lot). In the first case statement, the area is reported to the Area.Greenspace reporting variable; in the second (the else case), the area is reported to Area.BuildUp.

Note:

By using a dot (.) as a separator in a reporting variable, the report output displays both variables as well as their combination (Area) summed.

3. Select some footprints, and generate models.
4. Select an arbitrary set of generated models, and open the Reports pane in the Inspector window.



The Reports pane displays the two reported variables Area.BuildUp and Area.Greenspace, as well as the automatically added sum Area.

Note:

Report variables sharing the same group name before the dot character are automatically collected in a group variable.

• The N column displays the number of reports of the variables. The next column, %, displays that number as a percentage.
• The Sum column displays the sum of the reported values of each report variable. Again, the % column displays these results relative to each other as a percentage.
• The next three columns display additional statistic information about average, minimum, and maximum reported value per model.

Reports pane

The Reports pane displays reports depending on the current selection.

1. Select a different set of generated models, and compare the report results in the Inspector window.

   

2. Select a larger set of models.

   

3. In the rule parameters, change the value of greenspacePercentage to 75.
4. Reselect the models to see the changes reflected in the reports.

   

Additional reports for Gross Floor Area and Floor Area Ratio

Next, you'll add additional reports for Gross Floor Area (GFA) and Floor Area Ratio (FAR) to the rule file.

Set up

1. Open the Tutorial_11_Reporting/scenes/reporting_02.cej scene.
2. In the Navigator window, double-click the rules/reporting_02.cga file to open the CGA Editor window to see the rules for your facade.

Report GFA and FAR

The Lot rule stores the total area of the lot to the plotArea attribute for the building. This information will be used later in the rules to calculate the FAR.

@Hidden
attr plotArea = 0 # used to calc FAR

@StartRule
Lot --> 
	case p(greenspacePercentage):
		report("Area.Greenspace",geometry.area)
		GreenSpace
	else:
		set(plotArea, geometry.area)
		report("Area.BuildUp",geometry.area)
		BuildingLot

Compared to the rule file in the first section, the building mass is now split into floors. Find the FloorBottom rule. This rule (and the report() command) is called for every floor in a building, and the value of the reporting variable GFA is incrementally summed, resulting in the sum of all floor areas.

The same is true for the FAR, where the area is divided by the plotArea stored earlier, resulting in the ratio of total floor area to plot area.

FloorBottom -->
		report("GFA",geometry.area) 
	 	report("FAR",geometry.area/plotArea)

1. Select a generated building, and locate the Reports pane in the Inspector window.



In addition to the reported values for area from the first section above, the new FAR and GFA report variables are displayed. The value 16 in the N column denotes the number of times the report variable has been called for the selection; in this case, it equals the number of floors. The Sum column displays the calculated FAR (15.16) and the GFA (60118.35).

2. Select a generated building.
3. Use the slider to change the distanceStreet parameter.
4. Note how the values for FAR and GFA update to the new building model.

Change visualization modes

The rules/reporting_02.cga rule file allows you to switch between visualization modes for building models.

Select a building model, and change the vizMode rule parameter.

Report by usage type

You'll now extend reporting variables to different land-use types by floor.

1. Open the Tutorial_11_Reporting/scenes/reporting_03.cej scene.
2. In the Navigator window, double-click the rules/reporting_03.cga file to open the CGA Editor window to see the rules for your facade.

Add a land-use type

The following three attributes are added:

• The mixedOffice attribute globally controls the ratio of office space versus residential space in buildings with land-use type Mixed.
  attr mixedOffice = 0.2

• The landuseType attribute for buildings can be individually set to Office, Residential, or Mixed (Office and Residential). The initial value is set to randomly choose one land-use type equally.
  @Enum("Office","Mixed","Residential")  
  attr landuseType = round-shape
  	33% : "Mixed"
  	33% : "Office"
  	else : "Residential"

• The BaseFloors attribute controls the number of retail floors on the buildings base. Residential buildings have no base floors, and Office and Mixed land-use types have one to three base floors chosen at random.
  attr baseFloors = 
  	case landuseType == "Residential" : 0 
  	else : ceil(rand(0,3))

In the BuildingLot rule, you'll also add reports for Floor Height and Floor Count.

BuildingLot -->
	report("Floor Height", floorHeight)
	report("Floor Count", nFloor)
	setback(distanceStreet)
		{ street.front: OpenSpace 
		| remainder: Parcel }

Report by type

To be able to report floor areas by usage type, you'll extend the floorBottom rule with the argument type. Depending on this type, the area is reported to the corresponding usage type, denoted by GFA.usagetype. By using the prefix GFA, the report statistics will display the individual usage types as well as the summed total GFA. Also, you can assign different colors depending on the usage type to visualize their function in the generated model (Red: Retail, Green: Office, Blue: Residential).

FloorBottom(type) -->
	case type == "Retail":
		report("GFA.Retail",geometry.area) 
	 	report("FAR",geometry.area/plotArea)
	 	color("#ff4444") #Red
	 	FloorViz
	 	
	case type == "Office" || (type == "Mixed" && split.index < mixedOffice*split.total): 
		report("GFA.Office",geometry.area) 
	 	report("FAR",geometry.area/plotArea)
	 	color("#44ff44") #Green
	 	FloorViz
	 		
	else:
		report("GFA.Residential",geometry.area) 
	 	report("FAR",geometry.area/plotArea)
	 	color("#4444ff") #Blue
	 	FloorViz

You can use a special expression to differentiate between office and residential usage in the case of mixed land-use type. By using split.index (which equals the floor index in this context), you ensure that office floors are generated up to the desired floor index, controlled by the mixedOffice attribute.

1. Select and generate a building.
2. Change the landuseType parameter to get different representations of the building.









The new report variables are displayed in the Reports pane. In the following image, GFA.Office reports six occurrences (six office floors) totaling 38777.78 square meters of office floor space, which is 46.15 percent of the total floor area.

In the next section, you'll use a map layer to control land-use type distribution.

Reports controlled by land-use map layer

Rather than using a random distribution of land-use types, you'll now use a map layer to control the distribution.

Set up

Open the Tutorial_11_Reporting/scenes/reporting_04.cej scene.

Land-use type map layer

You can use map layers to control the global appearance of a city. The reporting_04.cej scene already contains the map layer you're going to use. Unhide the Landuse Map layer in the Scene Editor window to display it in the 3D viewport.

1. In the Scene Editor window, select the Landuse Map layer, and locate the layer attributes in the Inspector window.
   attr Office      = brightness > 0.66
   attr Mixed       = !Office && brightness > 0.33
   attr Residential = !Office && !Mixed
   
   attr landuseType = 
   	case Office : "Office"
   	case Mixed  : "Mixed"
   	else :        "Residential""

The first three attributes are controlled by the brightness of the map layer. For example, where the map is bright, Office evaluates to true.

As a result, the bright part in the center triggers office buildings, the middle part triggers buildings of mixed land use (retail, offices, and residential), and the outer part triggers residential buildings.

2. Examine the corresponding Tutorial_11_Reporting/rules/reporting_04.cga rule file.

The reporting_04.cga rule file adds rules that create different mass models depending on the land-use type, including Mixed, Office, and Residential, as well as their successor rules.

Citywide reports

1. Change the mixedOffice parameter from 0.2 to 0.3 (on all buildings), and generate the report.
2. Reselect all buildings to see the updated reports.

   

   The office GFA increased from 18.8 percent to 23.9 percent for the entire city, while the residential area decreased from 75.5 percent to 70.4 percent.

Export the report data

To export the reported data, complete the following steps:

1. Select the rows to export (press Shift and click, or press Ctrl and click).
2. Click Edit > Copy to copy the data to the clipboard (tab separated).
3. Paste the data into Microsoft Excel or another application.

   

Another option for exporting report data is to generate a .csv file that divides the report by object and displays the corresponding value for each category. Some objects contain multiple floors, and the .csv file will display the amount for that category for each building and floor.

1. Click inside the export_report.py script file in the CGA Editor window.
2. Click Python > Run Script to generate the .csv file.
3. Double-click the data/reports.csv file to open the Excel spreadsheet.