Tutorial 13: Facade wizard

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.

Part 1: Intro and Basic Example

The Facade Wizard is a handy tool which lets the user create complex CGA Facade rule templates. The great advantage is that no actual CGA code has to be written by the user, but it is automatically produced in the background by the CityEngine. Very complex structures can be generated very efficiently and easily.

The beauty of the process is that CGA rules can be created which can adapt to any given facade geometries.

In the following picture, we see an example facade picture and the resulting models after the rule file has been assigned to different sized building facades. Note that the number of windows adapts to the facade sizes.

Adaptable facade template

With the Facade Wizard, it is easy to create large pools of facade templates that can always be reused - This is most welcome, especially in upcoming projects!

Facade wizard

  1. Create a new scene file File > New > CityEngine scene.
  2. First, we import the mass model of the National Bank building in Zurich. To do so, click on the asset file NationalBankMassModel.obj with the right mouse button and click Import.
  3. The OBJ importer opens. Unselect the Import as static model option and click Finish.

    The building should now be visible near the origin of the scene.

    The mass model as starting point:

    The mass model of the bank
  4. Select the short side facade shape by double clicking it.
  5. Click Shapes > Separate Faces to separate the faces of the model.
  6. Open the Facade Wizard under Window > Show Facade Wizard.
  7. Click on the New Facade from Image button New facade from image in the Facade Wizard and open the Plane_MG_3_TX.jpg located in the assets folder.
  8. Click OK to use default region width.

Ground floor splits

Next, you will use the Split tool to cut out specific regions of the facade.

  1. Verify that Y Split button Y Split is selected, and create horizontal Splits 1 and 2 to block out the main building masses into the ground floor, upper floors, and roof part.
    Splits 1 and 2
  2. Next, create ground floor areas; two left windows, the entrance, and the two right windows.
    1. Select the X Split button X Split .
    2. With the X Split blue line, click on the left on the ground floor to create Splits 3 and 4 to separate the two (repetitive) left windows.
    3. Continue to create vertical splits and click on the right side of the entry to create Split 5.
    4. Finally, click on the ground floor at the very far right to create Split 6 and define the two (repetitive ) right windows.
      Splits 3 through 6

    To speed up the process of selecting the correct split type, you can also cycle through the split types by using the left and right arrow keys!

    After splits have been set, you can go back to the split line and edit it's position interactively to refine the positions.

  3. Click the X Repeat button X Repeat to change the split type to repetitive splits.
    1. Create the red repetitive Splits 7 and 8.
    2. With repetitive splits, the blue areas are the ones being repeated. In this example, choose the area where the light does not show through the windows. Right-click on the region and choose Select region. Repeat the same steps for the right (repetitive) windows.
    Ground floor with repetitive splits

Upper floor splits

  1. For the upper floors, to create Splits 9 and 10 click the vertical split button Vertical split and press SHIFT to snap to Splits 3 and 6 that were created on the ground floor level.
  2. Click the Y Repeat button Y repeat one time inside the upper floors area to set up the 2 remaining horizontal repetitive Splits 11 and 12.
    Splits 11 and 12
  3. Click the X Repeat button one time to create the 9 vertical repetitive splits.
  4. Choose one of the darker windows and set the repetitive region by choosing Select Region
    Set repetitive region
  5. Use the X Split and Y Split tools to isolate the window.
  6. On the roof part, split off the roof ledge ornament.
    Roof ledge ornament split
  7. To add a more volumetric appearance to the so far flat surface, you can define an offset by setting the zAdjust value per split tile. Simply click the desired shape and slide left or right while holding the left mouse button to edit the value. You can do this on as many parts of the building as you like.

    Using the zAdjust functionality:

    zAdjust functionality
  8. Click on the Save Rules and Textures for Current Facade button Save Rules and Textures for Current Facade to generate a .cga file for the facade.
  9. Click on the viewport tab and assign the rule to the facade shape.
  10. Select the shape and generate it to see the volumetric facade.
  11. Click the show hide shapes button to hide the original shape.

    In the Visibility Settings, click Show/Hide Shapes (F11) Show/hide shapes to hide the original shape:

    Original mass model face with the final facade rule

    In order to see the volumetric facade correctly, you have to deselect the Show/Hide Shapes (F11) button. In contrast, when you want to select other facades, you must activate it again.

Part 2: Advanced Facade Creation


In this example, we will load an image file into the Facade Wizard to create a facade rule template. Later, we will create a simple mass model building rule and trigger the previously generated facade rule.

Facade Analysis and rule creation

The original facade texture file we will be using will be an Advanced Facade:

Advanced Facade

