Tutorial 21: CSV import

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

This tutorial shows you how to import data from a CSV file and use it in CGA code with arrays.

To demonstrate CSV file import, you will use a rule that splits a building into floors and allows you to assign space usages to each floor. The CSV file contains a list of available space usages and their colors and floor heights. In the CGA code, the data from the CSV file is read into an array and is used to drive the rule and the corresponding UI in the Inspector.

Setup example

1. Open the Assign_Floor_Usages_01.cej scene.
2. Assign the Assign_Floor_Usages_01.cga rule file to the 2D building footprint using the Lot start rule.
3. Assign the Assign_Floor_Usages_01.cga rule file to the 3D mass model using the MassModel start rule.
4. Select both shapes.
5. In the Inspector, click the expand button to expand the floor_usages array attribute, which is initially empty.
6. Click the add button to add an element to the array. Click this button four times to create four floors with the default usage, Residential Single-Family.
   

   If you need to delete a row, right-click the gray array index on the side of each element and click Delete Row.

   

   The rule is applied to a 2D building footprint (left) and a 3D mass model (right). In this initial state, the rule has a default usage, color, and floor height assigned to each floor.

   

Import data from CSV file

To import data from a CSV file, complete the following steps:

1. Open the Assign_Floor_Usages_02.cej scene.
2. Open the Assign_Floor_Usages_02.cga rule file.
3. Look at the space usage data stored in the CSV file in /assets/usages.csv.

   The first column lists space usages, and the next columns contain colors and floor heights for each usage. This file is formatted with comma and new line delimiters, but many common delimiters, including commas, semicolons, tabs, and spaces, are also valid. The Excel file looks like this:

   
4. To read data from the CSV file, add the following code after the definition of default_floor_height located in the Constants and Functions section:

   // read usages data from csv file
   const usages_filename = "usages.csv"
   const usages_data = readStringTable(usages_filename)
   const numUsages = nRows(usages_data)

   The readStringTable function reads the CSV file data and returns a string array, and stores it in usages_data. The array’s dimensions are 15 by 3, which corresponds to the number of rows and columns in the data file. The nRows function returns the number of rows in the array.

5. Redefine the usages attribute and set it to the first column of the data array. The brackets are used to access a subset of array elements. Inside the brackets, rows are listed first and columns after. 0:numUsages-1 returns all the rows from 0 to 14. The 0 after the comma refers to the first column. Array indices start from 0.

   @Hidden
   attr usages = usages_data[0:numUsages-1,0]

6. In the Inspector, click each element in the floor_usages array and select the usage from the drop-down menu to change the usages per floor. The values in the list come from the usages array in the CSV file. This relationship is defined in the @Enum annotation above the attribute definition.

   @Enum(valuesAttr=usages)
   attr floor_usages = stringArray()

   
7. Define constants to store the data of the other two columns. You can add these lines below the usages definition. The floatArray function converts the string array into a float array.

   const colors = usages_data[0:numUsages-1,1]
   const floor_heights = floatArray(usages_data[0:numUsages-1,2])

8. Write functions to get the color or floor height of a given usage.

   getUsageColor(usage) = _getUsageColorFromIndex(findFirst(usages, usage))
   _getUsageColorFromIndex(usageInd) =
   	case usageInd==-1:           default_color
   	else:                        colors[usageInd]
   
   getFloorHeight(usage) = _getFloorHeightFromIndex(findFirst(usages, usage))
   _getFloorHeightFromIndex(usageInd) =
   	case usageInd==-1:           default_floor_height
   	else:                        floor_heights[usageInd]

9. Use the data to get the proper floor height for each usage. In the CreateFloor, FloorMass, and SplitMassModel rules, replace default_floor_height with the following code:

   getFloorHeight(floor_usages[floorInd])

10. Use the data to color each floor according to its usage. In the FloorMass rule, replace the two occurrences of default_color with the following code:

    getUsageColor(floor_usages[floorInd])

11. Press Ctrl+S to save the CGA rule file.
12. Select the shapes.
13. Click Generate.

    

    

    The rule now uses the data from the imported CSV file to determine the floor height and color of each floor according to the specified usage per floor.

Create a dashboard

To create a dashboard, complete the following steps:

1. Fix the reports so they report usages with their corresponding colors. In the FloorMass rule, replace usages[0] with the following code:

   floor_usages[floorInd]

2. Save the CGA rule file and generate the models again.
3. Create a dashboard card to visualize the gross floor area (GFA) per usage.
   1. Click Window > Dashboard.
   2. Click Add a Chart.
   3. Click Bar Chart.
   4. Under Icon & Title, type GFA By Usage.
   5. Under Report, click GFA.*.
   6. Under Unit, type sqm.
   7. Click Add Card to finish.