Back to Top

Tutorial 11: Reporting

In this topic

  1. Work with area reports
  2. Explore additional reports for gross floor area and floor area ratio
  3. Report by usage type
  4. Control reports with a land-use mapping layer
  5. Export the report data

To access the tutorial projects in ArcGIS CityEngine, open CityEngine and click Help > Download Tutorials and Examples in the main menu. After choosing a tutorial or example, the project is automatically downloaded and added to your CityEngine workspace.

Report table

The reporting feature expands CityEngine beyond the generation of geometry. The feature 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 enhance them by generating numerical reports, such as .csv files for further processing in Microsoft Excel or a similar spreadsheet app. Similar to 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 you can create rules that are only for reporting without creating any geometry.

With the report operation, you can create reporting values for building design or master plan properties. This makes reporting completely generic and customizable. For example, you can create reports that include values such as gross floor area (GFA), floor area ratio (FAR), number of units, and land use mixes. Also, by changing the urban design—that is, regenerating the models—the reports are updated automatically and immediately.

In this tutorial, you’ll go through an example scenario in which a master plan is built from the beginning. After, you’ll learn how reporting functionalities are used to analyze the existing geospatial data.

Work with area reports

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

Open the area report scene

To open the area report scene, do the following:

  1. Expand the Tutorial_11_Reporting tutorial folder in the Navigator window.
  2. Double-click the reporting_01.cej scene in the scenes folder to open the scene in the Viewport window.
  3. Click Yes when prompted if you want to regenerate the models:

    Overview of the scene with generated models

    The scene displays shapes with simple extrusion rules applied and a green space percentage set. It was generated using a spiral pattern with the grow street feature of CityEngine.

    For the rest of this tutorial, you will not need to show the graph networks, so press F10 to turn off the Graph Networks visibility setting under Visibility settings Visibility settings.

Explore the Area.Greenspace and Area.BuildUp reports

To explore the reporting in the CGA rule, do the following:

  1. Double-click the reporting_01.cga file in the rules folder to open the rule in the CGA Editor window.
    Find the Lot rule and explore the report operation in both statements:

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

    In the case statement, the p function returns either true or false values depending on the probability and the current shape seed value. If the value is true, the shape will be generated as green space and the current geometry area (the area of the lot), calculated by the geometry.area function, is reported as the Area.Greenspace variable. Otherwise, it will be generated as a building and the geometry.area function gets reported as the Area.BuildUp variable instead.

    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.

  2. Click the Select tool Select tool (Q) to select some of the models.
  3. Expand the Reports section in the Inspector window:

    BuildUp and Greenspace area reports displayed in the Inspector window

    The Reports section displays the Area.BuildUp and Area.Greenspace reported variables, as well as the automatically added sum Area. The columns in the reports have the following descriptions:

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

    Note:

    Report variables sharing the same group name before the dot character are automatically collected in a group variable. For nongroup variables, the % columns for the N and Sum values are displayed as 0.00.

  4. Select a different set of generated models, and compare the results in the Reports section.
  5. Explore the Rules section in the Inspector window.

    The greenspacePercentage attribute value is set to 30 by default, which means that 30 percent of the lots are dedicated to green spaces:

    greenspacePercentage set to 30

    The greenspacePercentage attribute determines what percentage of the lots are reserved for green spaces, or open-space areas; in other words, what percentage of the lots remains unbuilt.

    Depending on the probability and the seed value, the percentage varies slightly. When you update the seed values (Shapes > Update Seed or Ctrl+Shift+G), the values change, as well.

  6. Change the value of the greenspacePercentage attribute to 75:

    Reports with greenspacePercentage set to 75

    There are now significantly more green spaces in the scene and the Area.Greenspace values have increased accordingly in the Reports section.

Explore additional reports for gross floor area and floor area ratio

Next, you'll explore how the GFA and FAR can be reported.

  1. Open the reporting_02.cej scene.
  2. Open the reporting_02.cga rule file.

    In the Lot rule, the set operation is used to store the total area of the lot to the plotArea attribute for the building. This information will be used later in the FloorBottom rule 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 therefore also the report() operation , are called for every floor in a building. Hence, the value of the GFA reporting variable is incrementally summed, resulting in the sum of all the floor areas.

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

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

  3. Select a generated building and explore the Reports section:

    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, the new FAR and GFA report variables are displayed. The value 18 in the N column indicates the number of times the report variable was called for the selection; in this case, the value is the number of floors. The Sum column displays the calculated values for FAR and GFA. Notice that the % columns for FAR and GFA display as 0.00 because they do not have group variables.

  4. Move the distanceStreet slider to change the parameter:

    GFA and FAR with distanceStreet changed

    The values for FAR and GFA update, reflecting the changes to the building model.

  5. To change the model visualization, click the vizMode drop-down menu in the Rules section.

    You can visualize the models with one of the following representations:

    massOnly

    Mass model without floors:

    massOnly
    floors

    Model with only floors:

    floors
    massAndFloors

    Model with mass and floors:

    massAndFloors

    Changing the visualization has no effect on the reported values when using this rule file.

Report by usage type

Next, you'll look at how the rule can be extended to visualize and report different land-use types by floor.

Open the reporting_03.cej scene and the reporting_03.cga rule file.