It has a nice set of difficulties which a user will encounter often when creating more complex facades with the Facade Wizard.

Most of the times, when using the Facade Wizard, it is necessary to carefully study the facade details, like numbers of window subdivisions, repetitions in ornamental details or uneven floor heights, to find the best way to split up the structure. Really take a few minutes to think about this strategically!

In the following scheme, you can see one possible approach towards the creation of the main facade subdivision.

  • Green: single tile, non-repetitive
  • Blue: repetitive tile [x or y]
  • Red: nested repetitive tile [ tileable in x and y ]
  • Yellow: rule symmetry [will be linked in Rule refinement section.]

Main facade structure: An analysis of single splits, repetitive splits and rule symmetry:

Main facade structure

Unlike in the previous example, we start directly by selecting a texture file.

  1. Open the Facade Wizard under Window > Show Facade Wizard.
  2. Click the New Facade from Image button New facade from image and navigate to the file AdvancedFacade.tif.

    A small window pops up, called Set Region Width, where you can enter the total width of the facade, so that the split dimensions also make geometric sense. Please note that this value can be edited later in the process. Often, you do not know the exact dimension of the facade, but you know that a window has a specific size. In that case just enter the value when you have reached the scope of this single window.

  3. Set the value to 20 for now, we will set this again later.
    Set Region Width dialog box


Chances are great that you will be working with facade photographs which are tilted and none of the main lines are correctly vertical or horizontal. In these cases, you can use the Crop Image Tool to create an orthogonal texture.

  1. Select the Tutorial_13_Facade_Wizard__2015_0\Images\facadeFoto.jpg image in the File Navigator and click Shapes > Crop Image or select File Navigator > Tutorial_13_Facade_Wizard__2015_0 > Images and right-click the facadeFoto.jpg and choose Crop Image.
  2. Once the Crop Image Tool is started, it automatically analyzes the image for perspective lines and tries to find a possible Facade area.

  3. Edit the rectangular region in the left window, which automatically updates the result on the right side. Once you are happy with the cropped extent, save your file.
Crop Image dialog box

EXCURSUS END: --> We have learned that images can be rectified within the CityEngine. This allows a more streamlined process without having to leave the software.

Single splits

To allow the facade to increase in size and have the texture repeat, you will add the single and repetitive splits and define splits as absolute or floating.

  1. Use the X Split and Y Split tools to add single splits to the facade.
    First sequence of SINGLE splits

    The right vertical upper floor part is left without splits. That part is the same as on the left side and will be solved later in this tutorial using rule relinking. The same will happen with the tile on the left side of the entrance, where we will link one of the tiles from the right side.

  2. Define the vertical size for the second and fourth upper floors as absolute.

    In this first split series, it is important that we define split types correctly as either absolute or floating. We want the facade to tile afterwards, so the parts which need an absolute value must be defined as absolute splits. To define whether a split is an absolute or floating distance, you cycle through the types by using the up and down arrow keys.

    • absolute: yellow line
    • floating: yellow dashed line

    Do this right after you have clicked to define the split and hover over the area of the last split and hit the up or down arrow keys. Note that the floating split corresponds to the tilde ‘ ~ ‘ sign in CGA code.

Repetitive splits

The following splits are repetitive splits which define which parts of the facade get repeated to adapt to any facade sizes. Splits 2, 4, 6 and 7 are first defined as horizontal splits with one tile size, so those floors get repeated as the building gets higher. Do not forget to set the two horizontal repetitive splits which remain (each to 4 horizontal tiles).

REPETITIVE splits which define which parts of the facade get repeated

To further detail the geometry, split each of the remaining tiles further, like shown in the upcoming scheme, until you have broken down each window. Split up the window types into their components.

Splitting up the window types into their components

A special case is the ground floor where there is an arc. Split this right at the sides of the arc, so we can insert an asset in the upcoming Part 3 of the tutorial.

Splitting the ground floor tile

Set the region width

At this point, we will redefine the total facade size by defining the width of one single window. At the beginning of this part of the tutorial, we have defined the full facade size in the Set Region Width popup. But since we are not sure if this value was correct and in general, we are more familiar with sizes of windows than complete facades, we set a new value.

  1. Right-click the window split and choose Set Region Width ... and
  2. Enter an appropriate size like 1.2 meters.
  3. Use the zAdjust to edit the depth values to give the facade a volumetric appearance. Push windows back a little and ledges forward. Also move forward the triangular and trapezoid ornamental decor if you like.
  4. Click the Save Rules and Textures for Current Facade button Save Rules and Textures for Current Facade to create your rule file. It is also recommended you create a second copy in case you want to revert your script file back to this stage later on.

