Tutorial 13: Facade Wizard—ArcGIS CityEngine Resources

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.

Get started with the wizard

The Facade Wizard is a tool that allows you to create complex CGA facade rule templates. The tool doesn't require you to write CGA code; instead, the code is automatically produced in the background by CityEngine. The wizard allows complex structures to be generated quickly and efficiently.

With this tool, you can create CGA rules that can adapt to any facade geometries.

The following images are a photograph of an example facade 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.

With the Facade Wizard, you can create large collections of facade templates for reuse, which may be helpful in upcoming projects.

Facade Wizard

To create a scene file, click File > New > CityEngine scene.
Import the mass model of the National Bank building in Zurich. Right-click the NationalBankMassModel.obj asset file and click Import.
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 appears as a starting point:
Double-click the short side facade shape to select it.
Click Shapes > Separate Faces to separate the faces of the model.
Click Window > Show Facade Wizard and open the Facade Wizard.
Click the New Facade from Image button in the Facade Wizard and open the Plane_MG_3_TX.jpg file in the assets folder.
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.

Verify that the Y Split button is selected, and create horizontal splits 1 and 2 to block the main building masses into the ground floor, upper floors, and roof.
Next, create ground floor areas: two left windows, the entrance, and two right windows.
1. Click the X Split button .
2. With the X Split blue line, click the left side 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 the right side of the entry to create split 5.
4. Finally, click the ground floor at the far right to create split 6 and define the two (repetitive) right windows.
Tip:

To select the correct split type more quickly, you can also cycle through the split types by using the left and right arrow keys.

Note:
After splits have been set, you can go back to the split line and edit its position interactively to refine the positions.
Click the X Repeat button 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 the region and choose Select region. Repeat the same steps for the right (repetitive) windows.

Upper floor splits

For the upper floors, to create splits 9 and 10, click the vertical split button and press Shift to snap to splits 3 and 6, which were created on the ground floor level.
Click the Y Repeat button one time inside the upper floors area to set up the two remaining horizontal repetitive splits, 11 and 12.
Click the X Repeat button once to create the nine vertical repetitive splits.
Select one of the darker windows and set the repetitive region by choosing Select Region.
Use the X Split and Y Split tools to isolate the window.
On the roof, split off the roof ledge ornament.
To add a more volumetric appearance to the currently flat surface, you can define an offset by setting the zAdjust value per split tile. Click the desired shape and slide left or right to edit the value. You can do this on as many parts of the building as you want.

Using the zAdjust functionality:
Click the Save Rules and Textures for Current Facade button to generate a .cga file for the facade.
Click the viewport tab and assign the rule to the facade shape.
Select the shape and generate it to see the volumetric facade.
Click the Show/Hide Shapes button to hide the original shape.

In the Visibility Settings menu, click Show/Hide Shapes to hide the original shape:

Note:

To see the volumetric facade correctly, deselect the Show/Hide Shapes button. When you want to select other facades, you must activate it again.

Advanced facade creation

In this example, you will load an image file into the Facade Wizard to create a facade rule template. Later, you 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 you will be using is an advanced facade:

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

Most of the time, when using the Facade Wizard, it is necessary to carefully study the facade details, such as numbers of window subdivisions, repetitions in ornamental details, or uneven floor heights, to find the best way to split up the structure. It is recommended that you take time to think about this strategically.

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

Green—Single tile, nonrepetitive
Blue—Repetitive tile (x or y)
Red—Nested repetitive tile (tileable in x and y)
Yellow—Rule symmetry (will be linked in the Rule refinement section)

The main facade structure includes an analysis of single splits, repetitive splits, and rule symmetry:

Unlike in the previous example, you'll start by directly selecting a texture file.

To open the Facade Wizard, click Window > Show Facade Wizard.
Click the New Facade from Image button and browse to the AdvancedFacade.tif file.
The Set Region Width window appears, where you can enter the total width of the facade so that the split dimensions also make geometric sense. 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 this case, enter the value when you have reached the scope of this single window.
Set the value to 20 for now. You will set this again later.

