Tutorial 20: Local edits—ArcGIS CityEngine Resources

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

Building with Footprint rule added without losing local edits

This tutorial shows you how to make local edits in ArcGIS CityEngine. Using local edits, you can modify individual window sizes, make alterations to the ground floor, and add balconies independently without the need to specify these local changes within the CGA code.

It is useful to understand how generated models are structured. To better understand this, it is recommended that you get familiar with the Model Hierarchy tool, which can be used to inspect the shape tree of a generated model.

Modify individual windows

To modify individual windows, complete the following steps:

Expand the Tutorial_20_Local_Edits tutorial folder in the Navigator window.
Double-click the Simple_Building_LE_01.cej file in the scenes folder to open the scene in the Viewport window.
Double-click the Simple_Building_LE_01.cga file in the rules folder to open the rule in the CGA Editor window.
Local edits are available for attributes that have handles. To enable local editing of window sizes, attributes for window dimensions are created at the start of the rule. The Tile rule is then modified to use these attributes, and handles are added to unique attributes to enable interactive changes in the Viewport window.
In the Simple_Building_LE_01.cga rule file, add attributes for the window width and height.
```
attr window_width = 2
attr window_height = 1.5
```
Explore this rule file in the CGA Editor window to find the Tile rule. Replace the exact values for the window size with these attributes.
A tile contains a window with some surrounding wall on all four sides. The Tile rule creates the window with the desired width and height in the center of the tile.
```
Tile -->
	split(x){ ~1 : Wall 
			| window_width: split(y){ ~1: Wall | window_height: Window | ~1: Wall }
			| ~1 : Wall }
```

Add handles to the attributes.

@Handle(shape=Window, axis=x)
attr window_width = 2

@Handle(shape=Window)
attr window_height = 1.5

Press Ctrl+S to save the CGA file, and regenerate the building by clicking the Generate Models tool (Ctrl+G) on the toolbar.
Drag one of the blue window handles.
This action changes the window size for all the windows in the same way.
With local edits, it is possible to change the width of each window individually even though only one attribute for window width exists in the rule.
In the Inspector window, choose Default style to reset the attributes.
Click the Local Edits tool on the toolbar.
Select a single window.
The orange highlighting in the Viewport window indicates the current selection. The attributes in the Inspector window that are also highlighted in orange, can be locally edited for the current selection. The window_width and window_height attributes can be locally set for just this window.
Drag the blue handle to change the size of this window only.
In the Inspector window, the * symbol next to the window_width and window_height attributes indicates that these attributes have been locally edited for the current selection.

With multiple selections, the same local edit can be applied to multiple windows at the same time.

Press and hold Shift to select multiple windows.
Press Ctrl to perform an inverse selection and Ctrl+Shift to deselect.
Change the size of the windows in the selection either by dragging the handles or by entering a value in the Inspector window.

Windows above a door are often smaller because that’s where the staircase is. You can undo all previous changes and create this using local edits.

To undo all local edits, right-click in the Viewport window or Inspector window and click Reset all local edits.
Select a window above the door.
Press End to select all windows in the column above the door.
You can press the Home and End keys to cycle backward and forward through available patterns. Patterns are automatically detected based on the shape tree and how the CGA code creates that hierarchy. In this case, the option available is the selection of the column of windows above the ground floor.
Make the windows smaller either by dragging the handles or by entering a value in the Inspector window.

Make the ground floor different

Ground floors are often different from the upper floors of a building. For example, ground floor windows are typically larger than upper floor windows. This simple building rule uses the same window tiling code to create the same window tiles on all floors. With local edits, the ground floor windows on the front of the building can be made bigger without needing to write a separate rule for the ground floor tiles.

Open the Simple_Building_LE_02.cej scene.
Open the Simple_Building_LE_02.cga rule file.
In the Simple_Building_LE_02.cga rule file, add a handle to the tile_width attribute. This allows the attribute to be locally editable.
```
@Handle(shape=Tile, axis=x)
@Range(min=1, max=10, restricted=false)
attr tile_width = rand(2.5,6)
```
Save the CGA file and regenerate the building.
Click the Local Edits tool .
Select a window on the ground floor and change its tile width, window width, and window height.

This changes one tile on the ground floor. However, the goal is to change all the tiles on the ground floor. This is possible by selecting shapes at a higher level.

Press PageUp to go up one level in the local edits hierarchy.