Rule refinement

You may ask now: How should we proceed with this rule? Since a rule file from the Facade Wizard is constructed for facades, we can only assign it to vertical surfaces. So let us create a simple mass model rule, on which we can test it.

  1. Create a new rule called MassModel.cga, open it up in the CGA Editor.
  2. Create an attribute called buildingHeight, with a value of 25.
  3. Import the facade template file we just created by opening the context menu by right-clicking the mouse in the CGA Editor, choose Import Rules..., and select the facade template CGA rule file. (Alternatively, drag-and-drop the CGA file from the File Navigator).
  4. Create a new rule called Lot, with an extrude command. Use the previously generated buildingHeight attribute for the extrusion value.
  5. After the extrude, add a component split which splits off all 'side' faces.
  6. Assign the Facade rule of the facade template file we imported. In our sample this is gen_Facade_AdvancedFacade.Facade. You will get the following mass model rule file:
    import gen_Facade_AdvancedFacade : "gen_Facade_AdvancedFacade_dist.cga"
    attr buildingHeight = 25
    	extrude(buildingHeight) comp(f) { side : gen_Facade_AdvancedFacade.Facade }
  7. Create a footprint shape with the Lot Start Rule and assign to it the MassModel.cga rule and generate the model. You will see that the facade template is directly used and the rule adapts to the new lot's geometry and the predefined extrusion height of 25 [meters].
    Custom MassModel rule and triggering the facade template on all side faces

Relinking rules

In the following picture, we see those parts (colored yellow) which we left without further detailing beforehand. Now, we will use CGA and the Model Hierarchy Window to relink the specific subrules from the facade templates to fill in the missing parts in the yellow colored areas.

Yellow areas show where detailing is missing

  1. Click Window > Show Model Hierarchy and select the building model.
  2. Activate Inspect Model located on the Model Hierarchy toolbar. The model turns slightly transparent after you enter the Inspect Model mode.
  3. Click on the shape node you want to replace: The right vertical part of the facade, marked yellow in the above image. This selects the shape in Model Hierarchy View.
    Model hierarchy view with part facade selected

    Right-click in the Model Hierarchy View window and choose Graph > Collapse Others to tidy up the view in Model Hierarchy View by collapsing non-selected parts of the shape tree.

  4. Select the parent shape node, and double click it. This will highlight the Facade template rule responsible for creating this shape node in the CGA Editor.
    parent shape node selected
  5. The selected rule in the CGA Editor is responsible for creating the 3 facade parts: Left, middle and right part. Replace the facade rule on the right with the one from the left part. In our case, we replace Facade__1_3_3 with Facade__1_3_1.


    Facade__1_3 -->
    	split(x, noAdjust) { 2.68: Facade__1_3_1 | ~10.62: Facade__1_3_2 | 2.66: Facade__1_3_3 }


    Facade__1_3 -->
    	split(x, noAdjust) { 2.68: Facade__1_3_1 | ~10.62: Facade__1_3_2 | 2.66: Facade__1_3_1 }

    The right part of the facade now uses the same rule as the left. The now unused rule Facade__1_3_3 can be deleted since it is not needed any more.

    Before relinking:

    Before relinking

    After relinking:

    After relinking
  6. Now, do the same for the yellow part near the entrance and replace the left most tile with the one to the right of the entry.

You have completed Part 2 of the tutorial and can enjoy the final model after generating it once again:

Final model

Part 3: LODs and asset insertion


After having covered the basic creation of facade templates within the Facade Wizard, it's time to think outside the box and explore, how CGA and the Model Hierarchy can be used to enhance the quality of the default Facade Wizard rules.

In this last part of the Facade Wizard Tutorial, we will cover the following two topics:

  • Levels of Detail (LOD)
  • Inserting assets in facade templates

Levels of Detail

Since the creation of 3D cities can generate huge datasets, which often can be handled only with great care concerning resources, advanced users sometimes may want to rely on creating different models of the same building with different levels of complexity. For example, if a building is seen directly in front of the camera, all the details should be visible, while a building, which is far away from the camera (or maybe cannot even be seen), should have as few details as possible, but still recognizable in its basic form. This trick to create different models of the same object and using them according to the distance to the camera is widely known in the field of computer graphics by the term Levels of Detail(LOD).

If you take a look at the rule files which are created by the Facade Wizard, you see that there is already a default LOD System implemented. The top of the CGA file (seen in the CGA script editor) contains an explanation of the default values.

Please note that the CityEngine can create different LODs but does not have a system implemented for direct camera-proximity-based switching of the models.

