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.

Report table

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:

Street network
Parcels from a street network

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

Overview of the scene with generated models

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.
    Lot --> 
    	case p(greenspacePercentage/100):
  3. 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.

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

  4. Select some footprints, and generate models.
  5. Select an arbitrary set of generated models, and open the Reports pane in the Inspector window.
  6. BuildUp and Greenspace area reports displayed 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.


    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.
    BuildUp and Greenspace area reports on a different selection
  2. Select a larger set of models.
    Reports on a larger area, with greenspacePercentage set to 30
  3. In the rule parameters, change the value of greenspacePercentage to 75.
  4. Reselect the models to see the changes reflected in the reports.
    Reports with greenspacePercentage set to 75

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.

attr plotArea = 0 # used to calc FAR

Lot --> 
	case p(greenspacePercentage):
		set(plotArea, geometry.area)

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 -->
  1. Select a generated building, and locate the Reports pane in the Inspector window.
  2. FAR and GFA for a single selected building shown in the Reports pane

    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).

  3. Select a generated building.
  4. Use the slider to change the distanceStreet parameter.
  5. 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.

Different visualization modes set in the Inspector window via the 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.
    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)
		{ 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":
	 	color("#ff4444") #Red
	case type == "Office" || (type == "Mixed" && split.index < mixedOffice*split.total): 
	 	color("#44ff44") #Green
	 	color("#4444ff") #Blue

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.
  3. Residential land-use type
    Office land-use type, with three retail floors
    Mixed land-use type, with 20 percent office floors, mixedOffice = 0.2
    Mixed land-use type, with 60 percent office floors, mixedOffice = 0.6

    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.

    Gross Floor Area reported by usage type

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.

Landuse Map layer, left; grayscale map image, right; map layer in 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""
  2. 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.

  3. Examine the corresponding Tutorial_11_Reporting/rules/reporting_04.cga rule file.
  4. 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.

    Buildings with different land-use type, left: Office, center: Mixed Office, right: Residential

Citywide reports

Entire city generated with mass only visualization
Entire city generated with colored floors visualization
By selecting all building models, report statistics are displayed citywide.
  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.
    Report after changing mixedOffice to 0.3 and selecting all models

    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.
    Report data pasted into an Excel spreadsheet

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.
    Report data in exported .csv file