Add land-use types

In the reporting_03.cga rule, the following three attributes are added:

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

    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:

    @Group("Building attributes", 1) @Enum("Office","Mixed","Residential")
attr landuseType = 
	33% : "Mixed"
	33% : "Office"
	else : "Residential"

  • The BaseFloors attribute controls the number of retail floors at the base of the building. 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, the Floor Height and Floor Count reports are added:

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, the floorBottom rule is extended with the argument type. Depending on the type, the area is reported to the corresponding usage type, indicated by GFA.usagetype. By using the prefix GFA, the report statistics 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.

Change the land-use type

To change the land-use type in the Inspector window, do the following:

  1. Select a model.
  2. Click the landuseType drop-down menu in the Rules section to change the representation of the building.

    You can change the landuseType parameter to one of the following types:

    Residential
    Residential land-use type
    Office
    Office land-use type, with three retail floors
    Mixed
    Mixed land-use type, with 20 percent office floors, mixedOffice = 0.2

  3. Change the mixedOffice percentage value from .2 to .6.

    The number of green office floors in the scene has increased:

    Mixed land-use type, with 60 percent office floors, mixedOffice = 0.6

    The new report variables are displayed in the Reports section. The GFA.Office reports that there are nine occurrences (nine office floors) with an increase in the total square meters of office floor space and the percent of the total floor area.

Control reports with a land-use mapping layer

In this section, rather than using a random distribution of land-use types, you'll use a mapping layer to control the distribution.

Use a land-use type mapping layer

You can use a mapping layer to control the global appearance of a city.

  1. Open the reporting_04.cej scene.
  2. Check the Landuse Map layer visibility check box in the Scene Editor window to display it in the Viewport window:

    Landuse Map layer, left; grayscale map image, right; map layer in 3D viewport

  3. Select the Landuse Map layer in the Scene Editor window.
  4. Expand the Layer Attributes section in the Inspector window: 

    attr landuse = map_01(red, 0.0, 1.0)
attr Office = case landuse > 0.66: true else: false
attr Mixed = case !Office && landuse > 0.33: true else: false
attr Residential = case !Office && !Mixed: true else: false 

attr landuseType = 
	case Office : "Office"
	case Mixed  : "Mixed"
	else :        "Residential"

    The Office, Mixed, and Residential attributes are controlled by the brightness of the map which is determined by the red channel of the map. For example, where the map is bright, Office evaluates to true.

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

    With the same method, the height of the buildings is controlled by the BuildingHeight mapping layer. If you make the layer visible, you can see the correlation between the map and the generated buildings.

  5. Open and explore the reporting_04.cga rule file.

    In comparison to the previous rule reporting, the reporting_04.cga rule renders the floors in a different color and also creates different mass models depending on the land-use type:

    ...
Subparcel -->
	case landuseType == "Office": Office
	case landuseType == "Mixed" : Mixed
	else: Residential

Mixed -->
	[ extrude(baseFloors*floorHeight) RetailBase ]
	t(0,baseFloors*floorHeight,0) 
	set(nFloor,nFloor-baseFloors)
	offset(-5,inside) LUShape
...

    The following examples show the Office, Mixed, and Residential visualizations of land-use types for buildings:

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

Create citywide reports

Next, you'll create reports for all spaces and buildings citywide.

  1. Select all the shapes in the scene with the Select tool Select tool (Q).

    You can also select all the shapes by selecting the Blocks layer in the Scene Editor window and clicking Select Objects.

  2. Click the Generate tool Generate (Ctrl+G) to generate the spaces and buildings for all the lots:

    Entire city generated with colored floors visualization

    The mixedOffice attribute is set to 0.2 percent by default. You can see the results in the scene and the Reports section:

    By selecting all building models, report statistics are displayed citywide.

  3. Keeping all the buildings selected, change the mixedOffice attribute from 0.2 to 0.6.

    The buildings automatically regenerate:

    Report after changing mixedOffice to 0.6 and selecting all models

    The reported values update with the regeneration of the buildings and spaces, and the GFA.Office areas increased while the GFA.Residential areas decreased.

Export the report data

To export the reported data, complete the following steps:

  1. Select the rows in the report table to export. (Press Shift and click, or press Ctrl and click. Press Ctrl+A to select all the rows.)
  2. Press Ctrl+C to copy the data to the clipboard (tab separated).
  3. Press Ctrl+V to 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. Ensure all the buildings are selected.
  2. Click Scripts > Run Script in the main menu.
  3. Click export_report to generate the .csv file.
  4. Double-click the reports.csv file in the data folder to open the Excel spreadsheet:

    Report data in exported .csv file

In this tutorial, you learned how to do the following:

  • Calculate and report values such as the area of a lot.
  • Explore additional reports for GFA and FAR.
  • Report by usage type and create visualizations for different land-use types by floor.
  • Control land-use type and reports using a mapping layer.
  • Export reports to Microsoft Excel or a similar spreadsheet app.

To continue your learning with CityEngine, see the complete CityEngine tutorial catalog.

Feedback on this topic?

In this topic
  1. Work with area reports
  2. Explore additional reports for gross floor area and floor area ratio
  3. Report by usage type
  4. Control reports with a land-use mapping layer
  5. Export the report data