Use the Crop Image tool

You will likely work with facade photographs that 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.

Select the Tutorial_13_Facade_Wizard__2015_0\Images\facadeFoto.jpg image in the File Navigator window and click Shapes > Crop Image, or click File Navigator > Tutorial_13_Facade_Wizard__2015_0 > Images and right-click the facadeFoto.jpg file and choose Crop Image.
The Crop Image tool automatically analyzes the image for perspective lines and tries to find a possible facade area.

Edit the rectangular region in the left window, which automatically updates the result on the right side.
When you are satisfied with the cropped extent, save the file.

You have learned that images can be rectified in CityEngine. This allows a more streamlined process without leaving 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.

Use the X Split and Y Split tools to add single splits to the facade.
Note:
The right vertical upper floor is not split. This 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 you will link one of the tiles from the right side.
Define the vertical size for the second and fourth upper floors as absolute.
In this first split series, it is important that you define split types correctly as either absolute or floating. You want the facade to tile afterward, so the parts that need an absolute value must be defined as absolute splits. To define whether a split is an absolute or floating distance, cycle through the types by using the up and down arrow keys.
- Absolute—Yellow line
- Floating—Yellow dashed line
Do this immediately after you click to define the split, and hover over the area of the last split and press the up or down arrow keys. Note that the floating split corresponds to the tilde symbol (~) in CGA code.

Repetitive splits

The following splits are repetitive splits that define which parts of the facade are 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 are repeated as the building gets higher. Remember to set the two horizontal repetitive splits that remain (each to four horizontal tiles).

To further detail the geometry, continue to split each of the remaining tiles, as shown in the example below, until you have completed splitting 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 exactly at the sides of the arc, so you can insert an asset in the next part of the tutorial.

Set the region width

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

Right-click the window split and choose Set Region Width.
Enter an appropriate size, such as 1.2 meters.
Use the zAdjust tool to edit the depth values to give the facade a volumetric appearance. Push windows back a little and ledges forward. You can also move forward the triangular and trapezoid ornamental decor.
Click the Save Rules and Textures for Current Facade button to create your rule file.

It is recommended that you create a second copy in case you want to revert your script file to this stage later.

Refine rules

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

Create a rule, name it MassModel.cga, and open it in the CGA Editor window.
Create an attribute, name it buildingHeight, and give it a value of 25.
To import the facade template file you just created, right-click in the CGA Editor window, choose Import Rules from the context menu, and select the facade template CGA rule file. Alternatively, drag the CGA file from the File Navigator window.
Create a rule named Lot with an extrude command. Use the previously generated buildingHeight attribute for the extrusion value.
After the extrusion, add a component split that splits off all side faces.

Assign the Facade rule of the facade template file you imported. In your 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

Lot-->
	extrude(buildingHeight) comp(f) { side : gen_Facade_AdvancedFacade.Facade }

Create a footprint shape with the Lot start rule, and assign to it the MassModel.cga rule and generate the model.
The facade template is used directly, and the rule adapts to the new lot's geometry and the predefined extrusion height of 25 (meters).

Relink rules

In the following image, you can see those parts (in yellow) that you left without further detailing beforehand. Now, you 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 areas.

Yellow areas show where detailing is missing.

Click Window > Show Model Hierarchy and select the building model.
Click Inspect Model on the Model Hierarchy toolbar.
The model turns slightly transparent after you enter the Inspect Model mode.
Click the shape node you want to replace: the right vertical part of the facade, highlighted in yellow in the previous image. This selects the shape in the Model Hierarchy window.

Right-click the Model Hierarchy window and choose Graph > Collapse Others to simplify the view by collapsing parts of the shape tree that are not selected.
Select the parent shape node and double-click it.

