CityEngine Part 2:
Procedural design with CityEngine
CityEngine is a tool that allows to generate shapes procedurally, i.e. by writing the rules that describe them instead of creating their geometry directly. This strategy, also known as grammar-based modeling is particularly useful when shapes that obey certain standardized rules need to be created in large numbers, which makes it very suitable for the generation of urban environment. CityEngine offers its own programming language, called CGA shape grammar, that is specifically created for writing rules for the generation of architectural 3D content.
> CityEngine Tutorials: Here you can find a series of tutorials that walks you through the main aspects of working in the CityEngine, and the basics of procedural modelling using CGA rules.
Getting environment data
The initialization of the design environment in CityEngine can be easily done by importing data from ArcGIS or other online sources. This brings in streets, blocks, parcels, existing buildings, height-map and other elements along with their attributes for further processing.
> More information about importing data to CityEngine:
Video tutorial: CityEngine How-To | Get Map Data
ArcGIS Blog post: Import Terrain, Imagery & OSM data into CityEngine
CityEngine tutorial: Import streets
Refining urban layout
Street networks can be downloaded or imported from a variety of sources, as well as generated using the street grow feature. The street network geometry and attributes create the urban layout: street lanes, sidewalks and parcels. CityEngine offers a variety of tools for refining the street network both manually (such as drawing and editing streets, and creating streets on multiple levels) as well as automatically (such as cleaning up streets, aligning streets to terrain, or simplifing street graphs). Analysis tools are also available: computation of global integration, local integration and in-between centrality.
CGA rules
Modular approach
Once the context has been prepared, we can start creating the rules and applying them to the urban layout shapes for the generation of the city. We started experimenting with simple rules but soon it became clear that in order to achieve the desired details and diversity more complex CGA code would be required. Before going any further, we took some time to think of a way to organize that code to make sure that it doesn’t become hard to handle. Thus we decided to structure the shape grammar code in a modular way: separate the various aspects of our design in smaller blocks of code, which are then connected to generate the buildings and the environment. These blocks of code that form separate CGA rules can be combined in various ways to achieve more morphological diversity with less coding through different combinations.
The typology we came up with is organized by means of several categories: envelope; volume; façade; green space; landscape; ground floor plan; interior plan; street front. For each category we created a number of design alternatives based on the use such as residential; mixed use; commercial; industrial, or based on the position such as standard; on view corridor; transitory.
Envelope
The envelope represents the building’s outer shape if it were to develop to the maximum of its capacity according to the city rules. The parameters set in the envelope are the height, offset from street, shape, setbacks, lot coverage and orientation of the building. We specified different types of envelopes according to the position of the building in regards to the street network: standard, on view corridor or transitory, and we also added exceptions.
Volume
The volume rules are subtractive operations on the mass of the envelope that refine the outer shape of the building and determine the position of walls, doors, windows, slabs, green space etc.
Façade
The façade rules add detail to the building elements that were defined in the volume. For example, the surface that represents the position of a window is replaced by glass, frame and shading elements.
Green space
The green space distributes plants in the designated areas using CityEngine built-in plant libraries.
Ground floor plan
The ground floor plan generates a 3D plan and building structure on the ground floors from the edges of the building envelope, in order to enhance the street level views.
Interior plan
Walls and structural elements are generated in the interior of buildings that have large glazing surfaces on their facade, in order to create depth and shadows for more realistic visualization.
Landscape
The landscape rules refine the free space around the buildings. While CGA rules are very handy for creating straight lines, they have limitations in the creation of curves and free form shapes. A strategy to overcome this is to create OBJ assets using a 3D modeling tool (in our case Rhino-Grasshopper) that are then imported in CityEngine as start shapes and are then processed further with CGA rules.
Organisation of CGA rules
Now that we have seen what blocks of code we have, let’s take a look at how these are connected. This can be done in various ways. In our project we chose to have as the assigned rule file the envelope and make all other rules dependent on it. The envelope controls the attributes (for example height, shape, use of floors, level of detail), assigns further rules according to the building’s specific attributes and determines what shapes will be passed on to each rule. Parameters are also propagated from the envelope to the other rules.
Organizing the code with one main rule that assigns sub-rules has many advantages. Firstly, features of the building can be turned on and off at any moment, so the user can choose which level of abstraction to work on. For example, it is possible to work on the massing of the buildings (envelope rule) at any given moment without having to generate fully detailed buildings, by turning off all the subsequent rules. Also, the buildings can change forms and characteristics just by changing attributes, without the need to assign a different rule file. What is more, combining smaller rules instead of creating big end-to-end rules leads to the formation of small rules that are easier to isolate, modify and debug.
Example
We present a simplified example for the generation of a building that is created with the logic described above, with an envelope, a volume, and a façade rule.
We start by creating three new CGA files in our rules folder in a CityEngine project.
The rule file envelope.cga creates the outer shape of the building.
/**
* File: envelope.cga
*/
version "2019.0"
attr lot_coverage_parameter = 0.50
attr building_height = 40
Lot -->
offset(-rand(2,3.5))
comp(f){inside: Lot_for_building
|border: Free_space}
Lot_for_building -->
50%: #orthogonal shape
alignScopeToAxes(y)
center(xz)
split(x){'lot_coverage_parameter: Footprint
|~1 : Free_space}
else: #shapeL
alignScopeToAxes(y)
shapeL(lot_coverage_parameter*scope.sz, lot_coverage_parameter*scope.sx)
{shape : Footprint
|remainder: Free_space}
Free_space -->
color("#4A966C")
Footprint -->
extrude(building_height)
Complete_envelope
Then we want to call our last shape, or leaf, called ‘Complete_envelope’ in the next rule (volume.cga) for further processing. The first thing we need to do is connect the envelope with the volume and façade rules, so we import them at the beginning of envelope.cga. Note that if you drag and drop the rule files from the navigator into the file envelope.cga then the imports appear automatically. And then we add the rule that points towards the file volume.cga.
/**
* File: envelope.cga
*/
import volume: "volume.cga"
import facade: "facade.cga"
Complete_envelope -->
volume.Create_volume
This means that the ‘Complete_envelope’ shape is passed on to the volume.cga and the ‘Create_volume‘ is applied to it. As mentioned, the volume rule is a subtractive transformation of the mass of the envelope that refines the outer shape, so that the building remains within the boundary of the desired development. Here’s our volume.cga rule.
/**
* File: volume.cga
*/
version "2019.0"
attr height_ground_floor= 5.5
attr height_floor = 3.1
attr slab_thickness = 0.4
Create_volume -->
split(y){height_ground_floor: Ground_floor
|{~height_floor : Floor }*}
#--- Ground floor
Ground_floor -->
split(y){~1 : Ground_floor_volume
|slab_thickness: Slab}
Ground_floor_volume -->
comp(f){bottom: Bottom_srfc_ground}
Bottom_srfc_ground -->
offset(-4)
comp(f){inside: Offseted_ground
|border: color("#4A966C") End.}
Offseted_ground -->
reverseNormals
extrude(height_ground_floor - slab_thickness)
comp(f){side: Enclosure_ground_floor}
##--- All other floors
Floor -->
split(y){~1 : Floor_volume
|slab_thickness: Slab}
Floor_volume -->
comp(f){bottom: Floor_srfc}
Floor_srfc -->
offset(-2)
comp(f){inside: Offseted_floor
|border: NIL}
Offseted_floor -->
reverseNormals
extrude(height_floor - slab_thickness)
comp(f){side: Enclosure_floor}
The next step is to call the end shapes of the volume to the façade rule for further processing. This will be done again in the file envelope.cga, as this is our main rule set that manages all the other rules. To do that we need to add the following lines of code to envelope.cga:
/**
* File: envelope.cga
*/
volume.Slab -->
facade.Slab
volume.Enclosure_ground_floor -->
facade.Enclosure_ground_floor
volume.Enclosure_floor -->
facade.Enclosure_floor
And finally, we can write our facade.cga that adds detail on the shapes that are outputted by the volume.
/**
* File: facade.cga
*/
version "2019.0"
Slab -->
color(0.5,0.5,0.5) Slab_End.
Enclosure_floor --> #recursive subdivision of enclosure surface to walls + openings
split(x){rand(0.5,3): Wall
|rand(1,5) : split(x){~1.3: Opening((split.index+1)/split.total)}*
|~1: For_further_subdivision}
For_further_subdivision -->
case geometry.area < 9: Wall
else : Enclosure_floor
Enclosure_ground_floor -->
split(x){~1.3: Opening((split.index+1)/split.total)}*
#Refine Wall
Wall -->
extrude(-0.3) color("#FFFFFF") End.
#Refine Opening
Opening(n) -->
split(y){{0.1: Mullion
|~2: Glazing(n)}*
|0.1: Mullion}
Glazing(n) -->
case n == 1: #last glass panel, mullion in both sides
split(x){0.11: Mullion
|~1 : Glazing_material
|0.11: Mullion}
else: #all other panels, mullion only in one side
split(x){0.11: Mullion
|~1 : Glazing_material}
Mullion -->
color(0.4, 0.4, 0.4)
extrude(0.05)
Mullion_end.
Glazing_material -->
set(material.color.r, 0.5)
set(material.color.g, 0.8)
set(material.color.b, 1)
set(material.opacity, 0.6)
Once we’ve started creating detailed buildings it becomes useful to be able to turn on and off features according to the task at hand, so that we can always work on the desired level of abstraction and avoid waiting for the generation of unnecessary details. To do that, we add some Boolean parameters to envelope.cga that will be used in conditional statements to decide if the shapes are called or not by the sub-rules.
/**
* File: envelope.cga
*/
@Order(1)@Enum(true, false)
attr create_volume = true
@Order(2)@Enum(true, false)
attr create_facade = true
#volume
Complete_envelope -->
case create_volume == true:
volume.Create_volume
else:
Envelope_end.
#facade
volume.Slab -->
case create_facade == true:
facade.Slab
else:
Slab_end.
volume.Enclosure_ground_floor -->
case create_facade == true:
facade.Enclosure_ground_floor
else:
Ground_floor_end.
volume.Enclosure_floor -->
case create_facade == true:
facade.Enclosure_floor
else:
Floor_end.
Once we select the building in the inspector window we see all the parameters that we have set, and there we can manually change the attributes. Note that if we select more than one buildings that have the same parameters, then we can change them for all the buildings with one move. A handy tip for selecting all the buildings that are generated by the same rule is to right click on one building and then click on ‘Select Objects with Same Rule File’.
We can continue adding rules that are controlled by the envelope, for example ground floor plan, interior plan, landscape, green space, rules that add furniture and so on. Also, we can create variations of envelope, volume or façade rules with the same inputs and outputs and try different combinations of the code blocks. For example, if we create a second volume rule, we can add on the envelope.cga a parameter (volume_type) and a conditional statement that allows us to change the volume rule, while the envelope and the façade remain the same. Here’s an example of an alternative volume rule with the same envelope and façade rules.
/**
* File: envelope.cga
*/
@Order(3)@Enum("Type1", "Type2")
attr volume_type = "Type1"
Complete_envelope -->
case create_volume == true:
case volume_type == "Type1":
volume.Create_volume
else:
volume.Create_volume_2
else: Envelope_end.
Level of detail (LOD)
It is a good practice to keep the polygon count (i.e. the detail) of the shapes as low as possible, especially if they are repeated many times over the scene, because that can lead to a heavy scene that can be difficult to navigate or export. To see the number of polygons of one or more shapes, press ‘d’ twice while having the viewport active. On the bottom of the viewport you can see the total number of polygons for the selected shapes. However, for many applications, such as viewing a scene in virtual reality (VR), there is the need to create highly detailed buildings that have all the necessary information for close views. As a result, it is useful to be able to control the level of detail (LOD) of the shapes, so that we can decide how much complexity we want in each shape depending on how close they are to our point of interest or cameras. In other words, we can create alternative options for the generation of geometry depending on how detailed we need each building to be. Firstly, we add a parameter in the envelope.cga that controls the level of detail.
/**
* File: envelope.cga
*/
@Enum("High", "Low")
attr level_of_detail = "High"
In which sub-rule/rules alternative options need to be created for the generation of geometry depends on the characteristics of each design. In our example the detail is added on the façade rule, so there we will provide an alternative option of how the openings can be generated when less detail is required. On the facade.cga we create the same parameter.
/**
* File: facade.cga
*/
@Enum("High", "Low")
attr level_of_detail = "High"
As the import of the façade in the envelope is left to default, attribute values from the importing rule file (envelope.cga in this case) are propagated to the imported rule file (facade.cga). This means that any change we make on the parameter level_of_detail in envelope.cga automatically overwrites the value of the same parameter in facade.cga. (Find more information about the import of CGA rules in the CityEngine documentation). Then we add a low detail option for the openings to facade.cga:
/**
* File: facade.cga
*/
Glazing(n) -->
case level_of_detail == "High":
case n == 1: #last glass panel, mullion in both sides
split(x){0.11: Mullion
|~1 : Glazing_material
|0.11: Mullion}
else: #all other panels, mullion only in one side
split(x){0.11: Mullion
|~1 : Glazing_material}
else:
case n == 1: #last glass panel, mullion in both sides
split(x){0.11: Mullion
|~1 : Glazing_material
|0.11: Mullion}
else: #all other panels, mullion only in one side
split(x){0.11: Mullion
|~1 : Glazing_material}
Mullion -->
case level_of_detail == "High":
color(0.4, 0.4, 0.4)
extrude(0.05)
Mullion_end.
else:
color(0.4, 0.4, 0.4)
Mullion_end.
High LOD, 15.400 polygons (left), low LOD 3.065 polygons (right)
Now by selecting the building and changing the level_of_detail parameter on the envelope.cga we see a substantial difference in the polygon count, in this example approximately 15.000 versus 3.000 polygons.
Reporting and view analysis tools
By bringing everything together, we now have created a custom set of procedural tools for generating buildings and public spaces specific to our project. During the formation of this computational basis for the project a series of design decisions had to be made regarding the organization of the rules and their content. At the same time, many more design decisions are required for the completion of the project in order to specify how to use these rules in a reasonable and consistent way to achieve the design goals. This process is facilitated by a range of analysis tools offered in CityEngine. A very useful tool for analysis is the reporting feature of CityEngine that allows to extract quantified information from the models in order to evaluate the goals that are achieved. Another example of analysis tools are the visibility analysis tools offered in CityEngine that compute in real time surfaces that are visible or hidden to an observer with a given position and width of view.
ESRI.lib: a ready-to-use procedural modeling library
CityEngine includes a library of rules and assets called ESRI.lib. The library can be used directly from CGA rules and can be customized according to specific project needs. The library includes assets like ground cover, plants and street furniture, as well as CGA rules for buildings, façades, streets and plant distribution. To install and manage ESRI.lib in CityEngine go to File > Manage ESRI.lib.
An example of a handy feature in ESRI.lib is the library of plants (82 species) that are available in different representations, as well as a rule for distributing them with various mixture and density options (Plant_Loader.cga, Plant_Distributor.cga).
We can import and use those in our rules in the same way that we imported and used multiple rules in the envelope.cga at the previous example. For example, once we have downloaded ESRI.lib and want to connect our rule to the Plant_Distributor.cga then we can import it in our rule and then we can set its parameters and use its functionalities.
# import Plant_Distributor from ESRI.lib
import Plant_Distributor: "/ESRI.lib/rules/Plants/Plant_Distributor.cga"
Create_garden -->
set(Plant_Distributor.Density, 1)
set(Plant_Distributor.Mix , "Random Shrub")
Plant_Distributor.Generate
CityEngine tutorials and examples
Comprehensive tutorial and example projects are also available for download in CityEngine. They are useful for learning how to use CityEngine and they can also be used as a source of ready-to-use rules and assets. To download them, go to Help > Download Tutorials and Examples. For example, in the Example_Complete_Streets__2016_0 you can find a collection of rules for creating streets along with textures, street furniture, street lights, cars and other useful assets.
Continue reading: Part 3 – Visualization strategies with Unreal Engine