attr LOD = 2
# LOD 0 generates the original texture
# LOD 1 generates flat splits
# LOD 2 generates splits with depth as defined in Facade Wizard

The following picture shows the application of all of the 3 predefined LODs, shown on the base of the rule which was created in the previous part of this tutorial. Please note that the difference between the LODs 1 and 2 is quite small but significant: the LOD 1 generates just a plane which is split up and ignores all zAdjust edits, while the LOD 2 actually generates the volumetric representation with textured cubic objects, incorporating the zAdjusts.

Display of the 3 default LODs of the same Facade Wizard rule template:

LODs of the same Facade Wizard rule template

It is very important to understand that if a Facade Wizard rule template is imported in other CGA rules (as done e.g. in the MassModel.cga file from the last part of the tutorial), the LOD attribute must also be initialized in the primary CGA file --> attr LOD = 2

An important question comes up: What can be done if the templates, which can be created with the Facade Wizard, are not detailed enough - even in LOD 2? Could we create an LOD 3?

Guess what: Yes, you can!

The solution to this is a clever combination of shape highlighting in the Model Hierarchy, code highlighting in CGA and the insertion of custom made assets.

Edit assets

First, let us edit the MassModels.cga file.

  • Change the previously introduced attribute LOD to a value of 3.

After having studied the facade's ornaments, we decide to introduce the following assets:

  • tympanon.obj
  • triangularPediment.obj
  • squarePediment.obj
  • entryArc.obj
Facade ornaments

Starting with the triangular pediment asset, open the facade rule in the CGA editor.

  1. Add a new rule for the triangular pediment asset at the bottom.
    insertTriangularPedimentAsset --> 
    	case LOD ==3 : Shape
            t(0, 0, '1)
            s('1, '1, 0.25) 
            projectUV(0) Asset
    	else : Shape

    For LOD 3, we load the obj asset; t() and s() place and scale the asset correctly; projectUV() will overlay the facade texture on the asset.

  2. Add similar rules for the other 3 assets.
    insertSquarePedimentAsset --> 
    	case LOD ==3 : 
    		t(0, 0, '1) s('1, '1, 0.25) i("squarePediment.obj") 
    		projectUV(0) Asset
    	else : Shape		
    insertArcEntryAsset --> 
    	case LOD ==3 : 
    		t(0, 0, -0.35) s('1, '1, 0.5) i("entryArc.obj")
    		projectUV(0) Asset
    	else : Shape
    addTympanonAsset --> 
    	case LOD ==3 : 
    		t(0, 0, '1) i("tympanon.obj") 
    		projectUV(0) Asset
    	else : Shape

    The assets entryArc.obj and tympanon.obj will replace the geometry of the existing shape, while the assets triangularPediment.obj and squarePediment.obj will be placed on top on the existing shapes. The main code difference in the rules is the first 'shape' in the rules.

Asset insertion

What is now left to do is to find the correct terminal shapes from which we can link to those new rules and insert the assets, as done in the next picture.

  1. Select the building and go into Inspect Model mode.
  2. Select the shape where the asset is to be inserted.
  3. In Model Hierarchy View, double-click the selected shape. This will highlight the facade template rule responsible for creating this shape node in the CGA editor .
  4. In the second case, at the end of the existing rule, add the insertTriangularPedimentAsset rule to trigger asset insertion.
    Facade__1_3_1_2_2_2 -->
    	case LOD <= 1:
    		setupProjection(0, scope.xy, '8.0953, '19.2869, '-0.1945, '-11.3296)
    		setupProjection(0, scope.xy, '8.0953, '19.2869, '-0.1945, '-11.3296)
    		t(0, 0, -0.2) 
    		s('1, '1, 0.2) 
    		projectUV(0) insertTriangularPedimentAsset

Before asset insertion:

Before asset insertion

After asset insertion:

After asset insertion

Do the same steps to insert this asset at other positions in the facade, and for the other assets.

Remove roof elements

The last step is removing the outer elements on the roof.

  1. Use Inspect Model mode to find the rule, and replace the outer split parts with NIL.
    Facade__1_5 -->
    	split(x, noAdjust) { 2.68: NIL | ~10.62: Facade__1_5_2 | 2.66: NIL }
  2. Delete the unused Facade__1_5_1 and Facade__1_5_3 rules.
    A NIL command is used to get rid of the geometry which gets textured transparent

After you have linked all necessary rules, the generated facade will look like this:

Generated facade

This final picture shows all four LODs next to each other:

Four LOD buildings

Poly counts in this example (facades only): 4, 1288, 6616, 9654. Well done.