The Facade template rule responsible for creating this shape node in the CGA Editor window is highlighted. The selected rule creates the three facade parts: left, middle, and right.
Replace the facade rule on the right with the one from the left. In this case, replace Facade__1_3_3 with Facade__1_3_1.
Original
```
Facade__1_3 -->
	split(x, noAdjust) { 2.68: Facade__1_3_1 | ~10.62: Facade__1_3_2 | 2.66: Facade__1_3_3 }
```
Modified
```
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 no longer needed.

Before relinking:

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

The final model appears after generating it again:

LODs and asset insertion

You've now covered the basic creation of facade templates in the Facade Wizard. You will now explore how you can use CGA and the model hierarchy to enhance the quality of the default Facade Wizard rules.

This last part of the Facade Wizard tutorial discusses the following two topics:

Levels of detail (LOD)
Inserting assets in facade templates

Levels of detail

Since the creation of 3D cities can generate very large datasets, which often require careful management of resources, advanced users may sometimes choose to create different models of the same building with varying levels of complexity. For example, if a building is directly in front of the camera, all the details should be visible, while a building that is far away from the camera (or may not be visible) should have as few details as possible but still be recognizable in its basic form. The process of creating 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 as creating levels of detail (LOD).

The rule files created by the Facade Wizard show 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.

Note that 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 image shows the application of all of the three predefined LODs, shown on the base of the rule that was created in the previous part of this tutorial. Note that the difference between LODs 1 and 2 is small but significant: LOD 1 generates only a plane that is split up and ignores all zAdjust edits, while LOD 2 generates the volumetric representation with textured cubic objects, incorporating the zAdjusts.

The three default LODs of the same Facade Wizard rule template are displayed:

Tip:

If a Facade Wizard rule template is imported in other CGA rules (for example, as done 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.

This brings up the question of what can be done if the templates, which can be created with the Facade Wizard, are not detailed enough—even in LOD 2. Can you create an LOD 3? The answer is yes.

The solution is a combination of shape highlighting in the model hierarchy, code highlighting in CGA, and the insertion of custom-made assets.

Edit assets

First, edit the MassModels.cga file.

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

After studying the facade's ornaments, you decide to introduce the following assets:

tympanon.obj
triangularPediment.obj
squarePediment.obj
entryArc.obj

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

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) 
        i("triangularPediment.obj") 
        projectUV(0) Asset
	else : Shape
```
For LOD 3, load the obj asset; t() and s() place and scale the asset correctly; projectUV() will overlay the facade texture on the asset.

Add similar rules for the other three assets.

                    
                  
insertSquarePedimentAsset --> 
	case LOD ==3 : 
		Shape
		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

Note:

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

Insert assets

Now you will find the correct terminal shapes from which you can link to the new rules and insert the assets, as shown in the image below.

Select the building and go to Inspect Model mode.
Select the shape where the asset is to be inserted.
In Model Hierarchy window, double-click the selected shape.
The facade template rule responsible for creating this shape node in the CGA Editor window is highlighted.

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)
		projectUV(0) 
	else:
		setupProjection(0, scope.xy, '8.0953, '19.2869, '-0.1945, '-11.3296)
		t(0, 0, -0.2) 
		s('1, '1, 0.2) 
		i("builtin:cube") 
		projectUV(0) insertTriangularPedimentAsset

The facade appears as follows before asset insertion:

The facade appears as follows after asset insertion:

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

Remove roof elements

The last step is to remove the outer elements on the roof.

Use the 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 }

Delete the unused Facade__1_5_1 and Facade__1_5_3 rules.

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

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

The poly counts in this example (facades only) are 4, 1288, 6616, and 9654.

Feedback on this topic?

Get started with the wizard

Facade Wizard

Ground floor splits

Tip:

Note:

Upper floor splits

Note:

Advanced facade creation

Facade analysis and rule creation

Use the Crop Image tool

Single splits

Note:

Repetitive splits

Set the region width

Refine rules

Relink rules

LODs and asset insertion

Levels of detail

Tip:

Edit assets

Note:

Insert assets

Remove roof elements

In this topic