Now all the windows on the ground floor are selected and highlighted in orange. The PageUp and PageDown keys move up to higher levels and move down to lower levels, respectively. Local edits are linked to the shape tree, and they can be applied to multiple objects, such as all windows on a floor, by putting the edits on higher levels of the shape tree.
Increase the window height to make the windows on the ground floor bigger.
This changes all the windows on the ground floor except for the first window that was changed above. This is because the edits made to the first window were at a lower level. When multiple edits on the same object exist, the edit made at the lowest level has precedence.
In the Inspector window, the down arrow ↓, next to the tile_width, window_width, and window_height attributes, indicates that these attributes have been edited at a lower level than the current selection level. The * symbol next to the window_width attribute means it has also been edited at the current selection level.

Since all ground floor windows should be the same, the changes made at the lower level should be undone to the inconsistent window.

Select the inconsistent window at a lower level by pressing PageDown to move down a level.
Right-click in the Viewport window or the Inspector window and click Reset highlighted local edits.
Select the ground floor windows by pressing PageUp or clicking Select higher level in the Local Edits Menu.
Increase the tile width, window width, and window height to make the ground floor windows bigger.
Now all windows have the same size since there are no local edits at a lower level.

Note:

You may need to reselect the ground floor windows if the orange highlight is lost after the tile width change.

Add balconies

Providing options to add geometry or details to the building locally is possible, but it is important that you can access the handle when the geometry doesn’t exist. For example, local edits can be used to put balconies on select windows. To do this, the balcony must have sibling geometry. This sibling geometry allows access to the balcony’s handle even when the balcony does not exist.

Open the Simple_Building_LE_03.cej scene.
Open the Simple_Building_LE_03.cga rule file.
In the Simple_Building_LE_03.cga rule file, add an attribute that determines whether there are balconies.
```
attr hasBalcony = false
```

Add code to create balconies.

Tile -->
	split(x){ ~1 : Wall 
			| window_width: split(y){ ~1: Wall | window_height: Window BalconyMass | ~1: Wall }
			| ~1 : Wall }		 

BalconyMass -->
	s('1,0.9,0.9)
	t(0,0,'-0.5)
	Balcony
	
Balcony -->
	case hasBalcony:
		primitiveCylinder(32)
		color(0.8,0.8,0.8)
		split(z) { ~1: NIL
				 | ~1: comp(f) { top: NIL
				 			   | back: NIL
				 			   | bottom: extrude(0.05) Bottom.
				 			   | all= BalconyRailing } }
	else:
		NIL
		
BalconyRailing -->
	comp(f) { side: s(0.05,'1,'1) center(x) extrude(0.05) Bar. }
	s('1,0.05,'1)
	[ t(0,-0.05,0) extrude(vertex.normal, 0.05) Bottom. ]
	[ t(0,0.9,0) extrude(vertex.normal, 0.05) Railing. ]

Since the Balcony rule may either generate geometry for the balcony or generate nothing (NIL), there should be a sibling shape with geometry so that the handle can be accessed when there is no balcony. That sibling shape is the window. The BalconyMass rule creates a volume into which the balcony is inserted, and the remaining rules create the balcony geometry.

Add a toggle handle on the hasBalcony attribute to enable local edits.

@Handle(shape=Balcony, type=toggle, occlusion=false)
attr hasBalcony = false

Save the CGA file.
Click the Local Edits tool and select a single window.
Hover over a window to see a shaded volume and a new type of handle (visualized as a square switch icon).
This is the toggle handle attached to the Balcony rule that, when clicked, switches between true and false to enable or disable the hasBalcony attribute.
Click the switch icon to switch to true to show a balcony on the selected window.
Save the CGA file and regenerate the building.

Usually, balconies only make sense on the upper floors of a building and are often excluded from the staircase windows above the door.

Select an upper floor window and press PageUp until all the upper floors are selected (no ground floor).
Add balconies to all upper floor windows by using the toggle handle to switch the hasBalcony attribute to true.
Select a window above the door by pressing PageDown.
In the Inspector window, there is an up arrow ↑ next to the hasBalcony attribute. This means that this attribute has been locally edited at a higher level. This change can be overridden because edits performed at a lower level take precedence.
Select all the windows above the door by pressing End.
Tip:
The Home and End keys can be used to select patterns.
Remove the balconies from the windows above the door by setting the hasBalcony attribute to false.

Note:

One limitation with local edits is that changing the shape tree structure may cause already applied local edits to be lost. This means that changing the code after applying local edits can lead to unexpected results. It is recommended that you make local edits only after the code is finished.

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

Modify individual window sizes.
Make alterations to the ground floor.
Add balconies independently without changing the CGA rule file.

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

Feedback on this topic?

Modify individual windows

Make the ground floor different

Note:

Add balconies

Tip:

Note:

In this topic