City Engine Help 2010 3 PDF

The Quick Start Guide provides a short The CityEngine Manual contains the complete The Tutorials describe
torials describe step-by-step typical You might take the red pill for the
overview of the CityEngine's user interface reference to the user interface, the different CityEngine workflows with practical examples - CGA Shape Grammar Reference
and workflow possibilities. The guide the quick tools, import and export, magic wizards, and and lots of basic aspects of the CityEngine are and go straight for the truth.
way to learn to use the CityEngine and the data structures. teached.
efficiently create your first cityscape.
Version 2010.3. Copyright 2008 - 2010 Procedural Inc.
Quick Start Guide
This quick start guide is intended for CityEngine beginners. It introduces its major components and helps you to understand
the basic tasks required when modeling a generative city. After a general overview, the guide highlights the user interface, and
explains the modeling workflow when using the CityEngine. Then it shows the basics of rule-based modeling and shows how to
export generated models.
Table of Contents
1. CityEngine Overview
2. User Interface
3. CityEngine Workflow
4. Rule-based Modeling
5. Model Export
Copyright 2008 - 2010 Procedural Inc.
CityEngine Manual
Table of Contents
A. User Interface
1. Window Type Overview
2. The Viewport Window
3D Navigation Essentials
Viewing Modes and Display Settings
Object Selection
Object Edit and Transform Tools
Cameras
Bookmarks
Multiple Viewport Windows
Keyboard Shortcut Reference
3. The File Navigator
4. The Scene Window
5. The CGA Editor
6. The Log View
7. The CGA Console
8. The CGA Problems View
9. The Progress View
10. The Inspector
11. Configuring the Windows Layout
Editors
Views
Dragging Windows
Default Window Layouts
Saving and Loading Window Layouts
12. CityEngine Preferences
General
Appearance
Automatic Exit
Colors and Fonts
Label Decorations
Editors
File Associations
Text Editors
Accessibility
Hyperlinking
Linked Mode
Quick Diff
Grammar Core
Keys
Mouse
3D Mouse
Perspectives
Startup and Shutdown
Bookmarks
Cameras
Help
B. Project Management
1. Why Project Management
2. Using CityEngine Projects
Creating a CityEngine Project
Folder Organization and File Types
Importing Files into a Project
Exploring Projects with the File Navigator
Editing and Refreshing Assets
3. The CityEngine Workspace
Creating a new Workspace
Switching Workspaces
4. Archiving or Exchanging CityEngine Projects
Importing a Project into the Workspace
Exporting a Project
C. Map Layers
1. General
2. What is a Map Layer
3. Creating a Map Layer
Texture
Obstacle
Terrain
Mapping
Function
4. Working with Map Layers in the Inspector Window
5. Editing Map Layer Functions
6. Controlling Rule Attributes with Map Layers
7. Selection via Image Maps
8. Aligning Terrains to Shapes
9. Exporting Terrains to geometry or image files
D. Shapes
1. What are Shapes
2. Creating and Editing Shapes Manually
Aligning Shapes to the Terrain
Subdividing Shapes
3. Creation of Shapes from Graph Networks
Block Parameters
Street Parameters
Crossing Parameters
Parameter Source
Street Shapes
4. Importing Shapes
Creating and Preparing Polygons for Shape Import
5. Exporting Shapes
E. Street Networks
1. What are Street Networks
2. Creating and Editing Street Networks Manually
3. Growing Street Networks
4. Importing Graph Networks
5. Exporting Graph Networks
6. Aligning Graph Networks to the Terrain
F. Rule-based Modeling
1. Basics of Rule-based Modeling
2. Rule Files
3. Writing Rules
4. Shape Operations
5. Rule Editing Tools
G. Exporting Models
1. Export Overview
2. General Export Reference
3. Supported Formats and Specific Options
4. Export Application Notes
H. Python Scripting
1. Scripting Usage
2. Commands by Category
3. Command Reference
I. Interactive Facade Editing

1. Facade Wizard Overview
Licensing
1. Licensing Overview
2. Node-locked License
3. Floating License
Tutorials
The CityEngine tutorials are the starting point to experience the features of the CityEngine. The different tutorials cover all parts
of the CityEngine workflow like project management, map usage, street network generation, data import features and Shape
Grammar modeling.
How to work with the Tutorials
Table of Contents
1. CityEngine Basics Tutorial
2. Street Tutorial
3. Map Control Tutorial
4. Import Streets Tutorial
5. Import Shapes Tutorial
6. Basic Shape Grammar Tutorial
7. Facade Modeling Tutorial
8. Mass Modeling Tutorial
9. Advanced Shape Grammar Tutorial
10. Python Scripting Tutorial
11. Reporting Tutorial
12. GIS Mapping Tutorial

13. Scripted Report Export Tutorial
14. Visual CGA Tutorial
15. Facade Wizard Tutorial

CGA Shape Grammar Reference
Shape Operations
alignScopeToAxes alignScopeToGeometry center color
comp convexify deleteUV extrude
innerRect i (insert) mirror mirrorScope
normalizeUV NIL offset pop
print projectUV push r (scope rotate)
report reverseNormals roofGable roofHip
roofPyramid roofShed rotate rotateScope
rotateUV s (scope size) scaleUV scatter
set setback setPivot setupProjection
shapeL shapeU shapeO split
t (scope translate) taper texture tileUV
translate translateUV trim

Shape Attributes
comp initialShape material pivot
seedian scope split trim
Builtin Functions
Math
abs acos asin atan
atan2 ceil cos exp
floor isinf isnan ln
log10 pow rint sin
sqrt tan
Probability
p rand
Conversion
bool float sel str
String
count find len substring
Geometry
geometry.area geometry.du/dv geometry.isConcave geometry.isPlanar
geometry.isRectangular geometry.nEdges geometry.nFaces geometry.nVertices
geometry.volume
File
fileExists fileSearch
Assets and Images
assetInfo assetsSortRatio assetsSortSize imageInfo
imagesSortRatio
Occlusion
inside overlaps touches
Misc
convert
Other
Simple Types Operations attr const import
version
CGA Utility Functions Library
String Utility Functions
findFirst findLast getPrefix getRange
getSuffix replace
String List Utility Functions

Stringlists are a series of strings stored inside one string. The elements are separated by a semicolon (";"). The data type is
"string", thus it is not any real type of array as used in other scripting languages.
listAdd listClean listFirst listIndex
listItem listLast listRandom listRange
listSize
File, Asset and Image Utility Functions
assetApproxRatio assetApproxSize assetBestRatio assetBestSize
assetFitSize fileBasename fileDirectory fileExtension
fileName fileRandom imageApproxRatio imageBestRatio
Misc
CGA Changelog
Asset Search
Builtin Assets

CityEngine Overview
This page gives a introduction to the 3D content creation concepts of the CityEngine. It provides an overview of CityEngine's
main features, modeling pipeline and the general ideas behind the procedural modeling of cities and buildings are explained.
Introduction to the CityEngine
The CityEngine Features
Procedural Modeling Core

The main concept of the CityEngine is the "procedural" approach towards modeling efficiently. The computer is given a codebased
"procedure" which represents a series of commands - in this context geometric modeling commands - which then will be executed.
Instead of the "classical" intervention of the user, who manually interacts with the model and models 3d geometries, the task is
described "abstractly", in a rule file.
The commands which are provided in the CityEngine's CGA shape grammar, such as "extrude", "split" or "texture" are widely
known commands in most 3d applications and thus any user can adapt them easily and create complex architectural forms in short
time.
To learn more about procedural modeling, read the paragraph 'Grammar-based modeling' lower on this page.
Dynamic City Layouts

The Dynamic City Layouts give the user a powerful tool to create interactive street networks which automatically update in realtime.
Streets, Sidewalks and whole Blocks, which form the specific urban context adapt efficiently to the user's input and give the user an
intuitive way to design the layout of complete cities.
And of course, all the Geometries which depend on the layout of the underlying Dynamic City Layout are also updated on the fly !
Watch your buildings getting rebuilt while you edit the width of the surrounding streets !
Customizable User Interface
The User Interface in the CityEngine can be adapted to any task at hand. Whether this is rule creation, working on the street
network, editing attributes with realtime feedback or studying the statistical reports of your current city's development: "anything
goes".
For users who want to have control over repetitive tasks, create formatted reports in file format or automating other specific actions,
Python Scripting is available to further streamline the workflow in the CityEngine.
Data Interoperability
The CityEngine supports the Industry's most common formats for both import and export. The user is able to transport line data,
shape data (footprints) and 3d geometry to and out of the CityEngine. Whether you work in the field of Urban Planning,
Architecture, Entertainment or Simulation, we provide a way to transport your data.
The CityEngine Modeling Pipeline

Modeling an urban environment with the CityEngine usually implies the individual stages of the pipeline given in the figure below.
The pipeline consists of several procedural modeling tools for generating large-scale urban layouts, as well as applying CGA rules
for the creation of detailed building models.
Overview of the CityEngine modeling pipeline. Black boxes illustrate data types (layers) and white boxes the operations
to create them. Typically, in the first step, the street network is created, afterwards the resulting blocks are subdivided
into lots. Finally, the 3D models of the buildings are generated using the CGA rules. The output of the CityEngine are
polygonal building models.
A CityEngine scene is stored as layers of different data types representing the different stages. The pipeline is flexible and can be
entered at different stages. For example, street blocks or building masses - both as polygons in (grouped) .obj files - can be
imported and further processed.
Generating Large-Scale Urban Layouts

The CityEngine consists of several procedural and interactive tools to layout street networks, align and subdivide shapes. On the
one hand, streets can be grown according to different patterns and edited in an interactive way. For example, street-crossings can
be moved, streets can be deleted or selected and the street growth wizard can be applied again on the selection. On the other
hand, tools for the editing of lot shapes are available, such as aligning building lots to a terrain etc. The tools usually work on the
selection done in the 3D view window, the viewport, or operate on the whole layer.
The CityEngine provides several tools for the efficient and interactive creation of urban layouts.
The layered organization of CityEngine scenes provides a practical and organized handling of the massive data sets. For example,
it is recommended to duplicate layers before editing and therefore creating different variations in each layers. Of course, the
visibility of each layer can be switched on or off.
Grammar-based Modeling
"Grammar-based" or "procedural" modeling has a widespread range of applications, but mostly it is applied, when large numbers of
interations of a design or large numbers of objects have to be created which obey certain standardized rules. Automation of the
modeling is the goal and the overall quality of the grammar-based description is reflected in the quality and number of details of the
generated models. Uniqe objects (such as landmark buildings) are best modeled by hand and usually do not need the procedural
approach since often none of the modeling tasks on that object can be automated.
Of course, the preparation of the rule set creates a certain overhead at the beginning, but on the other side, the model generation
itself is done in a small fraction of the time compared to classic manual modeling. The following chart compares both techniques
and it is obvious that the application of grammar based modeling becomes useful with a certain amount of models to do.
CGA
The CGA shape grammar of the CityEngine is a unique programming language specified to generate architectural 3D content. The
term CGA stands for Computer Generated Architecture. The idea of grammar-based modeling is to define rules, or CGA rules
within CityEngine, that iteratively refine a design by creating more and more detail. The rules operate on shapes which consist of a
geometry in a locally oriented bounding-box (the so-called scope). The following rule derivation illustrates the process: on the left
side the start shape is shown and on the right side the resulting generated model is displayed.
The generation of building geometries with the CGA shape grammar works as follows:
1. The building lots are either created by the CityEngine with the above mentioned tools or imported. In the latter case,
also mass models (building envelopes) can be the starting point.
2. The user selects which rule file (.cga) she or he wishes to apply onto these shapes. The user can either assign one
rule to all buildings, or assign rule sets on a per-building basis.
3. Then, the user can trigger the application of the rules on the selected shapes. Therefore it is important that the Start
Rule of the shape is present in the rule file. Otherwise no rule can be invoked. The generated models can then be
explored in the 3D viewer of the CityEngine. In the case of very large models, it is not recommended to generate all
buildings in the CityEngine due to memory constraints.
4. In order to edit the resulting 3D models, different possibilities exist: (1) edit the rules, (2) overwrite the rule parameters
of a rule set on a per-building basis, and (3) if stochastic rules are used (rules with random parameters), the random
seed of all or single buildings can be altered.
5. After the design is finalized, the user can export the selected buildings or streets to the hard disk (including textures).
Note that there are no memory constraints in the exporting mode.

User Interface
This page gives a quick overview of the user interface of the CityEngine. On the one hand the main types of windows are
described, and on the other hand basic functionalities like project management and navigation are shortly explained.
The CityEngine Main Window

The user interface revolves around a main window, which consist of several sub-window components. The screenshot below shows
a typical CityEngine modeling session.
The CityEngine User Interface with a scene opened. 1: Navigator; 2: Scene Editor; 3: CGA Shape Grammar Editor; 4: First
Viewport; 5: Second Viewport; 6: Inspector; 7: The default area for the Console, CGA Problems, Progess, etc.
Individual sub-windows can be opened in the menu Window . Each window can have multiple tabs, which can be freely arranged
via drag'n'drop. By dragging a tab into the corresponding half of another window, the tab becomes a single window. Most windows
(except the editors) can also be detached. The window layout configuration (a "perspective") can be stored and loaded via
Windows Layout ... . For example for grammar editing we recommend the corresponding default perspective.
In the following the different sub-window types and their main functions are described.
Navigator
The Navigator represents the workspace which is used for project and scene management. Hence the window shows the projects
in or linked into the workspace. A new CityEngine project can be created via File New CityEngine CityEngine Project
... .
A standard CityEngine project consists of the following folders:
assets : The assets are applied by the shape grammar to compose the 3D models. Assets can be in .obj format
(optionally with .mtl) and textures of any format.
data : This folder contains usually arbitrary additional data. For example lots or mass models (as grouped .obj) are
stored in this folder. These can be imported into the CityEngine as Shape Layers where shape grammar rules can be
applied on.
images : Additional imagery like Viewport snapshots are typically stored here.
maps : This folder usually contains the image maps used by the Map Layers. For example, a height- or water-map is
stored here.
models : This folder is intended as place to store the exported 3D models (.fbx, .dae, .obj, etc)
rules : This folder contains usually the CGA shape grammar rule files (.cga)
scenes : Here the CityEngine scenes (.cej) are stored.
Besides project management, other main function done in this window are the opening of a scene via double-click, assigning CGA
shape grammar rules to the selection via corresponding right-mouse-button, investigating assets via left-click (they appear in the
Inspector window then), or refreshing folders via F5 (useful when assets are modified or for collaborative working environments
i.e. a project is shared on the network and rules, scenes etc. have been added/modified).
In addition, the file navigator can inspect selected files. In the case of CGA rule files, the functions and rules are listed. Clicking on
entries in the CGA file inspector will let CGA Shape Editor to scroll to the corresponding entry in the rule file. Hence the file
navigator inspector is a powerful tool to navigate in a rule file.
Scene Editor
This window is the central place where you manage your scene. A CityEngine scene is organized in layers. Currently, five different
layer types exist:
Environment Layers control common 3D viewport parameters such as scene's panorama or the scene light. Both layers
are configured using the inspector.
Map Layers contain arbitrary maps (images) and can be used to globally control object attributes.
Graph Layers contain street networks and blocks, dynamically generated shapes and generated models.
Shape Layers contain static shapes, typically building lots used for generating CGA models.
The Scene Editor with a graph layer, two inital shape layers and a layer with generated models.
The layers tree allows you to navigate, delete or duplicate the layers and its objects as well as control the visibility of objects in the
tree through the search field. The visibility of each layer in the viewport can be toggled by clicking on the "eye" symbol left to the
layer name.
In the case where building lots or mass models have been already modeled with an external program, these can be imported as
shape layers. First, you have to convert your shapes into a grouped obj file (each group corresponds one shape). Afterwards copy
it into the data folder of your project and import it via File Import CityEngine Layers OBJ Import ... or via right-
mouse-button on the .obj file in the Navigator. Afterwards, CGA rules can be applied in the typical way on these imported meshes.
CGA Rule Editor

By double clicking on a .cga file in the Navigator window, the corresponding file is opened in the CGA Rule Editor. Another
possibility to open a .cga file for editing is to click on Rule File in the Inspector window if the selected object has already a rule
file assigned. The typical efficient workflow with the CGA Rule Editor is:
1. Assign a rule to the selected objects either via the RMB-menu on the rule file in the Navigator, or via RMB-menu in the
Viewport, or via Shapes Assign Rule File ... . In the latter two cases the rule has to be selected in the opened
dialog.
2. Open the rule file in the CGA Rule Editor and edit the rules.
3. Press Ctrl-s for saving the rule file.
4. Press Ctrl-g for (re-)generating the model.
The rule editor has syntax highlighting and shows syntax errors (the latter are described in more detail in the CGA Problems
window where you can double click on each entry). Furthermore, during typing, command completion can be invoked via Ctrl-
Space .
Viewport
The Viewport is the main view to interact with the 3D scene. As many Viewport windows can be opened as required by the user
(usually with other cameras or a different render mode). The 3D scene can be rendered as wireframe, shaded, with textures and/or
lighted. The default navigation works as follows:
Alt-LMB : Tumble camera around the center of interest.
Alt-MMB : Track (also called pan) camera parallel to the view plane (through the center of interest).
Alt-RMB : Dolly the camera to or away from the center of interest, means the distance of the camera to the center of
interest is alternated.
f : Frame the selection. The camera's center of interest is placed into the center of the selection and the distance is
adjusted accordingly.
As a consequence, the typical navigation works by selecting an object via LMB or via drag-LMB and then pressing f to frame the
camera. Afterwards the selection can be explored via tumble, track and dolly.
Other practical functions include the isolation of the selection (toggle it via short-key i ), framing all content (via short-key a ),
superimposing an information display (toggle via short-key d followed by another d ). or the bookmarks which store camera
positions. New bookmarks can be simply created by clicking on the bookmark icon.
Furthermore, in the corresponding drop-down icons of the Viewport, zooming (changing the focal length) can be done either via
camera preferences or the by setting the focal length directly to one of the presets.
Note: The CityEngine preferences ( Preferences Navigation Devices Mouse ) allow you change the mouse navigation
schemes according to the schemes of other 3D applications. Linux users might want to change the modifier key mapping for
navigation to CTRL since some window managers catch the ALT key.
Inspector
The "Inspector" is the main tool for viewing and modifying CityEngine objects. Depending on the type of object selected, the
inspector adapts its user interface to provide full access to the objects attributes. The inspector is invoked via
WindowInspector in the main-menu, or by pressing ALT+I .
For CityEngine layer objects such as shapes, the inspector shows all attributes and parameters of the object. If the object is
associated with a rule file, the rule file is parsed and all rule parameters are available for modification. Each rule parameter can take
its value from either the rule itself, from the object, from a user-defined value or from a compatible map. You can change the source
of the rule attribute value in the "Source" column of the rule parameter table.
Besides the attributes, shapes have a seed which is used for the random number generator of the rule engine. Changing the seed
will influence all random dependent rules such as explicit rand() calls as well as probabilistic rules (e.g. Lot33%: A 33%: B else:
C). To reset the seeds to their default values, select ShapesReset Seed from the main menu. To randomize seeds, select
ShapesUpdate Seed and Generate.
Shape inspector showing the relevant attributes and parameters.
The start rule where generation will start can be entered in the "Start Rule" field. If this value does not match any rule in the rules
file, no generation will take place.
The inspector not only supports editing of single objects but also collection of objects. Attributes that are unique across all objects
are shown as-is. If some attribute has different values in the object collection, the attribute is marked as non-unique with the ? sign.
Regardless of the uniqueness of attribute values, changing a value will apply this value to all objects in the collection. This allows
for easy editing of large collection of objects.
In addition, the inspector automatically groups object collections by type so that even for heterogeneous collection multi-edit is
possible.
CityEngine Workflow
This guide gives a hands-on description of the basic CityEngine modeling workflow. This page describes similar steps as
when using the City Wizard. But in contrast, here the different steps are invoked manually.
Creating a new CityEngine Scene

After at least one CityEngine project has been created, the first step is to create a new scene. This can be done in the main menu
via File New... CityEngine CityEngine scene . The name of the CityEngine scene can now be entered and after
pressing Finish, the new project is created.
Creating a City Layout

Starting with CityEngine 2010, street and lot shapes are created dynamically from given graph network structures. Therefore,
the extra steps of creating and subdividing shapes are no longer necessary.
The easiest way to create a city layout consisting of streets, blocks and lots is to invoke the Street Growth Wizard from the main
menu Graph Grow Streets... In this wizard, several growth parameters such as the intended number of streets or the street
pattern can be selected. When completing the wizard, CityEngine creates a new Street Network layer (or extends an existing street
layer, if selected) containing the graph network, blocks, and street and lot shapes. Later, the resulting shapes can be used as a
starting point for the grammar-based modeling.
The created layout in the 3D Viewport (generated with the default growth parameters). Top viewport shows street
network and blocks. Bottom viewport shows street and lot shapes.
Street networks can also be edited manually by using the graph edit or transform tools in the main toolbar. Selected streets are
deleted via the DELETE key. By using the inspector window, attributes such as the width of the selected streets can be edited.
Available tools for street network and shape editing.
In addition, street networks can be designed in an external application such as Autodesk's AutoCAD and then imported into the
CityEngine. This can be done by invoking the import wizard in the File menu, e.g. File Import... CityEngine Layers
DXF Import for .dxf files. Alternatively, CityEngine also supports data exported from OpenStreetMap.
Similarly, arbitrary polygon meshes can be designed in an external application such as Autodesk's Maya or ESRI's ArcGIS and
then imported into the CityEngine. This can be done by invoking the import wizard in the File menu, e.g. File Import...
CityEngine Layers OBJ Import for .obj files or (Shapefile Import for ESRI Shapefiles accordingly). The imported shapes can be
used in the same way as shapes generated by the CityEngine: You can edit them and you can assign CGA rule files in order to
generate building models.
Using the City Wizard

The City Wizard is the easiest way to generate your first city within seconds. It integrates above steps - creating street networks,
street and lot shapes - in a single user interface step and uses pre-defined parameter sets for the algorithms. It also assigns
selected rule files to the created shapes. The created city is stored in a CityEngine scene file, and can be explored, modified and
further extended.
The City Wizard is invoked from an existing workspace any time by selecting File New ... . Then select City Wizard, hit next
and follow the self-explaining wizard pages.
The four City Wizard pages that guide the generation of different city types.
The schematic city type.
The sci-fi city type.
The textured city type.

Rule-based Modeling
In CityEngine, building models are described through CGA Rules. A CGA rule file consists of several rules that define how
the actual building geometry is created. After a CGA rule file is assigned to a shape, the generation of the building model
starting from this shape can begin. In this tutorial we will create a single CGA file with very basic rules.
Creating and writing a new rule file

A new CGA shape grammar rule file can be created clicking:
New ... CityEngine CGA Grammar File
A new CGA file is created in the rules/ directory of your project, and the CGA rule editor is opened.
In the CGA editor, grammar authoring can now be started by defining the building parameters: Therefore, the minimum and
maximum building height are defined as so-called rule attributes. These values can later be changed conveniently for single
buildings in the Inspector.
attr minheight = 10
attr maxheight = 30
Every shape (lot or street shape) has a specific start rule that triggers a rule from the rule file. For example, lots generated in the
CityEngine have the start rule Lot by default. Select a single lot and look into the Inspector to see the current start rule.
Inspector view of a selected shape.
The start rule defines the first rule that is triggered form the rule set. We therefore write the start rule for our building as follows:
Lot --> extrude ( rand ( minheight , maxheight )) Envelope
The lot will be extruded to a random height between minheight and maxheight.
Note that pressing Ctrl-space in the CGA editor triggers the code completion feature. Possible commands and their parameters
are listed as suggestions which makes coding CGA easier without the need to look up commands in the reference.
Assigning rules and generating

In the next step, the newly created rule file has to be assigned to the corresponding shapes (in the above case to lots):
Select the lot layer Lots in the scene editor
Shapes Assign Rule File ...
Select the file CGA file from the rules directory and hit Ok . The selected lot now has an assigned rule file.
Select some lots in the 3D viewport and hit the Generate button in the toolbar in order to generate the buildings. You
see below the generated buildings using a simple extrusion rule in the CGA file for deviation.
The generated extruded models.

Quick Start: Model Export
CityEngine can export graphs (street networks), shapes (such as lots or street shapes), and models (such as buildings). This page
describes a step-by-step workflow how to export the models (i.e. building- and street-geometry) into the Wavefront OBJ format.
CityEngine can export to a number of other formats, here is an overview (see the manual for details):
Exporting Models to Wavefront OBJ Format

1. Open a scene (e.g. one of the tutorial scenes) and select some shapes in the Shape Layers or by Right-Left-Drag-
LMB . The highlighted parts in the following screenshot show that we have selected two shapes with the same rule file
and the same start rule. For the left shape, we have already generated a model.
2. Open the batch export wizard with File Export... . You will be presented with the first of three wizard pages for the
batch export of models. Select the entry
CityEngine Export Models of Selected Shapes (all models are generated) and hit next .
3. The second page lets you choose the file format. Select Wavefront OBJ .
4. The third page lets you choose amongst a variety of format-specific options, the most important ones are the export
location and the file base name (highlighted). Please refer to the Export Option Reference for a description of the
individual options.
5. Hit Finish to start the batch export.
6. The obj file, textures and an export log are written to the target location, in this case
C:\Users\shaegler\Documents\models\two_buildings_0.obj.
Copyright 2008- 2010 Procedural Inc.
Window Type Overview
The main window types of the CityEngine.

1. File navigator with CGA outline
2. Scene editor for scene, layer, and object management
3. CGA rule editor with text and graphical view
4. First 3D viewport
5. Second 3D viewport (with a different camera).
6. Inspector for a detailed view and editing of currently selected objects.
7. "Log" for CityEngine messages; "Console" for CGA output; "CGA Problems" for CGA compiler errors and warnings,
"Progress" for progress reporting of long-running CityEngine operations.
The Viewport Window
The 3D viewport is your main interaction tool with the current CityEngine scene besides the scene window. You can have any
number of open viewports. Select WindowNew Viewport from the main menu to create a new viewport.
Tasks:
1. 3D Navigation Essentials
2. Viewing Modes and Display Settings
3. Object Selection
4. Object Edit and Transform Tools
5. Cameras
6. Bookmarks
7. Multiple Viewport Windows
8. Keyboard Shortcut Reference
For navigation in the 3d viewport you may use the navigation tools to track, tumble or dolly. Select the appropriate tool in the toolbar
and click-and-drag the mouse in the viewport. Alternatively, the three navigation modes can be applied at any time in conjunction
with a modifier. The default settings are as follows:
ALT+LMB : Tumble camera around the point of interest.
ALT+MMB : Track camera parallel to the view plane (through the point of interest), also known as panning.
ALT+RMB or Mouse Wheel: Dolly the camera towards or away from the point of interest, meaning the distance of the camera to
the point of interest is changed while staying on the same axis.
In addition, there are a number of operations that make navigation within complex scenes easier:
F : Frame the selection. The camera's point of interest is placed in the center of the selection and the camera distance is adjusted
accordingly. You can also frame the current selection by clicking on the Frame button.
A : Frame all. The camera's point of interest is placed in the center of all objects and the camera distance is adjusted accordingly.
You can also frame all objects by clicking on the Frame All button.
SPACE : Maximize 3D viewport. The active 3D viewport is maximized and fills the entire CityEngine window. Pressing SPACE
again restores the previous window layout.
As a consequence, the typical navigation works by selecting an object via LMB or via drag-LMB and then pressing F to frame
the selection. Afterwards the selection can be explored via tumble, track and dolly.
Note: The CityEngine preferences ( Preferences Navigation Devices Mouse ) allow you change the mouse navigation
schemes according to the schemes of other 3D applications. Linux users might want to change the modifier key mapping for
navigation to CTRL since some window managers catch the ALT key.

A 3D viewport can render its contents in three different modes:
Wireframe: all edges of objects are drawn as lines. There are no filled polygons so you can "look-through" the objects.
The wireframe mode can be activated by selecting the Wireframe button or pressing 4 . You can always overlay
wireframe independent of the viewing mode by enabling Wireframe on Shaded/Textured in the View Settings menu or
pressing 7 .
Shaded: all polygons are filled with the object colour. No texturing takes place. The shaded mode can be activated by
selecting the Shaded button or pressing 5 .
Textured: all polygons are filled with textures and object colours. The textured mode can be activated by selecting the
Textured button or pressing 6 .
The View Settings menu allows further customization of the rendering:

Scene Light toggles between the global scene light (see Viewport Preferences) and the headlight scene illumination.
You can toggle the scene light by pressing L .
Wireframe on Shaded/Textured turns on and off the wireframe overlay. You can toggle wireframe overlay by pressing
7 .
Shadows turns on and off the shadows for generated models. Note that enabling on shadows on large models may
considerably affects rendering performance.
Bounding Boxes turns on and off the rendering of bounding boxes. Bounding boxes are "shoeboxes" around actual
objects that may help navigating complex scenes. You can toggle bounding box rendering by pressing B .
Information Display turns the information display on and off. The information display gives some statistics of the current
scene such as number of objects and polygon count. You can toggle information display visibility by pressing D and
then D again.
Grid turns the grid on and off. You can toggle the grid by pressing D and then G
Axes turns the axes on and off. You can toggle the axes by pressing D and then A
Compass turns the compass on and off. You can toggle the compass by pressing D and then C
The layer buttons determine, which layer types are visible on a per-viewport basis:
Show/Hide Map Layers toggles attribute map layer visibility for this viewport. Selective rendering of layers can be used
e.g. for rendering shapes in one viewport and geometries in another. You can toggle map layer visibility by pressing
F9 .
Show/Hide Graph Networks toggles graph network visibility for this viewport. You can toggle graph network visibility by
pressing F10 .
Show/Hide Shapes toggles shape visibility for this viewport. You can toggle shape visibility by pressing F11 .
Show/Hide Models toggles model visibility for this viewport. You can toggle model visibility by pressing F12 .
Note: On Linux, visibility is mapped to SHIFT+F9 , SHIFT+F10 , SHIFT+F11 , and SHIFT+F12 to avoid conflicts with key
bindings of certain window managers.
Viewport settings are stored per-viewport together with your scene data. This means that when you re-open a scene, you will get
exactly the same viewport settings while you were saving the scene.
Note: Global viewport settings can be changed by selection EditPreferencesGeneralViewport from the main menu.
See also Viewport Preferences.
Object Selection
The selection of objects forms the basis for most CityEngine operations such as generation or transformation. The selection
tool is enabled by pressing the corresponding tool button in the toolbar or by hitting Q .
Four different selection modes are available:

Click-LMB selects an individual object.
Double-Click-LMB selects an object's components (faces, edges, or vertices).
Right-Left-Drag-LMB selects objects that intersect with the selection rectangle.
Left-Right-Drag-LMB selects objects or components that are fully inside the selection rectangle.
In addition, four different types of selection modification are available: Replace (the default), Add, Invert, and Remove. The
modifiers define how a new selection behaves with respect to an existing one. The modifier keys SHIFT and CTRL temporarily
define the current selection modification:
If no modifier key is pressed the previous selection will be replaced with the new one.
Holding down SHIFT while clicking or dragging will add to the existing selection.
Holding down CTRL inverts/toggles the selection state of the newly selected objects.
Holding down CTRL+SHIFT removes objects from an existing selection.
The current selection modification can also be set persistently by choosing the appropriate selection icon in the toolbar, or by
repeatedly pressing Q to toggle through the available modifications.
Selection Menu
The selection menu provides a variety of methods to select a subset of the scene objects. Additionally, selection sets can be
saved, applied and edited. The menu can be accessed either over the main menu Select or by using the context menu of the
view port.
The selection menu
Selection Methods
Select All, Deselect All, Invert Selection

Select all and deselect all can also be triggered using the shortcuts CTRL+A and CTRL+SHIFT+A .
Select Objects in Same Layer

If the source selection contains layers, all children of these layers are selected. If the source selection contains layer-objects, all
children of all parent layers are selected.
Select Objects by Map Layer

Map layers that define a boolean attribute can be used as selection constraints. In the sub-menu, all boolean attributes of all map
layers are listed. After choosing one of these attributes, the attribute is evaluated for all objects of the source selection (at the
center of the objects). Then, the objects where the attribute evaluated to "true" are selected.
Select Objects of Same Type

Selects all objects having the same types as present in the source selection.
Select Objects of Same Group

Selects all objects belonging to the same group as the objects in the source selection. For example if the source selection contains
a block, the resulting selection will contain the block and the block's shapes.
Select Objects with Same Rule File

Selects all objects having assigned a rule file that is present in the source selection.
Select Objects with Same Start Rule

Selects all objects having a start rule that is present in the source selection.
Select Continuous Graph Objects

This method can be used to select graph segments that are continuous, e.g. if they together define one street. In the dialog, there
is one parameter (Max. Angle). This value defines the maximal angle under which two segments are said to be continuous. The
search for continues segments starts at the source selection.
Isolation mode ( I ) and per-viewport layer-visibility ( F9 , F10 , F11 , F12 ) have no influence on the selection result.
However, per-scene layer-visiblity (controlled in the scene window) does influence the result.
Selection Sets
Save Selection Set As...

Arbitrary sets of objects (graph, shapes, models) can be saved into selection sets. A selection set is identified with a user-defined
name.
Apply Selection Set

Existing selection sets are listed in the submenu. To apply one, select the corresponding name. Then, the set objects (which are
still present in the scene) are selected.
Edit Selection Sets...

The edit selection sets dialog
Existing selection sets are listed in this dialog. Sets can be removed, renamed and sorted (up/down).
Isolation the Selection

When working with larger models, it is often useful to reduce the scene temporarily to a smaller working set. To achieve this,
you can use the 3D viewport's "Isolation" feature. When you isolate a selection, only the currently selected object will be visible.
To isolate the selection, click on the Isolate button or press I . Pressing Isolate or I when already in isolation mode will show
the whole model again.

Besides the Selection Tool, a number of object edit and transform tools allow for manipulation of objects directly in the 3D
viewport.
Available Transform and Edit Tools

Currently, the following tools are available:
The Move Tool W moves selected objects and components along the axes (X, Y, Z). Note that
these axes are defined by the currently defined coordinate reference systems, see below. Click-Drag-LMB the
handles for individual axes. Use the "free handle" to move the selection on the X-Z or object plane. If the selection
contains a single street network node or shape vertex is selected, the tool will snap to edges and vertices of other
objects. Holding down SHIFT while dragging inhibits snapping.
The Rotate Tool E rotates selected objects and components around the axes (X, Y, Z). Press
SHIFT to snap to 45 degree angles.
The Scale Tool R scales selected objects and components along the axes (X, Y, Z). Use the "free
handle" in order to uniformly scale along all axes.
Using the Create Shape Tool S you may create new shapes or extend existing shapes with new vertices.
Refer to Creating and Editing Shapes Manually for details.
Similarly, by applying the Create Segment Tool S you may create new street or extend existing networks.
Refer to Creating and Editing Street Networks Manually for details.
The available object transform types: Move, Scale, Rotate.
Reference Coordinate Systems

By default, the transform tools (Move, Scale, Rotate) operate in the World Coordinate System, i.e. all operations take place along
the principal axes (X, Y, Z). In many cases, it is more convenient the use a specific object's coordinate system as the reference
system.
The currently active reference space (world vs. object) can be toggled by clicking in the appropriate toolbar icon or by pressing , .
World Coordinates
Object Coordinates
If object space is active and multiple objects are selected, the current coordinate space is determined by the currently selected
Lead Object. The lead object is always the most recent individually selected object. Therefore, you can change the lead object by
holding SHIFT and selecting the new lead object.
Several objects (with lead object bottom middle) selected in World mode.
The same selection after switching in Object mode.
The local coordinate space of an object depends on the object or component itself and is defined as follows.
Shapes: The local X axis is defined by the first edge. The local Y axis is defined by the face normal. The local Z axis is
given by the cross-product of X x Y, i.e. it is normal to local X and Y.
Shape edges: The local space is defined by the local space of the associated face.
Shape vertices: The local space is defined by the local space of the associated face, or the first face in case of multi-
face shapes.
Graph edges: The local X axis is defined by the direction of the edge. Local Y and Z are calculated in a way, that Z lies
in the world X-Z plane and Y is orthogonal to X and Z.
In addition, you may lock the current reference system by using the Lock icon or by pressing . .
Lock Current Coordinate Space
A locked reference space defines a persistent coordinate space (for example with ongoing selection) until it is unlocked (by pressing
the icon or . again).
Locked coordinate system.
Numeric Transform Input

While transforming one or multiple objects, the numeric transform text field in the Tools toolbar provides feedback of the current
transformation (e.g. when moving an object by 10.0 along the X axis, the field will show "10.0 0.0 0.0").
This text field can also be used to carry out transforms numerically. Since previous values are stored in the drop down menu, you
may select a different object and hit ENTER in the text field in order to execute the corresponding transformation. Note that vector
components (X Y Z) are separated by a space character. For scale transforms you may enter only a single value in order to scale
uniformly.
Make Names Unique

Names of generated objects in a CityEngine scene are not automatically unique. In some cases, unique names are required. This
can be achieved using the Make Names Unique Tool in the Edit Menu.
Edit Make Names Unique...
All selected scene objects are enumerated and renamed in ascending order. The delimiting character can be chosen.
The Make Names Unique dialog
Note that this is a one-time operation. Once you modify your scene (add scene objects), there might be new shapes with
non-unique names again.
Cameras
CityEngine supports an arbitrary number of cameras. Multiple cameras are especially useful if your are working with more
than one 3D viewport. There are four predefined cameras:
Perspective: a perspective view of the scene.

Front: a front view of the scene (you look along the z-axis)
Top: a top view of the scene (you look along the y-axis)
Side: a side view of the scene (you look along the x-axis)
In addition to these predefined cameras, you can always align the camera along a specific axis by pressing X , Y , or Z . While
Y only orients the Y-Axis in camera direction, X and Z also re-orient the Y-axis upwards. This in combination with switching
between orthographic and perspective view P allows you to quickly walk through multiple views of your scene.
The cameras are accessible from the Camera menu. Cameras are shared among 3D viewports, meaning that if multiple 3D
viewports use the same camera, changing the camera in one viewport (e.g. by rotation) will affect the second viewport with the
same camera as well.
In order to create your own camera, you can either click on the Camera menu button, or select New Camera from the Camera
menu. This will automatically clone the current camera and save it under a new name. By choosing Edit Cameras, you can fine-
tune the camera and change all camera parameters individually.
A camera configuration has the following options:

Perspective: if selected, the camera will give a perspectively correct image. If not selected, the camera will operate in
orthogonal mode where parallel edges will also appear as parallel lines in the 3D viewport. You can switch between
perspective and orthogonal mode by pressing P or selecting Orthogonal View from the Focal Length menu.
Angle of view: the width of the field of view. For your convenience, some predefined angles of view corresponding to
specific focal lengths are accessible from the Focal Length / Lens menu.
Near and far clipping plane: these values limit the space where your camera will work. If your scene disappears when
you move far away from it, increase the far clipping plane.
Configuration: these values position and orient the camera. You can enter a world coordinate position for the camera as
well as a specific rotation of the camera.
Distance to Point of Interest: this value corresponds to the distance between the camera and the POI. The POI is also
the center of rotation and thus the distance to the POI defines the radius of the camera rotation.
Bookmarks
A specific camera configuration can be saved as bookmark. Bookmarks are accessible from the Bookmarks menu . For the
predefined perspective, front, top, and side cameras there is always a "Home" bookmark which restores the default configuration
of the current camera. The home bookmark can also be activated by pressing H .
Bookmarks and cameras are independent this means that you can apply any bookmark to any camera. Bookmarks are always
applied to the currently active camera.
In order to create a new bookmark, you can either select Bookmark from the Boomarks menu or click on the Bookmarks menu
button. The first ten bookmarks are mapped to the numeric keypad and can be activated by pressing the corresponding key on the
numeric keypad. Pressing CTRL+[NUMPAD] on the numeric keypad will automatically store the current camera configuration at
the corresponding bookmark position. This allows you to store and recall bookmarks without navigating to the viewport menu.
Similar to cameras, bookmarks can be edited by choosing Edit Bookmark from the Bookmarks menu.
A camera bookmark has the following options:
Perspective: if selected, the camera will give a perspectively correct image. If not selected, the camera will operate in
perspective and orthogonal mode by pressing P or selecting Orthogonal View from the Focal Length menu.
Angle of view: the width of the field of view. For your convenience, some predefined angles of view corresponding to
specific focal lengths are accessible from the Focal Length menu.
Near and far clipping plane: these values limit the space where your camera will work. If your scene disappears when
Configuration: these values position and orient the camera. You can enter a world coordinate position for the camera as
well as a specific rotation of the camera.
Distance to Point of Interest: this value corresponds to the distance between the camera and the POI. The POI is also
You can open as many 3D viewports as you require for your modelling task. A new 3D viewport is created by selecting
WindowNew Viewport from the main menu. A very common configuration is a single viewport for navigating the scene as
well as a four viewport configuration with a perspective, top, front, and side view. By pressing SPACE you can maximize the
current viewport. Similarly, the previous viewport configuration is restored by pressing SPACE again.
By sharing a camera between viewports but having different rendering modes or layer visibility, you can very easily compare side to
side e.g. shapes and generated models. While sharing a camera between viewports, camera changes in one viewport affect the
other viewport and vice versa.
Keyboard Shortcut Reference for the 3D Viewport
The following table summarizes the 3D viewport shortcuts:
Key Description
ALT+LMB Rotate
ALT+MMB Track / pan
ALT+RMB Dolly
LMB Apply tool / Replace selection
SHIFT+LMB Add to selection
CTRL+LMB Toggle selection
SHIFT+CTRL+LMB Remove from selection
A Frame all
B Toggle bounding boxes
D Toggle information display visibility
F Frame selected
I Toggle isolation
L Toggle scene light
P Toggle between perspective and orthogonal view
X Apply left/right side view (changes camera orientation only)
Y Apply top/bottom view (changes camera orientation only)
Z Apply front/back view (changes camera orientation only)
H Apply default camera settings
[NUMPAD] Apply bookmark at position [NUMPAD]
CTRL+[NUMPAD] Save current camera settings as bookmark at position [NUMPAD]
CTRL+A Select all
4 Select wireframe mode
5 Select shaded mode
6 Select textured mode
7 Toggle wireframe on shaded
F9 Show / hide map layers
F10 Show / hide graph networks
F11 Show / hide shapes
F12 Show / hide models
Q Select selection tool
W Select translate tool
E Select rotate tool
R Select scale tool
S Select create shape tool
G Select graph (i.e., street network) create segment tool
Note: Depending on your Operating System, some of the default CityEngine shortcuts might be globally assigned to other
actions. In this case, you have the choice to either change the Operating System's defaults (where available) or to change
CityEngine's key bindings (see Keyboard Preferences
Note: You can always recall a list of currently active CityEngine shortcuts by pressing CTRL+SHIFT+L .
Note (Mac OS X): For most shortcuts, use the COMMAND key instead of CTRL .
The File Navigator
The Navigator is your main tool to navigate and operate on files and folders. You can open the navigator by selecting
WindowShow Navigator from the main menu.
The file navigator with

inspector visible, showing the outline of a CGA rule file.
You can open and edit CGA and scene files within CityEngine by double-clicking the corresponding file in the navigator. To directly
open a file, hit CTRL+SHIFT+R and type the name of the file you are looking for. The navigator provides also basic operations
such as copying, renaming and deleting files and folders.
For performance reasons the CityEngine keeps an internal copy of the workspace. If you modify files outside of CityEngine (e.g. by
editing a file in an external program or renaming a file in the system file explorer), you have to refresh the CityEngine's internal
representation. Choose FileRefresh Workspace or simply hit F5 .
The file navigator can inspect selected files. In the case of CGA rule files, the functions and rules are listed. Clicking on entries in
the CGA file inspector will let CGA Shape Editor to scroll to the corresponding entry in the rule file. Hence the file navigator
inspector is a powerful tool to navigate in a rule file.
The Scene Window
This window is the central place where you manage your scene. A CityEngine scene is organized in layers. Currently, the
following layer types exist:
Environment Layers control common 3D viewport parameters such as scene's panorama or the scene light. Both layers
are configured using the inspector.
Map Layers contain arbitrary maps (images) and can be used to globally control object attributes.
Graph Layers contain street networks and blocks, dynamic shapes (street shapes, building footprints), and generated
models
Shape Layers contain static shapes, typically used as building footprints for generation of CGA models.
Working with Layers

Layers can easily be deleted, duplicated or merged by selecting the corresponding menu item from the context menu or the "Layer"
menu in the main menu. In addition to that, you can use the standard cut, copy, and paste actions to transfer objects between
layers.
The visibility of each layer in the viewport can be toggled by clicking on the "eye" symbol left to the layer name. You may re-
arrange layers by dragging them to the desired position.
You can control the visibility of different object / layer types on a per-viewport basis from the view settings menu.
Using the Search Field to Select and Filter Objects

In the search field on the top of the scene window you can type a wildcard expression (e.g. "Lot*") and limit the visible objects in
the scene window by clicking on the magnifying glass icon on the right. You can use the same expression to select matching
objects. To show all objects again, clear the search field and select the magnifying glass icon again.
Importing and Exporting Layers

In the case where building lots or mass models have been already modeled with an external program, these can be imported as
shape layers. First you have to convert your shapes into a grouped ".obj" file (each group corresponds one shape) or a ".dxf" file.
Afterwards copy it into the data folder of your project and import it via FileImportCityEngine Layers from the main menu or
via the navigator context menu on the file. Afterwards the CGA shape grammar rules can be applied in the usual way on these
imported shapes.
Any object from the scene window can be exported to a new scene by choosing
FileExportExport Selected Objects as .cej File To import layers from the exported ".cej" file into a new scene, select
FileImportCityEngine Layers from the main menu.
The CGA Editor
By double clicking on a ".cga" file in the Navigator window, the corresponding file is opened in the CGA shape grammar editor.
Another possibility to open a ".cga" file for editing is to click on Rule File in the Inspector window if the selected object has already a
rule file assigned. The typical workflow with the CGA shape grammar editor is:
Assign a rule to the selected objects either via the RMB-menu on the rule file in the Navigator, or via RMB-menu in the
Viewport, or via ShapesAssign Rule File... in the main menu. In the latter two cases the rule has to be selected in
the opened dialog.
Open the rule file in the CGA shape grammar editor and edit the rules.
Press CTRL+S for saving the rule file.
Press CTRL+G for (re-)generating the model.
The rule editor has syntax highlighting and shows syntax errors (the latter are described in more detail in the CGA Problems
window where you can double click on each entry). Furthermore, during typing, command completion can be invoked via
CTRL+SPACE .
NOTE: you can always recall a list of currently active CityEngine shortcuts by pressing CTRL+L .
The Log View
The Log View shows the log records of the CityEngine. You can open the log view by selecting WindowShow Log from the
main menu. Log records are created by various parts of the CityEngine and range from informational messages to severe internal
errors conditions (such as out of memory). The properties and values of each log record are shown in this view. The Log View can
is especially useful in tracking down strange or erroneous behavior.
The meaning of the severity color is as follows:
None: Information
Yellow: Warning
Red: Error
The CGA Console
If a CGA command produces textual output (such as the CGA print command), this output will be shown in the CGA console.
You can open the CGA Console by selecting WindowShow Console from the main menu.
The CGA Problems View
If you encounter any errors during CGA shape grammar editing, they will be displayed in the Problems view. Errors and
warnings are passed up from the CGA compiler. The Problems view lists the error, filename and folder. If you select an error the
associated file will open in the CGA shape grammar editor and the cursor will display the line where the error was encountered.
You can open the CGA problems view by selecting WindowShow CGA Problems from the main menu.
The Progress View
The progress view shows the progress status of long running CityEngine operations. You can monitor the progress in the
progress view as well as cancel an operation by clicking on the red Stop button on the right-hand side of the operation. You can
open the progress view by selecting WindowShow Progress from the main menu.
NOTE: You can always cancel all pending model generation by pressing the ESC key or choosing Cancel from the main toolbar.
The Inspector
The "Inspector" is the main tool for viewing and modifying CityEngine objects. Depending on the type of object selected, the
inspector adapts its user interface to provide full access to the objects attributes. The inspector is invoked via
WindowInspector in the main-menu, or by pressing ALT+I .
Shape inspector showing the relevant attributes and parameters.
For CityEngine layer objects such as shapes, the inspector shows all attributes and parameters of the object. If the object is
associated with a rule file, the rule file is parsed and all rule parameters are available for modification. Each rule parameter can take
its value from either the rule itself, from the object, from a user-defined value or from a compatible map. You can change the source
of the rule attribute value in the "Source" column of the rule parameter table.
If the "Live Mode" is enabled, model generation is triggered immediately when attribute or parameters change. Thus, live mode
allows you to customize your rules interactively by just changing the values.
Besides the attributes, shapes have a seed which is used for the random number generator of the rule engine. Changing the seed
will influence all random dependent rules such as explicit rand() calls as well as probabilistic rules (e.g. Lot33%: A 33%: B else:
C). To reset the seeds to their default values, select ShapesReset Seed from the main menu. To randomize seeds, select
ShapesUpdate Seed and Generate.
The start rule where generation will start can be entered in the "Start Rule" field. If this value does not match any rule in the rules
file, no generation will take place.
The inspector not only supports editing of single objects but also collection of objects. Attributes that are unique across all objects
are shown as-is. If some attribute has different values in the object collection, the attribute is marked as non-unique with the ? sign.
Regardless of the uniqueness of attribute values, changing a value will apply this value to all objects in the collection. This allows
for easy editing of large collection of objects.
In addition, the inspector automatically groups object collections by type so that even for heterogeneous collection multi-edit is
possible.
For attribute maps, the inspector lets you change the map files, modify the bounds, and adjust the display offset (how much the
rendering of the map is displaced regarding the actual map values). In addition to that, an overly color and alpha value for the map
can be specified. The mapping function can also be edited by the map inspector.
Attribute map inspector including layer attributes.

Configuring the Windows Layout
The CityEngine main window can contain two different types of windows (views and editors) and its layout is controlled by
perspectives.
A perspective is a group of views and editors in the main CityEngine window. Within the main CityEngine window, each perspective
may have a different set of views but all perspectives share the same set of editors. With the exceptions of the 3D viewport, views
usually exist as a single instance, meaning that e.g. there is only one inspector. Modifications in views are immediately propagated
inside CityEngine and views may exist without an open editor. You can open views by selecting the view type from the main
Window menu. Editors follow more an open-save-close lifecycle model and are opened by double clicking on a file in the Navigator.
The CityEngine provides the following views:
Navigator for file management
Log view for CityEngine messages
Console view for CGA output
CGA Problems view for CGA compiler errors and warnings
Progress view for progress reporting of long-running CityEngine operations.
Multiple 3D viewports
Outline view for an overview of the currently selected objects
Shape tree view for browsing the shape tree
Inspector for a detailed view and editing of currently selected objects.
The editors provided by CityEngine are:

CGA shape grammar editor for editing .cga files
Scene editor for editing .cej files
A basic text editor for editing arbitrary text files
An editor is also a visual component within the Workbench. It is typically used to edit or browse a resource. The visual presentation
might be text or a diagram. Typically, editors are launched by clicking on a resource in a view. Modifications made in an editor
follow an open-save-close lifecycle model.
Note: To directly open a file, hit CTRL+SHIFT+R and type the name of the file you are looking for.
Some features are common to both views and editors. Both can be active or inactive, but only one window can be active at any one
time. The active window is the one whose title bar is highlighted. The active window is the target for common operations like
selection. The active window also determines the contents of the status line. If an editor tab is not highlighted it indicates the editor
is not active; however views may show information based on the last active editor.
Tasks:
1. Editors
2. Views
3. Dragging Windows
4. Default Window Layouts
5. Saving and Loading Window Layouts
Editors
Depending on the type of file that is being edited, the appropriate editor is displayed in the editor area. For example, if a
".cga" file is being edited, a CGA shape grammar editor is displayed in the editor area. The figure below shows an editor CGA
shape grammar editor open on the file "RR20_appartments_01.cga". The name of the file appears in the tab of the editor. An
asterisk (*) appearing at the left side of the tab indicates that the editor has unsaved changes. If an attempt is made to close the
editor or exit CityEngine with unsaved changes, a prompt to save the editor's changes will appear.
When an editor is active, the main menu bar and toolbar of CityEngine contain operations applicable to the editor. When a view
becomes active, the editor operations are disabled. However, certain operations may be appropriate in the context of a view and
will remain enabled.
The editors can be stacked in the editor area and individual editors can be activated by clicking the tab for the editor. Editors can
also be tiled side-by-side in the editor area so their content can be viewed simultaneously. See Dragging Windows how to
rearrange views and editors.
CTRL+F6 pops up a list of currently open editors. By default, the list will have selected the editor used before the current one,
allowing you to easily go back to the previous editor.
If a resource does not have an associated editor, CityEngine will attempt to launch an external editor registered with the platform.
These external editors are not tightly integrated with CityEngine and are not embedded in the main window of CityEngine.
On Windows, if the associated editor is an external editor, CityEngine may attempt to launch the editor in-place as an OLE
document editor. For example, editing a ".doc" file will cause Microsoft Word to be opened in-place within CityEngine if Microsoft
Word is installed on the machine. If Microsoft Word has not been installed, Word Pad will open instead.
Views
The primary use of Views is to provide navigation of the information inside CityEngine. For example:
The Shape Tree view displays the structure of a generated model.

The Navigator view displays CityEngine projects, their folders and files.
A view might appear by itself, in a floating window or stacked with other views in a tabbed window.
Views have two menus. The first, which is accessed by right clicking on the view's tab, allows the view to be manipulated in much
the same manner as the menu associated with editors. The second menu, called the "view pull-down menu", is accessed by
clicking the down arrow. The view pull-down menu typically contains operations that apply to the entire contents of the view, but not
to a specific item shown in the view. In addition to that, some often used view actions are placed in the toolbar of the view.
Dragging Windows
This section will explain how to rearrange editors and views to customize the layout of the main CityEngine window.
Drop cursors indicate where it is possible to dock views in the CityEngine main window. Several different drop cursors may be
displayed when rearranging views.
Dock above: If the mouse button is released when a dock above cursor is displayed, the view will appear above the view
underneath the cursor.
Dock below: If the mouse button is released when a dock below cursor is displayed, the view will appear below the view
underneath the cursor.
Dock to the right: If the mouse button is released when a dock to the right cursor is displayed, the view will appear to the right
of the view underneath the cursor.
Dock to the left: If the mouse button is released when a dock to the left cursor is displayed, the view will appear to the left of
the view underneath the cursor.
Stack: If the mouse button is released when a stack cursor is displayed, the view will appear as a tab in the same pane as the
view underneath the cursor.
Restricted: If the mouse button is released when a restricted cursor is displayed, the view will not dock there. For example, a
view cannot be docked in the editor area.
In order to change the position of a 3D viewport (or any other) view click in the title bar of the 3D viewport and drag the view across
the CityEngine main window. Do not release the mouse button yet.
While still dragging the view around on top of the CityEngine main window, note that various drop cursors appear. These drop
cursors (see above) indicate where the view will dock in relation to the view or editor area underneath the cursor when the mouse
button is released. Notice also that a rectangular highlight is drawn that provides additional feedback on where the view will dock.
Dock the view in any position in the CityEngine main window, and view the results of this action.
Click and drag the view's title bar to re-dock the view in another position in the CityEngine main window. Observe the results of this
action.
Click and drag the view's title bar outside the CityEngine main window. Notice that it becomes a "Detached" window (floating on the
desktop).
Finally, drag the 3D viewport over another view. A stack cursor will be displayed. If the mouse button is released the 3D viewport
will be stacked with the other view into a tabbed window.
The Workbench allows for the creation of two or more sets of editors in the editor area. The editor area can also be resized but
views cannot be dragged into the editor area.
Open at least two editors in the editor area by double-clicking editable files in the Navigator.
Still holding down the mouse button, drag the editor over the editor area and move the cursor along all four edges as well as in the
middle of the editor area, on top of another open editor. Notice that along the edges of the editor area the directional arrow drop
cursors appear, and in the middle of the editor area the stack drop cursor appears.
Dock the editor on a directional arrow drop cursor so that two editors appear in the editor area.
Notice that each editor can also be resized as well as the entire editor area to accommodate the editors and views as necessary.
It is important to observe the color of an editor tab (in the figure below there are two groups, one above the other)
Blue indicates that the editor is currently active
Default (gray on Windows XP) indicates that the editor was the last active editor. If there is an active view, it will be the
editor that the active view is currently working with. This is important when working with views like the Outline and the
Inspector that work closely with the active editor.
Drag and dock the editor somewhere else in the editor area, noting the behavior that results from docking on each kind of drop
cursor. Continue to experiment with docking and resizing editors and views until the CityEngine window layout has been arranged
to satisfaction.
There are a several predefined window layouts available in CityEngine. Window layouts are called perspectives and can be
accessed by selecting WindowLayout from the main menu. Choose your preferred layout from this list.
The "Four views" perspective resembles a classical perspective, top, front, and side layout and is handy for reviewing models
similar to 2D drawings.
The "Grammar Editing" perspective allocates a larger area to the CGA shape grammar editor and is intended for editing CGA files
and visually verifies the results in a perspective and a front view.
The street generation perspective has a large top and perspective view. It simplifies generation and editing of street networks
without cluttering the layout with unwanted editors.

If you have found a preferred arrangement of windows, you can save it by selecting WindowLayoutSave Perspective
As... from the main menu.
For your convenience, a perspective along with the current open scene is saved automatically with the same name as the scene.
This means that if you re-open a scene, the last associated window layout will automatically be restored.
NOTE: It is recommended to name layouts after specific modeling tasks such as "Grammar Editing". This allows you to easily pick
a corresponding layout to what you are currently working on.
CityEngine Preferences
1. General
2. Appearance
3. Automatic Exit
4. Colors and Fonts
5. Label Decorations
6. Editors
7. File Associations
8. Text Editors
9. Accessibility
10. Hyperlinking
11. Linked Mode
12. Quick Diff
13. Grammar Core
14. Keys
Key Strokes, Key Sequences, and Key Bindings
Schemes
Contexts
Platform and Locale
Customizing Key bindings
Conflict Resolution
15. Mouse
16. 3D Mouse
17. Perspectives
18. Startup and Shutdown
19. Bookmarks
20. Cameras
21. Help
General Preferences
The following preferences can be changed on the General preference page:

Always run in background: Turn this option on to perform long running operations in the background without blocking
you from doing other work.
Keep next/previous part dialog open: If this option is turned on then the editor and view cycle dialogs will remain open
when their activation key is let go. Normally the dialog closes as soon as the key combination is release.
Show Heap Status: Turn this option on to display an indicator showing information about current Java heap usage. A
basic heap monitor is always enabled inside CityEngine and reports Java and core heap usage.
Open mode: You can select one of the following methods for opening resources:
Double click - Single clicking on a resource will select it and double clicking on it will open it in an editor.
Single click (Select on hover) - Hovering the mouse cursor over the resource will select it and clicking on it
once will open it in an editor.
Single click (Open when using arrow keys) - Selecting a resource with the arrow keys will open it in an
editor.
Note: Depending on which view has focus, selecting and opening a resource may have different behavior.
Appearance Preferences
You can change the following preferences on the Appearance preferences page:
Current presentation: Specify the currently active presentation (look and feel).
Override presentation settings: Locally override the settings for the current presentation.
Editor tab positions: Specify either top or bottom to indicate where you want tabs for stacked editors to appear.
View tab positions: Specify either top or bottom to indicate where you want tabs for stacked views to appear.
Perspective switcher positions: Specify the location of the perspective switcher bar (unused in the current CityEngine
release).
Current theme: specifies the currently active theme (color and font set).
Show traditional style tabs: Specify whether traditional (square) tabs should be used in place of the curved tabs.
Enable animations: Enable/disable the feature where views animate to their location when closed or opened.
Automatic Exit
CityEngine features an auto-exit functionality. CityEngine can automatically exit after a given number of minutes of inactivity.
Before exiting, all open files will be saved. Enter '0' minutes in order to disable automatic exit. Automatic exit can be useful for
installations where people usually do not close applications and thus do not return licenses held by these application to the license
server. Closing the application returns the licenses held to the license server as a side-effect and allow in turn other users to start
the application.
Colors and Fonts Preferences
Many of the fonts and colors and used by the CityEngine editors can be set using the Colors and Fonts preference page.
A tree, used to navigation, shows a short preview of the various colors and fonts. The current face (but not size) of any font is
previewed in its label. Colors are previewed in the icon associated with its label. Additionally, some categories provide a more
detailed preview of their contributions. This preview is shown below the description area if available.
Font settings can be changed either by selecting the font from the list and clicking Use System Font to choose the Operating
System font setting or by clicking Change to open up a font selection dialog. Reset can be used to return to the default value.
Color settings can be changed by clicking color to the right of the tree area when a color is selected. Reset can be used to return to
the default value.
Label Decorations
Label Decorations allow additional information to be displayed in an item's label and icon.
The label decorations preference page provides a description of each decoration and allows the selection of which decorations are
visible.
Editor Preferences
You can change the following preferences on the Editor's preference page:
Size of recently opened files list: Each file that is opened in an editor is stored in a list of recently used files in the File
menu. This option controls the number of files that is displayed in that list.
Show multiple editor tabs: Specifies whether you wish to show multiple editor tabs. If off, editor workbooks have one
large tab and all non-visible editors are accessible only from the chevron.
Show Heap Status: Turn this option on to display an indicator showing information about current Java heap usage. A
basic heap monitor is always enabled inside CityEngine and reports Java and core heap usage.
Allow in place system editors: Specifies if OLE in-place editing will be used on the Windows platform.
Restore editor state on startup: Specifies if editors should be restored on the next launch of CityEngine.
Close editors automatically: Specifies whether or not to re-use editors in CityEngine. If on, you may specify the number
of editors to use before they are recycled (the default is 8). You can also specify if a prompt dialog should be opened or
if a new editor should be opened when all editors are "dirty" (have unsaved changes). Once it is turned on, the Pin
Editor action is added to the toolbar and editor tab menu. Pinned editors are not recycled.
File Association Preferences
On the File Associations preference page, you can add or remove file types recognized by CityEngine. You can also associate
editors with file types in the file types list.
File types list
Add...: Adds a new file or file type (extension) to the predefined list. In the resulting New File Type dialog,
type the name of a file or a file extension. If you are adding a file extension, you must type either a dot or a
"*." before the file type (e.g., ".txt" or "*.txt" as opposed to simply "txt").
Remove: Removes the selected file type from the list.
Associated editors list
Add...: Adds a new editor to the list of editors associated with the file type selected above. In the resulting
Editor Selection dialog, you can choose an editor to launch either inside CityEngine (internal) or outside
CityEngine (external); click Browse to locate an editor yourself if the editor you want is not displayed in the
list.
Remove: Removes the association between an editor and the file type selected above. Note: Any editor
that is bound by content type may not be removed from this list. Currently, there is no mechanism available
to remove these editors.
Default: Sets the selected editor as the default editor for the file type selected above. The editor moves to
the top of the Associated Editors list to indicate that it is the default editor for that file type.
Note: Depending on which view has focus, selecting and opening a resource may have different behavior.
Text Editor Preferences
The following preferences can be changed on the Text Editors page and affect the CGA shape grammar editor.
Undo history size: This option allows you to set the size of the undo history for text editors.
Displayed tab width: This option allows you to set the displayed tab width for text editors.
Insert spaces for tabs: This option allows you to insert space characters in place of tab characters.
Highlight current line: This option controls whether the current line is highlighted or not.
Show print margin: This option controls whether the print margin is visible or not.
Print margin column: This option allows you to set the print margin column position.
Show line numbers: This option controls whether or not line numbers are shown on the left side of the text editor.
Show range indicator: This option controls whether or not range indicators are shown in the text editor.
Show whitespace characters: This option controls whether to display whitespace characters in text editors.
Show affordance in hover on how to make it sticky: This option controls whether to show an affordance in the hover on
how to make it sticky.le
Enable drag and drop of text: This option controls whether text drag and drop is enabled.
Warn before editing a derived file: This option controls whether to warn if a derived file is going to be edited.
Smart caret positioning at line start and end: This option controls whether the editor automatically positions the caret
and the start or end of a line.
Appearance color options: This option controls various appearance colors.
Accessibility Preferences
You can change the following preferences on the Accessibility preference page:
Use custom caret: Replaces the original caret (the marker that indicates where the next character will appear) with a
custom caret and shows a different caret for Overwrite and Insert modes.
Enable thick caret: Replaces the original caret with a more visible, thicker caret.
Use characters to show changes on line number bar: Quick Diff shows the changes in a vertical ruler using colors.
Color-blind persons can enable this option to show differences with different characters in the line number ruler.
Hyperlinking
You can change the following preferences on the Hyperlinking preference page:
Enable on demand hyperlink style navigation: Enables/disables the hyperlinking feature in text editors. This setting is
currently not used by the CGA shape grammar editor.
Default modifier key: The default modifier key that activates the hyperlinking feature.
Linked Mode
You can change the following preferences on the Linked Mode preference page:
Ranges: the range, which activates the linked mode.
Show in text as: the visual appearance of the linked mode text.
Color: the color of the linked mode text.
Quick Diff
The following preferences can be changed on the Quick Diff preference page.
Enable quick diff: This option will enable or disable the quick diff option.
Show differences in overview ruler: This option will show differences in the overview ruler.
Colors Changes: This option controls the color of changes.
Colors Additions: This option controls the color of additions.
Colors Changes: This option controls the color of changes.
Colors Deletions: This option controls the color of deletions.
Use this reference source: This option sets which reference to use as the base for generating quick diff comparisons.
Options are:
Version on Disk: Current file is compared against the last saved version on disk.
Grammar Core
The Grammar Core preferences page controls various options with respect to rule derivation (model generation), display,
rendering, occlusion and miscellaneous engine arguments.
Derivation
The maximum function call depth controls the maximum recursion level of function calls. This includes attributes.
The maximum derivation depth controls the maximum recursion level of rules (createShape), or the depth of the shape
tree, respectively.
The maximum number of active shapes aims at limiting the breadth of the shape tree.
If "Generate with trim plane computation" is disabled, trim planes are not computed during derivation.
The extent of the trim planes can be controlled with trim plane size; note that this is for computation only, the rendering
size of the trim planes can be controlled in the display settings below.
Occlusion
Disable inter-/intra-occlusion queries: Disabling intra-shape tree or inter-shape tree (neighbors) occlusion queries might
be useful for rule debugging.
Maximum distance for touches: Due to floating point limitations, the distinction of touches() and overlaps() is
enforced using a threshold value.
Neighborhood distance for inter-occlusion queries: all shapes within this distance of the bounding box of a shape are
considered neighbors; this means their models need to be derived for inter-occlusion queries.
Display Options
Trim plane size: Defines the display size of trim planes.
Pivot size: Defines the display size of pivots.
Pivot line with: Defines the display line width of pivots.
Scope line with: Defines the display line width of scopes.
Rendering (affects only generated models)

Max texture width/height: Textures which are wider/higher than this value are rescaled to this value in order to save
memory.
Use CityEngine shader: Deselect to disable GLSL shaded rendering and enables the standard OpenGL shader. Use
this flag if OpenGL 2.0 is not available.
Matching profile: Using this popup, you can control render performance versus memory consumption. For most use
cases, "Balanced" is a good choice.
Use Two-Sided Lighting: Deselect to disable two-sided lighting.
Force OpenGL Double Buffering On Windows (starting with Vista) and Mac OSX, double buffering is disabled because
the operating system already takes care of smooth rendering. Use this option to force double buffering.
Statistics
Write grammarcore information: Select to enable console output of grammar core information.
Logging
Disable the RCP Logger: Disabling the logger might speed up generation and responsiveness of the CityEngine.
However, important feedback from the grammarcore is lost.
CityEngine Preferences
Keys
The function of the keyboard can be extensively customized CityEngine using the keys preference page. Within CityEngine, key
strokes and key sequences are assigned to invoke particular commands.
Tasks:
1. Key Strokes, Key Sequences, and Key Bindings
2. Schemes
3. Contexts
4. Platform and Locale
5. Customizing Key bindings
6. Conflict Resolution
Mouse Preferences
The mouse preferences allow you to select specific mouse schemes. CityEngine defines mouse schemes for major 3D applications.
The schemes are read-only, unless you select the Custom scheme, which allows you to define the mouse actions for 3D navigation
and editing according to your needs.
NOTE: On Linux platforms, it we suggests to use CityEngine Linux scheme. This scheme uses CTRL as the default modifier key
and does not interfere with window manager operations that commonly use the ALT modifier.
3D Mouse Preferences
3D Mouse support is not available in all CityEngine versions.
Note that on Windows platforms, the settings made in the Logitech/3DConnexion system control panel are bypassed. To
configure your 3D mouse for CityEngine, use CityEngine's builtin 3D Mouse preferences.
The 3D Mouse preference page lets you configure CityEngine related settings of your Logitech/3DConnexion 3D Mouse. The top of
the preference page presents you all CityEngine user interface commands. You can assign any of these commands to the
hardware buttons on your 3D Mouse. To assign a command to a button, just select the command from the list and press the button
on the device the command should be assigned to. In order to simplify command selection, the list of commands may be filtered by
typing the desired filter into the text field above the list of commands.
You can always restore the default command bindings for your specific device by clicking on the "Restore Defaults" button.
Settings
Overal Speed: The overall speed (or sensitivity) of the 3D Mouse. Change this if you think your device responds to
quick or slow.
Reverse all Axes: Some people prefer to have the movements in helicopter or camera mode aligned with the
mouse. You may reverse the axes with this option.
Zoom direction: By default, zoom is mapped to moving the cap forwards and backwards. Some people prefer zoom
on the up/down axis. You may select your preferred behavior with this option.
Navigation mode: The preferred navigation mode (see below).
Rotate: Enable rotation. If this option is not checked, the device will have no effect when you rotate the cap.
Pan/Zoom: Enable pan/zoom. If this option is not checked, the device will have no effect when you move the cap.
Navigation modes
Camera mode navigation is characterized by the user having the impression that he is moving around in the scene he
is observing. This moves the user around and turns in the direction that the cap on the 3D mouse moves, and causes
the objects displayed to move in the opposite direction. In camera mode the center of rotation is at the camera position.
The main characteristic of object mode navigation is that the user has the impression he is holding the object in his
hand. The center of rotation is the current point of interest, e.g. set to the center of the selection by framing.
As the name suggests, this mode simulates a helicopter control mechanism. The device's pan axes control the
movement in a plane parallel to the world's xz-plane irrespective of the applied tilt. The device's y-axis is used directly
to control the height above the world's xz- plane. In this navigation mode pulling the devices cap up causes the height
above world's xz-plane to increase, increasing the distance of the view point above the plane. Similarly, pressing the
cap down causes the view point to get closer to the plane. Not only are the device's y-translation values applied directly
to the world's up-axis, the same is true for the devices spin values: These rotations act as if the device's and the
world's up-axis were coincidental.
3D Mouse menu
By default, button "1" on the 3D Mouse is assigned to the 3D Mouse menu. This menu allows you to lock translation and/or
rotational movements as well as change the speed and navigation mode quickly.
Perspectives
On the Perspectives preference page, you can manage the various perspectives defined in CityEngine.
Open a new perspective: Use this option to set what happens when you open a new perspective. Do you want the
perspective opened within the current Workbench window or opened in a new window?
Open a new view: Use this option to specify what happens when a new view is opened. It is either opened to its default
position within the current perspective or it is opened as a fast view and docked to the side of the current perspective.
New project options: Use this option to specify the perspective behavior when a new project is created. You can set it
to switch the current perspective to be the one associated with the project type and open the perspective in the same
Workbench window as the current one, switch the perspective and open it in a new Workbench window, or not to switch
perspectives at all.
Make Default: Sets the selected perspective as the default perspective.
Reset: Resets the definition of the selected perspective to the default configuration. This option is only applicable to
built-in perspectives that have been overwritten using WindowLayoutSave Perspective As... .
Delete: Deletes the selected perspective. This option is only applicable to user-defined perspectives (built-in
perspectives can not be deleted).
Startup and Shutdown Preferences
The Startup and Shutdown preference page allows the selection of plug-ins to be automatically activated during CityEngine startup.
NOTE: The RCP Utilities plugin must be enabled for proper functioning of the CityEngine.
Normally CityEngine plugins are not activated until they are needed. However some plugins may specify that they wish to be
activated during startup. This preference page allows the selection of which of these plug-ins will actually be activated during
startup.
Prompt for workspace on startup: If this option is turned on then the workbench will prompt you each time it is started
for what workspace to use.
Refresh workspace on startup: If this option is turned on then the workbench will synchronize its contents with the file
system on startup.
Confirm exit when closing last window: If this option is turned on then the workbench will ask if you wish to exit when
closing the last window.
Plug-ins activated on startup: This option allows you to select which available plug-ins should be activated on startup.
Cameras
A camera bookmark has the following options:
Perspective: If selected, the camera will give a perspectively correct image. If not selected, the camera will operate in
perspective and orthogonal mode by pressing P or selecting Orthogonal View from the lens menu .
Angle of view: The width of the field of view. For your convenience, some predefined angles of view corresponding to
specific focal lengths are accessible from the lens menu .
Near and far clipping plane: These values limit the space where your camera will work. If your scene disappears when
Configuration: These values position and orient the camera. You can enter a world coordinate position for the camera
as well as a specific rotation of the camera.
Distance to Point of Interest: This value corresponds to the distance between the camera and the POI. The POI is also
Cameras
A camera configuration has the following options:
Perspective: If selected, the camera will give a perspectively correct image. If not selected, the camera will operate in
perspective and orthogonal mode by pressing P or selecting Orthogonal View from the lens menu .
Angle of view: The width of the field of view. For your convenience, some predefined angles of view corresponding to
specific focal lengths are accessible from the lens menu .
Near and far clipping plane: These values limit the space where your camera will work. If your scene disappears when
Help Preferences
On the Help preferences page, you can indicate how to display help information.
Use external browsers: If embedded web browser is supported on your system, help window uses an embedded help
browser to display help contents, whenever possible, and this option is available. Select it, to force help to use external
browsers. Use "Web Browser" preference page to select browser to use.
Open window context help: This option allows you to determine whether the window context help will be opened in a
dynamic help view or in an infopop.
Open dialog context help: This option allows you to determine whether the dialog context help will be opened in a
dynamic help section of help view or in an infopop.
Open help view documents: This option allows you to determine whether the documents selected in the help view will
be opened in-place or in the editor area.
Why Project Management
A project realized with CityEngine usually consists of a multitude of files. A CityEngine project comprises assets, rule files,
scene files and any other file related to that project. Rule files usually reference asset files and are referenced themselves by scene
files. Keeping assets, rules and scenes in predefined location helps you and your collaborators working with CityEngine projects,
importing, exporting and exchanging them. Furthermore, CityEngine features optimized file-selection dialogs for these predefined
locations, improving your workflow considerably.
Projects are collected in so-called workspaces that are mapped to a location on you local storage system. A default workspace is
created when you start CityEngine for the first time. It is usually located in a folder "CityEngine" in your home directory. A
workspace can hold any number of projects. CityEngine allows you to work with several workspaces and easily switch between
these.
Using CityEngine Projects
This section presents the basic operations with CityEngine projects. You learn how to create a CityEngine project and organize your
folders and files, and how to import external files, folders and projects. The navigator Windows Show Navigator is your main
interface for file and folder management inside CityEngine. It is also the bridge to your external tools for editing assets and maps
for a smooth integration in your existing pipeline.
Tasks:
1. Creating a CityEngine Project
2. Creating a CityEngine Scene
3. Folder Organization and File Types
4. Importing Files into a Project
5. Exploring Projects with the File Navigator
6. Editing and Refreshing Assets
Creating a CityEngine Project
CityEngine projects, folders, and files can be created using several different approaches. In this section a project will be created
using three different approaches:
Windows File menu
New wizard button
Navigator's context menu.
A project can be created using the File New menu. Once the project has been created a folder and file can be created as
well. From the menu bar, select File New , this has the same effect as clicking on the New Wizard button.
This will open the New Wizard.
In the New Wizard, select CityEngineCityEngine project and then click Next.
In the Project name field, enter a name for the new project. Do not use spaces or special characters in the project name (for
example, "MyFirstCity").
Leave the box checked to use the default location for your new project. Click Finish when you are done.
If you sneak a peek at the Navigator, you will see that it now contains the new project we just created.
You can also right-click in the Navigator in order to get the Navigator's context menu which allows you to create projects under
NewCityEngine project.
Folder Organization and File Types
For your convenience, a set of default folders is created for the various file types you encounter in a CityEngine project. These
default locations are also used by the CityEngine specific file-selectors for quick access. A default CityEngine project contains the
following folders:
assets : The assets from this folder are applied by the CGA insert command to compose 3D models during
generation. CityEngine supports various asset formats such as ".obj" and ".fbx". Assets can be previewed inside
CityEngine by the Inspector but you need an external tool to create or edit assets.
data : This folder contains arbitrary supplementary data. For example lots or mass models (as grouped ".obj" or ".dxf"
files) are stored in this folder. These can be imported into the CityEngine as shapes and street networks where shape
grammar rules can be applied on. If you have other project related resources such as artwork and sketches, place them
into the data folder as well.
images : Additional imagery like Viewport snapshots are stored here.
maps : This folder contains the image maps used by the map layers. For example, a height- or obstacle-map is
stored here. Various bitmap file formats such as ".jpg", ".png", ".tif" are supported by CityEngine.
models : This folder is the default location for exported 3D models.
rules : This folder contains the CGA shape grammar rule files ".cga". Double-clicking on a CGA file will directly open
the CGA editor for that file.
scenes : Here, CityEngine scene files (".cej") are stored. Double clicking on a scene file will close the current scene
(if any) and open the newly selected scene.
The easiest way to fill your project with files is dragging files into the navigator from your system file browser. More advanced import
options will be explained in the next section.
Importing Files into a Project
While dragging files form the file browser is convenient, importing a large number of files is cumbersome by dragging and
dropping. CityEngine offers a wide range of import options for many common cases without the need to resort to external programs.
Usually, a copy of a file is created inside your workspace. In a collaborative environment, an advanced option called "linking" can be
used in order to share files and folder among team members.
You can either import files and folders directly from the file system as well as from an archive file. Archive files are the preferred
way to exchange CityEngine projects since all project specific attributes will be preserved.
In order to import files into your project, select FileImport .
Select Files into Existing ProjectFile System and then click Next.
In the "From directory" field, type or browse to select the directory containing the files you like to import. Recent directories that
have been imported from are shown on the "From directory" field's combo box.
In the right pane check the files and folders you like to import. Checking a folder in the left pane will import its entire contents into
the workspace. A grayed checkbox indicates that only some of the files in the folder will be imported into the workspace.
The Filter Types button can be used to filter the types of files that will be imported.
The "Into folder" field should already be filled in with the name of the project you are working with but it can easily be changed
Browse.
In the Options area, options are given to:
Overwrite existing resources without warning.
Create complete folder structure (i.e., also create parent folders) or create selected folders only.
Click Finish when done. The selected files and folders will appear in the Navigator.
If your files are located in a zip or tar archive, choose Select Files into Existing ProjectArchive File and then click Next.
The following options are available for an archive file import:
Archive File: The file from which to import. Type in the full path or Browse to select the path on the file system.
Filter Types: Dialog to select which file types to import. Use this to restrict the import to only certain file types.
Folder: The folder into which the resources will be imported. Type the path or Browse to select a path in the
Workbench. The folder holding the selected resource
Overwrite existing resources without warning: Determines whether importing a resource should silently overwrite a
resource which already exists in the Workbench. If this option is off, you will be prompted before a given resource is
overwritten, in which case you can overwrite the resource, skip it, or cancel the import.
Exploring Projects with the File Navigator
The Navigator is your main tool to navigate and operate on files and folders.
You can directly open and edit CGA and scene files within CityEngine by double-clicking the corresponding file in the navigator. To
quickly search for a file, hit CTRL+SHIFT+R and type the name of the file you are looking for. The navigator provides also basic
operations such as copying, renaming and deleting files and folders. For performance reasons the CityEngine keeps an internal
copy of the workspace. If you modify files outside of CityEngine (e.g. by editing a file in an external program or renaming a file in
the system file explorer), you have to refresh the CityEngine's internal representation. Choose FileRefresh Workspace or
simply hit F5 .
The Inspector, if open, will give you a preview of the current Navigator selection.
Editing and Refreshing Assets
Besides CGA and scene files, the CityEngine does not provide asset and image editing capabilities. This means that you can
work with your favorite tools and leverage the full power of these tools without the need to learn an application specific editor.
Since the workspace is mapped to a file system location, you may access the files on the file system as usual. Remember that if
you change files and folders outside CityEngine, you have to refresh the CityEngine's internal representation. Choose
FileRefresh Workspace or hit F5 . Alternatively, you can assign your preferred application to a file type by selection Open
WithOther from the Navigator context menu.
Choose External programs and select the preferred program from the list.
The CityEngine Workspace
The central hub for your files is called the workspace. You can think of the Navigator as a tool that allows the user to navigate
and manipulate the workspace. The Navigator provides operations for creating, navigating, and manipulating files and folders in the
workspace.
There is exactly one workspace open at a time, and it is always open as long as the CityEngine is running. The workspace is
opened automatically when CityEngine starts up and the previous window configuration is restored.
The workspace contains a collection of resources. There are three different types of resources: projects, folders, and files. A project
is a collection of any number of files and folders. It is a container for organizing other resources that relate to a specific CityEngine
project. Files and folders are just like files and directories in the file system. A folder contains other folders or files.
A workspace's resources are organized into a tree structure, with projects at the top level, and folders and files underneath. A
workspace can have any number of projects, each of which can be stored in a different location in some file system.
The workspace resource namespace is always case-sensitive and case-preserving. Thus the workspace allows multiple sibling
resources to exist with names that differ only in case. The workspace also doesn't put any restrictions on valid characters in
resource names, the length of resource names, or the size of resources on disk. Of course, if you store resources in a file system
that is not case-sensitive, or that does have restrictions on resource names, then those restrictions will show through when you
actually try to create and modify resources.
Tasks:
1. Creating a new Workspace
2. Switching Workspaces
Creating a new Workspace
You cannot run CityEngine without a workspace. And you cannot run two instances of the CityEngine simultaneously with the
same workspace. Therefore, there is always a current workspace. In order to create a new Workspace, you have to switch from the
current workspace to a new one.
Switching Workspaces
You can easily maintain multiple workspaces, for instance one for each customer. In order to switch a workspace, select
FileSwitch WorkspaceOther . If you have already switched your workspace previously the previous workspaces will be
available for selection in the Switch Workspace menu.
The FileSwitch WorkspaceOther menu item will open the switch workspace dialog. The dialog will allow you to browse for
or manually enter a new workspace location. The combo will also allow you to select your previously selected workspaces.
When you switch your workspace you can select settings than will be transferred to the new workspace:
Workspace Layout: Opened views, their size, and selected perspectives.
Working Sets: The user defined working sets.
Archiving or Exchanging CityEngine Projects
The CityEngine provides means for exchanging projects in collaborative environments. The simplest way to exchange project
data is to archive projects. An archived project contains all project specific settings, scenes, rules, and assets.
Tasks:
1. Importing a Project into the Workspace
2. Exporting a Project
Importing a Project into the Workspace
In order to import a project into the workspace, select FileImport .
Choose ProjectExisting Projects into Workspace.

You can choose among the following import options:
Select root directory: Root directory in the File System to start scanning for projects to import. Type in the full path or
Browse to select the path on the file system.
Select archive file: Archive file to scan for projects to import. Type in the full path or Browse to select the archive on the
file system.
Refresh: Rescan the selected source for projects to import.
Copy projects into workspace: When selected this will cause the imported project to be copied into the current
workspace. If this option is not selected, the project content will be linked into the workspace.
Exporting a Project
In order to export a project, select FileExport .
You can either export a project as an archive GeneralArchive File or write it with as folders and files to the file system
GeneralFile System.
You have the following options for exporting a project as an archive file:
Select resources to export: The project (and resources within that project) to export to the archive.
Filter Types...: Dialog to select which file types to export. Use this to restrict the export to only certain file types.
Archive File: The path and name of the archive file into which the resources will be exported. Type the path, select a
previous path from the drop down list, or Browse to select a path and file name on the file system.
"Zip file" to export the file in "zip" format or "Tar file" to export the file in tar format. Compress the contents of the file:
Compresses the contents (resources selected to be exported) in the archive that is created.
Compress the contents of the file: Compresses the contents (resources selected to be exported) in the archive that is
created.
Overwrite existing file without warning: If the specified archive already exists in the file system, you will be prompted to
overwrite the file. If you do not want to be prompted turn this option on.
Create directory structure for files: Create hierarchical folder structure in the file system as it exists in the workspace.
Create only selected directories: Create hierarchical structure in the file system only for selected folders.
You have the following options for exporting to the file system:
Select resources to export: The project (and resources within that project) to export to the file system.
Filter Types: Dialog to select which file types to export. Use this to restrict the export to only certain file types.
Directory: The directory on the file system into which the resources will be exported. Type the path, select a previous
export path from the drop down list, or Browse to select a path.
Overwrite existing files without warning: Determines whether exporting a resource should silently overwrite a resource
which already exists in the file system. If this option is off, you will be prompted before a given file is overwritten, in
which case you can overwrite the file, skip it, or cancel the export.
Create directory structure for files: Create hierarchy (folder) structure in the file system as it exists in the Workbench.
Create only selected directories: Create hierarchy (folder) structure in the file system only for selected folders.
Attribute Layers
1. What is an Attribute Layer
2. Creating an Attribute Layer
Texture
Obstacle
Terrain
Mapping
Function
3. Working with Attribute Layers in the Inspector Window
4. Editing Attribute Layer Functions
5. Controlling Rule Attributes with Attribute Layers
6. Selection via Image Maps
7. Aligning the Terrain to Shapes
8. Exporting Terrains to geometry or image files
What is an Attribute Layer?
Attribute layer are a very powerful tool to control many generative aspects of CityEngine. With attribute layers you can control
street network growth, selection and arbitrary CGA shape grammar rule attributes.
Basically, an attribute layer evaluates for a specific attribute name and location to a value. The result of the evaluation can be
defined by e.g. the brightness of a bitmap but can also be any mathematical function or a combination of both.
CityEngine offers the following set of predefined combinations:
Terrain: With a terrain you control the elevation by an image and you have in addition to that the possibility to map a
texture on the terrain.
Obstacle: With an obstacle map you controls the areas where the street grow algorithms will work. An obstacle map as
any other attribute layer that evaluates to a Boolean (true/false) value can also be used for selection a range of objects.
Texture: Create a texture attribute layer if you just need to load in a reference image e.g. for manual street creation.
Mapping: An arbitrary combination of image map channels and mathematical functions. Typical usages of a mapping
layer are rule attributes such as building height or land use mixes. See the Map Control Tutorial for mapping layer
examples.
Function: An arbitrary mathematical function that can be used for controlling a rule attribute.
Attribute layers in general define one or more attributes as a function of the location and optionally a mapping channel. The
dimension of the map are normalized to the interval [0..1]. Thus the lower left corner of your map the coordinates (0, 0) and the
upper right corner of the map the coordinates (1, 1). The normalized position is available as the predefined values "u" and "v"
respectively for attribute functions. For example the following function will control the elevation by trigonometric functions:
attr PI2 = 3.141 * 2 // approx. 2 x PI
attr elevation = sin(u * PI2) * cos(v * PI2) * 100
In addition to that, inside an attribute function, "red", "green", "blue", "alpha", "hue", "saturation", "brightness" address the individual
channels of the map. For each object, the attribute function is evaluated with the projection of the center of gravity to the x-z plane.
In the following illustration, the attribute "x" is evaluated at the center of gravity of the object which is mapped onto the standard
[0..1] range for the "u" and "v" parameters. In addition to that, the map is sampled at the position "u,v" and its red channel is used
for the calculation of "x".

Creating an Attribute Layer
Attribute layers can be used to control the street network growth and the shape grammar rules via maps or functions. Via
LayerNew Attribute Layer... in the main-menu, a new attribute layer can be created. In the wizard dialog you can choose
between the five predefined attribute layer types.
After selecting the type, you can optionally edit the default Layer Name. By clicking Next, the corresponding attribute layer can then
be refined:
1. Texture
2. Obstacle
3. Terrain
4. Mapping
5. Function
Texture
A texture layer is the simplest layer that can be added. It simply inserts the given texture as a layer into to scene. This can be
useful for maps that have to be manually interpreted by the user e.g. for manual street creation.
After the type "Texture" has been selected in the Wizard, the texture layer can be created as follows:
1. Browse your project and select the image map. Note that only image maps in the workspace can be selected.
Therefore the image has to be copied or imported into corresponding project folder (typically "maps"). More information
about importing files into the project can be found here Importing Files into a Project.
2. Set the dimensions and location of the attribute layer
3. Click finish.
NOTE: All attribute layer properties can still be changed after creation through the Inspector.
Obstacle
The obstacle layer defines a Boolean attribute that can guide the creation of street networks.
The typical usage scenario is to create a land-water map where the water is marked in dark color (i.e. brightness below 0.5) and
the land in bright color. The obstacle attribute layer can then be selected in the automatic street generation wizard and streets are
generated accordingly (i.e. no streets in dark regions).
After the type "Obstacle" has been selected in the Wizard the obstacle attribute layer can be created as follows:
about importing files into the project can be found here Importing Files into a Project.
2. Select the source channel and the corresponding threshold. Values below the threshold are interpreted as obstacles.
3. Set the dimensions and location of the attribute layer in the scene.
4. Click finish.
As a result an obstacle attribute layer is selected where the channel threshold function is represented as a function returning a
Boolean function. This function and all other attribute layer properties can still be edited after creation.
NOTE: All attribute layer functions that evaluate a Boolean value such as the obstacle layer can also be used for selecting object
in the scene by choosing Select from the context menu. See also Selection via Image Maps.
Terrain
A terrain attribute layer is used for modeling the elevation of the scene topography with an image map. The street network can
follow the elevation and street networks as well as Shapes (Lots and Street Shapes) can be aligned to it.
After the type "Terrain" type has been selected in the Wizard, the terrain attribute layer can be created as follows:
1. Browse your project and select the image which will be used as heightmap. Note that only image maps in the
workspace can be selected. Therefore the image has to be copied or imported into corresponding project folder
(typically "maps"). More information about importing files into the project can be found here Importing Files into a
Project.
2. Optionally: An overlay texture can be specified by browsing the same way as you did for the heightmap.
3. Select the source channel and the corresponding elevation bounds.
5. Click finish.
The result is a terrain Attribute layer with an elevation function that returns values between "Min. elevation" and "Max. elevation" by
sampling the given "Channel" from the height map file. This function and all other attribute layer properties can still be edited after
creation.
16-bit images are supported. The 16-bit range is scaled to the elevation bounds similar as with standard images.
The resulting terrain can be modified by using the Align Terrain tool via Layer -> Align Terrain .
Selected objects in the scene can be aligned to this terrain by choosing Graph -> Align Graph or Shapes -> Align
Shapes .
Attributes
After import, the terrain can be modified in the inspector.
The attributes of a terrain layer in the inspector.
Attribute Function
Map The heightmap image.
Terrain resolution u The number of terrain mesh vertices in u direction.
Terrain resolution v The number of terrain mesh vertices in v direction.
Texture The texture image.
Wireframe alpha The transparency value used for wireframe rendering.
Enable elevationDelta If enabled, the built-in function "elevationDelta" returns the elevation deltas resulting from the terrain
alignment tool. If disabled, the function returns 0.
attr elevation The definition of the terrain elevation which is used to create the terrain mesh.
Mapping
The mapping attribute layer wizard allows the most generic form of attribute definition, where you can create mappings from an
image file to actual attribute values.
Typically, mapping attribute layers are used to control CGA shape grammar rule attributes: if an attribute defined in an attribute
layer matches an attribute defined in a rule file, the attribute layer can be selected as source for the rule attribute in the Inspector.
This is described in more detail here Controlling Rule Attributes with Attribute Layers.
After the type "Mapping" has been selected in the, the mapping attribute layer can be created as follows:
about importing files into the project can be found here ( Importing Files into a Project.
3. Create a new attribute by clicking on the top-left "insert-row" icon (left to "Attribute"). Note that an arbitrary number of
mappings can be defined per layer.
4. Enter the attribute name; select the source channel and the mapping range.
5. Click finish.
The result is a mapping Attribute layer with the named attribute function that returns values between "Minimum" and "Maximum" by
sampling the given "Channel" from the image map file.
NOTE: All attribute layer properties can still be changed after creation through the Inspector.
Function
The Function Attribute Layer wizard lets you create the most generic form of an attribute layer. You can write any mathematical
function by using a subset of the CGA Shape Grammar language.
After the type "Function" has been selected in the Wizard, the function attribute layer can be created by entering a function which
defines an arbitrary attribute. The "u" and "v" parameter correspond to normalized coordinates in the range [0..1] in x and z
direction. After creation, the dimensions and the location of the layer can be edited as well (resulting in a scaling and translation of
u and v accordingly).
The syntax is similar to the Shape Grammar and described in more detail here Editing Attribute Layer Functions.
Working with Attribute Layers in the Inspector Window
By double-clicking on an attribute layer in the scene window, the Inspector will open and allow you to edit attribute layer
parameters.
In the Inspector you can change the map files, modify the bounds, and adjust the display offset (to avoid z-fighting i.e. how much
the rendering of the map is displaced in y direction regarding the actual map values). In addition to that, an overlay color and alpha
value for the map can be specified. Depending on the layer type, some options may not be available.
Furthermore, the mapping functions can also be edited in the inspector. This is described on in more detail here Editing Attribute
Layer Functions.
Moving and Scaling Attribute Layers in the 3D Viewport

If you select one or more attribute layers in the Scene Window, you may use the transform or scale tool in order to move or scale
the layer(s) directly in the 3D viewport.
Editing Attribute Layer Functions
Attribute layers can have their own attributes. These are defined in the Layer Attributes pane of the Inspector, with the
Attribute Layer selected.
Attribute layer function editing is very similar to CGA shape grammar editing. But only a subset of functions are available for
attribute layers and no rules or shape operations. Use the command completion CTRL+SPACE to see a list of available
functions. See the CGA Shape Grammar Reference for a detailed description of the functions.
Predefined attributes
There are two predefined attributes that will be used for street generation and other generative parts of CityEngine:
"elevation" controls the elevation of a terrain and street generation can follow an elevation attribute layer.
"obstacle" controls the obstacle avoidance of the street generation.
Attribute Mapping
Object attributes of nodes, segments and shapes can be mapped via layer attributes using the command
getObjectAttr(ATTRNAME) . This command searches matching object attributes in its own or in other layers.
If you for example plan to use the object attribute width on street segments to control the width of created street shapes, use such
a layer attribute
attr streetWidth = getObjectAttr("width")
and set the source of the streetWidth parameter in the Street Parameters pane to its own layer.
Function attribute layer examples:

attr elevation = sin(u * 6.3) * cos(v * 6.3) * 100 Create a terrain as a function of sine and cosine.
attr obstacle = brightness > 0.5 Define all bright parts of an image map as obstacles.
attr height = exp(u * 5) Control the height attribute of a rule file with this exponential function.
attr selection = random > 0.5 Define a boolean attribute that can be used for selection to select 50% of
the objects randomly.
attr landuse = Define a string attribute that can be used by a CGA shape grammar rule
case u > 0.5:
50%: "industrial" to control e.g. building appearance.
else: "retail"
else :
"residential"
Controlling Rule Attributes with Attribute Layers
Attribute layers are a very powerful tool to control CGA shape grammar rules. Any attribute that you have defined in your
CGA shape grammar rules can be mapped to an attribute layer. This allows you to guide your rules by maps. Typically, maps
are used for controlling building attributes such as height or appearance, level of detail, or land-use mixes.
See the Shape Grammar Tutorial for a detailed description of controlling rule attributes with attribute layers.
The above cityscape was created with the help of the attribute map on the left hand side which defined by the red channel the
building height. See the Shape Grammar Tutorial for more details.
Values for rule attributes can come from three different sources:
The rules themselves (such as in attr height = 100)
Explicit values entered thriough the Inspector
Attribute layers
By default, a rule attribute takes its value from the rule itself. If you select a set of shapes with assigned rule files, the Inspector
allows you to change the source of each attribute.
If the attribute name of an attribute layer matches the attribute name of a rule file, you can select that attribute layer as source for
the rule value.
Skyline layer controls rule parameter height
In order to use an attribute layer for a rule attribute, do the following:

1. Create an attribute layer and make sure that the attribute matches the name and type in a CGA shape grammar file.
2. Assign the CGA shape grammar file to a shape. If there is a match between a rule file attribute and an attribute layer
attribute, the source of the corresponding rule file attribute will automatically be set to the correct attribute layer.
Alternatively, you can start with a CGA shape grammar file:

1. Assign the CGA shape grammar file to a shape.
2. Create an attribute layer and make sure that the attribute matches the name and type in a CGA shape grammar file.
3. Select the shapes with the CGA shape grammar file assigned in step 1.
4. Change the source in the inspector for the corresponding attribute.
Selection via Image Maps
If you need to work with selections depending on an attribute layer or a map, simply define a boolean attribute for the
selection that you require.
Using the terrain for selection

Your terrain layer contains an elevation attribute of a similar form like below:
attr elevation = map_01(brightness, 100, -100)
You want to select all elements that have an elevation of 40 meters or higher. Simply add a new attribute that evaluates to true
when elevation is bigger than 40.
attr high_elevated = elevation > 40
The new attribute high_elevated in the terrain layer
Boolean attributes in attribute layers are automatically added to the seletion menu. Right-click in the viewport (or choose from the
top menu),
Select Select Objects in Attribute Layer terrain: high_elevated
The new attribute is displayed in the selection menu
The resulting selection is shown in the image below:
Shapes above 40 meters are selected
Using a landuse map for selection

Landuse types are often used to define certain areas of a scene. The map below defines commercial (red), urban residential (blue)
and residential areas.
A typical landuse map in red, blue and green and as it is placed in the scene
After adding the a new attribute layer with the landusemap, 3 new booelan attributes are defined in the Inspector view of the new
layer. Depending on the color of the map, landuse types are evaluated.
The new attributes for different landuse types
In the menu, Select Select Objects in Attribute Layer landuse: commercial to select all shapes within the commercial area
defined by the landuse map.
Shapes in the commercial area are selected
Selection using the u,v coordinates of an attribute layer

For the following landuse attribute definition,
attr landuse =
case u > 0.5:
50%: "industrial"
else: "retail"
else: "residential"
just add the following attributes to the same attribute layer:
attr isIndustrial = landuse == "industrial"
attr isIRetail = landuse == "retail"
attr isResidential = landuse == "residential"
This will give you the following additional selection possibilities in the context menu:

Aligning Terrains to Shapes
Terrains can be aligned to shapes by using the Align Terrain tool. In order to run the tool, select some shapes and choose Layer
-> Align Terrain . The following dialog is shown:
The align terrain dialog with default settings.
This tool alignes one or all terrains to all shapes currently selected.
Settings
Parameter Function
Terrain The terrain which should be aligned or All.
Raise terrain If enabled, terrain vertices below selected shapes are aligned.
Maximal raise distance If distance between terrain and shape is smaller, terrain vertices below shape are raised.
Lower terrain If enabled, terrain vertices above selected shapes are aligned.
Maximal lower distance If distance between terrain and shape is smaller, terrain vertices above shape are lowered.
Add border If enabled, a small border region around the shapes is aligned, too.
Write cut/fill volumes to If enabled, for each selected shape cut/fill volumes are approximately calculated. The values are written
attributes. into the object attributes (fields "cutVolume" and "fillVolume").
Resetting Terrains
Terrains can be reset by using the Reset Terrain tool. Choose Layer -> Reset Terrain . The following dialog is shown:
The reset terrain dialog with default settings.
Reset means restoring the original height defined by the elevation attribute of the terrain layer.
Settings
Parameter Function
Terrain The terrain which should be reset or All.
Constraint If set to Everywhere, terrains are completely reset. If set to Inside selected shapes only, only the terrain
vertices intersecting the currently selected shapes are reset.
Add border If enabled, a small border region around the shapes is reset, too. Only meaningful if Constraint is set to
Inside selected shapes only.
Elevation Delta Maps

When aligning terrains, the original heightmap of the terrain is not modified. The elevation data is stored as a separate image file in
a subfolder (named after the CityEngine scene) in the project's data folder.
These files and folders should not be renamed or deleted. If required however you can modify the elevation delta image file with an
image processing tool (e.g. apply blurring), and store it under the same name.
Exporting Terrains
To export terrain(s) to geometry or image files you first select any map layer(s) from your scene.
Go to File -> Export -> CityEngine and you will have the choice between export to geometry or export to image files:
Exporting Terrains to Geometry

To export to geometry files, select File -> Export -> CityEngine -> Export Selected Terrains and choose a format. The rest of the
process is similar to the model exporter.
Exporting Terrains to Image
To export to image files, select File -> Export -> CityEngine -> Export Selected Terrains as Image and choose a format.
16-bit images are supported for the formats png, tif/tiff and 001(raw).
What are Shapes
Shapes are the starting point for every CGA generation. CGA rules operate on shapes and thus there must be some shape
to apply the first rule on. Through CGA operation, the shapes are modified and finally result in geometries.
Geometrically speaking, shapes are simply polygons. They can be generated within the CityEngine or imported from external
sources.
Shapes can reference a set of attributes, including a rule file, a start rule (the first rule that will be applied) as well as a seed
to control randomness. You can assign rules to shapes by selecting Assign Rule File... from the context menu.
Shapes are created either manually by hand, automatically from a graph, or by import:
Manually Created Shapes

Shapes can be drawn and edited using a set of tools, see Creating and Editing Shapes Manually.
A simple lot drawn within the CityEngine.
Shapes Created from a Graph

Street shapes and lots can be automatically created from a graph, see Creating Shapes from Graph Networks.
Street shapes and lots generated from a graph within the CityEngine.
Imported Shapes
Shapes from various file formats, including ".obj", ".dxf", ".shp" and ".osm", can be imported. See Importing Shapes.
Lots imported from a ".shp" file.
Unfortunately, the term Shape is also used in the context of Rule-based Modeling, see Shapes. Please don't confuse these
two types of shapes.
Creating and Editing Shapes Manually
Various editing modes allow for easy and intuitive shape editing. The selection tool provides selection of shapes, vertices and
edges. The selection shows up in the inspector, where attributes can be changed. Shapes can be transformed using the Move,
Scale, Rotate tools.
When working with shapes that already have generated models, it is useful to enable Live Mode to re-trigger automatic
updates to the generated model. See Applying the Rules to Generate a 3D Model for more information.
Adding and Extending Shapes

Select the Add/Edit Shape tool. A new shape is added by either a free vertex on the terrain (or X-Z plane if terrain not present) or
at a location where the cursor snaps to. Click and drag the mouse to draw the shape's first edge, and then continue to move the
mouse and click to draw additional edges. Press ESC or Enter to stop drawing. While moving the mouse, it will snap to existing
vertices or edges. Snapping is temporarily disabled by pressing Shift ).
The newly created "shape" (only consisting of a single edge, so far) is added to a corresponding layer determined by the following
order: 1. The layer of the start snap point. 2. The layer of the end snap point. 3. The currently selected layer. 4. A new layer is
created.
Adding a new face. First edge, dragged from left to right.
Extending the first edge. In a right-handed system, make sure to add vertices counter-clockwise.
You may extend existing faces by using Add/Edit Shape tool and to click on an arbitrary edge in order to create a new vertex.
Observe that you are not forced to created planar faces. However, we recommend that faces are kept planar. When extending a
face by dragging, the vertex will move in the existing face plane (unless it snaps to another vertex or edge).
Additional Shape Operations

In addition to the tools presented above, there are a number of operations for manipulating shapes. These operations are accessed
through the Shapes menu:
Split Shape Tool . Use the Split Shape tool to split existing shapes. Click on a vertex or edge and move the mouse
to a second vertex or edge in order to split.
Reverse normals . This operation reverses the normals (i.e., the orientation) of all selected faces. This step is often necessary
after importing shapes with reversed orientation.
Set First Edge . This operation sets the first edge of a face to the currently selected edge. This step is often needed to orient a
face's "zero" edge towards a street (e.g. for placing the buildings front correctly). If a face is selected, the highlighted gradient line
indicates the first edge (with gradient from vertex 0 to vertex 1).
Set Street Edges . This operation marks selected edges as street edges. More specifically, it sets the street width object attribute
array to 1 for selected edge indices. When mapped to a CGA rule, the streetWidth() attribute can be used to identify edges or faces
that are facing a street. (see also comp() in CGA reference)
Separate / Combine Faces . If your scene consists of shapes with multiple faces, the operations are helpful to compose and
decompose multi-face shapes. You can also combine a number of manually drawn faces into a single shape.
Shape alignment is a tool to align shapes to arbitrary terrains (map layers with attribute "elevation" defined) or to the y=0
level. All currently selected shapes and all shapes of the selected layers are aligned. The shapes are aligned to a terrain, using
an alignment function and an optional offset.
Non-aligned shapes (all points have a the same y-coordinate) versus shapes aligned to a terrain.
The shape alignment settings
The following parameters control the alignment:

Align function: The alignment function to apply to the vertices of the shape polygons.
Project All: Projects all shape vertices onto the terrain.
Project Below: Projects the vertices located below the terrain only.
Project to Object Average: Projects the shape vertices to the average of the these vertices.
Translate to Average: Translates the shape to the average elevation of the projected vertices.
Translate to Maximum: Translates the shape to the maximum elevation of the projected vertices.
Translate to Minimum: Translates the shape to the minimal elevation of the projected shape vertices on the
terrain.
Terrain: The terrain to align the shapes. All attribute layers with an "elevation" attribute plus the y=0 level are listed
here.
Offset: The offset to add after alignment to the y-coordinate of the shape points.
Subdividing Static Shapes
Tool execution
This tool computes the geometry of lots by recursively subdividing shapes (blocks). A variety of parameters can be used to
achieve different subdivision types. The tool can be executed on static shapes of shape layers.
The same algorithm is also available for dynamic street block subdivision, see Creating Shapes from Graph Networks. In that
case, the subdivision can be controlled through the Block Parameters in the inspector instead of the dialog shown below.
To execute the tool, select a number of static shapes and choose ShapesSubdivide... . The following dialog is shown:
Algorithm Overview
The subdivision is a recursive process which stops when the resulting lots satisfy user-specified area and shape constraints. This
process is performed independently for each block. At each recursion step, a split line is computed and the shape is split into two
smaller shapes. The user can modify a set of parameters to control the stop criterion.
Two different subdivision styles are supported: Recursive OBB and Offset. These two styles combined with the possibility of
changing multiple parameters allow for large variety in the subdivision results.
Recursive OBB: In this style, a split line is calculated to divide a parent lot into two children lots at each step of the
recursive subdivision process. For this purpose, the minimum-area Oriented Bounding Box (OBB) of the lot is
computed. In the default case, the split line is orthogonal to the main axis of the OBB, and pivoted at the middle point
of this axis. The direction and pivot point are respectively modified according to irregularity and forceStreetAccess
parameters.
Offset: In this style, the region to be subdivided is the stripe between the contour of the shape and its inwards offset.
The subdivision can automatically generate corners for each block. Corner lots are assigned the start rule LotCorner. Lots
that have no street access are assigned the start rule LotInner. All other lots are assigned the start rule Lot.
Parameters
Several parameters are available for the user to control the area and shape of the resulting lots. These parameters are described
below
Patterns parameters
Parameter Function
shapeCreation If true, shapes are created from the street network.
subdivisionRecursive Different true/false combinations determine which subdivision patterns will be used, as illustrated below.
subdivisionOffset
subdivisionRecursive
subdivisionRecursive = true
= false
subdivisionOffset = false
subdivisionOffset = false
subdivisionRecursive
= false subdivisionRecursive = true
subdivisionOffset = true subdivisionOffset = true
Area parameters
Parameter Function
lotAreaMin The lower and upper bounds of the area of lots obtained after subdivision.
lotAreaMax
Given in absolute area units
Subdivision Subdivision
obtained for smaller lotAreaMin and lotAreaMax obtained for larger lotAreaMin and lotAreaMax
values. values.
obtained when the difference between obtained when the difference between
lotAreaMax and lotAreaMin is small. lotAreaMax and lotAreaMin is large.
lotWidthMin The minimum width of the side of a lot. Subdivision stops if the length of any of the sides of any of the
resulting lots is less than this value. If this value is high, the area of resulting lots might be larger than the
area specified by lotAreaMax.
Given in absolute length units
obtained for a smaller lotWidthMin value. obtained for a larger lotWidthMin value.
Shape parameters
Parameter Function
Irregularity The relative deviation of the split line from the middle point of the center of the OBB. If this value is 0.0,
the split line will be pivoted at the middle point of the OBB of the parent lot. A higher value results in the
split line being further away from the middle point, and generally, in a higher difference in the areas of the
two children nodes.
Given in range [0.0,1.0]
obtained for an Irregularity value close to 0. obtained for an Irregularity value close to 0.5.
forceStreetAccess The factor indicating the preference for lots with street access. A higher value results in more lots having
street access.
Given in range [0.0,1.0]
obtained for a forceStreetAccess value close to obtained for a forceStreetAccess value close to
0. 1.0.
Offset parameters
Parameter Function
offsetWidth The perpendicular distance from the block contour to the inwards offset polygon. Intuitively, this value
corresponds to the depth of the lots that are created when offset subdivision is used.
If this value is close to 0.0, OBB subdivision is used.
If this value is high enough so that the offset polygon is collapsed, OBB subdivision is used.
obtained for a smaller offsetWidth value. obtained for a larger offsetWidth value.
Corner parameters
Parameter Function
cornerWidth Width of the interior side of the created corners. If this value is 0.0 no corners are created. The maximum
value for this attribute is automatically computed to avoid self-intersections.
obtained for a smaller cornerWidth value. obtained for a larger cornerWidth value.
cornerAngleMax Corner angle threshold. If the angle at the vertex of a block contour is less than this value, a corner lot is
inserted. A larger value results in a more relaxed criterion for inserting corners, and thus in more corners
being created. If this value is 0.0 no corners are created.
Given in degrees
obtained for a smaller cornerAngle value. obtained for a larger cornerAngle value.
Alignement parameter
Parameter Function
alignement This parameter is only used if the initial shapes are uneven. In this case, the user can choose if the
resulting shapes should be even or uneven, too. In the former, it is possible to set their y-coordinate to the
resulting shape minimum, average or maximum.
Seed parameter
Parameter Function
seed An integer seed to control randomness.
Advanced
Algorithms description
Recursive OBB algorithm
The recursive OBB algorithm computes a split line at each step. If the two lots resulting from the split meet the user-specified
constraints, the algorithm recurses on them. To determine the pivot point and direction of the split line, the minimum-area oriented
bounding box (OBB) of the lot is computed. By default, the pivot point is set to the midpoint of the largest edge of the OBB, and the
split line direction is set to the direction of the smallest edge of the OBB. The split line pivot and direction can be modified by three
criteria:
Street access: If one of the lots resulting from a split has no street access, the orthogonal vector to the initial direction
vector is used.
Snap to block contour vertices: If the split line is within a threshold distance from one of the vertices of the contour of
the original block, the pivot point of the split line is set to that vertex.
Edge alignment: To increase the stability of subdivisions under interactive editing operations, the sampling angle space
to compute an approximation of the OBB uses one of the lot edges as reference.
Random seeds: To increase the stability of subdivisions under interactive editing operations, the random seeds for the
children lots of a given lot are computed before the recursive call to the subdivision function.
Successive
steps of the recursive OBB algorithm
Offset algorithm
The offset subdivision algorithm computes the inwards offset of the block contour and subdivides into lots the stripe between the
block contour and its offset. The inwards offset is computed with CGAL. A set of sample points is computed along the offset.
Consecutive points are separated by a distance computed as a function of the user-specified lot areas. Lines orthogonal to the
offset at the sample points and passing through the sample points are used to split the stripe between the block contour and the
offset.
Consistent Indexing
As a result of the recursive nature of the subdivision algorithm and the different criteria dictated by shape attributes, the ordering of
the lots resulting from subdivision might significantly vary after an editing operation. This is particularly inconvenient if models have
been generated inside the lots.
To improve the consistency in the lot indexing among two consecutive subdivisions, the algorithm computes the relative position of
each lot for each one of the two subdivisions, using a metric based on generalized barycentric coordinates. Pairs of lots that are the
closest to each other in this barycentric space, are assigned the same index.
The same approach is also used to improve the consistency of the seed of each lot. As a result, two lots that are relatively in the
same position of the block at two different subdivision configurations, have higher chances of sharing the same seed and attributes.
The figure below shows a subdivision together with the shapes generated from a grammar that assigns one of 15 possible random
colors to each lot. Due to the consistency logic above, the colors of lots that have similar relative positions inside the block are
preserved, even though the topology and geometry of the subdivisions are different as a result of an editing operation.
Subdivision for
initial block. Subdivision for block after
interactive editing.

Creation of Shapes from Graph Networks
Overview
Graph Networks can automatically create shapes, i.e. lots and street shapes;
To enable or disable shape creation, use the shapeCreation parameter at the block, segment or node parameters in the
inspector. By default, shape creation is enabled.
Input: A graph network. Output: Lots and street shapes.
Shape Creation Parameters

Lots and street shapes can be controlled through the corresponding parameter panel in the inspector.
Blocks create lots, see Block Parameters
Segments create street shapes, see Street Parameters
Nodes create crossing shapes, see Crossing Parameters
For each loop in the graph network, a block is automatically created, see What are Street Networks.
Object Attribute Inheritance

Lots inherit the attributes of the block
Street Shapes inherit the attributes of the segment
Crossing shapes inherit the attributes of the node
Note the italic font for inherited attributes in the inspector:
Left: A standard attribute of a graph segment. Right: The (same) inherited attribute of the corresponding street shape.
UV Coordinates
UV coordinates are generated for each shape. They can be used for UV Splits or texturing. Three different uv coordinate
generation algorithms are used: Unitize, normalize and stitching. In the following, we briefly illustrate the use of the algorithms for
the different shape types.
Unitize: Street shapes, Sidewalk shapes, junction shapes, quad lots
Normalize: Crossing shapes, entry shapes, non-quad lots
Stitching: Crossing sidewalk shapes
An example of
generated uv coordinates.

Block Parameters
Block Parameters can be individually set for each block.
The parameters for block subdivision can be specified through the block parameter panel in the inspector
Parameter panel for block subdivision
Several parameters are available for the user to control the resulting street shapes. These parameters are described below.
The Source column specifies the source of the value and can be set to Default, User, Object or to a map layer. See
Parameter Source.
General Parameters
Parameter Function
shapeCreation If true, lots a are created by subdividing the block.
Subdivision Parameters
Subdivision parameters are explained on the Subdividing Static Shapes page.
Example
An example block subdivided with the above parameters:
A typical block subdivision.
Auto-generated street width attributes

For each resulting lot, an array of street width object attributes is generated.
Left: A typical lot selected in the viewport. Right: The generarted street width object attributes in the inspector.
The first edge of a lot is the edge with maximal street width.
Street Parameters
Street Parameters can be individually set for each graph segment.
The parameters for Street Shape creation can be specified through the street parameter panel in the inspector
Parameter panel for street shape creation
Five parameters are available for the user to control the resulting street shapes. These parameters are described below.
Parameter Source.
General Parameters
Parameter Function
shapeCreation If true, shapes are created from the street segment.
Street Width Parameters

Parameter Function
streetWidth Defines the width of the main street shape.
sidewalkWidthLeft Defines the width of the left sidewalk.
sidewalkWidthRight Defines the width of the right sidewalk.
Curved Street Parameters

Parameter Function
curved If true, the graph nodes are interpolated using Bezier splines, resulting in curved streets.
curvedSegmentLength Defines the length between two sampling points on the spline.
Street width and curved segment length parameters are given in absolute length units.
Example
Street shapes created with the above parameters:
Typical street shapes (main shape and two sidewalk shapes).

Crossing Parameters
Crossing Parameters can be individually set for each graph node.
The parameters for Crossing Shape creation can be specified through the crossing parameter panel in the inspector.
Parameter panel for crossing shape creation
Several parameters are available for the user to control the resulting crossing shapes. Crossing parameters define whether and
how to create arcs at crossings and whether and how to create junctions. These parameters are described below.
Parameter Source.
General Parameters
Parameter Function
shapeCreation If true, shapes are created from the graph node.
Arc Parameters
Parameter Function
createArcs Whether to create arcs at crossings.
crossingArcRadius The arc radius. Only meaningful if the option above is enabled.
Given in absolute length units.

adaptArcRadius If enabled, the arc radius changes depending on the angle between neighbor segments. Then, the given
radius is interpreted as the 90-degree-radius. When the angle is smaller or larger, the radius also gets
smaller or larger, respectively.
numberOfArcSegments The number of circle segments for arc tessellation.
A positive integer.
Junction Parameters
Parameter Function
createArcs Whether to create junctions at crossings with two priority segments.
junctionPreference Defines which segments are priority segments. Two options are available: Major Streets and Max. Street
Width.
Major Streets: Major streets are priority streets.
Max Street Width: Streets with maximal widths are priority streets.
verticalSmooth When enabled, shapes get vertically smoothed at crossings. Only recommended with uneven graph
networks.
Example
Crossing shapes at an example node with the above parameters:
Typical crossing shapes (consisting of junction, junction entry and sidewalk shapes).

Parameter Source
Street, crossing and block shape creation are controlled by a fixed set of parameters. In order to provide maximal flexibility,
for each parameter a source can be set. The source determines where the value comes from, i.e. either it's the default value, a
user chosen value, an object attribute or a value from a map layer.
The same concept is also applied to specify the Rule Parameters for Rule-based Modeling, see Overwriting Attributes with
the Inspector.
Parameter sources for the streetWidth parameter for street shape creation.
Default
The algorithm-specific default value is used. In the streetWidth example above, the default value is 8 [units].
Object
The value is taken from the corresponding object attribute, if such an attribute is present. If not, a new object attribute is created.
User
The value is simply a user-chosen value.
Map Layers
Map Layers which define the corresponding attribute are listed in the drop-down (i.e. in the example above, AttributeLayer0 defines
the attribute streetWidth). If a map layer is chosen, the value is taken from this layer.
Note that the value in the Value column changes depending on the source. For Default and map layers, it's a read-only value.
Street and Crossing Shapes
Shape Types
Street and crossing shapes generated within the CityEngine consist of different shape types. Each shape type is defined by its
shape symbol.
Standard start rules are: Street, Sidewalk, Crossing, Junction and JunctionEntry.
The shape types are illustrated in the following figure.
Note: Shapes have by default no rule file assigned. Therefore, if you like to work with these default shape symbols you have
to define the CGA rules "Street", "Sidewalk", "Crossing", "Junction" and "JunctionEntry". These rules will be the starting point for
geometry generation. For a more detailed discussion of street generation see also the Street Tutorial Part 2: Generate Street
Models with CGA Grammar.
Attributes
By default, street and crossing shapes contain a set of attributes which provide basic information about the underlying graph and
give context information. CGA rules may want to access the following attributes.
Attribute Description Shape Types

type street type (MINOR or MAJOR) street, sidewalk, crossing, junction,
junction_entry
connectionStart the start node connection type (STREET, CROSSING, JUNCTION or street
JUNTION_ENTRY)
connectionEnd the end node connection type (STREET, CROSSING, JUNCTION or street
JUNTION_ENTRY)
sidewalkWidthLeft the width of the left sidewalk (float) street
sidewalkWidthRight the width of the right sidewalk (float) street
streetWidth the street width (float) sidewalk
Conflicts
In order to understand why conflicts can occur, a basic understanding of the internal shape creation algorithm is needed:
The street and sidewalk width is defined at each segment. Basically, the algorithm computes the segment intersection
points at the street nodes (crossings).
Then these intersection points are connected in order to create crossing (node) and street (segment) shapes. This is
done twice, once for the streets and once for the sidewalks.
If two street nodes are too close or if an angle at a street node is too narrow, conflicts occur. Given the street width
attributes and the street graph, creating clean street shapes is not possible in certain cases.
Left: Conflicts due to unclean street graph. Right: Resolved by merging two nodes.
To resolve conflicts, different actions can help:

Cleanup the graph, see Graph Cleanup Tool
Edit the graph network, see Editing Street Networks Manually
Change shape creation attributes (i.e. street width), see Street Parameters and Crossing Parameters
Importing Shapes
In order to import shapes from an external source, select FileImport... from the main menu. Choose City Engine Layers and
select the appropriate file format.
Click Next and depending on the file format, different options will be available for import.
Preparing shape import

Supported file formats

1. Import Shapes from OBJ
2. Import Shapes from COLLADA DAE
3. Import Shapes from DXF
4. Import Shapes from SHP
5. Import Shapes from OSM
Beside the possibility to automatically create lots form street networks, lots can also be imported into the CityEngine. Typically this
is happens in cases where exact lots are needed, e.g. historically correct footprints of buildings in archaeology. The CityEngine
supports import of lots as polygon data in the ".obj" and ".dxf" format. Thus any tool that can write one of these formats can be
used for shape creation.
The following properties have to be considered when creating shapes:
The CityEngine interprets the order of the vertices to calculate the orientation of the lot. Draw polygons counter-
clockwise to create a lot facing upwards. (This is the normal case, as e.g. an extrusion of the lot should go upwards)
If the front facade of your future building should be addressed by CGA shape grammar operations, make sure that the
first edge you draw represents the side of the front facade. The CityEngine lets you add special rules to the front
facade, which will be the face that comes from the first edge of the lot polygon.
Depending on the file format, CityEngine interprets group, entity or object names as names for start rules. As a
consequence, make sure that you group your meshes and assign names that are valid CGA shape grammar identifiers
(e.g. no special characters, space, etc.).
Pay attention to the dimensions. Some tools might have different units or export units differently. Check the exported file
in a text editor to see the actual dimensions. The CityEngine has no predefined units. Most import wizards offer you to
apply a uniform scaling of the imported data.
In addition, the remarks about asset formats for the insert shape operation also apply here.
Exporting Shapes
In order to export shapes to an external format, select FileExport... from the main menu. Choose CityEngineExport
Selected Shapes .
Click Next and choose the file format. Then, depending on the file format, different options will be available for export.

Shapes can be exported to SHP, DXF and OBJ:
1. Exporting shapes to SHP
2. Exporting shapes to DXF
3. Exporting shapes to OBJ
What are Street Networks
General
Street networks represent the arteries of a city and describe therefore its formal shape and structure by defining or affecting
enclosed blocks, building lots and spaces in between.
The CityEngine contains a powerful tool set to design streets manually or to let street networks grow with a procedural street
generator enabling the user to create a variety of realistic looking street configurations.
Additionally, street networks can be exported from 3rd party applications like AutoCAD and imported as a street layer into the
CityEngine. Various file formats are supported, including ".shp", ".osm" and ".dxf".
Blocks
Street layers consist of the network (edges and nodes) and the blocks:
A street layer in the scene editor.
For each loop in the graph network, a block is created. A block can reference a set of attributes and controls its subdivision into
lots, see Creation of Shapes from Graph Networks.
Blocks are automatically updated and can't be deleted. However, shape (lot) creation can be disabled, see Block Parameters
Four blocks of a graph network.
Blocks can be selected by hitting the dashed line.

Creating and Editing Street Networks Manually
Various editing modes allow for easy and intuitive street network editing. The selection tool provides selection of street nodes
and edges. The selection shows up in the inspector, where attributes can be changed. Segments and nodes can be transformed
using the Move, Scale, Rotate tools.
Adding Street Network Segments

Select the Add/Edit Graph tool. Then, click and drag the mouse to create a new street segment. While moving or dragging the
mouse, the start and end positions will snap to existing street network segments and nodes (you may inhibit snapping by pressing
Shift ). If start or end snap point are on an existing segment, the segment split and a common start or end node is inserted. To
stop sequentially drawing graph networks press ESC or Enter or click in a view outside the viewport.
The newly created segment is added to a corresponding layer determined by the following order: 1. The layer of the start snap
segment or node. 2. The layer of the end snap segment or node. 3. The currently selected layer. 4. A new layer is created.
If both start and end point snap, but start and end reside in different layers, this will be indicated by a red snap mark. Nevertheless,
you may create the new segment. It will be placed in the start snap object's layer. The segment's nodes snap to the nodes of the
existing street network (the selected street layer). If no layer is selected, a new street layer is created.
Adding a new street segment with snapping enabled

Growing Streets
The Street Grow Tool can be used to generate typical street networks. Three different street patterns (organic, raster and
radial) can be arbitrarily combined. The dialog with a number of settings allows the user to generate street networks according to
its needs. Please see the Street Tutorial for examples.
The grow streets dialog. Initially only the basic parameters are visible.
The tool can be used in the following different ways:

Create a new street network (deselect all and start the generator).
Extend an existing street network by selecting an existing street layer before growing.
Extend a part of an existing street network (select some streets of an existing street network and apply the tool).
The tool can be started either via the context menu Grow Streets in the viewport or scene editor or in the main menu via
Graph Grow Streets
The algorithm distinguishes between major and minor streets. Basically, major street are created until they enclose an area,
called a quarter. Then the quarter is subdivided by minor streets. Afterwards the algorithm continues creating major streets and
so on.
Settings
The wizard creates a user-chosen number of streets. Each new street is added locally to the existing street network, depending on
a number of settings (where the street pattern is probably the most important).
Basic Settings consist of the number of streets to generate and the street patterns.
Pattern Specific Settings define the street patterns more precisely.
Advanced Settings specify the algorithm behavior and the algorithm constraints.
Environment Settings include obstacle maps to restrict the growth area and terrains to adapt the created streets to
the elevation.
Street Width Settings define the street widths of the created streets.
Basic Settings
The basic settings consist of the number of streets, the street patterns and the street lengths.
Left: Organic major street pattern and raster minor street pattern. Right: Radial pattern for both major and minor streets.
Street patterns need two street lengths: The long and the short length. The organic pattern needs just one length (the short length
is used).
Parameter Function
Number of Streets The number of streets to generate in total.
Pattern of Major Streets The street pattern used for major streets: Organic, raster or radial.
Pattern of Minor Streets The street pattern used for minor streets: Organic, raster or radial.
Long Length The average length of the long streets (used for the raster and radial pattern).
Long Length Deviation Before the subdivision of a quarter the length of the long streets is randomly set within the interval
[Long Length - Long Length Deviation, Long Length + Long Length Deviation]. In the case of the
organic pattern, this length is randomly set for each new street.
Short Length The average length of the short streets (used for all patterns). See Short Length Deviation.
Short Length Deviation Before the subdivision of a quarter the length of the short streets is randomly set within the
interval [Short Length - Short Length Deviation, Short Length + Short Length Deviation]. In the
case of the organic pattern, this length is randomly set for each new street.
Pattern Specific Settings

The pattern specific settings specify the street patterns in more detail.
The pattern specific settings.
Parameter Function
Max. Bend Angle (Organic) The maximal bending angle of organic streets. The angle of a new organic street is randomly set
within the interval [Proposed Angle - Max. Bend Angle, Proposed Angle + Max. Bend Angle]. It
defines the legal area of street expansion (the green area in the figure below).
Expansion functions for the organic pattern.
City Center (Radial) The city center used for the radial pattern. Streets go radial or centripetal around or outside of the
center.
Max. Bend Angle (Radial) The maximal bending angle of radial streets. The algorithm tries to adapt the proposed street to
either the radial or the centripetal direction. The maximal adaption angle is restricted by this
parameter.
Street Alignment (Radial) There is a long and a short length for radial streets. This parameter decides whether the long
streets are aligned radial or centripetal, or if the alignment is chosen randomly.
Left: Radial street alignment. Right: Centripetal street alignment.
Advanced Settings
The advanced settings specify the algorithm behavior and the algorithm constraints.
The advanced settings.
Parameter Function
Snapping Distance If the distance between a new street node and an existing one is smaller than this snapping
distance, the new node is snapped into the existing one. This way, one can control the minimal
distance between any two nodes of the street network. Note that only the half of this distance is
applied if a minor street intersects with a major street (in order to model more realistic quarter
subdivision).
Minimal Angle The minimal angle between any two neighbor streets of the street network. It is guaranteed that
no smaller angle originates.
Street to Crossing Ratio Using the street to crossing ratio, one can influence the average size of quarters. The algorithm
tries to fulfill this ratio (only the major streets and major crossings count!). Quarters are large if
this ratio is large and small if the ratio is small. Street to Crossing Ratio = #Major street nodes /
#Major crossing nodes where a street node is one with valence equal to 2 and a crossing node is
one with valence greater than 2.
Development Center If large, street nodes near the center are developed more likely than nodes outside. The center is
Preference defined as the center of mass of all selected nodes. If small, all nodes are developed equal likely.
Angle Offset of Major Streets Before major street creation, this offset angle is added to the proposed street angle.
Angle Offset of Minor Streets Before minor street creation, this offset angle is added to the proposed street angle.
Environment Settings
Using environment maps one can define boundary conditions like terrains or obstacle maps.
The environment settings.
Parameter Function
Adapt to Elevation Enables or disables adaption to elevation.
Critical Slope Only proposed streets with a slope greater than the critical slope are adapted.
Maximal Slope The maximal allowed street slope.
Adaption Angle The maximal angle a proposed street is adapted (rotation around the y-axis).
Terrain If a terrain is selected, the new streets align to the terrain and, if enabled (see below), the streets
adapt to the elevation. In the combo box, all terrain of the scene are listed. A terrain is an attribute
map which defines the float attribute elevation.
Obstacle Map If an obstacle map is selected, the new street nodes avoid the obstacles. The street algorithm is
able to avoid and circumnavigate obstacles. In the combo box, all obstacle maps are listed. An
obstacle map is an attribute map which defines the boolean attribute obstacle.
Street growth with obstacle map.
Adpation to elevation
The adaption of new streets to elevation is active if a terrain is selected and the adaption is enabled. If the proposed street's length
is close to Long Length, the proposed street is adapted to go along an elevation contour line, i.e. the goal is to create a street with
slope 0.
Adaption of streets to terrain elevation.
If its length is close to Short Length, the proposed street is adapted in order go maximally elevation up or downwards.
Street Width Settings

Street and sidewalk widths are assigned to the new streets. If an existing street is extended, their street and sidewalk widths are
copied to the new street. Otherwise, street and sidewalk widths are randomly set according to the following parameters.
The street width settings.
Parameter Function
Width of Major Streets The average street width of a major street. See Width Deviation of Major Streets.
Width Deviation of Major The street width deviation for major streets. The street width is randomly set within the interval
Streets [Width of Major Streets - Width Deviation of Major Streets, Width of Major Streets + Width
Deviation of Major Streets].
Sidewalk Width of Major The average sidewalk width of a major streets. See Sidewalk Width Deviation of Major Streets.
Streets
Sidewalk Width Deviation of The sidewalk width deviation for major streets. The sidewalk width is randomly set within the
Major Streets interval [Sidewalk Width of Major Streets - Sidewalk Width Deviation of Major Streets, Sidewalk
Width of Major Streets + Sidewalk Width Deviation of Major Streets].
Width of Minor Streets The average street width of a minor streets. See Width Deviation of Minor Streets.
Width Deviation of Minor The street width deviation for minor streets. The street width is randomly set within the interval
Streets [Width of Minor Streets - Width Deviation of Minor Streets, Width of Minor Streets + Width
Deviation of Minor Streets].
Sidewalk Width of Minor The average sidewalk width of a minor streets. See Sidewalk Width Deviation of Minor Streets.
Streets
Sidewalk Width Deviation of The sidewalk width deviation for minor streets. The sidewalk width is randomly set within the
Minor Streets interval [Sidewalk Width of Minor Streets - Sidewalk Width Deviation of Minor Streets, Sidewalk
Width of Minor Streets + Sidewalk Width Deviation of Minor Streets].
Importing Graph Segments
In order to import graph segments from an external source, select FileImport... from the main menu. Choose City Engine
Layers and select the appropriate file format.
Click Next and depending on the file format, different options will be available for import. If present, attributes are imported, too.

Graph segments can be imported from DXF, OSM or SHP files:
1. Importing graph segments from DXF
2. Importing graph segments from OSM
3. Importing graph segments from SHP
Exporting Graph Segments
In order to export graph segments to an external format, select FileExport... from the main menu. Choose
CityEngineExport Selected Graph Objects .
Click Next and choose the file format. Then, depending on the file format, different options will be available for export.

Graph segments can be exported to SHP and DXF:
1. Exporting graph segments to SHP
2. Exporting graph segments to DXF
Aligning Graph Networks to the Terrain
Graph networks can be aligned at any time to a terrain (map layers with attribute elevation defined) or to the y=0 level.
Non-aligned graph network versus graph network aligned to a terrain.
The graph alignment settings
In order to open the dialog, select a set of graph nodes or a graph layer and choose Graph Align Graph... from the main
menu or simply Align Graph... from the context menu.
Settings
The following parameters control the alignment:
Align function: The alignment function to apply to the nodes of the graph.
Project All: Projects all nodes onto the terrain.
Project Below: Projects the nodes located below the terrain only.
Terrain: The terrain to align the graph. All map layers with an "elevation" attribute plus the y=0 level are listed here.
Offset: The offset to add after alignment to the y-coordinate of the nodes.
Basics of Rule-based Modeling
The CGA shape grammar of the CityEngine is a unique programming language specified to generate architectural 3D content.
The term CGA stands for Computer Generated Architecture. The idea of grammar-based modeling is to define rules that iteratively
refine a design by creating more and more detail. These rules operate on shapes which consist of a geometry in a locally oriented
bounding-box (so-called scope). The following rule derivation illustrates the process: on the left side the initial shape is shown and
on the right side the resulting generated model is displayed.
In this section the essential concepts of procedural modeling with the CGA shape grammar are listed: First, it is described in detail
what a shape is. Afterwards, the definition of rules is given, the idea of shape operations is explained and the concept of inserting
arbitrary geometry, so-called assets, is presented. Finally it is described how rules are applied to generate a model. This results in
a data structure called model hierarchy (or shape tree) which plays an important role for the understanding of the modeling process.
Table of Contents
Shapes
Rule Application

Rule Files
In the CityEngine, buildings are described using the CGA grammar. A CGA rule file consists of several rules that define how the
actual building geometry is created. A CGA rule file is usually assigned to a shape (e.g., a lot or a street etc.). One of the rules
defined in the file is then chosen to be the shape's start rule, i.e., generation will start with this rule.
In this section, a short round-up off the typical steps necessary to work with rule files is given. Please also see the tutorial
CityEngine Basics Part 3 : Writing a CGA rule file and generating models .
Table of Contents
Creating a new Rule File
Writing a Rule File
Assigning a Rule File to a Shape
Applying the Rules to generate a 3D Model

Writing Rules
This section explains the rule syntax and presents a number of very short examples.
Table of Contents
Standard Rule
Parameterized Rule
Conditional Rule
Stochastic Rule
Attributes
Import
Functions
Comments

Shape Operations
The successor part of a rule consists of a number of shape operations and shape symbols. Shape operations can change the
current shape, the shape stack and/or the shape tree.
In this section only the most important operations and their typical applications are going to be explained. The CGA Shape
Grammar Reference describes all operations in detail.
Table of Contents
Extrusion
Transformations
Coordinate Systems
From Volume to Surface with the Component Split
The Subdivision Split
Repeat Split
Rhythm
Parallel Repeat
Relative Split
Insertion of Assets

Rule Editing Tools
This section discusses the individual tools in the CityEngine which are important for working with shape grammar rules.
Table of Contents
Working with the Shape Grammar Editor
Working with the Model Hierarchy Explorer
Overwriting Attributes with the Inspector

Exporting Models
This section describes the model export process, i.e. the generation and export of models in a file format suited for further
processing.
The model exporter is completely independent of the already generated models in the current scene, and can therefore export
arbitrarily large scenes: this means that you do not have to generate a scene prior to model export.
The formats listed in the lower part of the following figure are supported for model export:
Table of Contents
1. Model Export Quick Start

2. General Export Reference
3. Supported Formats and Specific Options
4. Wavefront OBJ
5. Autodesk FBX
6. Autodesk 3DS
7. Collada DAE
8. Renderman RIB
9. Mentalray MI
10. e-on Vue VOB
11. Massive Exporter
12. Script Based Exporter (Python)
13. Export Application Notes
General Export Reference
1. Supported Formats & Typical Usage
2. General Export Options
3. Formats Feature Comparison
Supported Formats & Typical Usage

Format Features/Typical Usage
Wavefront OBJ The most compatible format. Transfer models with solid coloring or single texture layers to any DCC tool or
rendering engine. Material definitions are exported into accompanying MTL files.
Autodesk FBX Provides export into Maya, Max, MotionBuilder and other DCC tools equipped with an FBX importer. Includes
support for layered textures (multi-textures) and per-texture UVW transformations (scale, translation, rotation).
Autodesk 3DS Provides export into Max, LandXPlorer and also many older applications and game engines.
Collada DAE Exports into a large number of DCC tools and rendering engines with support for asset-instancing, layered-
textures & file-referencing.
mental ray MI Direct export into mental ray or RealityServer with support for instanced assets, shaders and file-referencing.
Renderman RIB Direct export into any Renderman compatible renderer with support for delayed RIB loading, flexible shader
calls and multi-texturing. For fast preview, CityEngine is able to generate additional RIB statements (camera,
lights) in the master file and a phong-alike template shader, which allow for direct rendering without the need
for any additional scene-setup tools.
Massive MAS Allows for the direct generation of control data for the Massive crowd simulator by mapping the control
(beta) features of Massive to terminal shapes names.
Script Based Allows for execution of arbitrary Python commands during batch export.
Export (Python)
Please see below for a comparison of the different formats with respect to material and shading features.
General Export Options

These options are available for all export file formats. Certain formats contain additional settings which will be described in the
corresponding section.
In the export wizard, each export option widget displays a tooltip with a description.
General Settings
Option Description
Location Path to the export location. The path must exist.
Name The base name of the exported files. Various suffixes will be appended depending on the other export settings.
Granularity Settings
Option Description
File use file size limit
The geometry data is written into a single file if File Size Limit is zero, else File Size Limit is applied to the
unoptimized mesh size and multiple files will be written.
Remarks:
The geometry size is measured on the raw meshes before any optimization. Therefore, the file size is
usually smaller than the setting.
The check is performed per input shape not per rule output shape. I.e. very complex rules may
generate more data than the limit setting.
Multiple files will be forced if one file is larger than 2GB.
create one file per shape

Exports one geometry file per shape.
File Size Limit Maximum geometry file size in megabytes. See remarks above.
Mesh do not merge any meshes
No meshes will be merged, each mesh will be optimized individually
merge meshes by material
All meshes with the same material properties will be merged and optimized.
Reuse asset instances, merge generated meshes by material

Inserted assets/meshes (see CGA insert operation) will be preserved and instanced. Meshes generated by the
grammar will be merged by material.
Optimization Settings
Option Description
Precision These values can be used to reduce the floating point precision of any geometry data prior to the actual
file output (useful to reduce file size).
Share Identical ... Coordinates (vertices/normals/texture coordinates) which have an euclidean distance equal or less than
precision will be merged and their corresponding indices will be updated.
Triangulate Meshes Triangulate meshes after optimization.
Reproject UV Replaces all texture coordinates with planar projections onto the global xz-plane.
coordinates along y-
axis
Mesh Components
Option Description
Vertex Indexing Choose between indexed polygon vertices or separated vertex copies per polygon.
Normals Type Allow (potentially smoothed) vertex normals or force flat face normals.
Normals Indexing Choose between indexed polygon normals or separated normal copies per polygon.
Texture Coordinates none
No texture coordinates will be exported.
only first layer

Only the first layer of texture coordinates will be exported (see CGA material attributes)
all layers
All layers will be exported
Materials Settings
Option Description
Include Materials If enabled, material definitions (e.g. diffuse color) and textures will be included in the export (if supported by the
format). Otherwise, the default material will be referenced (if required by the format).
Collect Textures All referenced textures will be exported into the export target folder and the file references will be adapted.
Miscellaneous Settings
Option Description
Script Workspace path to python script for additional python execution parallel to export. (Only available for certain
CityEngine licenses.) See Python Scripting Interface
Shape Name This character will be used to resolve clashes in the shape names. Example for delimiter "_": {"shape", "shape",
Delimiter "shape"} will be resolved to {"shape", "shape_1", "shape_2"}. Already existing suffices like "_1" will be
recognized.
The name resolver can also be called manually on a selection of shapes via Edit Make Names
Unique... .
Batch Behavior normal
No file check is performed prior to writing the geometry files
skip existing files

Existing files (geometry, material and texture files) are not overwritten.
dry run
No files at all are written, except the export log. This is useful to validate a scene and estimate the export run
time of large scenes.
Write Export Log Writes a text file containing the export settings and statistics of the performed export into the target location.
Useful for later reference.
Formats Feature Comparison

Please note, the features in this table are listed with respect to the actual output of the CityEngine, not the theoretical features of
the individual format. Please also check the list with known interoperability limitations and issues in the application notes.
Format Instancing Shaders Multi-Textures Tex Trafo Triangulation Referencing
OBJ No No No No Yes No
FBX Yes (Note 1) No Yes Yes Yes No
3DS No No No No Yes No
DAE Yes No Yes (Note 2) Yes Yes (Note 3) Yes
RIB Yes Yes Yes Yes Yes Yes
MI Yes Yes No No (Note 4) Yes Yes
Feature Description:
Format
The file format.
Instancing
Support for instancing of geometry. Typically, the assets would be stored separately and in unmodified state from the
actual nodes and transformation data.
Shaders
Support for shaders
Multi-Textures
Support for multiple texture channels
Tex Trafo
Support for separate texture coordinate transformations independent from the texture coordinates stored in the meshes
(eg. texture rotation).
Triangulation
Does the exporter support optional triangulation upon export?
Referencing
Does the format support referencing of entities between files? This allows for the definition of a master file to combine all
scene elements
Notes:
Note 1: FBX 2011.2 does support instancing, FBX 2009.3 does not.
Note 2: The CityEngine uses a third-party library from "Feeling Software" for Collada export, where the multi-texturing
feature is not fully compatible with the collada standard and therefore only works with the corresponding Maya and Max
collada plugins from "Feeling Software".
Note 3: Triangulation is necessary when exporting to Google Earth (see Application Note #1).
Note 4: Available soon.
Further Reading
Export Quick Start: Step-by-step Guide
Wavefront OBJ
Autodesk FBX
Autodesk 3DS
Collada DAE
Renderman RIB
Mentalray MI
Massive Exporter
Export Application Notes
Supported Formats
1. Wavefront OBJ
2. Autodesk FBX
3. Autodesk 3DS
4. Collada DAE
5. Renderman RIB
6. Mentalray MI
7. Massive Exporter
8. Script Based Exporter (Python)
Batch Export Application Notes
1. Format Recommendations
2. Working with Expensive Assets
3. Working with Large Models
4. Memory Issues during Batch Export
5. Known Limitations and Issues
6. Export Tips and Tricks
Note #1: Format Recommendations

Please note that some of the listed tools require additional plugins to be able to load all formats.
Tool Format Mandatory Options
Autodesk Max OBJ, FBX, 3DS (for obj, enable import of smoothing groups in max)
Autodesk Maya OBJ, FBX, DAE
Autodesk MotionBuilder OBJ, FBX
Autodesk Softimage OBJ, DAE
Blender OBJ, DAE, 3DS - Multi-Texturing
Cinema 4D OBJ, DAE - Multi-Texturing
Deep Exploration OBJ, FBX, DAE, 3DS
Google Earth (Windows) DAE + Triangulate, - Multi-Texturing
Google Earth (Linux) DAE + Triangulate, - Textures, - Materials
Houdini OBJ, FBX - Multi-Texturing
Lightwave OBJ
Polytrans OBJ, FBX, DAE, 3DS
e-on Vue VOB, OBJ
Note #2: Working with Expensive Assets

If you work with expensive (i.e., large) assets, it is of advantage to create simplified proxy assets and switch between them with a
global LOD (Level of Detail) attribute. To avoid scattering the LOD attribute all over the rules, it is useful to put the conditions into
separate "asset loader" rules:
attr LOD = 0
...
Shaft -->
s(diameter,'1,diameter) center(xz) color(shaftC) ShaftAsset
ShaftAsset -->
case LOD == 0: i("builtin:cube")
else: i("path/to/expensive/asset.obj")
...
Note #3: Working with Large Models

If you plan to create large models, it is of great advantage to implement global CGA attributes into your rule sets that allow to
selectively block the generation of polygon-intensive model features. For example, one could replace some high-polygon greek
columns with simple cuboids by using an attribute LOD, together with a corresponding condition in the CGA rules.
Application Example
Let's assume you want to render a large scene with Renderman and you have a CityEngine scene ready with a LOD switch. By
exporting the scene with LOD = 0 to a single obj file (without any textures) and importing it, for example, into Maya, you are able to
quickly setup the lights and camera without overburdening Maya with heavy geometry. Once the environment is ready you can go
back to CityEngine and export the whole scene with LOD = 1 to RIB files and link them to the render setup.
Implementation Example
Below you find a modified version of the Parthenon temple shape grammar example. Note the usage of the LOD attribute:
attr LOD = 0
...
### Columns ###
# Edge columns have different intercolumn-distance (the famous exception...)

Columns -->
set(trim.vertical,false)
split(x){ spacing+triglyphW*0.5-architraveD*0.5-0.05 : Column
| { ~spacing : Column }*
| spacing+triglyphW*0.5-architraveD*0.5-0.05 : Column }
# Greek Doric columns don't have a base

Column -->
case LOD == 0:
s(0,'1,0) Box
else:
s(0,'1,0) split(y){ ~1 : Shaft | capitalH : Capital }
Box -->
s(diameter,'1,diameter) center(xz) color(shaftC) i("builtin:cube")
Shaft -->
s(diameter,'1,diameter) center(xz) color(shaftC) i(shaftAsset)
Capital -->
s(capitalW,'1,capitalW) center(xz) color(capitalC)
split(y){ ~echinusPartsH : Echinus | ~abacusPartsH : Abacus }
Echinus --> i(echinusAsset)
Abacus --> i(abacusAsset)
...
The temple with LOD = 0, ~80k polygons
The temple with LOD = 1, ~290k polygons

Memory Issues during Batch Export
On 32bit systems, if you see low memory error messages during batch export, try to set the "File Size Limit" option to a lower value
(eg. 200-300mb). A lower value will consume less memory when the geometry data is optimized for each exported file.
On 64bit systems, there is still enough address space to complete the export (although the system might start swapping memory,
which will slow down the exporter).
Known Interoperability Limitations and Issues (up to CityEngine 2009.2)
CityEngine Export Limitations
Autodesk 3DS
Smoothing groups are not exported. Models will have flat shading.
Due to a bug in the 3ds export library, when trying to override a file which is locked by another
windows application, the CityEngine needs to be restarted to be able to again export 3ds files.
3DS only supports triangles.
Autodesk FBX
Transparent textures are not connected to the transparency (and specular) channel.
COLLADA
Transparent textures are not connected to the transparency (and specular) channel.
3rd Party Tool Import Limitations & Issues

Autodesk Maya 2009
FBX: At least the FBX plugin 2010.2 is needed to get correct UV transformation order.
COLLADA: All texture placement nodes which are assigned to the same texture file are merged together by mistake
(i.e. all texture placements end up with the same parameters).
DeepExploration 5.7
FBX:
Models with indexed normals are not correctly rendered.
UV transformations are not executed.
COLLADA:
Assets with multiple texture layers: only one texture is shown.
Instanced assets may show wrong texture.
3dsMax 2009
COLLADA/DAE:
The "tile" parameter of maps is not automatically set.
Models with indexed polygon vertices show corrupt texture coordinates.
The import of models with instanced assets crashes.
FBX:
Models with indexed normals are not correctly rendered.
The "Use Real-World Scale" map parameter is not correctly set.
General Tips and Tricks

As we constantly update our knowledge base, please visit http://www.procedural.com for additional tips and tricks.
Trick #1: Native formats are faster

If you export to your favorite DCC tool, we recommend you export using its native format instead of using a general interchange
format.
Further Reading
Export Quick Start: Step-by-step guide
Wavefront OBJ
Autodesk FBX
Autodesk 3DS
Collada DAE
Renderman RIB
Mentalray MI
Massive Exporter
Python Scripting Interface
Learn how to use the Python Console and the Editor inside the CityEngine.
Python Console
Python scripts can be executed either in the Python console or from the Python Editor.
To open the Python console, display the Console ( WindowShow Console ), and select Python Console from the dropdown list
below the small triangle in the toolbar.
Opening the Python console
In the console, the specific CityEngine scripting commands as well as conventional Python commands can be typed. To execute a
command line, press Enter . Use Ctrl-Space to show the command completion popup, which displays possible commands
depending on your typing. The last used command can be called by pressing the Up Arrow key.
Command completion (Ctrl-Space) in the Python Console
To load your custom scripts, add your script directory to the Python system path, and import your module.
>>> sys.path.append($PATH_TO_YOUR_SCRIPTS_DIRECTORY)
>>> import $YOUR_MODULE
Importing a custom Python module
Python Editor
The Python Editor offers a more convenient way to edit and execute scripts. Create new script modules via FileNew...Python
Module . Select the scripts folder of your current project as Source Folder, and specify a Name for your module.
Four module templates are available:
<Empty> Creates an empty template

Module: Class Creates an empty python class
Module: Export Creates callback calls to be used with the Python-based exporter
Module: Main Creates an executable script
Create Python module dialog
To execute a script in the Editor, press F9 . NOTE: You can always cancel all running Python scripts by choosing Cancel from the
main toolbar.
As in the console, you can use Ctrl-Space to show the command completion.
Below you see an empty Main template in black, and the added code in red. This script exports selected models as .obj files into
the model folder of the current project.
'''
Created on May 19, 2009
@author: andi
'''
from scripting import *
# get a CityEngine instance

ce = CE()
def Export(objects):
dir = ce.toFSPath("models/")
file = "building"
settings = OBJExportModel()
settings.setName(file)
settings.setLocation(dir)
ce.export(objects, settings)
if __name__ == '__main__':
Export(ce.getObjectsFrom(ce.selection))
pass
Script Based Export

See also Tutorial 13
Another powerful feature of the scripting interface is the Script Based Export. Arbitrary python commands can be executed during
model generation via the following callbacks:
initExport Called before the export starts

initModel Called for each shape before generation.
finishModel Called for each shape after generation.
finishExport Called after all shapes are generated.
The following code snippet is a typical example of a CGA rule that reports data during generation.
FloorArea --> report("area", geometry.area)
Reported data can be accessed using the export callback functions.
Create a new python export script from template File New ... Python Python Module
Choose Module: Export (Reporting) as template
The code below gives an example of how report data can be accessed and written to a file.
global REPORT
def finishModel(exportContextUUID, shapeUUID, modelUUID):

ctx = ScriptExportModelSettings(exportContextUUID)
shape = Shape(shapeUUID)
model = Model(modelUUID)
rep = model.getReports()['area']
i = 0
area = 0.0
for r in rep:
area +=float(str(r))
i+=1
global REPORT
REPORT += str(model) + ","
REPORT += (str(i) + ",")
REPORT += (str(area) + ",")
REPORT += str(area/i)+"\n"
def finishExport(exportContextUUID):
filename = ce.toFSPath("models/reportdata.txt")
FILE = open(filename, "w")
FILE.write(REPORT)
FILE.close()
In this case, the resulting comma-separated file contains the following data:
Lot name nrOfFloors totalFloorArea avgFloorArea

Lot 1 7 9221.8 1317.4
Lot 2 6 7897.2 1316.2
... ... ... ...
Startup script
A special python file can be specified that is automatically executed whenever a Python console is started or a script is executed
from the Python editor. The file must be named startup.py, and located in your CityEngine workspace.
This is helpful for example to add your scripting directory to the system path, or load your custom modules on startup.
In addition to that, if a scripting.py file exists in the workspace root, it will be merged with the CityEngine scripting commands.
See also
Commands by Category
Command Reference
Python Scripting Tutorial
Scripted Report Export Tutorial

Python Scripting Interface :
Commands by Category
Scene Objects Attributes
CE.getObjectsFrom CE.addAttributeLayer
CE.addGraphLayer CE.deleteAttribute
CE.addShapeLayer CE.getAttribute
CE.createShape CE.getAttributeLayerExtents
CE.delete CE.getAttributeList
CE.getModelFromShape CE.getAttributeSource
CE.getName CE.getLayerAttributes
CE.getNodesFromGraphSegments CE.getRuleFile
CE.getPosition CE.getSeed
CE.getShapeFromModel CE.getStartRule
CE.getUUID CE.sampleBooleanLayerAttribute
CE.getVertices CE.sampleFloatLayerAttribute
CE.move CE.sampleStringLayerAttribute
CE.rotate CE.setAttribute
CE.scale CE.setAttributeLayerExtents
CE.selection CE.setAttributeSource
CE.setName CE.setLayerAttributes
CE.setPosition CE.setRuleFile
CE.setSelection CE.setSeed
CE.setVertices CE.setStartRule
Model.getReports
Operations GUI
AlignGraphSettings CE.get3DViews
CE.alignGraph CE.inspect
CE.alignShapes CE.openView
CE.cleanupGraph CE.refreshWorkspace
CE.createGraphSegments CE.waitForUIIdle
CE.generateModels View3D.frame
CE.growStreets View3D.setCameraAngleOfView
CE.subdivideShapes View3D.setCameraPerspective
CleanupGraphSettings View3D.setCameraPosition
GrowStreetsSettings View3D.setCameraRotation
SubdivideShapesSettings View3D.snapshot
Filter
CE.isBlock
CE.isEnvironmentLayer
CE.isFile
CE.isFolder
CE.isGraphLayer
CE.isGraphNode
CE.isGraphSegment
CE.isInspector
CE.isLayer
CE.isModel
CE.isShape
CE.isShapeLayer
CE.isViewport
CE.scene
CE.withName
Import Export
CE.importFile CE.export
CEJImportSettings A3DSExportModelSettings
DAEImportSettings A3DSExportTerrainSettings
DXFImportSettings DAEExportModelSettings
OBJImportSettings DAEExportTerrainSettings
OSMImportSettings DXFExportGraphSettings
SHPImportSettings FBXExportModelSettings
FBXExportTerrainSettings
MIExportModelSettings
MIExportTerrainSettings
OBJExportModelSettings
OBJExportShapeSettings
OBJExportTerrainSettings
ScriptExportModelSettings
RIBExportModelSettings
RIBExportTerrainSettings
SHPExportGraphSettings
SHPExportShapeSettings
VOBExportModelSettings
VOBExportTerrainSettings
System File
CE.getVersion CE.closeFile
CE.getVersionMajor CE.getWorkspaceRoot
CE.getVersionMinor CE.newFile
CE.getVersionString CE.openFile
CE.saveFile
CE.toFSPath
Changelog
2010.3
Status Commands
new ExportTerrainSettings for all model export formats
new VOBExportModelSettings
new @noUIupdate
changed getObjectsFrom moved to class CE
2010.2
Status Commands
changed CleanupGraphSettings
fixed getVertices, getPosition on dynamic shapes
2010.1
Status Commands
new CE.isBlock
new CE.addAttributeLayer
new CE.getAttributeLayerExtents
new CE.getAttributeSource
new CE.getLayerAttributes
new CE.sampleBooleanLayerAttribute
new CE.sampleFloatLayerAttribute
new CE.sampleStringLayerAttribute
new CE.setAttributeLayerExtents
new CE.setLayerAttributes
new DAEImportSettings
new FBX20112ExportModelSettings
replaced CE.getStartRule (prev. getShapeSymbol)
replaced CE.setStartRule (prev. setShapeSymbol)
removed CE.isModelLayer
removed ce.createShapesFromGraph
removed createShapesFromGraphSettings
Copyright 2010 Procedural Inc.
Command Reference
Package Contents
A3DSExportModelSettings MassiveExportSettings
A3DSExportTerrainSettings Model
AlignGraphSettings OBJExportModelSettings
AlignShapesSettings OBJExportShapeSettings
CE OBJExportTerrainSettings
CEJImportSettings OBJImportSettings
CleanupGraphSettings OSMImportSettings
DAEExportModelSettings RIBExportModelSettings
DAEExportTerrainSettings RIBExportTerrainSettings
DAEImportSettings SHPExportGraphSettings
DXFExportGraphSettings SHPExportShapeSettings
DXFExportShapeSettings SHPImportSettings
DXFImportSettings ScriptExportModelSettings
FBXExportModelSettings SubdivideShapesSettings
FBXExportTerrainSettings VOBExportModelSettings
GrowStreetsSettings VOBExportTerrainSettings
MIExportModelSettings View3D
MIExportTerrainSettings @noUIupdate
Facade Wizard Overview
Example facade created with the Facade Wizard in about 5 minutes.
CityEngine 2010.1 features a Beta preview of the Facade Wizard, a streamlined interactive tool for the rapid creation of
textured 3D facades. The tool outputs CGA code that can be used within CityEngine as any other piece of CGA code. This
document provides an overview of the typical facade creation workflow and explains the individual steps. The Facade Wizard is
invoked via WindowShow Facade Wizard in the main menu.
The Facade Wizard's toolbar.
Basic Workflow
The basic workflow of the Facade Wizard is as follows:
1. Open the Facade Wizard.
2. Select a shape or a shape's face (textured or untextured) of your scene or a facade texture image in your project using
the navigator.
3. Load selected shape or image into the Facade Wizard using the "New Facade" icon in the wizard's toolbar.
Alternatively press the "New Facade from Image" icon to load an image via file browser.
4. Use the standard CityEngine 3D navigation controls and shortcuts to navigate when editing the facade (in particular,
press A to frame the whole facade, and Z to position the camera in front.
5. Start adding splits and repeats. When moving the mouse over the facade or individual regions, lines will indicate where
the split will be applied, or how many repeats will fit into the region. Use the Cursor Left and Cursor Right keys to
quickly switch between the different tools.
6. Move existing splits or modify repeats: Move the mouse near a region's edge until the move mouse cursor appears.
Drag the mouse to move / adjust.
7. Adjust the depth of the final regions by using the depth adjust tool. Move over a region and drag the mouse.
8. Save the facade using the toolbar's "Save facade" icon. A file browser will ask you to specify a CGA rule file where to
the rules will be written.
9. If your facade was loaded from a shape, the shape's or face's rule file and the start rule will be set, and you can select
and generate the model.
Note: Currently, the Facade Wizard creates CGA code "one way" only, i.e., you cannot "load" a facade with associated rules
into the Facade Wizard. However, the created CGA code can easily be edited using the CGA graphical or text editors.
Additional Features
Flexible vs. rigid splits. Normally, if you have multiple splits along an axis (X or Y), the Facade Wizard will assign
flexible splits automatically, so a created facade can adapt to different shapes. However, in some cases, it manually
defining split types. Move with the mouse over a region and press the Cursor up or Cursor down keys to change the
split model: A bold yellow line indicates a rigid split, a dotted yellow line indicates a flexible split. No line indicates
automatic mode.
Facade dimensions. When loading images, a dialog will ask for an approximate initial width. When loading a
shape, the dimensions will be taken from the actual shape size. Note that a more precise width can be specified at any
time using the context menu's "Set Region Width..." entry.
Rectification. Also when loading images, the image can be rectified or cropped if necessary. Select the rectify tool,
and use the mouse to specify the four new corner points. The new image will be written into your project when saving
the facade. The original image will not be modified.
Select region. Using the context menu's "Select Region" you can specify which texture area will be used for repeats.
The selected region appears differently colored than the other repeating regions.
Immediate saving and generation. You may enable live model generation using the context menu. If enabled,
the shape's model will be generated on-the-fly when changing the facade structure.
Snapping. The Facade Wizard maintains a history of all previous X and Y splits. Hold down Shift when adding
splits, and the split will snap to previous locations. The snapping history is kept when loading new facades, making
snapping very useful when for instance creating multiple facades of the same mass volume. Use the context menu to
clear the snap history.
Licensing
This section describes the batch export of shapes into complete models in a file format suited for further processing. CityEngine
supports these major formats:
CityEngine 2009 is powered by FLEXnet licensing system and supports node-locked and floating licenses. The CityEngine
PRO is available with node-locked or floating licensing, whereas the CityEngine SE supports node-locked licenses only (see
Feature Comparison Chart).
Node-Locked License
A node-locked license is bound to the MAC address and valid for a single computer. No network connection is required at any time,
setup is easy and quick.
How to install a node-locked license
Floating License
Floating licenses are well suited for multi-user environments. Licenses are not bound to specific computers, and can be obtained on
demand. A license server is required to use floating licenses.
For normal CityEngine usage, a network connection to the license server is required. To be able to run the CityEngine in offline
environments as well, floating licenses can be conveniently "borrowed" (i.e. checking out a license) for a specified period from
within the CityEngine.
How to setup and install floating licenses
License Activation
After purchasing a CityEngine license, the following steps have to be carried out to activate the CityEngine. As soon as we have
received your payment, we will contact you via e-mail to provide you with the needed information.
In case of licensing troubles please contact us (note that we can guarantee immediate response to subscribed users only).

Node-locked License Installation
1. Download and Install the Software

In the first step, we will send you the login information to access the download area. There you can download the full version of the
CityEngine and then install it.
2. Get the License File

As soon as we get your MAC address, we will send you the license file.
3. Activate the CityEngine

Finally, the CityEngine can be activated. Now start up the CityEngine and the license manager dialog will appear:
Choose Select License File and browse to the file.
After successful license evaluation, you are ready to use the CityEngine.

Floating License Installation
1. Download and Install the Software

In the first step, we will send you the login information to access the download area. There you can download the full version of the
CityEngine and then install it.
2. Get the License File

For floating licenses, we need the
MAC address
IP (e.g. 192.168.1.55) or hostname (e.g. server.company.com, servername)
of the system to be used as license server. As soon as we get the required data, we will send you the license file.
3. Running the License Server

Download the FLEXnet License Server installation files from the user area on the Procedural website. A detailed manual for
installing, setting up and running the FLEXnet license server is included in this zipfile.
The easiest way to run the license server on all platforms is to execute the following command from the command line:
lmgrd -c LICENSEFILE.dat
4. Activate the CityEngine

Finally, the CityEngine can be activated. Now start up the CityEngine and the license manager dialog will appear:
Choose Select License File, and browse to the license file
Select the same license file as used on the FLEXnet server.
After successful license evaluation, you are ready to use the CityEngine.
Optional: Borrowing a License

Borrowing a License is a temporary checkout of a floating license from the license server to use the CityEngine during a period
where no connection to the license server is possible. To borrow a license, start the dialog in the CityEngine from the menu:
Help Borrow License...

Choose a date or enter the borrow duration
Note that for the borrowed time, the floating license will not be available on the license server for other users.

Tutorial Howto
Find out how to import the necessary tutorial project data to work with the CityEngine tutorials.
Tutorial Setup
Start the CityEngine
Browse the Tutorial section in the CityEngine help to find out what tutorials you want to work with
Select Help Download Tutorials and Examples... and hit Next
Click on the tutorials you're interested in and get some additional info in the bottom window
Mark the checkboxes on the tutorials you want to download and hit Finish
The tutorials you checked will be downloaded and copied into your current workspace. They are ready to use.
The CityEngine Download Dialog to download Tutorials and Examples

CityEngine Basics Tutorial
This tutorial shows how to quickly create a city from scratch. It introduces the complete workflow through all the parts of the
CityEngine. You will learn how to setup a new project, how to create a street network and setup the shape creation parameters.
Finally, you will learn how to use the rule editor and generate the city's building models.
Table of Contents
Part 1: Prepare a new Project
Part 2: Streets and Building Shapes
Part 3: Assign CGA Rules and Generate Building Models

Street Tutorial
In this tutorial you will learn how street networks and detailed street models are created in the CityEngine. The created street
graph reacts to obstacles such as lakes and follows the terrain. In the second part, street shapes are created form the street graph.
By applying CGA shape grammar rules onto the streets, detailed street models are generated. The last part shows some example
street networks with the attributes needed to create those.
Table of Contents
Part 1 : Create a street network
Part 2 : Generate street models with CGA Grammar

Part 3 : Advanced street network patterns
Map Control Tutorial
Cities consist of a large number of objects. Controlling these by setting attributes of the single buildings is tedious or impossible.
In this tutorial you will learn first how CGA rule parameters are used. In a second step, you'll learn how to use maps to control
parameters of your cities.
Table of Contents
Part 1 : Understanding CGA rule parameters
Part 2 : Controlling the skyline of your city
Part 3 : Map-controlled land-use types of buildings

Import Streets Tutorial
This tutorial shows how to work with external street data. Street network data in the .dxf, .shp or .osm file format created in
external applications or coming from databases can be imported into the CityEngine and used as starting data for creating cities.
Table of Contents
Part 1 : Import DXF street data
Part 2 : Import OSM street data

Import Shapes Tutorial
This tutorial shows how to import external models as shapes. Imported shapes can be used in the scene as they are, or
processed further with CGA rules.
Table of Contents
Part 1 : Create and Import Lots
Part 2 : Import Named Lots
Part 3 : Import Volumes
Part 4 : Import textured Assets

Basic Shape Grammar Tutorial
The CGA Shape Grammar is the core of the CityEngine. Getting to know its powerful features is essential to create your
buildings and cities. Start with the simple building example which explains the basic steps needed to create your first building.
See Tutorial 14 for a demonstration how a similar building can be created using the visual CGA editor.
Table of Contents
Part 1 : Modeling a Simple Building
Part 2 : Texturing the Simple Building
Part 3 : Adding LOD
Part 4 : Random Variation of Building Attributes

Facade Modeling Tutorial
Modeling a Facade from a real-world photograph.
Table of Contents
Part 1 : Modeling the Facade Structure
Part 2 : Inserting Facade Assets
Part 3 : Texturing the Facade

Mass Modeling Tutorial
Learn how to create mass models of buildings using CGA Shape Grammar.
Table of Contents
Part 1 : Mass Modeling: L and U Shapes
Part 2 : Mass Modeling using Recursion
Part 3 : Adapting the parcel with setbacks
Part 4 : Combine Masses and setback parcels
Part 5 : Add Textured Facades

Advanced Shape Grammar Tutorial
This tutorial contains some more complex examples of procedcural modeling using the Shape Grammar. A real-world example
of a complex facade is analyzed and recreated with CGA rules in the first part. By analyzing the rule files of the Candler Building
and the Parthenon, an ancient greek temple, you will learn some more advanced CGA techniques.
Table of Contents
Complex Facade Patterns
The Candler Building
The Parthenon Temple

Python Scripting Tutorial
The Python Scripting Interface greatly enhances the possibilities of the CityEngine. This tutorials explains the basic usage of the
Python Console and the Editor, and gives two examples for automatisation of CityEngine tasks.
More information on the CityEngine-specific Python command set can be found in the CityEngine help: Help Help
Contents Manual Python Scripting
The Python scripting interface is not available in all CityEngine versions.
Table of Contents
Python Console and Editor
Changing street widths
Setting camera from FBX file

Animation : Growing Building
Writing an asset library rule file

Reporting Tutorial
The reporting feature augments the CityEngine beyond generation of geometry: It permits rule-based calculation and
accumulation of a model's parameters. This tutorial shows how to embed reporting actions in your CGA files and how resulting
reports are generated.
The standard (inspector-based) reporting features are available in all CityEngine versions. Script based export reporting
feature is only available in the CityEngine Pro version.
Table of Contents
Reporting Tutorial

CityEngine GIS Mapping Tutorial
This tutorial shows how to use CGA Shape Grammar to process GIS data that contain additional attributes to the footprints
such as height or usage type. Final models use a satellite image for roof texturing and advanced texturing techniques for realistic
facades.
Table of Contents
Part 1 : Extrusion using Height Data
Part 2 : Creating Roofs
Part 3 : Texturing the Facades

Part 4 : Analysing Attributes

CityEngine Scripted Report Export Tutorial
This tutorial shows how to use CGA report variables in combination with the Python-based exporter. We will report information
of instances distributed in our scene, and use it to generate an instance map in a simple text file.
The Python scripting interface is not available in all CityEngine versions.

Exporters are disabled in CityEngine Trial version.
Table of Contents
Part 1 : Report information of instanced buildings
Part 2 : The export script
Part 3 : Additional elements

CityEngine Visual CGA Tutorial
This tutorial shows how to use the visual mode of the CGA editor to create rules for a simple building (similar to the one from
Tutorial 6) without using the text editor.
Table of Contents
Part 1 : Modeling a simple Building
Part 2 : Inserting assets and texturing the building

CityEngine Facade Wizard Tutorial
This tutorial shows how to use the Facade Wizard to generate facade rule templates, without the need to code the complete
facades, but rather use just a series of mouse clicks. The Facade Wizard will then produce the resulting code which can be saved
for the use on arbitrary facades.
Table of Contents
Part 1 : Intro and Basic Example
Part 2 : Advanced Facade Creation
Part 3 : LODs and asset insertion

alignScopeToAxes
Synopsis
alignScopeToAxes()
alignScopeToAxes(alignAxesSelector)
Parameters
alignAxesSelector (selstr)
y (Note: x ,z and combinations of two axes not supported yet).
The alignScopeToAxes operation manipulates the scope , the pivot and the geometry attributes such that the scope 's axes are
parallel to the main axes. After this operation, the pivot.o , scope.r and the scope.t vectors are zero and the geometry is
projected to the new scope (i.e. stays at the same place in world coordinates).
A variant of the operation aligns only the y axis of the scope (the x axis is then projected to the world coordinates xz-plane).
Related
alignScopeToGeometry operation
setPivot operation
scope attribute
pivot attribute
Examples
A-->
t(5,0,4) s(8,24,8) r(10,20,30)
i("boxnewsredlowress.obj")
The initial scene: The pivot (fat) is in the origin; the scope (yellow) contains a
translation and a rotation.
A-->
t(5,0,4) s(8,24,8) r(10,20,30)
alignScopeToAxes()
Applying alignScopeToAxes() removes the scope translation and rotation, rotates

the pivot such that all pivot axes are parallel to the world coordinate axes and
projects the geometry to the new scope such that it stays at the same place in
world coordinates. Note that the pivot lies at a corner of the bounding box (which
is the new scope).
A-->
t(5,0,4) s(8,24,8) r(10,20,30)
alignScopeToAxes("y")
Using the y-axis variant only aligns the pivot to the y-axis.

alignScopeToGeometry
Synopsis
alignScopeToGeometry(upAxisSelector, float faceIndex, float edgeIndex)
alignScopeToGeometry(upAxisSelector, faceSelector, edgeIndex)
alignScopeToGeometry(upAxisSelector, faceIndex, edgeSelector)
alignScopeToGeometry(upAxisSelector, faceSelector, edgeSelector)
Parameters
upAxisSelector (selstr)
yUp , zUp (Note: xUp not supported yet)
faceIndex (float)
0-based index of face which contains the edge. Negative indices are modulo-adjusted, i.e. -1 is the last face.
edgeIndex (float)
0-based index of edge which will become the new x-axis. Negative indices are modulo-adjusted, i.e. -1 is the last edge.
Note that the edge index is relative to the selected face!
faceSelector (selstr)
world.lowest : takes the face with lowest y world-coordinates.

largest : takes the largest face.
any (only in combination with an edgeSelector ): takes the face for which the edge selector has extremal
value.
edgeSelector (selstr)
world.lowest : takes the edge with lowest y world-coordinates.

longest : takes the longest edge.
The alignScopeToGeometry operation manipulates the scope , the pivot and the geometry attributes in the following way:
1. select new pivot axis directions (defined by upAxisSelector and the selected face and edge, see below)
2. calculate the oriented bounding box (OOB) for the geometry along these axes and set pivot.p to the origin of the OOB. The new
scope dimensions are set to the OOB.
3. transform the geometry into this new coordinate system.
The parameters let you choose an edge of a face in the geometry. The new x-axis of the scope will be parallel to this edge, and the
up-axis will be the face's normal. The geometry is projected to the new scope (i.e. stays at the same place in world coordinates).
Related
alignScopeToAxes operation
setPivot operation
scope attribute
pivot attribute
Examples
Usage of the "auto" mode

A--> comp(f){ 25 : Faces }
The initial scene: After a face component split, the scope (and pivot, fat) happen to
be positioned such that the y-axis points towards the ground.
A--> comp(f){ 25 : Faces }
alignScopeToGeometry(zUp, auto)
Applying alignScopeToGeometry() with the "auto" mode selector guarantees that

the y-axis of the scope points upwards.
This is very useful e.g. for placing bricks on a roof.
Basic usage
A -->
s(2,3,2)
i("cylinder.obj")
B
comp(f){
0: color("#ff0000") t(0,0,0.01) X |
32: color("#0000ff") t(0,0,0.01) X }
The initial scene: A mesh is inserted and two faces highlighted by applying a
component split.
The same scene, with scope and pivot of shape B highlighted.
B -->
alignScopeToGeometry(zUp, 1)
After alignScopeToGeometry(),the pivot's (and the scope's) x-axis points along

edge 1 of face 0 (red); the z-axis points along the face normal and the x-axis is
normal to the two others. The pivot is positioned at the edges starting point and
the scope is the pivot-aligned bounding box of the geometry.
B -->
alignScopeToGeometry(yUp, 32, 2)
Here, the second edge of face 32 (blue) is used, and the face-normal becomes
the new y-axis.
B -->
alignScopeToGeometry(yUp, any, world.lowest)
In this case, "any" and "world.lowest" select the edge with lowest y-position (in
world coordinates), which becomes the new x-axis, and the corresponding face-
normal becomes the new y-axis (because of the yUp selector).

center operation
Synopsis
center(axesSelector)
Parameters
axesSelector (keyword)
Axes to include in center calculation (x|y|z|xy|xz|yz|xyz).
The center operation moves the scope of the current shape to the center of the previous shape's scope . 'Previous shape'
means the previous shape on the shape stack.
Related
push/pop operations
scope attribute
Examples
Positions of the axes selectors

Lot-->
i("builtin:cube")
s(4,4,4)
t(-2,-2,-2)
SelCube
SelCube-->
[ color("#ff0000") s(1,1,1) center(x) X ]
[ color("#00ff00") s(1,1,1) center(y) X ]
[ color("#0000ff") s(1,1,1) center(z) X ]
[ color("#ffff00") s(1,1,1) center(xy) X ]
[ color("#ff00ff") s(1,1,1) center(xz) X ]
[ color("#00ffff") s(1,1,1) center(yz) X ]
[ color("#ffffff") s(1,1,1) center(xyz) X ]
The colored small cubes show the positions of the axis-selectors relative to the
previous shape's (SelCube) scope.

color operation
Synopsis
color(val)
Parameters
val (string)
Color to set, in the format "#rrggbb" (hex).
The color operation sets the color of the current shape's material. The alpha channekl is not touched.
Note: this command has the same effect as set(material.color, val) , it is a shortcut for convenience.
Related
material.color attribute
set operation
Examples
Three ways to set a shape's color

Lot-->
extrude(20)
split(x) {
2 : color("#ff0000") X |
2 : set(material.color.rgb, "#ff0000") X |
2 : set(material.color.r, 1.0)
set(material.color.g, 0)
set(material.color.b, 0) X
}
Three ways to set a shape's color. The results are identical.

comp
Synopsis
comp(compSelector) { selector operator operations | selector operator operations ... }
Parameters
compSelector (keyword)
The component into which to split (f for faces, e for edges, v for vertices),
selector (keyword)
Semantic selection keyword:
front, back, left, right, top, bottom : The y-normals of the components are analyzed by classifying
their directions into the corresponding quadrants (in relation to the local coordinate system of the current
shape).
object.front, object.back, object.left, object.right, object.top, object.bottom : The y-normals
of the components are analyzed by classifying their directions into the corresponding quadrants (in relation
to the object coordinate system of the current initial shape).
world.south, world.north, world.west, world.east, world.up, world.down : The y-normals of the
components are analyzed by classifying their directions into the corresponding quadrants (in relation to the
world coordinate system).
vertical, horizontal, aslant, nutant : The y-normals are analyzed in relation to the xz-plane of the
current shape's local coordinate system. The the angle between normals and xz-plane is used to classify
the components as follows:
The exact ranges are (in degrees):
horizontal: ]78.75, 90]
aslant: ]11.25, 78.75]
vertical: ]-11.25, 11.25]
nutant: ]-78.55, -11.25]
horizontal: [-90, -78.75]
side: Selects all but the horizontal components
border, inside: Components at the border of or fully inside the geometry respectively. Border edges are
connected to only one face; border faces contain one or more border faces; border vertices are start or end
point of one or more border edges.
eave, hip, valley, ridge: These selectors work on edges only and are designed to be used in
conjunction with roofs. See section below for more details.
streetSide, noStreetSide : Components adjacent to a street can be selected with the streetSide
selector, and components not adjacent to a street can be selected with the noStreetSide selector. This
selector depends of the availability of the streetWidth attribute map; see Auto-generated street width
attributes.
all : Selects all components
index (float): Selects the index-th component (0-based).
operator
The operator defines how the selected components are used to generate successor shapes. Valid operators are:
: Each selected component is put into a new shape
= All selected components are combined into one new shape
operations
A sequence of CGA operations to execute.
The comp operation (component split) allows to divide a shape into its geometric components, which are either faces, edges
or vertices.
The components can be selected using either their index or a set of semantic selection keywords. The selected components are
transformed to a new shape and processed by a sequence of shape operations. Depending on the operator, either one shape is
created for each individual selected component (":") ore one shape for the whole set of selected components ("=").
The selection parameters of a component split work in a excluding manner: if a parameter has selected a specific component, this
component cannot be part of another selection (from left to right).
The local coordinate systems (pivot and scope ) of the newly generated shapes are aligned according to the geometry's topology;
the component split is one of the few shape operations which manipulate the pivot of a shape.
In the case of a face component split, the x-axis will be parallel to the first edge of the face and the z-axis wil point along the face's
normal. The pivot will be positioned at the first vertex of the first edge of the face; the scope will be the bounding box of the face,
i.e.the z-dimension of the emerging shape's scope is set to zero.
In the case of an edge component split, the x-axes of the pivot an the scope are along the edge and the z-axes point along the
average of the normals of the neighboring faces. The y- and z-dimension of the scope are set to zero and the x-dimension is the
length of the edge. The pivot will be positioned at one of the endpoints of the edge. The indexing of edges is as follows: index 0 is
the first edge of the first face, index 2 the second edge of the first face etc. Shared edges are skipped on second encounter.
In case of a vertex component split, the pivot is positioned at the vertex, the z-axes will point along the average of the normals of
the neighboring faces and all scope dimensions are set to zero.
Shape attributes
Each generated shape will have a number of attributes set:
comp.sel: A string containing the selector which chose the componets for this shape.
comp.index: The zero-based index of the selected component.
comp.total: The total number of components selected by the selector.
Index and total are per selector; for instance
...
i("builtin:cube")
comp(f) { front : Front | side : Side }
will create one Front shape with comp.sel="front", comp.index=0, comp.total=1 and 3 Side shapes with comp.sel="side",
comp.index=0,1,2 and comp.total=3.
Trim Planes
Additionally, for faces, the component split generates trim planes. Trim planes are placed along the shared edges of the new face
in a bisecting angle. The purpose of trim planes is twofold. On one side, trimming handles geometry intersections on the boundary
of two neighboring faces, and on the other side, trimming is used to handle non-rectangular faces.
According to the direction of the shared edge, trim planes are classified into horizontal and vertical planes. They can be switched
on or off by setting the trim attribute to true or false. By default, trimming is activated for vertical trim planes and deactivated for
horizontal trim planes. Check the trim planes examples below.
Trim planes are only generated if the : operator is used!
Roof Edges
There is a number of selectors which are designed to classify typical roof edges:
eave: Horizontal border edges on the bottom of the roof. The edges are always oriented anti-clockwise around the
original face.
hip : Inside edges connected to at least one eave edge. Hip edges are always oriented upwards, i.e. the ending point
has larger y-coordinate than the starting point.
valley : Inside edges where the two connected faces form a concavity. Valley edges are always oriented upwards, i.e.
the ending point has larger y-coordinate than the starting point.
ridge : Inside edges which are not hip or valley . Ridge edges are always oriented upwards, i.e. the ending point has
larger y-coordinate than the starting point.
The figure below shows a few examples.

These selectors can only be applied on edge component splits!
Related
i (insert) operation
comp attribute
pivot attribute
scope attribute
trim attribute
Examples
Facade Selection / Face Split Details

Let us split the mass model of a building into the main facade and a number of
side facades.
Note the orientation of the pivot (the annotated axes).
Building-->
comp(f) {
front : color("#ff0000") Main |
side : color("#0000ff") Side
}
Each face is now the geometry of a new shape; the new shapes' scopes and
pivots depend on the faces' orientation. The x-axis points along the first edge and
the z-axis points along the face normal. The scope's z-dimension is zero.
Selectors 1: Quadrant-based
Sphere-->
comp(f){
top: color("#0000ff") X |
bottom: color("#ffff00") X |
front: color("#ff0000") X |
back: color("#ff00ff") X |
left: color("#00ffff") X |
right: color("#00ff00") X
}
Selectors are demonstrated by using them to color the faces of a spherical

geometry. The selection is relative to the local coordinate system (the shown
scope).
Selectors 2: Angle to y-axis based

Sphere-->
comp(f){
horizontal: color("#0000ff") X |
aslant: color("#ff0000") X |
vertical: color("#ffff00") X |
nutant: color("#ff00ff") X
}
Note the horizontal areas (blue) on the sphere's poles.
Index-based Selection
A mesh can also be disassembled into its components by addressing them directly
by their index.
The indexing scheme is inherently encoded in the model itself!
Tube-->
comp(f) {
0 : X |
2 : X |
4 : X
}
Here, only faces 0, 2 and 4 of the cylinder are selected.

Trim Planes
Start-->
s(10,10,10)
i("builtin:cube")
comp(f) {5 : X}
At shared edges, trim planes (green) are inserted.
X-->
s(15,'1, 2)
center(xyz)
i("builtin:cube")
Inserted geometry is cut with the trim planes.
Start-->
s(10,10,10)
i("builtin:cube")
set(trim.horizontal, true)
comp(f) {5 : X}
By default, horizontal trim planes are off. Enabling them before inserting the
geometry gives a different result.
The Operator
Lot-->
extrude(20)
comp(f) { side : Sides }
Using the ":" operator results in a new shape for each component selected by the
selector.
In the example above, a shape is created for each side of the extruded geometry.
Therefore, the Lot Shape has five successors (one for each side). Each successor
shape has its pivot and scope set up differently.
Lot-->
extrude(20)
comp(f) { side = Sides }
In contrast, using the "=" operator results in exactly one new shape for all
component selected by the selector.
In the example above, one shape is created for all five sides of the extruded
geometry. Thje new shape's geometry contains all five faces, and the pivot and
scope are set up relative to the first selected face.
Border and Inside Selectors
The picture on the left shows the initial shape. It is a subdivided plane, consisting
of a number of faces.
Init-->
comp(f) { border : FBorder | inside : FInside }
BorderF-->
color("#ff0000")
InsideF-->
color("#00ff00")
The example selects the border and inside faces and colors them.
Init-->
comp(e) { border : EBorder | inside : EInside }
EBorder--> s('1, 0.05, 0.05) t(0, '-0.5, 0)

color("#ff0000") i("builtin:cube")
EInside--> s('1, 0.01, 0.01) t(0, '-0.5, 0)

color("#00ff00") i("builtin:cube")
Here, there border and inside edges are selected and colored cubes are inserted.
Init-->
comp(v) { border : VBorder | inside : VInside }
VBorder--> s(0.05, 0.05, 0.05) t(-0.025, -0.025, -0.025)

color("#ff0000") i("builtin:cube")
VInside--> s(0.05, 0.05, 0.05) t(-0.025, -0.025, -0.025)
color("#00ff00") i("builtin:cube")
Finally, the border and inside vertices are used to insert colored cubes.
Edge Split Details

Lot-->
extrude(10)
comp(e) { all : i("builtin:cube")
s('1, 0.8, 0.8) X }
A building mass model is split into its edges, and the built-in cube model is
inserted into each edge shape.
The pivot of the new shape is set to the edge's start vertex, and the alignment is
as follows: the x-axis points along the edge, the z-axis is the average of the
neighbouring face normals and the y-axis is normal to the two former ones.
The scope has zero translation and rotation, and the sizes are (edge-length, 0, 0).
Vertex Split Details

Lot-->
extrude(10)
MassModel
comp(v) { all : VShapes }
A building mass model is split into its vertices.

The pivot of the new shape (the VShapes in the rule above) is set to the vertex
position, and the alignment is as follows: the z-axis is the average of the
neighbouring face normals and the x- and y-axes are chosen such that they are all
normal to each other.
The scope has zero translation, rotation and size.

convexify
Synopsis
convexify()
convexify(float maxLength)
Parameters
maxLength
Maximum length of the split line which splits concave polygons into subpolygons. If not provided, no limit is applied, i.e.
all resulting polygons are convex.
This function splits a concave polygon into a number of convex polygons. If a maxLength parameter is provided, only split lines
shorter than this value are applied and one of the resulting polygons might still be concave.
Note: The "split edge" of the shapes which are split off has this shape's highest egde index. For example to align the scope to
the split edge one would use "alignScopeToGeometry(zUp, 0, geometry.nEdges-1)"
Related
innerRect operation
Examples
attr maxLength = 1
Lot -->
convexify(maxLength)
comp(f){all: SubShapes}
SubShapes -->
case scope.sx >= maxLength && scope.sy >= maxLength :
color("#00ff00")
else:
color("#ff0000")
Initial shapes: Generated shapes:

deleteUV operation
Synopsis
deleteUV(uvSet)
Parameters
uvSet
Number of texture a set/layer (integer number in [0,5]). The numbering corresponds to the texture layers of the material
attribute.
Note: colormap has uvSet 0, dirtmap has uvSet 2. See also: Material Shape Attributes.
The deleteteUV operation deletes the texture coordinates of the given uvSet .
Related
normalizeUV operation
projectUV operation
rotateUV operation
scaleUV operation
translateUV operation
setupProjection operation
texture operation
material.map attribute
extrude
Synopsis
extrude(height)
extrude(axisWorld, height)
Parameters
height (float)
How many units to extrude.
axisWorld (keyword)
Use a world coordinate axis as extrusion direction (world.x | world.y | world.z ).
Extrudes the shape. Each face polygon of all meshes in the geometry asset is taken and extruded along the face normal or the
given world-coordinate axis. The scope orientation is set in the following way:
x-axis direction is kept as much as possible (old x-axis is projected to plane orthogonal to extrusion direction)
y-axis along the extrusion direction
z-axis normal to the two above
The scope's sizes are adjusted to tighly fit the extruded geometry.
If height is < 0, the scope.sy attribute will be < 0.
Related
offset operation
taper operation
roofGable operation
roofHip operation
roofPyramid operation
roofShed operation
Examples
Lot Extrusion
Lot-->
extrude(4) Building
Extruding a building lot. On the left, the lot and the initial scope and pivot are
shown; on the right is the extruded building mass model, again with scope and
pivot.
Lot Extrusion along a World Coordinate Axis
This building footprint is slanted, e.g. lies on a hill.
Lot-->
extrude(world.y, 30)
By extruding along the world coordinate system's y-axis, a mass model with
upright sides is produced.
Extrusion of Multi-Face Initial Shapes
On the right, an initial shape consisting of 3 faces is shown..
Lot-->
extrude(12)
The extrude operation extrudes all faces and combines the results. No internal
lamina faces are created.

innerRect
Synopsis
innerRect()
The innerRect operation finds for each face of the current shape's geometry the largest rectangle with sides parallel to the
scope's x- and y-axes which is fully inside the face.
Related
convexify operation
offset operation
Examples
Inner Rectangles of Lot Shapes

Lot-->
innerRect
color("#ff0000")
set(material.color.a, 0.3)
extrude(20)
This example shows how to use innerRect() to place mass volumes in lots.

insert operation
Synopsis
i(geometryPath)
Parameters
geometryPath (string)
Name of the geometry asset to insert. See Asset Search for information about search locations and Built-in Assets for
a list of built-in assets.
Reads a geometry asset (3D model, polygon mesh) from a file and inserts it into the scope of the current shape. The asset is
transformed such that its bounding box coincides with the scope.
If one or more of the scope 's sizes sx , sy and sz (i.e. width, height or depth) are zero the scope is modified as follows:
If all three sizes of the scope are zero, such a point-like scope serves as origin for the asset to be inserted. Therefore,
the size vector of the scope is set to the sizes of the assets bounding box i.e. scope.sx = asset.sx, scope.sy =
asset.sy and scope.sz = asset.sz. Similarly, the scope is translated with the values from the asset, i.e. scope.tx
+=asset.tx, scope.ty += asset.ty and scope.tz += asset.tz. As a consequence, the inserted asset has not been
modified and its original dimension are completely preserved.
If two sizes are zero, such a line-like scope is modified relative to the non-zero size. For example, if only the height
(scope.sy) is non-zero, the following scaling value is calculated: scalexz = scope.sy/asset.sy. The size modifications
are then: scope.sx = scalexz*asset.sx and scope.sz = scalexz*asset.sz. Accordingly, the position of the scope is
modified for the two corresponding axes with scope.tx +=scalexz*asset.tx and scope.tz += scalexz*asset.tz. Thus the
inserted asset is uniformly scaled i.e. the proportions of the asset are completely preserved.
If one of the sizes is zero, the scope 's size is modified relative to the average of the two non-zero sizes. For example, if
the depth (scope.sz) is zero, the following calculation is performed: scope.sz
=(scope.sx/ asset.sx +scope.sy/ asset.sy )*0.5* asset.sz. Note that the position of the scope is not modified.
If the current shape has trim planes (generated in a component split), the model is cut with the trim planes.
Supported Asset Formats

Currently, the Wavefront OBJ and the COLLADA DAE formats are supported as asset formats.
The OBJ reader imports the material description file (.mtl) and it also understands negative indices (referencing from current
position backwards). It will silently drop unsupported geometry/material tags and will also delete normals or texture coordinates of
inconsistent meshes.
The COLLADA reader imports unlimited scene graphs and also reads transformation nodes. Extra tags are ignored and it will also
delete normals and texture coordinates of inconsistent meshes.
Remarks:
Both formats support per-mesh and per-face material assignments.

Mesh Consistency Requirement: All faces of a mesh must have the same usage of vertices, texture coordinates and
vertex normals. If one face does not use texture coordantes while other faces do, all texture coordinates are dropped
from this mesh. Other meshes are not modified.
Model Export Dependency: Assets which are used multiple times and are not modified geometry- or material-wise
during CGA model generation can be exported as instances (see Mesh Granularity export settings).
Related
comp operation
scope attribute
Examples
Window insertion
Lot-->
extrude(47)
comp(f){side : Facade |
top : X }
Facade-->
split(y) { { ~1 : X |
~8 : Floor }* |
~1 : X }
Floor-->
split(x) { { ~1 : X |
~5 : Window }* |
~1 : X }
The rules above yield the subdivided mass model on the left.
Window-->
i("window.obj")
The effect of inserting a window model in the Window rule is shown on the right.
Insertion and Zero Scope Dimensions
The asset which is going to be inserted, displayed in the inspector. The asset's
coordinates contain a translation of (12.3, 4.3, 7.2).
Head-->
s(0,0,0)
i("beethoven.obj")
Inserting an asset into a shape with a zero-sized scope sets the scope's size to
the asset's dimensions and translates the scope such that the asset's position is
preserved. Note that the translation relative to the shape's pivot (small axes on the
left) is identical to the translation of the asset in the inspector, relative to the origin
(picture above).
Head-->
s(9,0,0)
i("beethoven.obj")
If the scope size is non-zero in one dimension, the two other dimensions are set
relative to the non-zero dimension. The same is valid for the scope translation
along the zero-dimensions. In the picture on the left, the original scope is shown (it
is one-dimensional along the x-axis).
Head-->
s(9,9,0)
i("beethoven.obj")
If one of the scope sizes is zero, the scope's size is modified relative to the
average of the two non-zero sizes. Note that the position of the scope is not
modified.
Trim Planes and Insertion
Lot-->
i("builtin:cube")
s(10,40,10)
t(-5, 0, -5)
comp(f) { side: Side }
Side-->
t(0,0,-5)
s('1,'1,10)
i("cylinder.vert.obj")
The cylinder model, shown on the left, is inserted at the four side-faces of a cube.
The inserted cylinders are cut with the trim planes generated by the component
split.
In the picture on the left, the geometry of one Side shape (i.e. the cut cylinder) and
its trim planes are highlighted.
On the right is the smae scene from top view (top), and a close-up of the upper
area (bottom).
Lot-->
i("builtin:cube")
s(10,40,10)
t(-5, 0, -5)
comp(f) { side: Side }
Side-->
t(0,0,-5)
s('1,'1,10)
set(trim.vertical, false)
i("cylinder.vert.obj")
Note how disabling the trim planes just before the insert operation changes the
resulting geometry.

mirror
Synopsis
mirror(xFlip, yFlip, zFlip)
Parameters
xFlip (bool), yFlip (bool), zFlip (bool)
A boolean value (true or false ) for each scope axis; true means flip along the corresponding axis.
This function mirrors the geometry of the current shape.
Note: The current shape's scope stays the same.
Related
mirrorScope operation
reverseNormals operation
s operation
mirrorScope
Synopsis
mirrorScope(xFlip, yFlip, zFlip)
Parameters
xFlip (bool), yFlip (bool), zFlip (bool)
A boolean value (true or false ) for each scope axis; true means flip along the corresponding axis.
This function mirrors the scope of the current shape.
Note: The current shape's geometry stays the same.
Related
mirror operation
s operation
Synopsis
normalizeUV(uvSet, uvNormalizeMode, uvNormalizeType)
Parameters
uvSet
attribute.
uvNormalizeMode
There are four possible modes: uv , uvUniform, u or v .
uvNormalizeType
There are two possible types: separatePerFace or collectiveAllFaces.
The normalizeUV operation normalizes the texture coordinates of the given uvSet . Depending on the mode, the texture
coordinates are normalized to the [0, 1] range.
Related
deleteUV operation
projectUV operation
rotateUV operation
scaleUV operation
texture operation
NIL operation
Synopsis
NIL
The NIL operation deletes the current shape from the shape tree. It can be used to create holes in split operations or to
terminate recursive rules.
Examples
Using NIL to create Holes

Lot-->
extrude(10)
split(x){ { ~1 : X | ~1 : NIL }* | ~1 : X } }
Using NIL to stop a Recursion

attr ErkerFact = 0.8
attr ErkerDepth = 0.8
attr ErkerStop = 2
Lot-->
extrude(10)
X
comp(f) { all : Erker }
Erker-->
case(scope.sx > ErkerStop) :
s('ErkerFact, 'ErkerFact, 0)
center(xy)
alignScopeToGeometry(yUp, 0)
extrude(ErkerDepth)
X
comp(f){top : Erker}
else:
NIL

offset
Synopsis
offset(offsetDistance)
offset(offsetDistance, offsetSelector)
Parameters
offsetDistance (float)
Offset distance, negative or positive
offsetSelector (selstring)
(all | inside | border) - selects which faces to keep. all is default.
The offset operation constructs offset polygons at distance offsetDistance for each face of the current shape's geometry.
Depending on the sign of the parameter, offset polygons are constructed in the interior (negative sign) or in the exterior (positive
sign), respectively.
The resulting shape contains both the offset polygons and the border faces (that is the difference between the original faces
and the offset polygons). If only the offset polygons are needed, the corresponding faces can simply be extracted by using a
component split (see examples below).
Scope
The scope's size is adapted to the new geometry.
Related
extrude operation
innerRect operation
roofGable operation
roofHip operation
roofShed operation
taper operation
Examples
Offset Polygons and Border Faces

The following illustration lists offset polygons (red) and border faces (green) in both the interior and exterior case.
The original polygon (in the middle) is downsized (negative offsets) and enlarged (positive offsets). Offset polygons are
colored in red, border faces are in green. Note that in the case of enlarging, offset polygons and the border faces overlap.
These offset polygons have been generated using the rule

attr red = "#FF0000"
attr green = "#00FF00"
Lot --> offset(-3) A

A --> comp(f) { inside: I | border: O }
I --> color(red)
O --> color(green)
with offset between -3 and 3.
To extract the offset polygons, the inside selector is used for the component split. In the exterior case, this might be
confusing, since offset polygons are actually outside in this case.
When using positive offsets, border faces (green) and offset polygons (red) overlap. In this case the normals of the border
faces point down (see below).
Face Orientation
In the following illustration for each face, the first edge is marked.
In the interior case (offset = -1), both the inside and the border faces are oriented
counter-clockwise (positive).
In the exterior case (offset = 1), only the red face is oriented counter-clockwise.
The green border faces are clockwise (negative).
Since the border faces are negative in the exterior case, the following boolean equation holds in both cases: Inside faces +
Border faces = Original Face.
push / pop operation
Synopsis
[
The [ operation pushes the current shape onto the top of the shape stack. It must be matched by a succeeding ] operation,
which pops the shape on top of the shape stack and deletes the shape.
Related
center operation
Examples
Push/Pop Example
Lot-->
extrude(15)
r(scopeCenter, 0, 22.5, 0) X
In this example, the extruded shape is rotated three times and assigned to a new
shape (X).
Lot-->
extrude(15)
[ r(scopeCenter, 0, 22.5, 0) X ]
Encapsulating the rotations and createShape operations with a push/pop pair

makes all X coincide.

print operation
Synopsis
print(a)
Parameters
a (float | bool | string)
Value (or variable / shape attribute) to print
Prints the passed variable to the "console" console.
Examples
Printing some stuff

Lot-->
extrude(16)
split(y) {
2 : r(scopeCenter, 0, rand(90), 0)
print("split idx " + split.index + ",
tx = " + scope.tx +
" ry = " + scope.ry)
X
}*
The rule above prints some information about the split nodes, see the screenshot
on the left.

projectUV operation
Synopsis
projectUV(uvSet)
Parameters
uvSet
Index of uv-set to create (integer number in [0,5]). The numbering corresponds to the texture layers of the material
attribute.
The projectUV operation creates the final texture coordinates of the selected uv-set by applying the corresponding projection
matrix. Thus, this operation 'bakes' the texture projection into the texture coordinates of the geometry of the current shape.
The projection is based on the uvw-coordinate system specified by the setupProjection operation.
Note: colormap has uvSet 0, bumpmap will have uvSet 1, dirtmap has uvSet 2.
Related
deleteUV operation
rotateUV operation
scaleUV operation
texture operation
scope attribute
Example
Please refer to the examples in the setupProjection reference.
r operation
Synopsis
r(xAngle, yAngle, zAngle)
r(centerSelector, xAngle, yAngle, zAngle)
Parameters
xAngle (float), yAngle (float), zAngle (float)
Angles in degrees to rotate about each axis.
centerSelector (selstr)
The rotation center: scopeOrigin or scopeCenter .
Note: scopeOrigin is the default (used if no centerSelector is given).
The r operation rotates the scope of the current shape around the pivot-axes in xyz order. The center of rotation is either the
scopeOrigin (scope.t ) of the current shape or the scopeCenter of the current shape.
Note: r(x, y, z) is the same as rotate(rel, scopeOrigin, x, y, z) .
Related
rotate operation
s operation
t operation
translate operation
pivot attribute
scope attribute
Examples
Rotation Centers
height = 18
dy = 2
Lot-->
extrude(height)
split(y) {
dy : r(0, 360*split.index/split.total, 0)
X
}*
In this example, a mass model is split in vertical direction and the slices are
rotated around the scope.t . Each slice's scope is shown, note how the y-axes
denote an axis of symmetry.
height = 18
dy = 2
Lot-->
extrude(height)
split(y) {
dy : r(scopeCenter,
0, 360*split.index/split.total, 0)
X
}*
The same example as above, but this time the rotations are around the scope
center.

report operation
Synopsis
report(key, value)
Parameters
key (string)
A string which defines a key for a report collection. Keys can be grouped with the name sparator ''.''
value (float | bool | string)
Value (or variable / shape attribute) to add to the collection.
The report operation permits collection of arbitrary data during model generation. The operation takes two parameters: a key of
type string and a value of any type. The key and value type define a collection to which the value is added on every invocation.
After generation, the collections are assessed statistically and displayed in the Reports shelf in the Inspector.
Reports can be manually exported from the Inspector via the copy-paste clipboard (select the rows you want to export with shift
and the cursor keys, hit ctrl-c and paste the data to a text editor or a spreadsheet). Python scripting provides another, more
powerful way to export the reports; scripting allows for accessing all values in the collections, see the Reporting Tutorial .
Examples
Reporting Window State

Lot -->
extrude(30)
comp(f) { side : Facade | top : Roof }
Facade -->
report("facades", 1)
split(y) { ~5 : Floor | ~0.5 : Ledge }*
Floor -->
split(x) { ~1 : Tile | 2 : Window | ~1 : Tile}*
Window -->
40%:
report("windowarea", geometry.area())
report("windows.open", 1)
NIL
else:
report("windowarea", geometry.area())
report("windows.closed", 1)
color("#aaffaa")
The rules on the right produce the model above and the report shown below.

reverseNormals
Synopsis
reverseNormals()
This operation reverses the face normals of the geometry of the current shape.
Note: To check the orientation of the face normals, deactivate the "Use Two-Sided Lighting" option under
Preferences/General/Grammar Core.
Related
s operation
Examples
Note.1: Screenshots with deactivated "Two-Sided Lighting", thus the faces are black whose normals are facing away from the
camera.
Note.2: Note that the generated geometry only is changed, not the scope. You can see this by the fact that the translation
command in the example translates both the normal and inverted geometry in the same direction. --> reverseNormals s('1,'1,-
1) [when scope is zUp]
Left box: face with index=0 not inverted right box: face with index=0 inverted
Lot --> Lot -->

extrude(y,1) extrude(y,1)
comp(f){side: Facade} comp(f){side: Facade}
Facade --> Facade -->

case comp.index == 0: case comp.index == 0:
color("#ff0000") color("#ff0000")
# = red # = red
t(0,0,0.1) t(0,0,0.1)
else: reverseNormals
color("#00ff00") else:
# = green color("#00ff00")
t(0,0,0.1) # = green
t(0,0,0.1)
Advanced knowledge: Understanding the reversion process

Normals: The normal of a polygonal face is defined by the vertex order. By default, the order is counter clockwise.
Some advanced users may notice that after the reverseNormals command, the vertex order [black] is not only inverted (as in the
classic mathematical definition of the normal inversion [blue]) but is offset by the value of 1 [red]. The reason for this is because
the CityEngine often works with the "First Edge", which is defined by the vertex indices 0 and 1. Thus, in the reverseNormals
command, the "First Edge" is retained.
black: standard vertex order of the face (counter clockwise)
blue: classic reverted vertex order
red: reverted vertex order as used in the CityEngine, with retained first edge.
Note: Some game engines cannot display two-sided geometries, thus they display only those polygons whose normals are
oriented towards the camera. Other polygons are not rendered. Because of this fact it is particularly important to write cga code
with this fact in mind when modeling for game engines.
roofGable
Synopsis
roofGable(angle)
roofGable(angle, overhangX)
roofGable(angle, overhangX, overhangY)
roofGable(angle, overhangX, overhangY, even)
roofGable(angle, overhangX, overhangY, even, index)
Parameters
angle (float)
Angle of the roof-planes.
overhangX (float)
Overhang distance for overhangs perpendicular to ridges, measured perpendicular to the shape edges (on the roof).
overhangY (float)
Overhang distance for overhangs in the direction of the ridges, measured perpendicular to the shape edges (on the
roof).
even (bool)
Whether to make the roof gable even or not. If true, non-planar faces originate.
index (integer)
Edge index to control the orientation of the ridge. Use with caution!
The roofGable operation builds a gable roof perpendicular to each face of the current shape's geometry. The orientation of
the ridges is automatically computed (except in the 5-argument case). At all non-ridge (eave) edges, a plane is generated with
angle angle to the polygon plane. The planes are cut with each other to form the roof faces.
If overhangX is set, the roof faces overlap along the eave edges by this distance. Overhang distances are measured perpendicular
to the edges (on the roof planes).
If overhangY is set, the roof faces overlap in the direction of the riges by this distance. Overhang distances are measured
perpendicular to the shape edges (on the roof planes).
If even is set to true, the gable edges are forced to be horizontal. In this case, non-planar roof faces originate.
If index is set, the ridge is forced to be oriented in the direction of the edge index . Warning: This only works on convex shapes!
The even parameter is neglected.
The connectivity of the roof mesh is optimized for trim plane generation to cut bricks inserted into the roof planes (see
examples below).
Scope
The scope orientation is set in the following way:
x-axis direction is kept as much as possible (old x-axis is projected to plane orthogonal to face normal of the first face)
y-axis along the face normal of the first face
Related
extrude operation
roofHip operation
roofShed operation
taper operation
Examples
Simple Gable Roof

A basic gable roof is generated on top of an extruded L-lot.
Lot --> extrude(10) Mass

Mass --> comp(f) { top: Top | all: X }
Top --> roofGable(30, 2, 1) Roof
A gable roof with roof slope 30 degrees is built on top of an extruded

L-lot. The overhangX distance is set to 2 and the overhangY distance
is set to 1. Note the different overlap distances at the eaves (X) and
in the direction of the ridges (Y). Also note the setting of the pivot and
scope.
Roof --> set(trim.horizontal, true)

comp(f) { all : X }
After a component split, each roof face contains trim planes to cut
bricks on insertion.
Note that per default there are no horizontal trim planes at the
ridges. To enable them, set(trim.horizontal, true) is used in
front of the component split.
Note that there is exactly one roof face per Top shape edge. Unfortunately in the images it seems like the overlap is in a
separate face. However, the simple reason for this is that the edges of the faces in behind bleed through.
Even Gable Roof

This example demonstrates the difference between a standard and an even gable roof built on a trapezoid-lot.

Top --> roofGable(30, 1, 1, false) Roof
A gable roof with roof slope 30 degrees is built on top of an extruded

trapezoid-lot. The overhangs (X and Y) are both set to 1. Note that
the ridge is uneven.
Top --> roofGable(30, 1, 1, true) Roof
When using the above rule for the Top shape, the ridge vertices are
set to the average height, making the gable roof even.
The roof faces are non-planar now.
For many shapes, ridges get implicitly even and hence the even option doesn't change anything.
roofHip
Synopsis
roofHip(angle)
roofHip(angle, overhang)
roofHip(angle, overhang, even)
Parameters
angle (float)
overhang (float)
Overhang distance, measured perpendicular to the shape edges (on the roof).
even (bool)
Whether to make the ridges even or not. If true, non-planar faces originate.
The roofHip operation builds a hip roof perpendicular to each face of the current shape's geometry. At every edge, a plane is
generated with angle angle to the polygon plane. All planes are cut with each other to form the roof faces.
If overhang is set, the roof faces overlap the original shape by this distance. Overhang distances are measured perpendicular to the
shape edges (on the roof planes).
If even is set to true, the gable edges are forced to be horizontal. In this case, non-planar roof faces originate.
examples below).
Scope
Related
extrude operation
offset operation
roofGable operation
roofShed operation
taper operation
Examples
Simple Hip Roof

A basic hip roof is generated on top of an extruded L-lot.

Top --> roofHip(30, 2) Roof
A hip roof with roof slope 30 degrees is built on top of an extruded L-

lot. The overhang distance is set to 2. Note the setting of the pivot
and scope.
Roof --> set(trim.horizontal, true)

comp(f) { all : X }
Note that per default there are no horizontal trim planes at the
ridges. To enable them, set(trim.horizontal, true) is used in
front of the component split.
Note that there is exactly one roof face per Top shape edge. Unfortunately in the images it seems like the overlap is in a
separate face. However, the simple reason for this is that the edges of the shapes in behind bleed through.
Even Hip Roof

This example demonstrates the difference between a standard and an even hip roof built on a trapezoid-lot.

Top --> roofHip(45, 1, false) Roof
A hip roof with roof slope 45 degrees is built on top of an extruded

trapezoid-lot. The overhang is set to 1. Note that the ridge is uneven.
Top --> roofHip(45, 1, true) Roof
When using the above rule for the Top shape, the ridge vertices are
set to the average height, making the hip roof even.
The roof faces are non-planar now.

For many shapes, ridges get implicitly even and hence the even option doesn't change anything.
roofPyramid
Synopsis
roofPyramid(angle)
Parameters
angle (float)
The roofPyramid operation builds a pyramid roof perpendicular to each face of the current shape's geometry. The polygon
center (average of all vertices) gets extruded along the face normal and connected to all polygon vertices. The new triangles are
the roof faces. The height is chosen such that angle between roof triangle 1 and the polygon is angle .
examples below).
Scope
Related
extrude operation
offset operation
roofGable operation
roofHip operation
roofShed operation
taper operation
Examples
Simple Pyramid Roof

A basic pyramid roof is generated on top of an extruded L-lot.

Top --> roofPyramid(30) Roof
A pyramid roof with roof slope 30 degrees is built on top of an

extruded L-lot. Note the setting of the pivot and scope.
Roof --> comp(f) { all : X }
There is exactly one roof face per Top shape edge.

roofShed
Synopsis
roofShed(angle)
roofShed(angle, index)
Parameters
angle (float)
Angle of the roof plane.
index (float)
Edge index (thus integral value) to specify the orientation of the shed roof.
The roofShed operation builds a shed roof perpendicular to each face of the current shape's geometry. At edge index (default
value 0), a plane is generated with angle angle to the polygon plane.
If index is set, the roof plane is oriented to the specified edge.
examples below).
Scope
Related
extrude operation
offset operation
roofGable operation
roofHip operation
taper operation
Examples
Simple Shed Roof

A basic shed roof is generated on top of an extruded L-lot.

Top --> roofShed(10, 3) Roof
A shed roof with roof slope 10 degrees is built on top of an extruded

L-lot. The edge index is set to 3. Note the roof orientation and the
setting of the pivot and scope.
Roof --> comp(f) { all : X }
After a component split, roof side faces contain trim planes to cut
There is exactly one side roof face per Top shape edge.
Edge index should not be a concave edge!

rotate operation
Synopsis
rotate(mode, coordSystem, xAngle, yAngle, zAngle)
Parameters
mode
(abs | rel) Absolute or relative mode. Absolute means the angles are set to the given value, relative means the
angles are added.
coordSystem
(scope | pivot | object | world ) Name of the coordinate system in which the following angles are given.
Angles in degrees to rotate about each axis.
The rotate operation rotates the scope around the scope origin. The angles can be defined in any coordinate system, and the
rotation can either be absolute (= set the angles) or relative (= add the angles). This operation manipulates the scope orientation
(scope.r attribute).
Related
convert function
r operation
t operation
translate operation
scope attribute
Examples
Set scope orientation to world coordinate system angles
version "2009.2"
Init-->
extrude(10)
t('0.2, 0, '0.3)
s('0.5, '1, '0.5)
rotate(abs, world, 0, 90, 0)
Using the absolute mode, the scope orientation can be set to an orientation relatiove to the
world origin.

rotateScope operation
Synopsis
rotateScope(xAngle, yAngle, zAngle)
Parameters
Angles in degrees to rotate about each pivot axis.
The rotateScope operation rotates the scope of the current shape around the pivot-axes in xyz order. The geometry is not
rotated, and the size and translation of the scope is adjusted such that the scope is the the geometry's bounding box aligned to the
scope axes.
Related
rotate operation
s operation
t operation
translate operation
pivot attribute
scope attribute
rotateUV
Synopsis
rotateUV(uvSet, rotAngle)
Parameters
uvset
Defines the uv set to rotate (integer number in [0,5]). The numbering corresponds to the texture layers of the material
attribute.
rotAngle
Defines the angle of the rotation.
Returns
Rotates the texture coordinates (uvSet).
This function rotates the texture coordinates (uvs) of the current shape by the rotAngle.
Note.1: The rotation center is at the texture position u=0 and v=0.
Note.2: Rotating uvs works only after the uvs have been projected.
Related
deleteUV operation
projectUV operation
scaleUV operation
texture operation
Examples
brickMap = "assets/bricks.jpg"
dirtMap = "assets/dirt.jpg"
randBuildingHeight = 1
Lot -->
s('.75,'1,'.75)
center(xz)
extrude(y, randBuildingHeight)
comp(f){side: Facade | top: set(material.color.a, .3) Roof.}
Facade -->
# color, uv set 0
setupProjection(0, scope.xy, scope.sx, scope.sy)
texture(brickMap)
projectUV(0) # projection of the uvs
rotateUV(0,10) # rotate command after the projection
Example with standard uvs and rotated uvs:

s operation
Synopsis
s(float xSize, float ySize, float zSize)
Parameters
xSize (float), ySize (float), zSize (float)
Sizes of the new scope dimensions.
The s operation sets the size vector scope.s.

The relative operator ' permits a convenient notation relative to the current shape's scope size:
s('sx,0,0) is equivalent to s(sx*scope.sx, 0, 0)
Negative sizes result in mirroring along the corresponding axes; this means the normals are inverted!
Related
r operation
rotate operation
t operation
translate operation
scope attribute
Examples
Basic Usage
Lot-->
extrude(10)
The initial shape with its scope highlighted.
Lot-->
extrude(10)
s(5,5,5)
Here, all scope sizes are set to the absolute value 5.
Lot-->
extrude(10)
s('0.5,'1,'1.5)
This example demonstrates the usage of the relative operator '. The s operation
above is equivalent to
s(0.5*scope.sx,scope.sy,1.5*scope.sz)

scaleUV operation
Synopsis
scaleUV(float uvSet, float uFactor, float vFactor)
Parameters
uvSet
attribute.
uFactor (float)
A factor to multiply all texture coordinates in u-direction.
vFactor (float)
A factor to multiply all texture coordinates in v-direction.
The scaleUV operation scales the corresponding texture layer by multiplying each of its texture coordinates with uFactor and
vFactor .
Related
deleteUV operation
projectUV operation
rotateUV operation
texture operation
scatter operation
Synopsis
scatter(domain, nPoints, distributionType) { operations }
scatter(domain, nPoints, gaussian, scatterMean, scatterStddev) { operations }
Parameters
domain (selstr)
Where to distribute the points. One of (surface|volume|scope ). Note that volume only works if applied to a closed
surface geometry; id the mesh is not closed, the operation falls back to surface .
nPoints (float)
The number of points to distribute.
distributionType (selstr)
The random distribution type. Valid types are (uniform|gaussian ).
scatterMean (selstr)
The position in the scope to use as the mean for the gaussian normal distribution. One of
(center|front|back|left|right|top|bottom). Default value is center .
scatterStddev (float)
The standard deviation for the gaussian normal distribution. Note that this parameter can also be given in relative
coordinates (leading to axisspecific standard deviations according to the dimensions of the scope). Default value is
'0.16.
The scatter operation places point shapes in or on the geometry of the current shape. The parameter nPoints determines
how many point shapes shape are created. The first parameter domain chooses where to distribute the points. Two different
random distributions can be used (uniform or gaussian; the optional parameter mean describes the center position of the point
cluster relative to the current shape. It currently can be either center (default), front, back, left, right, top, or bottom. The optional
parameter deviation describes the standard deviation. Note that this parameter can also be given in relative coordinates (leading
to axisspecific standard deviations according to the dimensions of the scope). Per default the value of deviation is set to 0.16.
The scatter operation does not affect the rotation of the children shapes except if the domain is set to surface . Then the the
children's scopes are oriented such that the y-direction corresponds to the surface normal.
Note: the children shape's scope sizes are set to 0.
Note: the children shape's geometry is replaced by a builtin:cube.
Examples
Point Distribution on a Surface
Leaf-->
s(0.2,0.3,0.1)
color("#ff0000")
Init-->
scatter(surface, 100, uniform) { Leaf }
Uniform point distribution on a surface.
Leaf-->
s(0.2,0.3,0.1)
color("#ff0000")
Init-->
scatter(surface, 100, gaussian) { Leaf }
Gaussian normal point distribution on a surface.
Leaf-->
s(0.2,0.3,0.1)
color("#ff0000")
Init-->
scatter(surface, 100, gaussian, left, '0.1) { Leaf }
Gaussian normal point distribution agan; the mean of the distribution is moved to the
scope's left side and a smaller standard deviation is used.

set(attribute, value)
Synopsis
set(attribute, value)
Parameters
attribute (keyword)
Name of shape attribute to set.
value (bool, float or string - same type as attribute)
Value to assign to shape attribute. Note: Not all shape attributes are writable!
The set operation assigns a value to a shape attribute of the current shape.
Related
material attribute
pivot attribute
scope attribute
seedian attribute
trim attribute
Examples
Enable horizontal trim planes set(trim.horizontal, true)
set(scope.tx, 0)
Set x-translation of scope to 0
set(material.color.r, 0.5)
Set the material color's red component to 0.5
set(material.colormap, "builtin:uvtest.png")
Assign the built-in test texture to the colormap
channel
setback operation
Synopsis
setback(setbackDistance) { selector operator operations | selector operator operations ... }
Parameters
setbackDistance (float)
The setback distance.
selector (keyword)
front, back, left, right, top, bottom : The edges' outwards normals in the polygon plane are
analyzed by classifying their directions into the corresponding scope quadrants.
object.front, object.back, object.left, object.right, object.top, object.bottom : The edges'
outwards normals in the polygon plane are analyzed by classifying their directions into the corresponding
object coordinate system quadrants.
world.south, world.north, world.west, world.east, world.up, world.down : The edges' outwards
normals in the polygon plane are analyzed by classifying their directions into the corresponding world
coordinate system quadrants.
streetSide, noStreetSide : Edges adjacent to a street can be selected with the streetSide selector, and
edges not adjacent to a street can be selected with the noStreetSide selector. This selector depends of the
availability of the streetWidth attribute map; see Auto-generated street width attributes.
all : Selects all edges
remainder: Selects the remainder of the polygon.
Note: the remainder depends on the selected edges but is always the same, independent of the
position of the remainder selector in the selector-operator sequence!.
index (float): Selects the index-th component (0-based). Too large and negative indices a modulo wrapped
to a correct index.
operator
The operator defines how the setback polygons are used to generate successor shapes. This also applies to shapes
with more than one faces. Valid operators are:
: Each polygon is put into a new shape.
= All polygons corresponding to the selector are combined into one new shape.
operations
The setback operation selects a number of edges and sets them back by a given distance. This is somewhat similar to the
polygon offset operation , with the difference that only a subset of the edges are setback.
Related
comp operation
offset operation
shapeL operation
shapeU operation
shapeO operation
Examples
Setback on Streed Side

LotInner-->Lot
Lot-->
setback(5) { streetSide : Garten | remainder : Building }
Garten --> color("#00ff00")
Building-->
offset(-3, inside)
extrude(world.y, rand(5, 15))
setPivot
Synopsis
setPivot(axisMapSelector, cornerIndex)
Parameters
axisMapSelector (selstr)
Selector which defines the mapping of the old scope axes to the new pivot (and scope) axes. Supported values are:
xyz : Keeps the current orientation, i.e. in corner 0 (the origin, see visual guide below), the new x-axis will point along
the old scope's x-axis, the new y-axis will point along the old scope's y-axis and the new z-axis will point along the old
scope's z-axis.
yzx : In corner 0, the new x-axis will point along the old scope's z-axis, the new y-axis will point along the old scope's x-
axis and the new z-axis will point along the old scope's x-axis.
zxy : In corner 0, the new x-axis will point along the old scope's y-axis, the new y-axis will point along the old scope's z-
axis and the new z-axis will point along the old scope's x-axis.
cornerIndex (float)
Integer value in [0, 7] to select one of the scope 's corners to become the new pivot.p .
The setPivot operation lets you re-position and re-orient the current shape's pivot . The new orientation will be based on the
current shape'sscope axes, the axisMapSelector and the cornerIndex .
The new pivot.p will lie at a selected corner (cornerIndex ) of the current shape'sscope , and the pivot will be rotated such that all
axes point inside the scope.
The new scope will have zero translation and rotation (relative to the pivot), and will stay at the same place (in world coordinates),
but with different axes. The geometry is projected to the new scope (i.e. stays at the same place in world coordinates).
Visual Guide
The scope of the current shape prior to the setPivot() operation is depicted in the
picture on the left. The numbers depict the cornerIndices.
The pivots after setPivot(xyz, v) with v = the cornerIndex.
Note the orientation of the pivots: in corner 0, the axes are the same as the
original scope axes; at all other corners, the direction of y is the same (or the
negative) of the y axis of the original scope. The other axes are oriented such that
they conicide with a scope axis.
The pivots after setPivot(yzx, v) with v = the cornerIndex.

Note the orientation of the pivots: in corner 0, the scope axes xyz are replaced by
the axes yzx.
The pivots after setPivot(zxy, v) with v = the cornerIndex.
Note the orientation of the pivots: in corner 0, the scope axes xyz are replaced by
the axes zxy.
Related
scope attribute
pivot attribute
Synopsis
setupProjection(uvSet, axesSelector, texWidth, texHeight)
setupProjection(uvSet, axesSelector, texWidth, texHeight, widthOrigin, heightOrigin)
setupProjection(uvSet, axesSelector, texWidth, texHeight, widthOrigin, heightOrigin, uwFactor)
Parameters
uvSet (float)
Index of the uv-set (texture layer) to set up (integer number in [0,5]). The numbering corresponds to the texture layers
of the material attribute.
axesSelector (selstr)
Describes the origin and which axes are taken as u- and v-axes. Possible values:
scope.xy, scope.xz, scope.yx, scope.yz, scope.zx, scope.zy :
Choose the scope origin and two of its axes.
world.xy, world.xz, world.yx, world.yz, world.zx, world.zy :
Choose the world origin and two of its axes.
texWidth (float)
The texture width in world coordinate system units (e.g. meters). Values < 0 are allowed and mirror the texture. The
operators ~ (floating) and (relative) can be used, see below.
texHeight (float)
The texture texHeight in world coordinate system units (e.g. meters). Values < 0 are allowed and mirror the texture.
The operators ~ (floating) and (relative) can be used, see below.
widthOffset (float)
The offset in u-direction, in world coordinate system units (e.g. meters).
heightOffset (float)
The offset in v-direction, in world coordinate system units (e.g. meters).
uwFactor (float)
Sets the factor by which the texture is applied on the w-axis relative to the u-axis (see examples below). The default
value is 0.
The setupProjection operation initializes a projection matrix for the chosen uv-set based on the reference coordinates
system specified with axesSelector . It can be chosen between scope and world coordinate systems. For example, to initialize
the u- and v-axes with the x- and y-axes of the current scope, the axesSelector has to be set to scope.xy. Note that some
combinations result in a mirrored texture!
The texWidth and texHeight parameters support usage of the floating and relative operators to avoid complex calculations with
the scope dimension, analogous to the transformation and split operations. For example, if the parameter texWidth is set to ~2,
the projection matrix is initialized such that the current scope width is exactly spanned with texture tiles of approximately size 2.
Or if the paramter texHeight is set to 0.5, the texture will be repeated twice along the height.
Optionally, the influence of the pixels's z-coordinate on the w-texture coordinate relative to the u-coordinate can be set. Note that
it defaults to 0 if not provided.
Related
deleteUV operation
projectUV operation
rotateUV operation
scaleUV operation
texture operation
scope attribute
Examples
Standard Texturing of a Building
The setupProjection/projectUV example uses the SimpleBuilding scene from the Shape Grammar Tutorials.
Default Use Case

The first rule snippet shows how the setupProjection operation is used in the facade rule to define the texture coordinate system
(also called "uvw" system to avoid confusion with the xyz system for the geometry) for the subsequent projectUV operations (=
texture projections).
Lot -->
... Building
Building -->
... Frontfacade ...
Frontfacade -->
setupProjection(0, scope.xy, 1.5, 1, 1) # setup 1.5m x 1m texture tiles
setupProjection(2, scope.xy, scope.sx, scope.sy, 1) # using dirtmap (uvSet #2)
split(y){ groundfloor_height : Groundfloor

| {~floor_height : Floor}* }
In the second snippet we show how the projectUV operation computes new texture coordinates for the wall asset. Already existing
texture coordinates on this channel are replaced. projectUV uses the uvw coordinate system previously defined by setupProjection
and projects the assets vertices along the w-axis to get the new texture coordinates.
... rules for floors and facade tiles ...
Wall -->
color(wallColor)
set(material.colormap, wall_tex)
set(material.dirtmap, dirt_tex)
projectUV(0) projectUV(2)
In contrast, note how the rule for the door does not use any projectUV operation to apply the texture, it just uses the generic texture
coordinates from the cube asset.
Door -->
s('1,'1,0.1)
t(0,0,-0.5)
set(material.colormap, frontdoor_tex)
i("builtin:cube")
Scope vs. setupUV

The example below shows the difference if we put the setupProjection command next to the projectUV in the wall rule instead in the
rule on the facade level. Please note that in the bottom picture, the brick texture does not span over the whole facade anymore;
there are visible seams.
Frontfacade -->
setupProjection(0, scope.xy, 1.5, 1, 1)
setupProjection(2, scope.xy, scope.sx, scope.sy, 1)
...
...
Wall -->
color(wallColor)
Frontfacade -->
setupProjection(2, scope.xy, scope.sx, scope.sy, 1)
...
...
Wall -->
color(wallColor)
Working with the z- resp. w-coordinate
Planar texture projection along the w-axis sometimes results in artifacts like on this doorframe:
For this reason the setupProjection command has an optional parameter uwFactor which allows for the projection of the texture also
along the w-direction. The value of the uwFactor specifies the tile width relative to the u-direction. This feature is sometimes useful
to "bend" textures around corners and avoid excessive use of component splits.
Global Texture Projection
This example demonstrates how to quickly create textured mass models from an areal picture.
First, an attribute layer is created with the picture. This attribute layer is shown on
the left. Below are the details of the attribute layer setup.
version "2009.3"
attr buildingheight= 20
Lot-->
extrude(buildingheight)
A number of initial shapes are manually drawn (following the countours of the
buildings). Then the initial shapes are extruded to basic mass models using the
extrude operation.
version "2009.3"
attr buildingheight= 20
Lot-->
extrude(buildingheight)
comp(f){top : Roof | side : Facade}
Roof-->
setupProjection(0, world.xz, 586, 442)
projectUV(0)
scaleUV(0, 1, -1)
set(material.colormap, "test_0102_ortho.jpg")
The Roof rule is added. It projects the same texture as shown in the attribute
layer onto the top faces of the mass models. The global x-axis is chosen as the
u-axis, and the global z-axis as the v-axis. This results in an inverted texture
along the v-axis and is corrected with the scaleUV() operation.

shapeL, shapeU, shapeO operations
Synopsis
shapeL(frontWidth, leftWidth) { selector operator operations | selector operator operations }
shapeU(frontWidth, rightWidth, leftWidth) { selector operator operations | selector operator operations }
shapeO(frontWidth, rightWidth, leftWidth, backWidth) { selector operator operations | selector operator

operations }
Parameters
frontWidth (float)
The distance of the front setback.
leftWidth (float)
The distance of the left setback.
rightWidth (float)
The distance of the right setback.
backWidth (float)
The distance of the back setback.
selector (keyword)
shape : The setback polygon (i.e. the L,U or O shape)
remainder: Selects the remainder of the polygon.
operator
The operator defines how the setback polygons are used to generate successor shapes. This also applies to shapes
with more than one faces. Valid operators are:
: Each polygon is put into a new shape.
= All polygons corresponding to the selector are combined into one new shape.
operations
The shapeL, shapeU, shapeO operations select a number of edges, depending on predefined spatial selectors, and set them
back by a user-defined distance.
Related
comp operation
offset operation
Examples
L-Shapes
A block filled with L-shapes.
attr front = 5
attr left = 11
LotInner-->Lot
Lot-->
offset(-3, inside)
shapeL(front,left) { shape : extrude(rand(10,20)) clr.Red | remainder: NIL }
U-Shapes
A block filled with U-shapes.
attr front = 5
attr left = 11
attr right = 3
LotInner-->Lot
Lot-->
offset(-3, inside)
shapeU(front,right,left) { shape : extrude(rand(10,20)) clr.Red | remainder: NIL }
O-Shapes
A block filled with O-shapes.
attr front = 5
attr left = 11
attr right = 3
attr top = 2
LotInner-->Lot
Lot-->
offset(-3, inside)
shapeO(front,right,top,left) { shape : extrude(rand(10,20)) clr.Red | remainder: NIL }

split operation
Synopsis
XYZ Split (Cartesian Space)
split(splitAxis) { size1 : operations 1 | size2 : operations 2 | ... | sizen - 1 : operations n-1 }
split(splitAxis) { size1 : operations 1 | size2 : operations 2 | ... | sizen - 1 : operations n-1 }*
split(splitAxis, adjustSelector) { size1 : operations 1 | ... | sizen - 1 : operations n-1 }
split(splitAxis, adjustSelector) { size1 : operations 1 | ... | sizen - 1 : operations n-1 }*
UV Split (Texture Space)
split(splitDirection, surfaceParameterization, uvSet) { size1 : operations 1 | ... | sizen - 1 : operations n-1 }*
Parameters
splitAxis (selstring)
(x | y | z) - Name of axis to split along. This is relative to the local coordinate system (i.e. the scope ).
adjustSelector
(adjust | noAdjust ) - optional selector to control scope calculation of the calculated shapes: the default is to adjust the
scope to the geometrie's bounding box; noAdjust avoids this, therefore the scopes of the resulting shapes fill the
parent's scope without gaps.
splitDirection (selstring)
(u | v ) - Name of axis to split along.
surfaceParameterization (selstring)
(uvSpace | unitSpace) - uvSpace is the planar texture space defined by the uv coordinates; unitSpace is the 2d space
on the 3d geometry surface, measured in units (e.g. meters).
uvSet (float)
attribute.
General
size (float)
Split width. Depending on the prefix, the widths along axis are interpreted in the following way:
no prefix (absolute)
the new shape will have exactly size size.
' (relative)
the new shape's size will be size * current scope size.
~ (floating)
the remaining space is distributed to all floating sizes. The sizes are used as relative weights to assign the
absolute sizes.
If the repeat switch is set, floating sizes are interpreted as absolute and adjusted to fit the whole space
afterwards.
operations
A sequence of shape operations to execute on the newly created shape.
*
Repeat switch: fit the content of {...} into the current shape's scope as often as possible.

The split operation subdivides the current shape along the specified scope axis into a set of smaller shapes. For each
size-operation block inside the curly brackets, a new shape is pushed onto the shape stack, a number of shape operations is
executed and the shape on top of the shape stack is popped again.
If the optional repeat switch * is appended to the split operation, the content of {...} is repeated as often as it fully fits into the
scope 's dimension along the selected axis.
The geometry of the current shape is cut with a plane perpendicular to the split axis at every intersection between two blocks (i.e. at
size1 , size2 , ... sizen-1 ). Hollow meshes are closed after the cut, i.e. cutting planes introduce new surfaces to preserve the
volume.
Splits can be nested, i.e. a size : operation block can be replaced by a {...} block. In theory, the nested level is unlimited.
Splits can also be applied in the 2d uv texture domain. Texture coordinates define a 2d parameter space on a 3d surface. Examples
of such parameterizations are streets (u along thew street direction, v along the width) and facades (generated with
setupProjection() and projectUV() , u along the width and v along the height). This permits to operate directly on the surface. In
general, uv coordinates are in the [0,1] range and not connected to a unit like meters or yards on the surface (defined by the
underlying mesh). Setting the splitDirection parameter to unitSpace permits to operate directly on the surface, i.e. work in units
(e.g. meters or yards). Depending on the geometry and type of parameterization there is some inherent distortion in this conversion.
Borders (start, end) of the uv split are defined by the minimal and maximal values found in the selected uv coordinates. The genral
syntax of the split is the same as in the carthesian case described above, i.e. relative and floating operators (' and ~) can be used
as well as the repeat operator (*). Please check out the examples below.
Related
scope attribute
pivot attribute
split attribute
Examples
Setup
This is the initial shape before the split. We will present a number of split examples
along the x axis, the current shape's scope.sx is 10.
Below are the rules used to color and size the shapes created in the split:
X(h)-->
s('1,'h,'1)
color("#0000ff")
Y(h)-->
s('1,'h,'1)
color("#ffff00")
Z(h)-->
s('1,'h,'1)
color("#00ff00")
Relative Sizes
A-->
split(x){ '0.5 : Z |
'0.1 : Y(2) |
'0.2 : X(1) }
This example shows the usage of the relative prefix. The green Z shape takes half
of the initial shape's size (5 units) and so on. The total sum of all shape sizes in x-
direction is 8, therefore the gap at the end.
Floating Sizes only: Ratios
A-->
split(x){ ~0.5 : Z |
~0.1 : Y(2) |
~0.2 : X(1) }
The same example as above, but all sizes with the floating prefix. Note how the
whole initial scope is filled (no gap at the end), and the ratios are kept.
Absolute and Floating Sizes
A-->
split(x){ 3.3 : Z(1) |
~3 : Y(2) |
5 : X(1) }
Here, a floating sized shape is framed between two absolute sized shapes. Its size
is adjusted from 3 to 1.7 to fulfill the absolute constraints.
Oversized
A-->
split(x){ '0.5 : Z(1) |
'0.6 : Y(2) |
3 : X(1) }
The first shape Z (green) fits in, but the second one Y (yellow) is cut at size 5. The
X never gets created because there is no space left.
Repeat Split with Absolute Sizes
A-->
split(x){ 2 : X(2) |
1 : Y(1) }*
A repeat split example. All sizes are absolute. The XY pattern is repeated 3 times,
and the remaining unit is filled with half a X, i.e. the geometry of the last X is cut
off.
Repeat Split with Floating Sizes
A-->
split(x){ ~2 : X(2) |
~1 : Y(1) }*
If floating sizes are used in the repeat split, no shape is cut but the sizes are
adjusted such that the ratio between the elements is kept and the whole scope can
be filled.
Interleaved Repeat Split
A-->
split(x){ 1 : X(3) |
{ ~1 : Y(2) |
0.2 : Z(1) |
~1 : Y(2) }* |
1 : X(3) }
A interleaved split consisting of two absolute-sized shapes at both ends and a

repeat split in-between. Note: the green shapes Z have absolute sizes, while the
yellow Y shapes have floating sizes which turn out to be 0.9.
Rhythm
A-->
split(x){ { 1 : X(3) |
~3 : Y(1) }* |
1 : X(3) }
Here it is demonstrated how a pattern ABABABA etc. can be achieved. Note the
floating size of the yellow Y shapes.
Cutting Geometry
A-->
i("cylinder.hor.obj")
t(0,'0.5,0)
Here it is demonstrated how a the geometry of the current shape is cut into a
number of smaller shapes. A cylinder model is inserted into the current shape.
A-->
i("cylinder.hor.obj")
t(0,'0.5,0)
split(x) { { ~0.75 : XX | ~1 : NIL }* | ~0.5 : XX }
Splitting the shape and using NIL in the split rule results in holes. Note how the cut
surfaces are closed.
UV Split Basics
Init-->
extrude(scope.sx * 0.5)
comp(f) { front : Facade }
Facade-->
setupProjection(0, scope.xy, '1, '1)
projectUV(0)
texture("builtin:uvtest.png")
split(u, uvSpace, 0) { 0.5 : X }*
u split in uvSpace - the split happens at u = 0.5, independent of facade size.
Init-->
extrude(scope.sx * 0.5)
comp(f) { front : Facade }
Facade-->
projectUV(0)
split(u, unitSpace, 0) { 5 : X }*
u split in unitSpace - the splits happen at u = 5, dependent of facade size.
UV Split on Streets
Street-->
The test texture on a street with two segments. The street's texture coordinates
are automatically generated; note that the two street segments have different
lenghts but are both covered by a [0,1] uv space, the u axis following the street
direction and the v axis, perpendicular to u, along the width.
Street-->
split(u, unitSpace, 0) { ~10 : NIL | ~3 : color("#ff0000") X
| ~10 : NIL}*
The same street after a u-split in unitSpace. Every 20 meters a 3 meter wide band
is drawn accross the street.

t operation
Synopsis
t(tx, ty, tz)
Parameters
tx (float), ty float), tz (float)
Amount to translate in each direction.
The t operation translates the scope by the vector (tx, ty, tz ), i.e. the vector is added to scope.t . If the scope rotation is
non-zero, then the passed translation vector is rotated around the pivot, with angles (scope.rx, scope.ry, scope.rz), first. In
other words, the translation is relative to the scope axes.
The relative operator ' permits a convenient notation relative to the scope size: t('tx,0,0) is equivalent to t(tx*scope.sx, 0, 0) .
Note: t(x,y,z) is the same as translate(rel, scope, x, y, z) .
Related
scope attribute
r operation
rotate operation
s operation
translate operation
Examples
Translate - Rotation Concatenation

A-->
i("builtin:cube")
This is the initial shape we start with.
A-->
i("builtin:cube")
t(2,0,0)
First a translation of two units along the x-axis.
A-->
i("builtin:cube")
t(2,0,0)
r(0,30,0)
Then a rotation of 30 degrees around the y-axis.

A-->
i("builtin:cube")
t(2,0,0)
r(0,30,0)
t('2,0,0)
And another translation of 2 units along the x-axis.

Note:
translations are along the scope's x-axis, i.e. the rotation changes the
global translation direction!
the relative operator ' is used - here it does not make a difference
because scope.sx is 1
taper
Synopsis
taper(height)
Parameters
height (float)
How many units to extrude..
Tapers the shape (i.e. forms a pyramid over a polygon). The first polygon of the first mesh in the geometry asset is taken and
tapered along the face normal through the the polygon's center of gravity. The scope orientation is set in the following way:
x-axis direction is kept as much as possible (old x-axis is projected to plane orthogonal to face normal)
y-axis along the face normal (taper direction)
If height is < 0, the scope.sy attribute will be < 0 and the taper will be down-wards.
Related
extrude operation
offset operation
roofGable operation
roofHip operation
roofShed operation
Examples
The initial shape which is a lot (= geometry with 1 face).
Lot-->
taper(10)
The tapered shape.

texture
Synopsis
texture(string texturePath)
Parameters
texturePath (string)
Name of the texture file to insert. See Asset Search for information about search locations and Built-in Assets for a list
of built-in textures.
This function uses the file specified in the texturePath to texture the current shape (colormap channel).
Note: The "texture" command is the simplified version of "set(material.colormap,..).
Note: The "texture" command does not create texture coordinates!
Related
deleteUV operation
projectUV operation
rotateUV operation
scaleUV operation
Examples
brickMap = "assets/bricks.jpg"
randBuildingHeight = rand(3,20)
Lot -->
s('.75,'1,'.75)
center(xz)
extrude(y, randBuildingHeight)
comp(f){side: Facade | top: set(material.color.a, .3) Roof.}
Facade -->
# color, uv set 0
setupProjection(0, scope.xy, 5, 5)
texture(brickMap)
// = set(material.colormap,brickMap)
projectUV(0)
tileUV operation
Synopsis
tileUV(uvSet, textureWidth, textureHeight)
Parameters
uvSet (float)
Index of the uv-set (texture layer) to set up (integer number in [0,5]). The numbering corresponds to the texture layers
of the material attribute.
textureWidth (float)
The texture width in world coordinate system units (e.g. meters). Values < 0 are allowed and mirror the texture. The
operators ~ (floating) and (relative) can be used, see below.
textureHeight (float)
The texture texHeight in world coordinate system units (e.g. meters). Values < 0 are allowed and mirror the texture.
The operators ~ (floating) and (relative) can be used, see below.
The tileUV operation rescales the texture coordinates of the selected uv-set such that the uv space gets tiled with tiles of a
given width and height. The textureWidth and textureHeight parameters support usage of the floating and relative operators to
avoid complex calculations with the texture space dimension. For example, if the parameter textureWidth is set to ~20, the
projection matrix is initialized such that the surface of the current shape's geometry is exactly spanned with texture tiles of
approximately size 20 along the u direction. Or if the paramter texHeight is set to 0.5, the texture will be repeated twice along
the height.
Related
deleteUV operation
projectUV operation
rotateUV operation
scaleUV operation
texture operation
scope attribute
Examples
Street Tiling
A multi-face street shape.
Street-->
tileUV(0, ~20, '0.5)
The default texture coordinates.

Street-->
The tiled texture coordinates. The tile width (in u-

direction) is exactly 20 meters and the tile height is
exaclty 10 meters. Some tiles are cut.
Street-->
tileUV(0, ~20, '0.5)
Usage of the ~ and ' operators. The tile width is roughly

20 meters, such that the whole available space is exactly
filled, and the tile height is half of the available space
sucht that exaclty two tiles fit in.

translate operation
Synopsis
translate(mode, coordSystem, x, y, z)
Parameters
mode
(abs | rel) Absolute or relative mode. Absolute means the position is set to the given value, relative means the
translation is added.
coordSystem
(scope | pivot | object | world ) Name of the coordinate system in which the following coordinates are given.
x (float), y (float), z (float)
The coordinates define a position in the coordSystem to which the current shape's scope (scope.t ) is set if the mode is
abs or a translation vector to apply if the mode is rel .
The translate operation translates the scope. The coordinates can be defined in any coordinate system, and the translation
can either be absolute (= set to x,y,z ) or relative (= add the x,y,z vector). This operation manipulates the scope position (scope.t
attribute).
Related
convert function
r operation
t operation
rotate operation
scope attribute
Examples
Translate a shape along the world x-axis

version "2009.2"
Init-->
split(x) { '0.2 : split(z) { '0.2 : PP }* }*
PP-->
43%:
i("builtin:cube")
X
translate(rel, world, 2, 0, 0)
color("#ff0000")
X
else:
NIL
The red cubes are copies of the white cubes, translated by two units along the x-axis of the world
coordinate system (i.e. the red axis on the bottom right).
Translate a shape along the object x-axis

The red cubes are copies of the white cubes, translated by two units along the x-axis of the object coordinate system (i.e. the red
axis in the center).
version "2009.2"
Init-->
split(x) { '0.2 : split(z) { '0.2 : PP }* }*
PP-->
43%:
i("builtin:cube")
X
translate(rel, object, 2, 0, 0)
color("#ff0000")
X
else:
NIL

Synopsis
translateUV(uvSet, uOffset, vOffset)
Parameters
uvSet
attribute.
uOffset (float)
How much to translate in u direction.
vOffset (float)
How much to translate in v direction.
The translateUV operation translates the corresponding texture layer by adding uOffset and vOffset to each of its texture
coordinates.
For example, to move the texture to the right by half of the width, use translateUV(0, 0.5, 0) .
Related
deleteUV operation
projectUV operation
rotateUV operation
scaleUV operation
texture operation
trim
Synopsis
trim()
This operation applies the current shape's trim planes to the geometry of the current shape.
Related
comp (component split) operation
i operation
comp shape attribute
Synopsis
string comp.sel
string comp.index
string comp.total
The comp shape attributes give information about the last component split in the chain of the shape's predecessors.
comp.sel is a string describing the component split selector which selected the current shape (or it's predecessor, respectively) in
the last component split.
comp.index is the zero-based index into the group of shapes generated by the selector.
comp.total is the total number of shapes generated by the selector.
Related
comp operation (Component split)
initialShape attribute
Synopsis
string initialShape.name
string initialShape.startRule
float initialShape.origin.p[x|y|z]
float initialShape.origin.o[x|y|z]
The initialShape attribute contains the name and the startRule of the initial shape, as set in the inspector. It also contains the
origin of the object space (defined by a postion vector p and a set of euler angles o, relative to the world coodinate system). A
shape's pivot is relative to the initialShape.origin.
This attribute can only be read.
Related
Example
Wall --> print("initialShape.name: " + initialShape.name)

print("initialShape.startRule: " + initialShape.startRule)
Material Shape Attributes
The material shape attributes control the shading, texturing and export of the shape's geometry. CityEngine supports up to six
texture channels, where the first three (colormap, bumpmap, dirtmap) are rendered in the CityEngine viewports (all of them are
exported).
All of these attributes can be changed using the set shape operation. You can use the print operation to output the value of a
certain material attribute, eg. print(material.colormap.r).
Synopsis
Attribute Description
string material.name The name used to reference materials in the exported model files. If this attribute is not
set, the material will get the name of the shape which did the last modification.
string material.shader The shader name used for export (currently supported by Renderman RIB).
float material.color.{r|g|b|a} Diffuse color. Individual access to each color component. More details.
string material.color.rgb Diffuse color. Access to the complete color as hex-formatted string, eg. RED =
"#ff0000". More details.
float material.ambient.{r|g|b|a} Ambient color. Individual access to each color component.
float material.specular.{r|g|b} Specular color. Individual access to each color component.
float material.shininess Phong specular exponent.
string material.{colormap|...|map5} Texture file paths for the texture channels. More details.
float
material.{colormap|...|map5}.s{u|v} Per-channel texture scaling factors.
float
material.{colormap|...|map5}.t{u|v} Per-channel texture translation factors.
float Per-channel texture rotation factors. The texture is rotated around the w-axis (w is the
material.{colormap|...|map5}.rw
cross product of u and v).
Related
set operation
projectUV operation
print operation
Example
attr wallC = "#FFFFFF"

attr wallTexture = "facade/walls/wall.c.09.tif"
attr dirtTexture = "dirtmaps/dirtmap.16.tif"
...
Wall -->
i("builtin:cube") color(wallC)
set(material.colormap, wallTexture) projectUV(0)
set(material.dirtmap, dirtTexture) projectUV(2)
pivot shape attribute
Synopsis
float pivot.p[x|y|z]
float pivot.o[x|y|z]
The pivot attribute describes the shape's coordinate system and is defined by a position vector p (origin) and an orientation
vector o (axis). The orientation vector is encoded as an ordered rotation in degrees around the x , y and z axis. Both vectors are in
object coordinates, relative to the initialShape.origin.
Like the CityEngine's world coordinate system, the pivot describes a right-hand coordinate system.
Related
comp operation
extrude operation
offset operation
roofGable operation
roofHip operation
roofShed operation
set operation
setPivot operation
taper operation
initialShape attribute
scope attribute
seedian shape attribute
Synopsis
float seedian
The seedian shape attribute controls the seed of the random number generator. It can both be read and set.
Related
rand function
p function
scope shape attribute
Synopsis
float scope.t[x|y|z]
float scope.r[x|y|z]
float scope.s[x|y|z]
The scope attribute represents the oriented bounding box for the current shape in space relative to the pivot and is defined by
three vectors: the translation vector t , the rotation vector r (encoded in the same way as pivot.o ) and the size vector s .
The vector elements are addressed with the x , y and z suffixes. This attribute can be both read and written.
Related
comp operation
extrude operation
offset operation
r operation
roofGable operation
roofHip operation
roofShed operation
rotate operation
s operation
set operation
setPivot operation
t operation
taper operation
transalte operation
pivot attribute
Example
Wall --> print(scope.sx)

s(10, '1, '1)
print(scope.sx)
Wall --> set(scope.rz, 87.3)
Wall --> print(scope.ty)

t(0, 10, 0)
print(scope.ty)
split shape attribute
Synopsis
float split.index
float split.total
The split shape attribute consists of two integer numbers (represented as floats because CGA does not know an integer type)
describing the number of total elements in the last split and the index of the current shape.
This attribute can not be set. It is written during the split operation.
Related
split operation
Examples
Lot --> extrude(20) A
A --> split(y){2 : B}*
B --> case (split.index == 0) :

color("#ff0000") X
case (split.index == split.total-1) :
color("#0000ff") X
else:
X

trim shape attribute
Synopsis
bool trim.[horizontal | vertical]
The trim shape attribute consists of a two booleans. It is used to control the application of trim planes to the current shape and
its successors. Classification of the trim planes depends on the orientation of the edge which was used to define the trim plane (i.e.
the shared edge between two pre-component split faces): if the angle to the xz-plane of the pivot is less than 40 degrees, the trim
plane is horizontal, otherwise vertical.
Classification of a trim planes depends on the angle between the ''generating'' edge (pink) and the xz plane of the pivot.
Set the attribute to enable or disable the trim planes in horizontal or vertical direction.
Note: horizontal trim planes are disabled by default. To enable them, use
set(trim.horizontal, true) .
Related
comp operation
insert operation
set operation
trim operation

abs function
Synopsis
float abs(float x)
Returns
The absolute value of floating point number x .
This function calculates the absolute value of x .
Related
ceil function
floor function
rint function
acos function
Synopsis
float acos(float x)
Returns
The arc cosine of x in degrees. This value is in the range [0, 180].
If x is outside [-1,1], nan is generated.
The acos function calculates the arc cosine of x , i.e. the value whose cosine is x .
Related
asin function
atan function
atan2 function
cos function
sin function
tan function
asin function
Synopsis
float asin(float x)
Returns
The arc sine of x in degrees. This value is in the range [-90, 90].
If x is outside [-1,1], nan is generated.
The asin function calculates the arc sine of x , i.e. the value whose sine is x .
Related
acos function
atan function
atan2 function
cos function
sin function
tan function
atan function
Synopsis
float atan(float x)
Returns
The arc tangent of x in degrees. This value is in the range [-90, 90].
The atan function calculates the arc tangent of x , i.e. the value whose tangent is x .
Related
acos function
asin function
cos function
sin function
tan function
atan2 function
Synopsis
float atan2(float y, float x)
Returns
The principal arc tangent of y/x, in the interval [-180, 180] degrees.
The atan2 function calculates the principal value of the arc tangent of y/x, using the signs of both arguments to determine the
quadrant of the return value.
Related
acos function
asin function
atan function
cos function
sin function
tan function
ceil function
Synopsis
float ceil(float value)
Returns
The rounded integer value. If value is integral, value is returned.
This function rounds value up to the nearest integer.
Related
abs function
floor function
rint function
cos function
Synopsis
float cos(float x)
Returns
The cosine of x , i.e. a value in [-1, 1].
The cos function calculates the cosine of x , where x is given in degrees.
Related
acos function
asin function
atan function
atan2 function
sin function
tan function
exp function
Synopsis
float exp(float x)
Returns
The base-e exponential function of x ; this is the e number raised to the power x .
The exp function calculates the exponential value of x .
Related
pow function
ln function
floor function
Synopsis
float floor(float x)
Returns
The rounded integer value. If x is integral, x is returned.
This function rounds x down to the nearest integer.
Related
abs function
ceil function
rint function
isinf ("is infinite")
Synopsis
bool isinf(float value)
Returns
true if value is infinite, false otherwise
This function checks if value is an infinite value.
Related
isNan function
Examples
example.1
isinf(1/0)
# result = true
example.2
isInf(ln(0))
# result = true

isnan ("is not a number")
Synopsis
bool isnan(float value)
Returns
true if value is not a number, false otherwise.
This function checks if value is not a number.
Related
isinf function
Examples
example.1
isnan(1)
# result = false
example.2
isnan(ln(-1))
# result = true
example.3
isnan(float("a"))
# result = true

ln function
Synopsis
float ln(float x)
Returns
Natural logarithm of x .
The ln function calculates the natural logarithm of x .

The natural logarithm is the base-e logarithm, the inverse of the natural exponential function (exp). For base-10 logarithms, use the
function log10 .
Related
exp function
log10 function
pow function
log10 function
Synopsis
float log10(float x)
Returns
Base-10 logarithm of x .
The log10 function calculates the base-10 logarithm of x .
Related
exp function
ln function
pow function
pow function
Synopsis
float pow(float base, exponent)
Returns
Returns base raised to the power exponent.
The pow function calculates the result of raising base to the power exponent.
Related
exp function
ln function
rint function
Synopsis
float rint(float x)
Returns
The rounded integer value if x . If x is integral, x is returned.
These function rounds x to the nearest integer.
Related
abs function
ceil function
floor function
sin function
Synopsis
float sin(float x)
Returns
The sine of x , i.e. a value in [-1, 1].
The sine function calculates the sine of x , where x is given in degrees.
Related
acos function
asin function
atan function
atan2 function
cos function
tan function
sqrt function
Synopsis
float sqrt(float x)
Returns
The non-negative square root of x .
If x is negative, nan is generated.
The sqrt function calculates the square root of x .
Related
tan function
Synopsis
float tan(float x)
Returns
The tangent of x .
The tan function calculates the tangent of x , where x is given in degrees.
Related
acos function
asin function
atan function
atan2 function
cos function
sin function
p function
Synopsis
bool p(float prob)
Parameters
prob
Probablity for true, in [0, 1].
Returns
true or false , depending on prob and the current shape's seedian . if prob < 0 false is returned, and if prob > 1 true is returned.
This function returns true with probablity prob or false with probability (1 - prob).
Related
rand function
seedian attribute
rand function
Synopsis
float rand()
float rand(float max)
float rand(float min, float max)
Returns
A random value in [min, max]. The value depends on the current shape's seedian .
This function returns a random value in the selected range. Defaults are 0 for min and 1 for max.
Related
p function
seedian attribute
bool
Synopsis
bool bool(string value)
bool bool(float value)
bool bool(bool value)
Returns
A boolean value calculated from value .
This function converts value to the corresponding boolean value. Float values are false if they are equal to 0, true otherwise.
Strings are false if equal to "f", "false", "0", 0.0" etc, true otherwise.
Related
str function
float function
Examples
example.1
bool(1)
# result = true
example.2
bool(0)
# result = false
example.3
bool("1")
# result = true
example.4
bool(6.66)
# result = true
example.5
bool("false")
# result = false
example.6
bool("f")
# result = false
example.7
bool("true")
# result = true
example.8
bool("beneath the remains")
# result = true
example.9
bool(11.5 == 0)
# result = false

float
Synopsis
float float(string value)
float float(float value)
float float(bool value)
Returns
Float value calculated from value .
This function converts value to the corresponding float value.
Related
str function
bool function
Examples
example.1
float("0.5")
# result = 0.5
example.2
float(true)
# result = 1
example.3
float("001.5")
# result = 1.5
example.4
float(1/0)
# result = 1.#INF00
sel
Synopsis
float sel(string selstring)
Returns
Seelector with the value of inputstring .
This conversion function allows to cast the inputstring to a selector.

str
Synopsis
string str(string value)
string str(float value)
string str(bool value)
Returns
String calculated from value .
This function converts value to the corresponding string value.
Related
float function
bool function
Examples
example.1
str(1.69)
# result = "1.69"
example.2
str(1.69 - 69/100)
# result = "1"
example.3
str(001)
# result = "1"
example.4
str(true)
# result = "true"

count
Synopsis
float count(string inputString, string matchString)
Returns
Number of matches of matchString in inputString .
This function returns the number of matches of the matchString in the inputString .
Related
find function
len function
substring function
Examples
example.1
count("cityengine", "e")
# result = 2
example.2
count("cityengine rocks my world; cityengine should rock yours too", "cityengine")
# result = 2
find
Synopsis
float find(string inputString, string matchString, float n)
Returns
Index of n th occurrence of matchString in inputString .
This function returns the index of the of the n th occurrence of the matchString in the inputString .
Note: Index n is 0-based.
Related
count function
len function
substring function
Examples
example.1
find("CE_Zero CE_One CE_Two", "CE", 0)
# result = 0
example.2
find("CE_Zero CE_One CE_Two", "CE", 1)
# result = 8
example.3
find("cityengine rocks my world; cityengine should rock yours too", "cityengine", 0)
# result = 0
example.4
find("cityengine rocks my world; cityengine should rock yours too", "cityengine", 1)
# result = 27
example.5
find("CE_Zero CE_One CE_Two", "asdf", 1)
# result = -1
# no match found.
len
Synopsis
float len(string inputstring)
Returns
Length of inputstring .
This function returns the number of characters of the inputstring .
Related
count function
find function
substring function
Examples
example.1
len("cityengine")
# result = 10
example.2
len("abc")
# result = 3

subString
Synopsis
string subString(string inputString, float startPos, float endPos)
Returns
Substring of inputString , extracted between indices startPos and endPos (endPos excluded).
This function returns a substring of the of the inputString , starting at the index startPos and ending WITHOUT the
character at index endPos . (endPos excluded)
Note: The indices startPos and endPos are 0-based.
Related
count function
find function
len function
Examples
example.1
subString("0123456789", 0, 5)
# result = "01234"
example.2
subString("0123456789", 2, 5)
# result = "234"
example.3
subString("0123456789", -20, 5) # startPos < 0
# result = "01234"
example.4
subString("0123456789", 0, 20) # endPos >= len(inputString)
# result = "0123456789"
example.5
subString("0123456789", 5, 0) # startPos >= endPos
# result = ""
geometry.area function
Synopsis
float geometry.area()
float geometry.area(areaSelector)
Parameters
areaSelector
Selector for the faces to include in the area calculation. Valid selectors are:
surface (default), all,
back, bottom, front, top, left, right, side,
object.back,object.bottom,object.top,object.left,object.right,object.side,
world.north,world.south,world.west,world.east,world.up,world.down,world.side,
Returns
Surface area of the current shape's geometry, depending on the provided area selector.
The surface area of the geometry is the sum of the area of all its faces.
Related
geometry.volume function
geometry.du/dv functions
Synopsis
float geometry.du(float uvSet, surfaceParameterization)
float geometry.dv(float uvSet, surfaceParameterization)
Parameters
uvSet
attribute.
surfaceParameterization (selstr)
The surface parameter space: uvSpace or unitSpace. While uvSpace selects the actual texture coordinates (typically in
the range [0,1]), unitSpace calculates the geometry-dependent surface stretch along the u- or v- axis and calculates an
approximation in world coordinate units (e.g. meters).
Returns
The range (i.e. max - min) spanned by the u- or the v-coordinate, respectively, of the selected uvset.
Related
split operation
geometry.isConcave function
Synopsis
bool geometry.isConcave()
Returns
true if the geometry contains at least one concave face, false otherwise.
Related
geometry.isRectangular function
geometry.isPlanar function
Synopsis
bool geometry.isPlanar(float tolerance)
Parameters
tolerance
The tolerance in degrees for deciding if an face is planar or not. The face normal is compared to the edges'
crossproduct (''local normal'') at every vertex; if the angle between a ''local normal'' and the face normal is larger than
the tolerance the face is non-planar. A reasonable value is 0.25 degrees.
Returns
true if all faces of the geometry are planar (within tolerance, false otherwise.
Related
Synopsis
bool geometry.isRectangular(float tolerance)
Parameters
tolerance
The tolerance in degrees for deciding if an angle is a right one or not.
Returns
true if all faces of the current shape's geometry consist of 4 vertices and contain only right angles, false otherwise. Angles in the
range [90-tolerance, 90+tolerance] are considered to be "right".
Related
geometry.nEdges function
Synopsis
float geometry.nEdges()
Returns
The (integral) number of edges of the current shape's geometry.
Related
geometry.nFaces function
geometry.nVertices function
Synopsis
float geometry.nFaces()
Returns
The (integral) number of faces of the current shape's geometry.
Related
Synopsis
float geometry.nVertices()
Returns
The (integral) number of vertices of the current shape's geometry.
Related
geometry.volume function
Synopsis
float geometry.volume()
Returns
Volume of the current shape's geometry.
Related
geometry.area function
fileExists function
Synopsis
bool fileExists(string fileName)
Returns
true if file fileName exists, false otherwise.
The fileExists function checks whether the file fileName exists in the workspace. The same search order as for asset
insertion and texture lookups is used.
Related
Asset search
fileSearch function
Synopsis
string fileSearch(string searchQuery)
Parameters
searchQuery
Search query to apply on list of all files in the workspace. See below for details.
Returns
A string list with all files in the workspace matching the searchQuery . Each entry is terminated with a ";"
The fileSearch function lists all files in the workspace and applies the searchQuery to filter out the results.
Search Queries
The CityEngine features advanced search queries supporting wildcards, regular expressions and file properties such as filetype. All
files in the workspace are filtered with the query and the absolute workspace path is returned. Whitespace means AND.
Wildcards
The common wildcards characters '*' (asterisk character) and '?' (question mark) are supported. The asterisk substitutes for any
zero or more characters, and the question mark substitutes for any one character.
Regular Expressions
Regular expressions allow for complex string patterns descriptions. A comprehensive introduction to regular expressions is out of
scope for this manual, please refer to other sources such as Wikipedia or the specifiaction from the Open Group.
Regular expressions start with '$'.
File Properties
Following file properties can be querried:
Name
Ext
Project
Path
Examples
In the following examples, we use a basic workspace with just one project and a few files:
Example 1: Wildcards
print(fileSearch("*.png"))
# result = "/MyProject/assets/textures/1.png;/MyProject/assets/textures/2.png;
/MyProject/assets/textures/4.png;/MyProject/assets/tower.png;"
print(fileSearch("?.png"))
/MyProject/assets/textures/4.png;"
print(fileSearch("*/textures/*"))
/MyProject/assets/textures/4.png;"
Example 4: Regular Expression to select specific characters

print(fileSearch("$[12].png"))
# result = "/MyProject/assets/textures/1.png;/MyProject/assets/textures/2.png;"
Example 5: Regular Expression to select a range of characters

print(fileSearch("$[2-5].png"))
# result = "/MyProject/assets/textures/2.png;/MyProject/assets/textures/4.png;"
Example 6: File Properties

print(fileSearch("Name=1.png"))
# result = "/MyProject/assets/textures/1.png;"
Example 7: File Properties

print(fileSearch("Project=MyProject Ext=obj"))
# result = "/MyProject/assets/tower.obj;"

assetInfo
Synopsis
float assetInfo(string assetName,attributeSelector)
Parameters
assetName
Input asset.
attributeSelector
Specified asset dimension or translation. Supported values are:
sx , sy , sz , tx , ty , tz
Returns
Returns asset sizes or translation.
This function returns the sizes or translations of the asset defined in the assetName, depending on the specified
attributeSelector .
Examples
Note.1: The translation values are calculated by the CityEngine based on the corner of the asset's bounding box, by using the
corner with the lowest possible x, y and z coordinates (XYZmin).
Note.2: Note that any specific 3d transformations (in this example maya's translations X = 0.6, Y = 0.7, Z = 0.8) are not to be
confused accidentally with the translations the CityEngine computes.
CGA code:
print(assetInfo(assets/unitCube.obj, sx))
print(assetInfo(assets/unitCube.obj, sy))
print(assetInfo(assets/unitCube.obj, sz))
print(assetInfo(assets/unitCube.obj, tx))
print(assetInfo(assets/unitCube.obj, ty))
print(assetInfo(assets/unitCube.obj, tz))
# results =
# 0.2
# 0.3
# 0.4
# 0.5
# 0.55
# 0.6
assetsSortRatio function
Synopsis
string assetsSortRatio(string fileList, axisSelectorRatio)
Parameters
fileList
String list with geometry files, seperated with ";" (also after the last entry).
axisSelectorRatio (keyword)
Selector which defines which scope axes ratio is used as a reference. Valid values are (xy | xz | yz | xyz ).
Returns
A string list with all files in the input fileList, sorted in order how good they match the reference ratio (first is best, last is worst).
Looks at all geometry files in the input fileList and sorts them depending on their ratio relative to the ratio of the two scope
axes defined by axisSelectorRatio .
Related
imageInfo function
imagesSortRatio function
assetsSortSize function
Synopsis
string assetsSortSize(string fileList, selstring axisSelectorSize, float maxScaleError)
Parameters
fileList
String with geometry files, seperated with ";" (also after the last entry).
axisSelectorSize
Selector which defines which scope axes ratio is used as a reference. Valid values are (x | y | z | xy | xz | yz |
xyz ).
maxScaleError
Float value to control file selection. If it is 0 all input files are returned, sorted depending on their size. If the value is >
0, only a subset of the input files is returned: 0.1 means that maximum +-10% scaling is allowed.
Returns
A string list with all or a subset of the files in the input fileList, sorted in order how good they match the reference size (first is
best, last is worst). The maxScaleError parameter can be used to only take the geometry assets matching a certain size range.
Looks at all geometry files in the input fileList and sorts them depending on their size relative to the rsize of the scope axes
defined by maxScaleError.
Related
imageInfo function
imageInfo
Synopsis
float imageInfo(string fileName,attributeSelectorXY)
Parameters
fileName
Input file texture.
attributeSelectorXY
Specified texture dimension. Supported values are:
sx ("width"), sy ("height")
Returns
Return the image resolution.
This function returns the image resolution of the texture defined in the fileName, depending on the specified
attributeSelectorXY.
Examples
example.1
imageInfo(myTexture.jpg, sy))
# result = 1024 (height of the texture in pixels)
example.2
imageInfo(myTexture.jpg, sx))
# result = 512(width of the texture in pixels)
Synopsis
string imagesSortRatio(string fileList, axisSelector)
Parameters
fileList
String with image files, seperated with ";" (also after the last entry).
axisSelector (keyword)
Selector which defines which scope axes ratio is used as a reference. Valid values are (xy | xz | yx | yz | zx |
zy ).
Returns
A string list with all files in the input fileList, sorted in order how good they match the reference ratio (first is best, last is worst).
Looks at all image files in the input fileList and sorts them depending on their ratio relative to the ratio of the two scope axes
defined by axisSelector .
Related
imageInfo function
assetsSortRatio function
inside / overlaps / touches functions (occlusion queries)
Synopsis
bool inside()
bool inside(target-selector)
bool overlaps()
bool overlaps(target-selector)
bool touches()
bool touches(target-selector)
Parameters
target-selector
(all | intra | inter ) Target selector for the query. intra just checks against shapes in the same shape tree, inter
just checks against shapes in other shape trees (i.e. neighboring models of different initial shapes) and all checks
both. If no selector is given, all is used.
Returns
true if the geometry of the current shape lies fully inside, overlaps, or touches the geometry of another shape, respectively.
An occlusion query tests for intersections between shapes. There are four different boolean functions available to examine
the spatial context of the geometry of the current shape:
inside(selector) returns true if the geometry of the current shape is completely inside one of the shapes specified
with selector.
overlaps(selector) returns true if the geometry of the current shape volumetrically overlaps one of the specified
shapes.
touches(selector) returns true if the geometry of the current shape overlaps or touches the surface of one of the
specified shapes.
The functions are typically applied in the conditional part of a rule. A visual definition of the four occlusion functions is given in the
figure below.
Table with occlusion query functions and their results for the five configurations between two 2D polygons; the polygon
configurations extend naturally to (closed) 3D surfaces.
For all functions, the parameter selector determines what the current geometry is tested against and can either be all (default),
intra, inter, or a specific shape symbol. Thus, the current geometry can be tested against geometries of shapes in both the same
model (intra-occlusion i.e. any shape in the current shape-tree) and neighboring models (inter-occlusion i.e. whole shape-trees
generated by other neighboring initial shapes). In any case, tests can only be performed against geometries which form a closed
surface (i.e. a waterproof mesh which has no boundary edges), other geometries are ignored.
Let us look at a concrete example. The picture below shows a building model. First the rules generated an U-shaped mass model
by using the subdivision split operation. As a consequence, the geometries of the side wings touch the geometry of the main block
and unrealistically intersected windows are generated.
Left: No occlusion queries are used. Center: Occluded windows are colored red. Right: In the final model, occluded
windows are dropped.
The rule which constructs the windows looks like this:

WindowOpening--> Sill s('1,'1,windowSetback) t(0,0,'-1) [ i(openbox) Wall ] Window
The rule first invokes the generation of a window sill, then sets the size of the scope to the depth of the window setback and
translates the scope accordingly. Afterwards the openbox asset is inserted to model the wall on the side of the window opening.
Finally the actual Window generation is invoked.
To make this rule react to the above mentioned occlusions, we just have to add a simple touches() condition:
WindowOpening-->
case touches() : Wall
else : Sill s('1,'1,windowSetback) t(0,0,'-1) [ i(openbox) Wall ] Window
Now, in case the geometry of the WindowOpening shape, which is a rectangular polygon generated by the typical facade split
rules, touches another shape's geometry, the rule just invokes the Wall rule and does not create a window. Otherwise the rule is
applied as before. The above figure shows the resulting building model on the right.
Note that the default selector (all) has been used in the applied occlusion function. In the following the different types of occlusions
i.e. selectors are described in more detail.
Intra-occlusion: In case the selector is set to intra, the geometry of the current shape is tested against a practical selection of
volumetric geometries generated with the ruleset. The evaluation of intra-occlusion queries is a two-pass process:
1. The whole model is generated with all intra-occlusion queries evaluating to false, resulting in the so-called ghost shape
tree.
2. The derivation is re-started, this time all intra-occlusion queries are evaluated by testing against the geometries of the
following shapes in the ghost shape tree (note that only shapes with volumetric geometries which are over the user-
defined volume threshold are considered):
Leaf shapes which are not children of the current shape.
Shapes where a component split has been applied and which are neither parents nor children of the current
shape.
The pre-component split shapes are taken as occlusion geometries since this operation represent typically the
transition from mass to surface, and furthermore consists of simple geometry which can be tested efficiently against
occlusion. The current shape's predecessors and successors are not tested against, since they most likely occlude the
current shape due to the top-down grammar modeling approach.
This algorithm does produce only partially correct results since the corresponding ghost shape tree should be updated as
soon as an occlusion query returns true. However, he described method proved to be completely satisfying in all applied
practical use case scenarios.
Inter-occlusion: In case the selector is set to inter, the geometry of the current shape is tested against volumetric geometries
generated on neighboring initial shapes. Therefore the initial shapes within a user-defined distance to the intial shape's bounding
box are taken into account (the default distance is 20, see the settings in the Occlusion group in the Grammarcore preferences).
The evaluation of inter-occlusion on a set of initial shapes works as follows:
1. Find all initial shapes within the user-defined radius.
2. All corresponding models are generated with all inter-occlusion queries evaluating to false, resulting in the so-called
ghost models. A ghost model consists of the geometries of the following shapes (and which are over the user-defined
volume threshold):
Leaf shapes.
Shapes where a component split has been applied.
3. The derivation is re-started, this time all inter-occlusion queries are evaluated against the geometries of the ghost
models except the one which belongs to the current initial shape.
Full-occlusion: In case the selector is set to all, first the intra-occlusion is evaluated and, if true, returned. Otherwise the inter-
occlusion is evaluated in addition and its result returned.
Examples
Intra occlusion
Init --> extrude(15)

split(x) { ~5 : Step }*
Step --> s('1, '0.7 * (split.index + 1), '1)

comp(f) { side: Facade | top: X. }
Facade --> split(y) { 4 : Floor }*
Floor --> case touches(intra):

color("#ff0000") X
else:
X
This example demonstrates the result of the touches() occlusion query on shapes
of one shape tree (intra occlusion).

convert function
Synopsis
float convert(coordSelector, fromSysSelector, toSysSelector, typeSelector, x, y, z)
Parameters
coordSelector
(x | y | z ) Coordinate component selector.
fromSysSelector
(scope | pivot | object | world ) Selector for coordinate system from which to convert.
toSysSelector
(scope | pivot | object | world ) Selector for coordinate system to which to convert.
typeSelector
(pos | orient ) Selector to choose interpretation of the x, y, z - triple as coordinates or angles.
x (float), y (float), z (float)
Position (coordinates) / orientation (angles in degrees) in the fromSystem to convert to the toSystem.
Returns
The selected coordinate component of the tuple (x, y, z), convertet from the fromSys coordinate system to the toSys coordinate
system. The tuple can either describe angles or a position.
The convert function converts positions and orientations between different coordinate systems.
Related
rotate operation
translate operation
Examples
Using convert() to find the position and orientation of the scope origin in world and pivot
coordinates as well as the highest point of the scope in world coordinates
version "2009.2"
Init-->
extrude(3)
t('0.2, 0, '0.7)
s('0.5, '1, '0.5)
r(-10, 70, 0)
print("pos. of scopeOrigin in world coords " +

convert(x, scope, world, pos, 0, 0, 0) + ", " +
convert(y, scope, world, pos, 0, 0, 0) + ", " +
convert(z, scope, world, pos, 0, 0, 0) )
print("orient. of scopeOrigin rel. to world axes " +
convert(x, scope, world, orient, 0, 0, 0) + ", " +
convert(y, scope, world, orient, 0, 0, 0) + ", " +
convert(z, scope, world, orient, 0, 0, 0) )
print("pos. of scopeOrigin in pivot coords " +
convert(x, scope, pivot, pos, 0, 0, 0) + ", " +
convert(y, scope, pivot, pos, 0, 0, 0) + ", " +
convert(z, scope, pivot, pos, 0, 0, 0) )
print("highest point in world coords " +
convert(x, scope, world, pos, scope.sx, scope.sy, scope.sz)
+ ", " +
convert(y, scope, world, pos, scope.sx, scope.sy, scope.sz)
+ ", " +
convert(z, scope, world, pos, scope.sx, scope.sy, scope.sz) )
The output of the cga code above in the scene on the left is:
Boolean Operations
Operator Name Example
! logical negation operator case(!(f(x))
|| logical OR operator case(a || b || f(x))
&& logical AND operator case(a && f(x))
== equality operator case(a == b)
!= inequality operator case(a != b)
Float Operations
- unary minus operator a = -b
- binary minus operator a=b-c
+ plus operator a=c+b
* multiply operator x = y*f(x)
/ division operator x=4/d
% modulus operator (remainder) a = b % 10
Float Comparison Operators

Name Example
< less than operator case(a < b)
<= less than or equal operator case(a <= b)
> greater than operator case(a > b)
>= greater than or equal operator case(a >= b)
String Operations
+ string concatenate a = "City" + "Engine"
+ string-float concatenate a = "Rule:" + 1
a = 1 + "th Rule"
String Comparison Operators

Name Example
< less than operator case(a < b)
<= less than or equal operator case(a <= b)
> greater than operator case(a > b)
>= greater than or equal operator case(a >= b)

attr
Synopsis
attr id = expression
A new attribute can be introduced by "attr" and is evaluated the first time it is encountered in a rule or expression. As in "const",
attributes are evaluated only once per generation and rule file. The values of attributes can be externally changed trough the
inspector or by a map. See also "Attributes"
Example
Defining an attribute with attr

attr height = 250 // define an attribute "height"
Lot-->extrude(height) A.

const
Synopsis
const id = expression
A new constant can be introduced by "const" and is evaluated the first time it is encountered in a rule or expression. As in "attr",
constant expressions are evaluated only once per generation and rule file. The values of constants cannot be externally changed
trough the inspector or by a map. Constant expressions do not appear in the inspector.
Example
Defining a constant with const

const height = 250 // define a constant "height"
Lot-->extrude(height) A.

import
Synopsis
import id : "file.cga"
Rules from an existing rule file can be imported by a rule file through "import". Importing a rule file makes all rules of the
imported rule file available prefixed by "id". In contrast to rules, attributes of an imported rule file are not prefixed and will be
overridden by the corresponding attribute of the importing rule file.
Example
Combining to facades with a structure

# -- facade1.cga
actualFloorHeight = scope.sy/rint(scope.sy/4)
actualTileWidth = scope.sx/rint(scope.sx/4)
Facade -->
setupUV(0, 8*actualTileWidth, 8*actualFloorHeight)
set(material.colormap, "f1.tif")
bakeUV(0)
# -- facade2.cga
Facade -->
bakeUV(0)
# -- structure.cga
// the attribute height will be overridden by the

// attribute height from "main.cga" if this rule
// file is included. Thus if this rule file is
// used standalone, the buildings will be of height
// 100, if this rule file is included by "main.cga",
// the buildings will be of height 200.
attr height = 100
Lot-->extrude(height) Mass
Mass-->comp(f){ side: Facade | top: Roof }

# -- main.cga
// define an attribute "height", potentially

// overriding the same attribute in imported
// rule files.
attr height = 200
// import facades
import f1 : "facade1.cga"
// import structure
import st : "structure.cga"
Lot-->
// reference rule "Lot" in structure.cga
st.Lot
// define rule "Facade" for structure.cga

st.Facade-->
// reference rule "Facade" in facade1.cga
50% : f1.Facade
else : f2.Facade

version
Synopsis
version version-string
Parameters
version-string
CGA version for which this rule file is written. The CGA version always corresponds to the City Engine version, e.g.
City Engine 2009.2 has CGA version "2009.2".
The version cga keyword is used to define the cga version for which the rules are written. This permits detection of potential
incompatibilities; warnings about potential incompatibilities are written to the log.
Such incompabilities come in two sorts: new features and changes to exisiting features. While the former are relatively
unproblematic, the latter are generally not desired and only occur when an obvious bug or other shortcoming needs to be
corrected. See CGA Changelog for an overview of the changes between CGA versions.
The version statement has to be the first code line of a cga file. If there is no version statement, the version defaults to
"2009.1".
Related
CGA Changelog

findFirst
Synopsis
float findFirst(string inputString, string matchString)
Returns
First occurrence (position/index) of matchString in the inputString .
This function returns the index of the first occurrence of the matchString in the inputString .
Note: Indices are 0 - based.
Related
findLast function
getPrefix function
getRange function
getSuffix function
replace function
Examples
findFirst("rule your city with cityengine","city")

# result = 10
# "rule your " = 10 characters; then the match string starts

findLast
Synopsis
float findLast(string inputString, string matchString)
Returns
Last occurrence (position/index) of matchString in the inputString
This function returns the index of the last occurrence of the match string in the input string
Related
findFirst function
getPrefix function
getRange function
getSuffix function
replace function
Examples
findLast("rule your city with cityengine","city")

# result = 20
# "rule your city with " = 20 characters; then the match string starts

getPrefix
Synopsis
string getPrefix(string inputString, string matchString)
Returns
Extract inputString up to first occurrence of matchString .
This function extracts the inputString from the start of the inputString up to the beginning of the matchString .
Related
findFirst function
findLast function
getRange function
getSuffix function
replace function
Examples
example.1
getPrefix("rule your city with cityengine","city")
# result = "rule your "
example.2
getPrefix("myTexture.has.prefix.jpg",".")
# result = "myTexture"
getRange
Synopsis
string getRange(string inputString, string lmatchString, string rmatchString)
Returns
Extract inputString between end of lmatchString and begin of rmatchString .
This function extracts the inputString from the end of the lmatchString up to the beginning of the rmatchString .
Note: overlapping l+r matchStrings return an empty string (see example.4)
Related
findFirst function
findLast function
getPrefix function
getSuffix function
replace function
Examples
example.1
getRange("rule your city with cityengine","y","city")
# result = "our city with "
example.2
getRange("myTexture.hasName.001.jpg","hasName.",".jpg")
# result = "001"
example.3
getRange("myTexture.hasName.001.jpg",".",".")
# result = "hasName.001"
example.4
getRange("CityEngine","CityEn","tyEngine")
# result = ""
getSuffix
Synopsis
string getSuffix(string inputString, string matchString)
Returns
Extract rest of inputString after last occurrence of matchString .
This function extracts the rest of the inputString after the last occurrence of the matchString .
Related
findFirst function
findLast function
getPrefix function
getRange function
replace function
Examples
getSuffix("rule your city with cityengine","city")

# result = "engine"

replace
Synopsis
string replace(string inputString, string oldString, string newString)
Returns
Copy of inputString with oldString replaced by newString.
This function replaces all occurences of the oldString inside the inputString with the newString.
Related
findFirst function
findLast function
getPrefix function
getRange function
getSuffix function
Examples
example.1
replace("rule your city with cityengine","your city","designs")
# result = "rule designs with cityengine"
example.2
replace("myTexture.#.jpg","#","1")
# result = "myTexture.1.jpg"
# this example is e.g. useful for index-based texturing
listAdd
Synopsis
string listAdd(string stringList, string item)
Returns
Append item to stringList .
This function appends the item to the stringList .
Note: Stringlists are a series of strings stored inside one string. The elements are separated by a semicolon (";"). The data
type is "string", thus it is not any real type of array as used in other scripting languages.
Related
listClean function
listFirst function
listIndex function
listItem function
listLast function
listRandom function
listRange function
listSize function
Examples
example.1
listAdd("rule;your;","city")
# result = "rule;your;city;"
example.2
listAdd("rule;your;","city;")
listClean
Synopsis
stringList listClean(string stringList)
Returns
Returns cleaned stringList .
This function checks if the stringList has the correct ";" at the end.
Related
listAdd function
listFirst function
listIndex function
listItem function
listLast function
listRandom function
listRange function
listSize function
Examples
example.1
listClean("cityengine;rules")
# result = "cityengine;rules;"
example.2
listClean("cityengine;rules;")

listFirst
Synopsis
string listFirst(string stringList)
Returns
Returns first item in stringList .
This function returns the first item in the stringList .
Related
listAdd function
listClean function
listIndex function
listItem function
listLast function
listRandom function
listRange function
listSize function
Examples
example.1
listFirst("rule;your;city;")
# result = "rule"
example.2
listFirst(fileSearch("/myProject/assets/image*.jpg"))
# result = the image from that directory with the lowest index
listIndex
Synopsis
float listIndex(string stringList, string item)
Returns
Returns index of first occurrence of item.
This function returns the index of the first occurrence of the item in the stringList .
Note.1: Indices are 0 - based.
Note.2: Stringlists are a series of strings stored inside one string. The elements are separated by a semicolon (";"). The data
Related
listAdd function
listClean function
listFirst function
listItem function
listLast function
listRandom function
listRange function
listSize function
Examples
example.1
listIndex("rule;your;city;","city")
# result = 2
example.2
listIndex("texture_1.jpg;texture_2.jpg;texture_3.jpg;","texture_1.jpg")
# result = 0
listItem
Synopsis
string listItem(string stringList, float index)
Returns
Returns item at the given index .
This function returns the item of the stringList at the given index .
Related
listAdd function
listClean function
listFirst function
listIndex function
listLast function
listRandom function
listRange function
listSize function
Examples
example.1
listItem("rule;your;city;",2)
# result = "city"
example.2
listItem("texture_1.jpg;texture_2.jpg;texture_3.jpg;",0)
# result = "texture_1.jpg"
listLast
Synopsis
string listLast(string stringList)
Returns
Returns last item in stringList .
This function returns the last item in the stringList .
Related
listAdd function
listClean function
listFirst function
listIndex function
listItem function
listRandom function
listRange function
listSize function
Examples
example.1
listLast("rule;your;city;")
# result = "city"
example.2
listLast(fileSearch("myProject/assets/image*.jpg"))
# result = the image from that directory with the highest index
listRandom
Synopsis
string listRandom(string stringList)
Returns
Returns random item of stringList .
This function returns a random item of the stringList .
Note.1: Getting a random element often is directly combined with a wildcard search. See example.2
Related
listAdd function
listClean function
listFirst function
listIndex function
listItem function
listLast function
listRange function
listSize function
Examples
example.1
listRandom("rule;your;city;")
# result = "rule" or "your" or "city"
example.2
listRandom(fileSearch("/myProject/assets/*.jpg"))
# result = a random .jpg image from that directory.
example.3
listRandom(fileSearch("*.obj"))
# result = a random asset from the whole workspace.

listRange
Synopsis
stringList listRange(string stringList, float index1, float index2)
Returns
Returns items from index1 to index2 (index2 excluded).
This function returns all items in the stringList from index1 to index2 (the index2 item is not included in the resulting list).
Related
listAdd function
listClean function
listFirst function
listIndex function
listItem function
listLast function
listRandom function
listSize function
Examples
example.1
listRange("rule;your;city;with;cityengine;",0,3)
example.2
listRange("texture_1;texture_2;texture_3;texture_4;texture_5;texture_6;",2,3)
# result = "texture_3"
listSize
Synopsis
float listSize(string stringList)
Returns
Returns number of elements in stringList .
This function returns the number of elements in the stringList .
Related
listAdd function
listClean function
listFirst function
listIndex function
listItem function
listLast function
listRandom function
listRange function
Examples
example.1
listSize("cityengine;rules;")
# result = 2
example.2
listSize(fileSearch("/myProject/assets/*.jpg"))
# result = the number of .jpg files in that directory.
assetApproxRatio
Synopsis
string assetApproxRatio(string searchQuery , string axisSelector, float n)
Parameters
searchQuery
Search query to apply on list of all files in the workspace. See fileSearch for details about the syntax.
axisSelector
Selector of axes for the currect scope. Supported values are: "xy","xz","yz","xyz" .
n
Number (integer >= 1) of assets to consider (one is randomly picked out of the n best assets).
Returns
Asset with one of the best n size fits (according to axisSelector ).
This function returns one of the n best assets of the best ratio, from the file list specified in string , according to the specified
axisSelector .
Note: assetApproxRatio( string , axisSelector , 1) = assetBestRatio(string , axisSelector )
Related
assetApproxSize function
assetBestRatio function
assetBestSize function
assetFitSize function
fileBasename function
fileDirectory function
fileExtension function
fileName function
fileRandom function
imageApproxRatio function
imageBestRatio function
Examples
Inserting assets based on their approximate ratio

The goal is to insert assets from a pool, depending on their (physical) size ratio. The pool of assets is seen in the following image.
Colors are (only) used to visually emphasize the physical size ratio.
CGA examples with n = 1 and n = 3:
Note.1: Since the assets are color coded with their ratio, it is visible that "long" and "wide" Lots utilize black and pink assets,
while "square-ish" Lots utilize red and blue assets.
Note.2: Note the color variations in the next two images by using only the "best ratio" (n = 1) and "choose randomly one of
the best three ratios" (n = 3).
n = 1:
Lot -->
innerRect
alignScopeToAxes(y)
s('1,0,'1)
i(assetApproxRatio("/myProject/assets/cube_*.obj", "xz", 1))
n = 3:
Lot -->
innerRect
alignScopeToAxes(y)
s('1,0,'1)
i(assetApproxRatio("/myProject/assets/cube_*.obj", "xz", 3))
assetApproxSize
Synopsis
string assetApproxSize(string searchQuery, string axisSelector, float n)
Parameters
searchQuery
axisSelector
Selector of axes for the currect scope. Supported values are: "x","y","z","xy","xz","yz","xyz"
n
Number (integer >= 1) of possible returned result strings. (1 returned randomly out of n possibilities)
Returns
Asset with one of the best n size fits (according to axisSelector ).
This function returns one of the n best size fitting assets, from the file list specified in string , according to the specified
axisSelector .
Note: assetApproxSize(string , axisSelector , 1) = assetBestSize( string , axisSelector )
Related
assetApproxRatio function
fileName function
fileRandom function
Examples
Inserting assets based on their (physical) size

The goal is to insert assets from a pool, depending on their (physical) size. The pool of assets is seen in the following image.
Colors are (only) used to visually emphasize the size ratio.
CGA examples with n = 1, n = 2 and n = 3:
Note.1: Note the geometry variations in the next 3 images by using only the n parameter.
Note.2: Note that small parts get blue assets while large parts get red assets.
n = 1:
Lot -->
s('.9,'.9,'.9) center(xz) recursiveSplit(0)
recursiveSplit(n) -->
case scope.sx >= 1.5 && scope.sz >= 1.5:
split(x){~scope.sx/3: split(z){~scope.sz/3: recursiveSplit(n+1)}*}*
else: doInsert
doInsert -->
innerRect
alignScopeToAxes(y)
i(assetApproxSize("/myProject/assets/cube_*.obj","xz",1))
n = 2:
..
n = 3:
..
assetBestRatio
Synopsis
string assetBestRatio(string searchQuery, string axisSelector)
Parameters
searchQuery
axisSelector
Selector of axes for the currect scope. Supported values are: "xy","xz","yz","xyz"
Related
fileName function
fileRandom function
Returns
Asset (according to axisSelector ) with the best ratio.
This function returns the asset with the best fitting ratio, from the file list specified in searchQuery , according to the specified
axisSelector .
Examples
Inserting assets based on the best ratio

The goal is to insert assets from a pool, depending on their (physical) size ratio. The pool of assets is seen in the following image.
Colors are (only) used to visually emphasize the physical size ratio.
CGA example:
Note: Since the assets are color coded with their ratio, it is visible that "long" and "wide" Lots utilize black and pink assets,
while "square-ish" Lots utilize red and blue assets.
Lot -->
innerRect
alignScopeToAxes(y)
s('1,0,'1)
i(assetBestRatio("/myProject/assets/cube_*.obj", "xz"))

assetBestSize
Synopsis
string assetBestSize(string searchQuery, string axisSelector)
Parameters
searchQuery
axisSelector
Returns
Asset with the best size fit (according to axisSelector ).
This function returns the asset with the best fitting size, from the file list specified in searchQuery , according to the specified
axisSelector .
Related
fileName function
fileRandom function
Examples
Inserting assets based on their (physical) size

The goal is to insert assets from a pool, depending on their (physical) size. The pool of assets is seen in the following image.
Colors are (only) used to visually emphasize the size ratio.
Lot -->
s('.9,'.9,'.9) center(xz) recursiveSplit(0)
else: doInsert
doInsert -->
innerRect
alignScopeToAxes(y)
i(assetBestSize("/myProject/assets/cube_*.obj","xz"))
Note: Note that small parts get blue assets while large parts get red assets.
assetFitSize
Synopsis
string assetFitSize(string searchQuery, string axisSelector, float maxScaleError)
Parameters
searchQuery
axisSelector
maxScaleError
Float value to control file selection. If it is 0 all input files are returned, sorted depending on their size. If the value is >
0, only a subset of the input files is returned: 0.1 means that maximum +-10% scaling is allowed.
Returns
Random asset (according to axisSelector ) which is in the maxScaleError range.
This function returns one of the assets in the maxScaleError range, from the file list specified in searchQuery , according to
the specified axisSelector .
Related
fileName function
fileRandom function
Examples
assetFitSize("assets/*.obj","xz",0.2)
# result = "assets/chosenAsset.obj"

fileBasename
Synopsis
string fileBasename(string path)
Returns
returns file base name of given path, without directory prefix and file extension.
This function returns the file base name (without the directories or extension) of the given path.
Related
fileName function
fileRandom function
Examples
fileBasename("assets/obj/mygeometry.01.obj")
# result = "mygeometry.01"

fileDirectory
Synopsis
string fileDirectory(string path)
Returns
returns file directory of given path, without file name.
This function returns the file directory (without the file name) of the given path.
Related
fileName function
fileRandom function
Examples
fileDirectory("assets/obj/mygeometry.01.obj")
# result = "assets/obj/"

fileExtension
Synopsis
string fileExtension(string path)
Returns
returns file extension ("suffix") of given file path.
This function returns file extension ("suffix") of the given file path.
Related
fileName function
fileRandom function
Examples
fileExtension("assets/obj/mygeometry.01.obj")
# result = "obj"

fileName
Synopsis
string fileName(string path)
Returns
returns file name of given path.
This function returns the file name (without the directory part) of the given path.
Related
fileRandom function
Examples
fileName("assets/obj/mygeometry.01.obj")
# result = "mygeometry.01.obj"

fileRandom
Synopsis
string fileRandom(string searchQuery)
Parameters
searchQuery
Returns
returns random file from list specified in searchQuery .
This function returns a random file from the list specified in searchQuery .
Related
fileName function
Examples
fileRandom("assets/*.obj")
# result = any one obj file from the assets dir

imageApproxRatio
Synopsis
string imageApproxRatio(string searchQuery, string axisSelector, float n)
Parameters
searchQuery
zy ).
n
Number (integer >= 1) of textures to consider (one is randomly picked out of the n best textures).
Returns
Texture with one of the n best ratio matches (according to axisSelector ).
This function returns one of the n textures with the best ratio match, from the file list specified in searchQuery , according to
the specified combination of axes.
Note: imageApproxRatio(path, axisSelector , 1) = imageBestRatio( path, axisSelector )
Related
fileName function
fileRandom function
Examples
Setting up texturing based on the best pixel ratio

The goal is to set up the texturing, depending on the best pixel ratio of the list of desired textures. The following textures all have
different resolutions.
CGA example:
Note: Note the color variations in the next two images by using only the "best ratio" (n = 1) and "choose randomly one of the
best three ratios" (n = 3).
n = 1:
Lot --> s('.9,'.9,'.9) center(xz) recursiveSplit(0)
else: doTexturing
doTexturing -->
set(material.colormap, imageApproxRatio("/myProject/assets/textures/*.jpg", "xz",1))
setupProjection(0, scope.xz, scope.sx, -scope.sz)
projectUV(0)
n = 3:
..
set(material.colormap, imageApproxRatio("/myProject/assets/textures/*.jpg", "xz", 3))
..

imageBestRatio
Synopsis
string imageBestRatio(string searchQuery, string axisSelector)
Parameters
searchQuery
zy ).
Returns
Returns texture with best ratio match (according to axisSelector ).
This function returns the texture with the best ratio match, from the list specified in searchQuery , according to the specified
combination of axes.
Note: In case multiple files share the best ratio, a random file is returned among those
Related
fileName function
fileRandom function
Examples
Setting up texturing based on the best pixel ratio

The goal is to set up the texturing, depending on the best pixel ratio of the list of desired textures. The following textures all have
different resolutions.
CGA example:
Lot --> s('.9,'.9,'.9) center(xz) recursiveSplit(0)
else: doTexturing
doTexturing -->
set(material.colormap, imageBestRatio("/myProject/assets/textures/*.jpg", "xz"))
setupProjection(0, scope.xz, scope.sx, -scope.sz)
projectUV(0)

CGA Changelog
City Changes
Engine
version (=
CGA
version)
2010.3 new operations:
scatter operation
setback operation
shapeL operation
shapeU operation
shapeO operation
tileUV operation
new features:
comp operation: added world.xxx, object.xxx and streetSide selectors.
geometry.area() function now supports component split-style selectors to calculate area of only a subset
of the geometry's faces.
changes to existing features:
extrude and taper operation: negative heights do not change the pivot anymore but result in negative
scope size.
bugfixes:
Fixed a bug in trimming a negative sized scope.
color does not touch alpha (used to set it to 1.0).
comp operation: corrected scope selectors for negative scope sizes (e.g. front becomes back if scope.sz
is < 0).
convexify and innerRect operations: fixed a numerical problem concerning colinear vertices: remove'em
before the operations.
mirrorScope operation: fixed a bug which resulted in wrong translations.
roofShed operation: fixed vertex indices for shed roofs on multi-face shapes.
offset operation: fixed a bug in the case where no inside/border geometry was generated (due to a too
large offset) and the according selector was used.
Fixed a compiler bug: functions beginning with const or attr (eg. construction) were parsed wrongly.
2010.2 new operations:

deleteUV operation
mirror operation
rotateScope operation
trim operation
new functions:
geometry.du/dv functions
new features:
split operation now supports splits in the uv (texture coordinates) domain including support for the
"unwarped" domain (unitSpace surface parameterization).
offset operation: a new overload allows for keeping only inside or border faces.
setupProjection operation: a new overload allows for adding a translation offset to the setup scope.
extrude and taper operations now keep texture coordinates.

extrude , taper , roofGable, roofHip , roofPyramid and roofShed operations do net set the pivot anymore
and try to maintain the scope's x-axis orientation as much as possible (i.e. the scope and pivot orientation
is different now).
alignScopeToGeometry operation: negative indices are supported now (modulo, i.e. -1 is the last
face/edge; was unspecified behaviour before).
comp(e) operation: edges have now a defined index, i.e. edge 0 is always guaranteed to be the first edge
of the first face.
roofGable, roofHip and roofShed operations are now guaranteed to put first roof face on first edge of
input face in all cases and to put all roof faces on corresponding edge if current geometry consists of one
face only.
setupProjection operation: deprecated
setupProjection(uvSet, axesSelector, width<, height, uwFactor)
overload .
changed recursion detection: control shape tree width rather than active nodes
bugfixes:
Recursive functions did not compile if the arguments were not float.
replace function: did replace only the first occurrence, now replaces all occurrences.
split and trim operations:
now handle concave polygons.

now handle negative-sized scopes.
Fixed a bug in intra-occlusion (in some cases wrong pre-component-split volume was taken to check
against).
geometry.isPlanar function: in case of colinear edges nonplanarity was reported.
innerRect, convexify, roofGable, roofHip , roofPyramid operations and roofShed operations: fixed a
numerical issue.
alignScopeToGeometry operation: world.lowest selector: if all vertices had y-coordinate exactly on 0.0
result was random.
comp operation: if the "=" operator was used in conjunction with a rotated scope, the resulting shape had
wrong scope and pivot position.
center operation: did not work properly if scope was rotated.
2010.1 SR1 new functions:

sel function
SR1 changes to existing features:
fixed signature matching bug (false syntax errors, eg. with alignScopeToGeometry)
fixed wrong asset search path in imported rule files
fixed cgalib replace() issue
fixed a bug in translate(rel, object, ...) operation
fixed a bug which led to unreferenced vertices in extrude and roofXXX operations (connected to very
thin features).
fixed a bug in multi-face-extrude: in special cases some faces got deleted
new operations:
convexify operation
rotateUV operation
texture operation
new functions:
pow function
exp function
log10 function
ln function
len function
count function
find function
substring function
isnan function
isinf function
assetInfo
assetsSortRatio
assetsSortSize
count function
fileExists function
fileSearch function
find function
float function
str function
bool function
imageInfo function
new features:
CGA Utility Functions Library with utility functions for string handling, string list handling and file, assets
and image handling.
Support for reading Collada assets.
Limited support for material-per-face assets
split operation: added optional noAdjust selector to avoid scope being set to the geometry's bounding
box.
initialShape.startRule is new and replaces the deprecated initialShape.symbol.

Asset and texture search: Now the search for an inserted asset (or texture) is always relative to the rule
file and the search locations changed. No search heuristcs are applied anymore, so for instance the
asset "assets/windows/window1.obj" must be inserted as i("windows/window1.obj"); in older versions,
i("window1.obj") would have found the file (but maybe another one instead, with the same file name,
but at a different location in the workspace).
s operation: a negative size now leads to a mirrored geometry (with reversed normals) rather than to an
implicit translation. Converting rules which used negative sizes is straight-forward: use the posive value
and add a t operation, for example this cga code s('1,'1,-1.2) OpeningWall("door") Door has to be
converted to this: s('1,'1,1.2) t(0,0,-1.2) OpeningWall("door") Door
fixed reverse face and mesh order of inserted obj assets - face ids are reversed (comp split!)
initialShape.symbol attribute: the signature string (''${}'') was dropped
alignScopeToGeometry : (a) New face selectors world.lowest, largest, any . (b) New edge selectors
world.lowest, largest and new syntax (combinations of face and edge selectors and indices). (c)
Deprecated alignScopeToGeometry (upAxis, faceSelector ) and alignScopeToGeometry (upAxis, auto).
innerRect operation:(a) Now operates on each face of the geometry (instead of just the first face). (b)
Concave faces are handled (they get convexified first and the innerRect is computed on the largest
rectangle). (c) Only keeps rectangular faces if they are aligned to x-axis.
It is not possible to use the ~ operator anymore in the s, r, t operations - it did not do anything anyway.
setupProjection operators ~ and ' can now be used.
setPivot : no support anymore for "yUp" and "zUp" selectors (use xyz and yzx ).
bugfixes:
Occlusion: (a) fixed a bug which led to wrong results (b) fixed an intra-occlusion memory leak (c) fixed a
bug which could have led to inconsitencies in the exported models.
geometry.isConcave function: fixed a numerical issue which led to wrong results.
changed const expression evaluation - they are always evaluated numbers are consistent, also if
overriden by inspector value
Component split: fixed a bug which led to lost materials if asset contained more than one mesh / material
innerRect operation: fixed some numerical issues which led to wrong results.
The obj asset reader now handles negative indices (max files)
color does not touch alpha (used to set it to 1.0).
Better name clashes handling of imported rule files.
Stricter type handling, some errors which were only detected during generation before are now detected
at complie time.
split operation: in some cases (extruded geometry), texture coordinates were repeated rather than split.
2009.3 new features:

roofGable operation
roofHip operation
roofShed operation
translateUV operation (was offsetUV )
innerRect operation
projectUV operation
Component split: (1) Added ''='' operator. This Operator combines all selected components into one new
shape. (2) New selectors: border, inside and eave, hip, valley, ridge . (3) New shape attributes
comp.index, comp.total .

Support for trim-planes along concave faces. Trim planes are not infinite anymore, their extent can be
controlled in the Grammarcore preferences.
roof operation deprecated.
offsetUV operation deprecated (is now translateUV ).
setupUV, bakeUV deprecated (use setupProjection and projectUV operations instead).
extrude , roofGable, roofHip and roofShed now handle multi-face initial shapes.
inside, overlaps, touches functions: (1) added inter, intra, all selectors. (2) A special
configuration (''face is completely covered by a side of a volume'') is now included in the inside case.
New settings to control endless recursion detection: (1) limit function call depth, (2) limit nr. of active
shapes (detect shapetrees-breadth-explosion), see Grammarcore preferences.
bugfixes:
alignScopeToAxes() (only the no-selector default case) did not work properly, fixed.
Non-boolean expressions are no longer valid in case statements (led to a run-time error before).
Fixed a bug connected to usage of convert() in import ed cga files.
Using alignScopeToAxes() or alignScopeToGeometry() between setupUV() and bakeUV() resulted in
incorrect texture coordinates, fixed with new operations.
Fixed a bug in euler angle extraction which sabotaged e.g. convert().
extrude operation: fixed indexing of first face.
convert function: convert(orient, scope, world | object, ...) did not work correctly
Component split: (1) using indices on an empty selection no longer crashes. (2) interleaved edge/vertex-
comp-splits did not work (resulted in empty selection), fixed
inside, overlaps, touches functions: fixed several bugs (dislocated intersection volumes, wrong
touches results, lost inter-occluders).
2009.2 new features:

translate operation
rotate operation
offsetUV operation
scaleUV operation
initialShape.origin shape attribute
convert function
atan2 function
version keyword

object coordinate system: a shape's pivot is now relative to initialShape.origin and not relative to the
world coordinate system anymore.
extrude(axis, h) : axis selectors (x | y | z ) deprecated; new selectors (world.x | world.y |
world.z ) change pivot orientation after operation to be the same as after extrude(h) .
alignScopeToGeometry : "auto" mode: (1) if all edges are on the same y-coordinate, the longest edge is
taken and (2) fixed a bug which led to undefined behaviour in rare cases.
2009.1 and -
older
(keyword
version not
supported)

Asset and Texture Search
The search for an inserted asset (or texture) is always relative to the rule file in which the concerning operation is invoked. This is
also the case for imported rule files.
The search order is as follows:
1. if filePath is an absolute workspace path (i.e., starts with "/") then no searching is done, filePath must match a file.
2. try to resolve relative to "assets" in the project where the rule file resides.
3. try to resolve relative to project.
Examples
The standard use case is the one where geometry assets and image files are stored in the project's asset folder. The example
below shows the expanded folder structure from the Candler building example from Tutorial 9:
And below is are some excerpts from the corresponding rule file. First, some file paths are set up in the attr section; thise attributes
are then sued in the rules to insert the obj and tif files. Note that the whole path relative to the projects assets folder has to be
passed.
...
// models
attr windowAsset = "facade/windows/win.single.05.sashwindow.obj"
attr ledgeAsset = "facade/ledges/ledge.02.twopart.obj"
attr corniceAsset = "facade/ledges/ledge.05.cornice_ledge_closed.obj"
attr modillionAsset = "facade/ledges/ledge_modillion.03.for_cornice_ledge.obj"
attr windowOpeningAsset = "general/primitives/cube.nofrontnoback.notex.obj"
attr doorOpeningAsset = "general/primitives/cube.leftrighttop.inw.obj"
// textures
attr roofTexture = "roof/roof.tif"
attr wallTexture = "facade/walls/wall.c.09.tif"
attr dirtmap = "dirtmaps/dirtmap.16.tif"
attr doorTexture = "facade/doors/tiles/1_shop_glass_grey.tif"
attr shopFrameAsset = "facade/shopwindows/shopwin_frame.obj"
shopTexture(nr) = "facade/shopwindows/shopwin_0" + nr + ".tif"
windowTexture(nr) = "facade/windows/tiles/1_rollo_" + nr + "_brown.tif"
...
WindowAsset -->
set(material.colormap, windowTexture(ceil(rand(7)))) i(windowAsset)
set(material.specular.r, 0.5) set(material.specular.g, 0.5) set(material.specular.b, 0.5)
set(material.shininess, 4)
...

Built-in Assets and Textures
CGA supports a number of built-in assets which are always available:
Geometry Assets
builtin:cube - the unit cube with vertex normals and texture coordinates on all texture layers.
builtin:cube:notex - the unit cube without texture coordinates.
Textures
builtin:default - a shiny 16x16 black and white checkerboard.
builtin:uvtest.png - our standard test rexture.
Examples
Init-->
i("builtin:cube")
texture("builtin:default")
Init-->
i("builtin:cube")
User Interface
1. Window Type Overview
2. The Viewport Window
Object Selection
Cameras
Bookmarks
Keyboard Shortcut Reference
3. The File Navigator
4. The Scene Window
5. The CGA Editor
6. The Log View
7. The CGA Console
8. The CGA Problems View
9. The Progress View
10. The Inspector
11. Configuring the Windows Layout
Editors
Views
Dragging Windows
12. CityEngine Preferences
Key Strokes, Key Sequences, and Key Bindings
A 'key stroke' is the pressing of a key on the keyboard, while optionally holding down one or more of these modifier keys:
CTRL , ALT , or SHIFT . For example, holding down CTRL then pressing A produces the key stroke CTRL+A . The pressing
of the modifier keys themselves do not constitute key strokes.
A 'key sequence' is one or more key strokes. Traditionally, Emacs assigned two or three key stroke key sequences to particular
commands. For example, the normal key sequence assigned to Close All in emacs is CTRL+X CTRL+C . To enter this key
sequence, one presses the key stroke CTRL+X followed by the key stroke CTRL+C . While Eclipse supports key sequences of
arbitrary lengths, it is recommended that keyboard shortcuts be four key strokes in length (or less).
A 'key binding' is the assignment of a key sequence to a command.
Schemes
A 'scheme' is a set of bindings. CityEngine includes two schemes:

Procedural CityEngine (default)
Autodesk Maya
Autodesk Revit
Google SketchUp
McNeel Rhino
Autodesk 3ds Max
Blender
Autodesk Autocad
Graphisoft ArchiCAD
Maxon Cinema4D
Emacs (do not use)
Default (do not use)
The Procedural CityEngine scheme contains a general set of bindings, in many cases recognizable as traditional key sequences for
well known commands. For instance, CTRL+A is assigned to Select All, and CTRL+S is assigned to Save.
Choose the scheme you are most comfortable with by changing the 'Scheme' setting on the keys preference page.
Contexts
Key bindings can vary based on the current context of CityEngine.
Sometimes the active part might be a CGA shape grammar editor, for instance, where a different set of key sequence assignments
may be more appropriate than if the active part was a 3D viewport. As a specific example, typically X , Y , or Z , are assigned to
normal typing actions in a context such as CGA shape grammar editing, while X , Y , or Z is assigned to axis alignment in a 3D
viewport. This context is usually determined by the active window, but it can be influenced by the active dialog as well. If the active
window does not choose a particular context, CityEngine will set the active context to In Windows.
CityEngine includes a number of different contexts. Some examples are:
In Dialogs and Windows
In Windows (extends In Dialogs and Windows)
In Dialogs (extends In Dialogs and Windows)
Editing Text (extends In Windows)
In Viewport
In Console
NOTE: It is not recommended to promote a key binding to a context which it extends. For example, it is not recommended to move
an Editing Text key binding to the In Dialogs and Windows context. This may have unexpected results.
It is possible for some key bindings to work in dialogs. Those key bindings are assigned to the In Dialogs and Windows context.
One example of such a key binding is the key binding for "cut". It is possible to change these key bindings. For example, it is
possible to have CTRL+X as cut in dialogs, but CTRL+W as cut in windows.
Platform and Locale
Key bindings also vary by platform and locale. On Chinese locales (zh), ALT+/ is assigned to Content Assist, instead of the
usual CTRL+SPACE .
The current platform and locale is determined when CityEngine starts, and does not vary over the lifetime of a running CityEngine.
Customizing Key bindings
With multi-stroke key sequences, schemes, and contexts, there are a lot of things to keep in mind when customizing key
bindings. To make things easier, all key customization is done on the keys preference page.
In this example we want to bind CTRL+5 to the About command. By default, the keys preference page will show you all possible
key bindings. You can see the About command listed in the Help category. You can bind the command by putting focus in the
Binding text box and pressing CTRL and 5 like you would if you were executing the command.
When you type CTRL+5 you have created a binding for About. The right-most column will indicate that this is a user binding by
displaying a U . If there was a conflict with another key, this column would also display a C. The binding will be in the default
context, "In Windows". You can now use the When combo box to change the key binding context (for example, to move this binding
to "Editing Text").
If you wanted to add a second key binding to About, you can use the Copy Command button to create a second command entry for
you to bind another key to. If you want to delete a binding, you can either use the Remove Binding button or simply give focus to
the Binding text box and hit Backspace.
Conflict Resolution
There are only a finite number of simple, common key strokes available to assign to a multitude of commands. We have seen
that scheme, context, platform, and locale all partition key sequence assignments into domains where they don't conflict with one
another.
If the user sets a keybinding and creates a conflict, the conflicting bindings will be displayed in the conflicts list. This can be used to
navigate between conflicting key bindings so that they can be changed.
These types of conflicts can be resolved by explicitly assigning the key sequence to one of the commands, or remove it from the
other.
Creating a CityEngine Scene
In order to create CityEngine scenes, the same methods as for creating projects apply. For example, you may use the New
Wizard to create a new scene:
This will open the New Wizard.
In the New Wizard, select CityEngineCityEngine scene and then click Next.
If not already set, enter the name of the target project in the Project folder. You may use the Browse button to select your project
using the browser.
In the File name field, enter a name for the new scene. Do not use spaces or special characters in the project name (for example,
"MyScene" is a valid name).
Click Finish when you are done.
If you sneak a peek at the Navigator, you will see the selected project containing the newly created scene.

Shapes
CGA Shapes are different from the shapes previously mentioned in section Shapes; those shapes are so-called initial
shapes.
Shapes are the central ingredient of the cga shape grammar. In short, a shape has a name (the so-called shape symbol) and
consists of a geometry with an oriented bounding box, the so-called scope. On this page this is going to be explained in detail.
The pivot, scope and geometry attributes of a shape. Note: the scope is the oriented bounding box of the geometry.
A shape consists of:
ShapeSymbol (or Rule Name)

A shape has a name, the so-called shape symbol. The shape symbol is very important because the rule with matching name (and
number and types of parameters, see below) is going to be used to generate the shape's successors.
Parameters
Each shape can have an associated parameter list. The ordered parameter list is implicitly defined in the rule which creates the
shape. Three parameter types are supported:
bool
numeric (internally represented with double-precision float)
string
Attributes
The attributes contain the numeric and spatial description (including the geometry) of the shape. During the rule application
process, these attributes can be accessed and modified by shape operations. The following shape attributes exist:
Geometry
The geometry of a shape is an arbitrary polygonal mesh. In addition, shader attributes like color, material and textures are also
included in the geometry.
Scope
The scope represents the oriented bounding box for the shape in space relative to the pivot (see below) and is defined by three
vectors: the translation vector t (scope.tx, scope.ty and scope.tz), the rotation vector r (scope.rx, scope.ry and scope.rz), and
the size vector s (scope.sx, scope.sy and scope.sz). The rotation vector is encoded as ordered rotation in degrees around the x, y
and z axis.
Pivot
The pivot describes the shape's coordinate system and is defined by a position vector p (pivot.px, pivot.py and pivot.pz) and an
orientation vector o (pivot.ox, pivot.oy and pivot.oz; similarly encoded as the rotation vector above). The pivot is given in object
coordinates, relative to the initial shape's origin; see also Coordinate Systems.
Applying the Rules to Generate a 3D Model
After writing the rule file and assigning it to a shape, the generation of the 3D models can be started and eventually viewed in
the 3D Viewport. Several ways exist to trigger the generation. the first step is always to select one or several start shapes. This
can be done either in the Scene view or in the 3D Viewport:
Single or multiple shapes can be selected in the Scene view or the Viewport.
Generating Models
After shapes are selected, generation can be triggered via the toolbar buttons Generate or Update Seed and Generate. The latter
randomly sets a new seed before generation; if the rules contain probabilistic elements such as stochastic rules or functions such
as rand() , the generated models will look different.
The two generate functions are also available via the main menu Shapes and the context menu (right-click in scene view or 3D
viewport)
In addition, Regenerate All Models provides a way to re-generate all models without the need to select them first.
An ongoing generation process can be canceled using the Cancel button.
Live Mode
If the live mode is enabled, the re-generation of selected models is automatically re-triggered on modifications. This is very useful
when working with shape edit and transformation tools or when editing attributes in the inspector in order to get automatic updates
after modifications. However, use the live mode carefully, since it may lead to large amounts of shapes being re-generated.
Street Networks
1. What are Street Networks
2. Creating and Editing Street Networks Manually
3. Growing Street Networks
4. Aligning Graph Networks to the Terrain
5. Cleanup Street Networks
6. Importing Graph Networks
7. Exporting Graph Networks
Overwriting Attributes with the Inspector
The values of functions marked with attr can be set individually for each initial shape in the inspector. For instance, this definition
attr height = 60
...
yields an entry in the Rule Parameters section of the inspector like this:
You can now click on the "60" and edit the value. Let's say you type in "30":
Note how the "Source" change from "Rules" to "User".
If you click into the "Source" field, a drop-down list appears
and lets you choose the source.
Live Mode
In order to see the effects of manipulating attributes, (re-)generation of the models is required. To generate, a button must be
pressed. This is not necessary if the live mode is turned on:
In the live mode, every change to the attributes triggers a re-generation immediately and gives near-realtime visual feedback. This
can be a great aid for interactively exploring designs or for demonstration purposes.
Of course the speed of the model generation depends on the complexity of the rules, the number of selected initial shapes and the
speed of your hardware.
Multi Assign
It is possible to manually assign a value to multiple initial shapes in a convenient way. Let's say we selected three initial shapes,
either in the Scene view (layers) or in the 3D Viewport:
Multiple initial shapes can be selected in the Scene view or the Viewport.
In the Inspector, the attributes of all three lots can now be manipulated (Note: they all must have the same rule file assigned; in the
example it is "test.cga"):
The attributes of all selected initial shapes can be manipulated in the inspector.
In this example, there are three attributes. Attribute "age" was manually set to 14 in the inspector (therefore the Source is "User").
"height" is set to the default value from the rules in some lot and manually set to a different value in the two others; therefore the
source and the value are not common and a "?" is shown in both. The "type" attribute was not changed anywhere, so the common
source is "Rules" and the value is the one from the rule file (left part of the picture).
Image Maps
Another possible source for attribute values are image maps. See Mapping Images to Attributes
Street Tutorial Part 2 :
Generate street models with CGA Grammar
Tutorial Setup
Continue your work from part 1 of the Street Tutorial or open Tutorial_02_Streets/scenes/streetTutorial_01.cej
Hide the Terrain layer by clicking on its eye symbol in the Scene Editor to have a better look at the streets.
Street Shapes
Street Shape Types

Zooming in on a crossing shows the 5 different street shape types that are created. These shapes already have a start rule
assigned. The start rule of a selected shape is shown in the Inspector.
The picture below shows the different types in colors. The start rules are important once a rule file is assigned.
The 5 different street shape types and their start rules
Apply CGA shape rules

Now comes the final step: Creating the actual 3D street geometry. The CGA shape rule rules/simpleStreets.cga is applied to the
street shapes. Each street shape type has a specific CGA start rule that is evaluated on the shape. The start rules are mapped as
follows:
Street apply street lane textures depending on the street width
Sidewalk extrude to sidewalk height
apply sidewalk texture
distribute lamps (3D assets)
Crossing apply concrete texture
Junction Same as crossing
JunctionEntry Same as crossing
Check the rule file simpleStreets.cga for details, the CGA Shape Grammar Reference or the CGA Shape Grammar tutorial to
learn more about the CGA Shape Grammar.
Select the layer Street Shapes in the Scene Editor
Shapes Assign Rule File... and select Tutorial_02_Streets/rules/simpleStreets.cga
Drag-select some street shapes
Hit the generate button in the top toolbar

The final street models
Alternatively, you can also open scene Tutorial_02_Streets/scenes/streetTutorial_02.cej and generate the streets to see the
result of this tutorial's second part.
Continue with part 3
Cleanup Graph Networks
Why Cleanup
Imported, merged or self-drawn graph networks may contain
duplicate or close-by nodes
duplicate or close-by segments
intersecting segments that do not have nodes where segments intersect.
Such unclean graph networks induce a number of problems when creating street shapes or extracting lots.
The Cleanup Tool allows for fast cleanup of such graph networks by merging nodes, merging segments and creating nodes
at intersecting segments.
The tool can be executed in the in the following ways:
Main tool bar:

Main menu: GraphCleanup Graph...
Right-click viewport context menu: Cleanup Graph...
Note: This tool operates on a selection of graph segments. Unselected segments stay unchanged. When merging, the nodes
of the selected segments are merged.
Cleanup Settings
After execution, the following dialog is shown:
The Cleanup Graph dialog.
The checked operations (intersect, snap and/or merge) are executed one after another. The following parameters can be set:
Intersect Segments:
If checked, missing nodes of intersecting segments are created.
Snap Nodes to Segments:
When checked, nodes snap to segments.
Nodes with smaller street widths always snap into segments with larger street widths. Node street width is defined
as the maximal street width of the adjacent segments.
Snapping Distance:
The maximal distance between a node and a target segment. Only meaningful if the option above is checked.
Merge Nodes:
When checked, nodes that are close to each other are merged.
Nodes with smaller street widths always merge into nodes with larger street widths. Node street width is defined
as the maximal street width of the adjacent segments.
Merging Distance:
Nodes that are closer than this distance are merged into one. Only meaningful if the option above is checked.
Note: This tool operated planar in the x-z plane. The y-coordinate is neglected. Therefore, running this tool on graph networks
containing segments on different y-levels is not recommended.
Examples
Simple Intersections
Snap Nodes to Segments
Simple Merge
Full Cleanup

Importing Shapes from OBJ
OBJ
Wavefront OBJ is a simple and commonly used 3D format that mainly describes 3D geometry. The format allows for minimal
additional information such as grouping.
Import Settings
OBJ import has no options. Simple select the ".obj" file by clicking on the Browse button and click on Finish .
Note: For each OBJ group, a shape is created.

Importing Shapes from COLLADA DAE
OBJ
COLLADA is an XML-based schema for digital asset exchange that enables the use of diverse digital-content-creation tools
to author sophisticated assets for use by 3D applications, including graphics, animation, kinematics, physics, and shader effects.
Import Settings
COLLADA import has no options. Simple select the ".DAE" file by clicking on the Browse button.
Note: For each collada mesh, a shape (with potentially multiple faces) is created.
Importing Shapes from DXF
DXF
AutoCAD DXF, Drawing Interchange Format, or Drawing Exchange Format, is a CAD data format developed by Autodesk. A
DXF file contains a set of entities. There are several entity types. The CityEngine can import the following entity types as shapes:
Circle, LwPolyline (must be closed), Polyline (must be either closed or polyface mesh) and Insert.
The importer allows you to browse layers and individual entities contained in the DXF file. One can select the entities to import by
using drag and drop.
Note: The same importer can also be used to import graph segments: For a graph specific description please visit: Importing
Graph Segments from DXF
Import Settings
The import dialog consists of several options, as shown below. As usual, presets can be saved and applied.
By using drag and drop one can select which entities to import.
File
Press Browse to open a dialog to select a .dxf file to import.
Note: After opening a file, the DXF entities are automatically classified as graph segment or shape and moved to the
containers on the right.
Offset
In the x- and y- offset fields, one can specify an offset in order to translate the data before importing. This can be useful to center
the imported data and to avoid floating point precision problems. By pressing the Center button, the offset of the selected DXF
entities is automatically computed.
Note: When changing the set of objects in the entity listings, the offset may also change. Therefore it may be necessary to
press Center again.
Scale
A scale factor that is applied to the selected entities.
Entity Listings
In the container on the left side all entities contained in the DXF file are listed. Entities that can be imported as shapes can be
moved to the container bottom right. All entities in this container are imported as shapes. Entities can be moved between and inside
containers by using drag and drop.
Note: Each entity is marked with an icon on the left side, indicating if this entity can be imported as graph segment, shape, or
both.
Graph only
Shape only
Graph or shape
Entity cannot be imported
To delete entities on the right side press Del .
Run Graph Cleanup Tool

This option is only of interest when importing graph segments. Depending on the DXF data it may be necessary to cleanup the
graph segments after import. If enabled, the graph cleanup tool is executed on the next wizard page.
Importing Shapes from SHP
Shapefile
The ESRI Shapefile or simply a shapefile is a popular geospatial vector data format for geographic information systems
software. A shapefile commonly refers to a collection of files. The main file (.shp) contains the shape data and the database file
(.dbf) contains attributes for each shape. The shapefile importer can import shapes and attributes from these files. The .dbf must
be present and must have the same base name as the .shp file.
The same importer can also be used to import graph segments: For a graph specific description please visit: Importing Graph
Segments from SHP
Shapefile support is not available in all CityEngine versions.
Import Settings
Options include scale factor, projection., projection details and offset.
File
Press Browse to open a dialog to select a .shp file to import.
After opening a file, the dialog detects the shape type of the file. The type is displayed in the header of the dialog (e.g. "Shape
Type: POLYGON. Importing shapes.."). The following types can be imported as shapes: Polygon, PolygonZ, Point, PointZ. Other
types are imported as graph segments.
Shapefiles containing points can also be imported. In this case, a marker (2x2m quad) is created for each point.
Scale
A scale factor that is finally applied to the projected and (potentially) offset data.
Projections
The projection method used to project spherical (lat/lon) coordinates into cartesian coordinates.
The importer doesn't read the .prj projection file of the shapefile. Therefore the projection must be manually set up.
Projection Settings
Depending on the projection several settings can be edited. Specifications of the projections and their settings are listed on the
PROJ.4 Homepage (PROJ.4 - Cartographic Projections Library).
Ellipsoid, Center Latitude (Latitude of origin), Center Longitude (Central meridian), False Easting, False Northing, Scale Factor,
Standard Parallel 1 (Latitude of first standard parallel), Standard Parallel 2 (Latitude of second standard parallel) and True Scale
Latitude can be specified.
Three parameters are common to all projections: Center Longitude, False Easting and False Northing. The other parameters
are only applicable for specific projections.
Cartesian Data
The projection Cartesian (Disable Projection) is a special projection variant that does not alter the input data, nor takes any
projection attributes (scale and offset do apply). It is suited for shapefiles where data is stored in cartesian coordinates. The file's
data is taken "as is" and mapped directly into the XY coordinate system of the CityEngine.
Shapefiles with cartesian coordinates are recommended to use with the CityEngine, because precision errors might be introduced
when projecting data.
Offset
the imported data and to avoid floating point precision problems. By pressing the Center button, the offset of the shapefile data is
automatically computed.
When changing the projection, the offset may also change. Therefore it may be necessary to press Center again.
Shape file polygons containing "negative" polygons that cut holes into polygons are not currently supported yet, and will be
imported as normal shapes instead of "holes".
Using Attributes from SHP file

A SHP file can have accompanying .dbf file that contains associated attributes for elements. After importing the SHP file, these
attributes appear in the Inspector in the Attributes tab. The picture below shows two shapefile attributes height and id in the
Inspector:
SHP file attributes height and id displayed in the inspector.
To use these attributes with the CGA grammar you need to declare CGA attributes with matching names. A simple CGA rule file
could look like this:
attr height = 10
Lot --> extrude(height)
After assigning this rule file to the shapes, the CGA attribute height appears in the CGA Attribute Mapping tab of the Inspector.
Note that the Source field is set to Value, which denotes that the CGA attribute height is controlled by the attribute of the lot.
New mapped CGA attribute height after assigning a rule file

Importing Shapes from OSM
OpenStreetMap
"OpenStreetMap is a project aimed squarely at creating and providing free geographic data such as street maps to anyone
who wants them." -- openstreetmap.org
OSM is an XML-based format to describe vector data used in a cartographic map. It defines three basic types to describe all the
elements of such a map:
Nodes The dots that are used for drawing segments between.
Ways An ordered list of nodes, displayed as connected by line segments in the editor.
Closed Ways Closed ways are ways which go in a complete loop. They are used to describe areas like buildings,
parks, lakes or islands.
By default, Ways and Closed Ways are converted into graph segments. However, if a Closed Way contains one of the tags
amenity, area, boundary, building, geological, historic, landuse, leisure, natural, place, shop, sport, tourism, it's converted into a
shape. Note the respective symbols, and , displayed on the left side of the ways.
The same importer can also be used to import graph networks: For a graph specific description please visit: Importing Graph
Segments from OSM
Import Settings
File
Press Browse to open a dialog to select a .osm file to import.
Scale
A scale factor that is applied to the projected data.
Offset
In the x- and y- offset fields, one can specify an offset in order to translate the data before importing. This can be useful to avoid
floating point precision problems. By pressing the Center button, the offset of the shapefile data is automatically computed. This
way one can center the imported data.
Note: When changing the selection or the projection, the offset may also change. Therefore it may be necessary to press
Center again.
Projection
The projection method used to project spherical (lat/lon) OSM coordinates into cartesian coordinates.
Projection Settings
Note: Three parameters are common to all projections: Center Longitude, False Easting and False Northing. The other
parameters are only applicable for specific projections.
Element Listing
Lists the layers and OSM ways contained in the selected OSM file. Select the element you want to import.
Note: You may select multiple OSM layers per import session. Then, all ways which are converted into shapes will be merged
into one shape layer. If you would like to generate several shape layers out of one OSM file, please repeat the process
accordingly.
Select / deselect all

Selects / deselects all layers.
Map OSM tags to street widths

If enabled, street and sidewalk widths are mapped from tags contained in the osm file. A corresponding wizard page will show up
after pressing Next. This is only of interest when importing graph segments, see Importing Graph Segments from OSM.
Run Cleanup Tool

This option is only needed when importing graph segments, see Importing Graph Segments from OSM.
Exporting Shapes to SHP
Shapefile
(.dbf) contains attributes for each shape. The shapefile exporter can export shapes and attributes to these files. Additionally, the
exporter writes an index file (.shx).
Note: The same exporter can also be used to export graph segments: For a graph segment specific description please visit:
Exporting Graph Segments to SHP
Export Settings
The export dialog consists of the filename and the projection option, as shown below. As usual, presets can be saved and applied.
Options include filename and projection.
File
Press Browse to open a dialog to select a .shp file to export.
Projection
The projection method used to transform cartesian CityEngine coordinates into (usually spherical) shapefile coordinates.
Note: The exporter doesn't write a .prj projection file.

Projection Settings
Cartesian Data
projection attributes (scale and offset do apply). It is suited for to export data shapefiles in cartesian coordinates.

Exporting Shapes to DXF
DXF
DXF file contains a set of entities. For each selected shape , the exporter writes an entity of type closed Polyline.
Note: The same exporter can also be used to export graph segments: For a graph segment specific description please visit:
Exporting Graph Segments to DXF
Export Settings
DXF export has no options. Choose or create the ".DXF" export file by clicking on the Browse button and click on Finish .

Exporting Shapes to OBJ
OBJ
Wavefront OBJ is a simple and commonly used 3D format that mainly describes 3D geometry. The format allows for minimal
additional information such as grouping.
Export Settings
OBJ export has no options. Simple select the ".obj" file by clicking on the Browse button and click on Finish .
Note: For each shape, an OBJ group is created.

Importing Graph Segments from DXF
DXF
DXF file contains a set of entities. There are several entity types. The CityEngine can import the following entity types as graph
segments: Line, Arc, Circle, Polyline, LwPolyline and Insert.
The importer allows you to browse layers and individual entities contained in the DXF file. One can select the entities to import by
using drag and drop.
Note: The same importer can also be used to import shapes, For a shape specific description please visit: Importing Shapes
from DXF
Import Settings
File
Press Browse to open a dialog to select a .dxf file to import.
Note: After opening a file, the DXF entities are automatically classified as graph segment or shape and moved to the
containers on the right.
Offset
the imported data and to avoid floating point precision problems. By pressing the Center button, the offset of the selected DXF
entities is automatically computed.
Note: When changing the set of objects in the entity listings, the offset may also change. Therefore it may be necessary to
press Center again.
Scale
A scale factor that is applied to the selected entities.
Entity Listings
In the container on the left side all entities contained in the DXF file are listed. Entities that can be imported as graph segments can
be moved to the container top right. All entities in this container are imported as graph segments. Entities can be moved between
and inside containers by using drag and drop.
Note: Each entity is marked with an icon on the left side, indicating if this entity can be imported as graph segment, shape, or
both.
Graph only
Shape only
Graph or intial shape
Entitiy cannot be imported
To delete entities on the right side press Del .
Run Graph Cleanup Tool

Depending on the DXF data it may be necessary to cleanup the graph segments after import. If enabled, the graph cleanup tool is
executed on the next wizard page.
Importing Graph Segments from OSM
OpenStreetMap
"OpenStreetMap is a project aimed squarely at creating and providing free geographic data such as street maps to anyone
who wants them." -- openstreetmap.org
OSM is an XML-based format to describe vector data used in a cartographic map. It defines three basic types to describe all the
elements of such a map:
Nodes The dots that are used for drawing segments between.
Ways An ordered list of nodes, displayed as connected by line segments in the editor.
Closed Ways Closed ways are ways which go in a complete loop. They are used to describe areas like buildings,
parks, lakes or islands.
By default, Ways and Closed Ways are converted into graph segments. However, if a Closed Way contains one of the tags
amenity, area, boundary, building, geological, historic, landuse, leisure, natural, place, shop, sport, tourism, it's converted into a
shape. Note the respective symbols, and , displayed on the left side of the ways.
The same importer can also be used to import shapes: For a shape specific description please visit: Importing Shapes from
OSM
Import Settings
The osm import dialog with a checked highway layer.
File
Press Browse to open a dialog to select a .osm file to import.
Scale
A scale factor that is applied to the projected data.
Offset
In the x- and y- offset fields, one can specify an offset in order to translate the data before importing. This can be useful to avoid
floating point precision problems. By pressing the Center button, the offset of the shapefile data is automatically computed. This
way one can center the imported data.
Note: When changing the selection or the projection, the offset may also change. Therefore it may be necessary to press
Center again.
Projection
The projection method used to project spherical (lat/lon) OSM coordinates into cartesian coordinates.
Projection Settings
Element Listing
Lists the layers and OSM ways contained in the selected OSM file. Select the element you want to import.
Note: OSM files may contain a large number of layers, of which the "highway" layer is usually the most interesting to create
street networks in the CityEngine.
Note: You may select multiple OSM layers per import session. Then, all ways which are converted into graph will be merged
into one graph layer. If you would like to generate several graph layers out of one OSM file, please repeat the process
accordingly.
Select / deselect all

Selects / deselects all layers.
Map OSM tags to street widths

If enabled, street and sidewalk widths are mapped from tags contained in the osm file. A corresponding wizard page will show up
after pressing Next. See below.
Run Cleanup Tool

Depending on the OSM data it may be necessary to cleanup the graph segments after import. If enabled, the graph cleanup tool is
executed on a following wizard page.
OSM Tag Mapping

If Map OSM tags to street widths is checked, the following wizard page is shown:
The osm tag mapping wizard page.
By default, an example function code maps common osm tags to street and sidewalk widths. The function code is copied into the
newly created street layer, and the street and sidewalk width parameters of the imported street segments are correctly mapped.
The correctly mapped street parameters (source is zurich 3) of a selected street segment in the inspector.
The function code can be edited in the wizard page, or after import in the inspector when selecting the street layer.
OSM Import Example

Tutorial 4 Import Streets
Importing Graph Segments from SHP
Shapefile
(.dbf) contains attributes for each shape. The shapefile importer can import graph segments and attributes from these files. The
.dbf must be present and must have the same base name as the .shp file.
The same importer can also be used to import shapes: For a shape specific description please visit: Importing Shapes from
SHP
Import Settings
Options include scale factor, projection., projection details and offset.
File
Press Browse to open a dialog to select a .shp file to import.
After opening a file, the dialog detects the shape type of the file. The type is displayed in the header of the dialog (e.g.
"Shape Type: POLYLINE. Importing graph.."). The following types can imported as graph: Polyline, PolylineZ. Other types are
imported as shapes.
Scale
A scale factor that is finally applied to the projected and (potentially) offset data.
Projection
The projection method used to project spherical (lat/lon) coordinates into cartesian coordinates.
The importer doesn't read the .prj projection file of the shapefile. Therefore the projection must be manually set up.
Projection Settings
Three parameters are common to all projections: Center Longitude, False Easting and False Northing. The other parameters
are only applicable for specific projections.
Cartesian Data
projection attributes (scale and offset do apply). It is suited for shapefiles where data is stored in cartesian coordinates. The file's
data is taken "as is" and mapped directly into the XY coordinate system of the CityEngine.
Offset
In the x- and y- offset fields, one can specify an offset in order to translate the data after the projection and before importing. This
can be useful to center the imported data and to avoid floating point precision problems. By pressing the Center button, the offset
of the shapefile data is automatically computed.
When changing the projection, the offset may also change. Therefore it may be necessary to press Center again.
Shapefile
(.dbf) contains attributes for each shape. The shapefile exporter can export graph segments and attributes to these files.
Additionally, the exporter writes an index file (.shx).
Note: The same exporter can also be used to export shapes: For a shape specific description please visit: Exporting Shapes
to SHP
Export Settings
The export dialog consists of the filename and the projection settings, as shown below. As usual, presets can be saved and
applied.
Options include filename, projection and specific projection settings.
File
Projection

Projection Settings
Cartesian Data
projection attributes (scale and offset do apply). It is suited for to export data shapefiles in cartesian coordinates.
Exporting Graph Segments to DXF
DXF
DXF file contains a set of entities. For each selected graph segment, the exporter writes an entity of type Line.
Note: The same exporter can also be used to export shapes: For a graph segment specific description please visit: Exporting
Shapes to DXF
Export Settings
The export dialog consists of the filename and the street width option, as shown below. As usual, presets can be saved and
applied.
File
Press Browse to open a dialog to select a .dxf file to export.
Export Street Width

When enabled, the street width is written into the "Thickness" field of the DXF Line entity (group code 39).
Note: The value which is written is the total street width, that is the street width plus the sidewalk widths.
Shapefile
The ESRI Shapefile or simply a shapefile is a popular geospatial vector data format for geographic information systems software. A shapefile
commonly refers to a collection of files. The main file (.shp) contains the shape data and the database file (.dbf) contains attributes for each shape. The
shapefile exporter can export graph segments and attributes to these files. Additionally, the exporter writes an index file (.shx).
Note: The same exporter can also be used to export initial shapes: For an initial shape specific description please visit: Exporting Initial Shapes to
SHP
Export Settings
The export dialog consists of the filename and the projection settings, as shown below. As usual, presets can be saved and applied.
Options include filename, projection and specific projection settings.
File
Projection
Projection Settings
Depending on the projection several settings can be edited. Specifications of the projections and their settings are listed on the PROJ.4 Homepage
(PROJ.4 - Cartographic Projections Library).
Ellipsoid, Center Latitude (Latitude of origin), Center Longitude (Central meridian), False Easting, False Northing, Scale Factor, Standard Parallel 1
(Latitude of first standard parallel), Standard Parallel 2 (Latitude of second standard parallel) and True Scale Latitude can be specified.
Note: Three parameters are common to all projections: Center Longitude, False Easting and False Northing. The other parameters are only
applicable for specific projections.
Cartesian Data
The projection Cartesian (Disable Projection) is a special projection variant that does not alter the input data, nor takes any projection attributes (scale and
offset do apply). It is suited for to export data shapefiles in cartesian coordinates.
Shapefiles with cartesian coordinates are recommended to use with the CityEngine, because precision errors might be introduced when projecting data.
Rule-based Modeling
1. Basics of Rule-based Modeling
2. Rule Files
3. Writing Rules
4. Shape Operations
5. Rule Editing Tools
Rule Application
The basic idea of a rule is to replace a shape with a certain shape symbol with a number of new shapes. Formally:
PredecessorShape --> Successor
Let us start with a very simple example:

A --> B
On application on a specific shape with symbol A, the rule above creates a copy of the shape and sets its shape symbol to B. The
A shape is now considered done and not processed anymore. If there is no rule matching symbol B the generation process is
finished. The resulting structure is called the shape tree and looks like this:
In the (extremely simple) shape tree above, A is the root shape and B is a leaf shape. Leaves are very important because
the sum of all leaves represents the generated model. Inner nodes are not visible in the final model.
In this simple example, we assume shape A's geometry, scope and pivot are set up such that the shape represents a unit cube in
the origin; because B is a copy of A, B looks exactly the same (see the picture above).
A rule can have more complex successors, e.g., the right side of the rule can consist of multiple shape symbols and so-called
shape operations:
A --> B t(3, 0, 0) C
This successor is now executed from the left to the right. Again, B is an identical copy of A. Then the current shape is translated by
3 units in x-direction (i.e., the scope.t is manipulated) and a new shape C is created. The shape tree now has two leaves:
The two leaves B and C make up the final 3D model:
If we add this rule for C:

C --> D s(2, 0.5, 1.75) E
The generation process will add two children, D and E to shape C. Shape D is an exact copy of shape C, but shape E will have a
different sized scope (because of the s() shape operation). The shape tree and the associated model look like this:
Note that now, the leaves (B, D, E) are not on the same level (i.e. have different distances to the root shape) but they are all part of
the model.
Another shape operation is the insert operation i():
E --> i("cylinder.obj") F
After starting the generation again, shape E is not a leaf anymore but now has a child shape F.
The geometry of shape F is not a cube anymore but was replaced with the mesh read from file "cylinder.obj". Note that the size (i.e.
the scope.s vector) of shape F is still the same as the one of shape E.
Terminal Shapes
In the E rule above, F is a so-called terminal shape: because no rule F is defined, the generation is stopped at this point. However,
the CGA editor will issue a "Undefined Rule" warning. This can be suppressed by adding a period after F, thus explicitely marking F
as a terminal shape:
E --> i("cylinder.obj") F.
A Note on Leaves
For convenience, rules like the E rule above can be truncated:
E --> i("cylinder.obj")
In this case (i.e. E has no children), the rule interpreter silently inserts a leaf with the same name as the rule itself. The shape tree
after applying the E rule above looks like this:

CityEngine Basics Part 3 :
Assign CGA Rules and Generate Building Models
Introducing CGA rules

In the CityEngine, buildings are described using the CGA rules. A CGA rule file consists of several rules that define how the actual
building geometry is generated. After a CGA rule file is assigned to a shape (i.e. a building parcel), the generation of the building
model can begin. In this tutorial we will assign and modify a single CGA file with basic rules.
Assign a CGA rule file

In the 3D view, click on one of the shapes in the middle to select it.
In the toolbar, click on Assign and select building.cga
The Inspector will now look like this:
Browse the CGA rules and set the start rule

Before we can generate the model, we need to set the start rule for the selected shape in the Inspector. We will use the Rule Editor
to locate it.
With the shape still selected from the previous section, locate the Start Rule entry in the Inspector.
Click on the "Rule File" link to open the Rule Editor. On the left (reddish nodes) the Rule Attributes are shown. On
the right (grayish nodes) the actual rule graph is displayed.
Click on the highlighted button to maximize the editor view.
Locate the rule at the root of the rule graph, in this case it is "Lot". This will be our start rule for the selected shape.
Back in the inspector, verify that "Lot" is set in the "Start Rule" field (this is the default value). Your Inspector should
now look like this:
We are now ready to generate the actual building model geometry.
Generate the first building model

Make sure the shape is still selected and click on Generate .
The building model will now appear on top of the selected shape.
Click on the model to select it and use right-click context menu "Delete Model" to delete it.
Generate it again.
We are now ready to modify the building model. First, we will modify a Rule Attribute, in this case the building height. Second, we
will add a different roof to the building, this will need a new CGA rule.
Modify the building height rule attribute

Generate the building a few times using the Update seed and Generate Models command. Notice how the building
changes height every time because the corresponding rule uses a random value.
Take a look at the default definition of the building height in the rule editor:
In the Inspector, locate the Rule Parameter shelf.
Find the "height" parameter and change the value to "18". Notice how the parameter source switches to "User".
Again click a few times on Update seed and Generate Models . Note how the building model stays constant in
height.
Next, we will add a new rule for the roof.
Add a roof rule

In the inspector, click on the rule file link to open the rule editor.
Find the "Lot" rule and expand its node by clicking on the "-" symbol in the upper right corner of the node.
In the "comp" section, right-click on "Shape" and call the context-menu to add a new rule.
Enter "Roof" for the new rule.
Observe how a new rule has been generated and attached to the "Lot" node.
To create the roof model, we now insert a gable roof shape operation. Right-click on the "Shape" of the new "Roof"
rule and call the roofGable(angle, overhangX, overhangY) operation.
Observe how the roofGable operation has been inserted. Click into the three parameter fields and enter 20, 1, 0 as
roof parameters.
Click on generate to view the new model.

Generate a small city model
In this final step, we will apply the rules on a larger number of shapes. To assign the rule to a larger number of shapes, we will use
the selection menu.
Select the generated model

Right click in the 3D viewport, and choose Select -> Select Objects of Same Group to select lot shapes in this
block.
Click on assign to assign the rule building.cga to the selected shapes.

Click on Generate to generate the models. NOTE: Depending on your selection, there will be a number of warning
dialogs about start rules "LotInner" and similar. You can ignore these, because we assigned our rules to all shapes,
but our rules do not contain start rules called "LotInner" etc.
You should now see a number of buildings with varying building heights.
Creating a new Rule File
Rule files can be created with the steps
Menu: New ... CityEngine CGA Grammar File
or
Right-click in Navigator: New ... CGA Grammar File
Setting the container (rule files are usually in the rules directory).
Naming the file (the standard extension is *.cga).
Hitting Finish
A new CGA file is created, and the CGA Editor is opened. It is empty except some header information ( /* .... */ ).
Writing a Rule File
After creating a new rule file the file is automatically opened in the editor. Existing files can be opened by double-clicking them in
the Navigator or via File Open
A rule file is a collection of attributes, functions and rules. In order to use the rule file, one of the rules must be named the same as
the shape's start rule.
Here is the example from the CityEngine Basic Tutorial:
/**
* File: building_01.cga
* Created: 31 Oct 2008 10:47:50 GMT
* Author: andi
*/
attr minheight = 10
attr maxheight = 30
attr floorheight = 3
attr windowwidth = 2
Lot --> extrude(rand(minheight,maxheight)) Components
Components --> comp(f){top : Roof. | side : Facade}
Facade --> split(y){~floorheight : Floor}*
Floor --> split(x){~windowwidth : Window}*
Window --> i("modern_window.obj")
Do not forget to save the file via

File Save or File Save As .
Assigning a Rule File to a Shape
Once a rule file is written it can be assigned to a shape by a number of ways:
Right click menu in the 3D Viewport:
Select a number of shapes, right-click and choose Assign Rule File...
Right click menu in the Scene view:

Select a number of shapes and choose Assign Rule File...
Browse button in the inspector:
Select a number of shapes (either in the 3D Viewport or in the Scene view) and hit Browse...
Shapes drop-down menu:

Select a number of shapes (either in the 3D Viewport or in the Scene view) and select Shapes Assign Rule Files...
Toolbar button:
Select a number of shapes (either in the 3D Viewport or in the Scene view) and hit the Assign button.
The Start Rule

Next, the start rule must be set for the shape(s). This is done in the Inspector:
Shapes generated from a street network (by subdivision) have their start rule set to "Lot" by default; shapes created manually with
the Create Shape Tool have their start rule set to "Init" by default and shapes which are imported from a .obj file (arbitrary
geometries) have their start rule set to the obj group name by default.
The start rule must be set to the name of a rule contained in the assigned rule file. This rule is then
taken as starting point of the generation.
Standard Rule
The basic idea of a rule is to replace a shape with a certain shape symbol with a number of new shapes. Formally:
PredecessorShape --> Successor
The successor consists of a number of shape operations and shape symbols. Shape operations change the current shape and
shape symbols create a copy of the current shape (with the new shape symbol) and add it as an active shape to the shape tree. If
a rule for the new shape symbol exists, the new shape will be derived later on, otherwise it will become a leaf.
Example:
Lot --> s('0.8, '1, '0.8) center(xz) extrude(20) Envelope
Envelope --> split(y){ ~4 : Floor. }*
This picture shows the Envelope shape after

execution of the Lot rule, before execution of the
Envelope rule.
The final Floor shapes, after execution of the

Envelope rule.
The final shape tree shows that an Envelope

shape was generated from the Lot shape by the
Lot rule, and five Floor shapes were generated
from the Envelope shape by the Envelope rule.
The formatting of the rule is arbitrary, for instance line breaks or spaces can be inserted. For example,
Lot
-->
s(0.8, 1,
0.8) center(xz)
extrude(20) Envelope
Is the same as the Lot rule above, just formatted differently.
Note: Insertion of a period (".") after a leaf shape (here, the undefined Floor in the Envelope rule) suppresses the generation of a
warning in the cga editor.

Parameterized Rule
Rules can be parameterized, i.e. a parameter signature can be defined and the matching signature is chosen during generation.
Note: No explicit parameter type is required, the CGA compiler automatically finds the simple type of the parameter. There are three
simple types in the CGA grammar: float, boolean and string. The float type is used for all numbers (also integers).
Example 1
Lot --> s(0.8,1,0.8)
center(xz)
Footprint(20)
Footprint(height) --> extrude(height*0.8)

Envelope
During execution of rule Lot, a new shape with shape symbol Footprint and float parameter "20" is generated. During execution of
rule lot, the height parameter will have the value 20. Note that arbitrary mathematical expressions can be built with float
parameters.
Example 2
Lot --> s(0.8,1,0.8)
center(xz)
Footprint(20,geometry.area)
Footprint(height,area) --> t(0,0,1)

extrude(height)
Envelope(area)
Envelope(area) --> split(y){ ~4 : Floor(area) }*
Here, the Footprint rule takes two parameters and the Envlope as well as the Floor rule takes one parameter. Note how area is
passed from rule to rule.
Example 3
Lot --> Footprint("just an example")
Footprint(height,area) --> t(0,0,1)

extrude(height)
Envelope(area)
Footprint(text) --> print(text)
Finally, rule overloading is shown in example 3. There are two Footprint rules, one with two float parameters and one with one
string parameter. The compiler automatically makes sure that only the matching one is used during shape creation (i.e. during
execution of the Lot rule above, a Footprint shape with a string parameter is created).
Note: If no matching rule exists a new leaf is generated.

Conditional Rule
It is possible to generate different successors for different conditions of rule parameters or shape attributes such as area.
PredecessorShape -->
case condition1: Successor1
case condition2: Successor2

...
else: SuccessorN
Example 1
Footprint(type) -->
case type == "residential" : extrude(10) Envelope
case geometry.area/2 < 200 : extrude(30) Envelope
else : NIL
In this example, the rule Footprint takes one parameter, type, of type string. If the string is equal to "residental", the first successor
is taken (i.e. the current shape is extruded by 10 units).
If the string is not equal to "residential", and the area of the current shape's geometry is smaller than 400, the second successor is
taken (i.e. the current shape is extruded by 30 units).
If none of the two conditions above is true, the third successor is taken and a NIL shape is generated (NIL is a special shape
symbol and means "do not generate a shape").
Conditions can arbitrarily be combined with operators && and || (boolean and / or operations), and mathematical expressions can
be used.
It is also possible to nest conditions. There is no limit on the nesting level.
Example 2
Footprint(type) -->
case type == "residential" || type == "park" :
case geometry.area/2 < 200 && geometry.area > 10 : extrude(10) Envelope
else: extrude(15) Envelope
case type == "industrial" : extrude(100) Factory
else : NIL
Example 2 demonstrates nested conditions and boolean operations.
Note: the case and the else statements must build a consecutive block and can not be interrupted with successors (like a switch-
case block, NOT like if statements in well-known programming languages).

Stochastic Rule
Analogous to conditional rules, the CGA Shape grammar permits stochastic rules, i.e. creating variation using randomness.
PredecessorShape -->
percentage%: Successor1
percentage%: Successor2
...
else: SuccessorN
The sum of all percentages must not be greater than 100.
Example 1
Lot -->
30% : Lot("residential")
20% : Lot("retail")
else : Lot("industrial")
In this example, there is a 30% chance the first successor is chosen and a new Lot shape with parameter "residential" is generated,
a 20% chance for the second successor and a 50% chance for the last successor to be chosen.
All random numbers, also the choice of the percentages above, depend on the current shape's seed (the seedian shape attribute).
Example 2
Again, condition blocks can be nested:
Lot -->
30% :
50% : Lot("residential")
else : NIL
20% : Lot("retail")
else : Lot("industrial")
Note that a condition block always needs to be finished with an else: and percentages and successors must not be mixed up.

Attributes
Attributes are a set of static global variables defined in the rule file. Each attribute is initialized to a specific value in the rule file. The
attribute values can individually be controlled on a per-start-shape basis; this can be done in the "Rule Parameters" shelf in the
inspector, where the source for each attribute can be set to either "Object", "Rule", "User" or a map layer. See also Overwriting
Attributes with the Inspector; using map layers based on image maps to control attributes is described in Mapping Images to
Attributes.
Example
attr height = 150
attr landuse = "residential"
Lot --> extrude(height) Envelope(landuse)
Here, two attributes are defined using the attr keyword: height which is of type float and landuse which is a string. The attributes
are used in the Lot rule.
Attributes can also be conditional or stochastic:
attr landuse = 50%: "residential"

else: "industrial"
Here, there is a 50% chance landuse evaluates to "residential" and a 50% chance it evaluates to "industrial". Note: in contrast to
functions, which are going to be explained in the next section, conditional and stochastic attributes are evaluated only once during
the generation process. If a rule is assigned to more than one shape, for each shape the conditional/stochastic attributes are
evaluated to a value once and then keep that value.
In the same way, the rand() function can be used:
attr height = rand(30,50)
Lot --> extrude(height) Envelope
Envelope -->
case height > 40: SmallBuilding
else: LargeBuilding
For each shape which has the start rule Lot, height evaluates to a value between 30 and 50 units. This height can then be used
everywhere in the rule file and always stays constant.

Importing Rules From Other CGA Files
Rules from an existing rule file can be imported by a rule file through "import". Importing a rule file makes all rules of the imported
rule file available under the given prefix. In contrast to rules, attributes of an imported rule file are not prefixed and will be
overridden by the corresponding attribute of the importing rule file.
Example
Combining two facades with a structure

# -- facade1.cga
Facade -->
bakeUV(0)
# -- facade2.cga
Facade -->
bakeUV(0)
# -- structure.cga
// the attribute height will be overridden by the

// attribute height from "main.cga" if this rule
// file is included. Thus if this rule file is
// used standalone, the buildings will be of height
// 100, if this rule file is included by "main.cga",
// the buildings will be of height 200.
attr height = 100
Lot-->extrude(height) Mass
Mass-->comp(f){ side: Facade | top: Roof }

# -- main.cga
// define an attribute "height", potentially

// overriding the same attribute in imported
// rule files.
attr height = 200
// import facades
// import structure
import st : "structure.cga"
Lot-->
// reference rule "Lot" in structure.cga
st.Lot
// define rule "Facade" for structure.cga

st.Facade-->
50% : f1.Facade
else : f2.Facade

Functions
Functions are used to encapsulate evaluations which are used several times in the rules. Unlike rules, functions are typed (i.e. they
return a value) and do not change the current shape. Functions can be parameterized, conditional and stochastic.
Example
getHeight(area) =
case area > 1000: 300
case area > 500:
20%: 200
50%: 150
else: 100
else: rand(20,50)
The getHeight function takes one float parameter (area), and returns a height depending on the parameter. If area is larger than
1000, 300 is returned. If area is larger than 500 (but smaller than, or equal to, 1000), the return value is either 200, 150 or 100 with
probabilities 0.2, 0.5 and 0.3. If area is smaller than, or equal to, 500, a random value between 20 and 50 is returned.
A rule which uses getHeight might look like this:
Lot --> extrude(getHeight(geometry.area)) Envelope.
Note: in contrast to attributes, functions are evaluated in every call. This means a function like
height = rand(30,50)
makes sense only for dedicated purposes because it returns a different value every time it is used.
Const Functions
Functions can made constant with the const keyword. Const functions behave the same as attrs, the only difference is that const
functions are internal to the rule file and can not be mapped in the inspector.

Comments
Comments can be added to CGA source code by either line comments
// a comment
# another comment
or block comments
/* block comments
can be used to write
multi-line comments
*/

Extrusion
Extrusion is typically the first step to generate a 3D building from a 2D footprint. This operation increases the dimension, i.e. a two-
dimensional building footprint can be extruded into a three-dimensional mass model.
Lot-->
extrude(4) Building
The picture in example 1 shows a simple extrusion of a 2D building footprint (left) to a 3D mass model (right). The rule to achieve
this is printed on the right. The extrusion direction is normal to the footprint polygon.
If a building lies on hill ground, it might be desired to extrude along a world coordinate axis rather than the face normal.
Lot-->
extrude(world.y, 30)
In example 2, the extrusion is along the global y-axis.
Another extrusion variant is to taper the fooprint, see the taper shape operation.
Transformations
The following transformations are available to modify the scope of the current shape:
t(tx,ty,tz) translates the scope's position along the scope axes.
r(rx,ry,rz) rotates the scope around its origin by adding rx,ry and rz to the scope's rotation vector scope.r . It is
also possible to rotate around the scope center by writing r(scopeCenter, rx,ry,rz) .
s(sx,sy,sz) sets the scope's size vector scope.s to the values of sx, sy and sz . Hence, in contrast to the translate
and rotate operations, the parameter values here are not added but overwrite the old ones. Furthermore, note that the
size operation sets the size in absolute values (e.g., meters or yards) and does not perform a relative scaling.
center(axes-selector) translates the scope of the current shape such that its center corresponds to the center of the
scope of the previous shape on the shape stack, according to the axes-selector. The latter determines in which axis
directions (of the previous shape on the shape stack) the translation is performed.
Relative Operator
For the t() and s() operations it is possible to conveniently transform the absolute values tx,ty,tz or sx,sy,sz to values relative
to the scope size using the operator "' ":
s('0.5, '1, '1)

t('2, 0, '3)
This is equal to:

s(0.5*scope.sx, 1*scope.sy, 1*scope.sz)
t(2*scope.sx, 0*scope.sy, 3*scope.sz)
Below are some examples; the next section explains the various coordinate systems useed in the CGS Shape Grammar.
Examples
Setting the Size

Lot-->
extrude(10)
s(5,5,5)
The extruded Lot is set to an absolute size of 5 units in

all three dimensions.
Relative Resizing and Center

Lot -->
s(0.8, 1, 0.8)
center(xz)
extrude(20)
The scope is first sized down by using the s() operation

in conjunction with the relative operator "'", then
centerd (relative to the scope of the Lot shape) and
finally extruded to a 3D geometry.
Rotation and Center
Lot-->
extrude(18)
split(y) {
2 : r(0, 360*split.index/split.total,
0)
center(xyz) X
}*
Each split shape is first rotated around its scope origin

and then centered. Note: using
r(scopeCenter,
0, 360*split.index/split.total, 0)
instead of the r() center() sequence gives the same

result.
Translate - Rotation Concatenation

A-->
i("builtin:cube")
This is the shape we start with.
A-->
i("builtin:cube")
t(2,0,0)
First a translation of two units along the x-axis.
A-->
i("builtin:cube")
t(2,0,0)
r(0,30,0)
Then a rotation of 30 degrees around the y-axis.
A-->
i("builtin:cube")
t(2,0,0)
r(0,30,0)
t('2,0,0)
And another translation of 2 units along the x-axis.
Note:
translations are along the scope's x-axis, i.e. the rotation changes the
global translation direction!
the relative operator ' is used - here it does not make a difference
because scope.sx is 1
Coordinate Systems
Several coordinate systems are involved when working with shapes. All transformations described above operate in the system
defined by the current shape's scope, the scope system. There is also a pivot system associated to each shape, and every shape
defines an object coordinate system.
In the table below, all four coordinate systems involved in the CGA Shape Grammar are presented by means of the example
whose rules are to be found further below.
World Coordinate System

Shapes are defined in world coordinates. The
world coordinate system can be visualized by
enabling Grid in the viewport and Menu:
Edit Preferences General Viewport
Show axes .
Object Coordinate System
On generation, a local coordinate system is
defined for each shape. The origin is placed at the
first point of the intial shape's first edge, and the
axes are oriented such that the x-axis is along the
first edge, the y-axis is along the first face's normal
and the z-axis is perpendicular to the former two.
The orientation and the position of the object
system can be queried (see the initialShape
attribute in the CGA shape grammar reference).
Pivot Coordinate System

Each shape has an associated pivot coordinate
system. The pivot is described in object space, i.e.,
relative to the shape's origin. The pivot is adjusted
on component splits (placed at the first point of the
first edge of the component, with x along the first
line and z along the face normal).
Therefore, the pivot coordinate system defines a
standard coordinate system for e.g. facades.
The orientation and the position of the pivot
system can be queried (see the pivot attribute in
the CGA shape grammar reference) and visualized
(see Working with the Shape Tree Explorer).
Scope Coordinate System
Each shape has an associated scope coordinate
system. The scope is described in pivot space and
has a size, i.e., is the bounding box of the scope's
geometry. The typical shape transformations
operate on the scope (see Transformations).
The rotation and the translation of the scope
system can be queried (see the scope attribute in
the CGA shape grammar reference) and visualized
(see Working with the Shape Tree Explorer).
Note: The scope in the picture on the right is flat,

i.e., its z-dimension is 0.
The picture below shows the rule applied on two identical (but differently positioned) lots.
The object space origin, pivot and scope of one corresponding shape are visualized in both generated models. The rule also prints
the numerical representations of the highlighted elements. For lot A, the ouptut looks as follows:
initialShape.origin.p = 10.5274, 0, 32.9774
initialShape.origin.o = -0, -30.0738, 0
pivot.p = 7.5134, 0, 1.90735e-006
pivot.o = 0, 95.6808, 0
scope.t = 0, 15, 0
scope.r = 0, 0, 0
And the output for lot B:

initialShape.origin.p = -17.9412, 0, 8.9387
initialShape.origin.o = -0, -79.7078, 0
pivot.p = 7.5134, 0, 0
pivot.o = 0, 95.6808, 0
scope.t = 0, 15, 0
scope.r = 0, 0, 0
Note that only the initialShape.origin attribute differs; all the other values are the same for both models. Also note the tiny error in
the pivot.pz value (0 vs. 1.90735e-006); this is a typical floating-point arithmetics roundoff error.
Finally the cga code:

/**
* File: test_0115_coordinate_systems.cgaref.cga
* Created: 28 Aug 2009 08:08:10 GMT
* Author: dec
*/
version "2009.2"
Lot-->
extrude(20)
comp(f) { 3 : FacadeSpec | side : Facade | top : Roof }
Facade-->
split(y) { 5 : Floor }*
FacadeSpec-->
split(y) { 5 : FloorSpec }*
FloorSpec-->
case split.index == 3:
print("initialShape.origin.p = " + initialShape.origin.px + ", " + initialShape.origin.py + ", " +
initialShape.origin.pz)
print("initialShape.origin.o = " + initialShape.origin.ox + ", " + initialShape.origin.oy + ", " +
initialShape.origin.oz)
print("pivot.p = " + pivot.px + ", " + pivot.py + ", " + pivot.pz)
print("pivot.o = " + pivot.ox + ", " + pivot.oy + ", " + pivot.oz)
print("scope.t = " + scope.tx + ", " + scope.ty + ", " + scope.tz)
print("scope.r = " + scope.rx + ", " + scope.ry + ", " + scope.rz)
X
else:
X
From Volume to Surface with the Component Split
A typical approach is to decompose an architectural design into geometric components. In the CGA shape grammar, the
component split permits breaking down shapes into shapes of lesser dimensions. The operation
comp(comp-selector) { selector : operations | selector : operations ... }
splits a predecessor shape, based on its geometry, into its components and executes a set of operations on each component. The
parametercomp-selector identifies the type of the component to split; it can be either f for faces, e for edges or v for vertices.
The selector parameters define the selection of components. As a basic example, the rule
A--> comp(f){ all: B }
creates a new shape B for each face of shape A's geometry. Similarly we use comp(e){ all: B } and comp(v){ all: B } to split
into edges and vertices respectively.
To access only selected components, we use operation calls such as comp(f){ 3 : B } to create a shape consisting of the
original shape's third face. Such calls are not very generic and require the user to be aware of the topology of the predecessor
shape's geometry. Therefore, as an alternative, we use semantic selection keywords:
Building --> comp(f){ side : Facade }
selects only the verical side faces of Building's geometry and creates the new facade shapes accordingly. To accomplish this, the
rule interpreter analyzes the spatial properties of the geometry components. The following semantic selection keywords are
available:
front, back, left, right, top, bottom : The y-normals of the components are analyzed by classifying their
directions into the corresponding quadrants (in relation to the local coordinate system of the current shape).
vertical, horizontal, aslant, nutant : The y-normals are analyzed in relation to the xz-plane of the current shape's
local coordinate system. For example, vertical matches if the y-normal is parallel to the xz-plane; horizontal matches if it
the normals are more or less perpendicular; aslant matches if the angle between normals and xz-plane is positive and
nutant matches if the in-between angle is negative.
side: Selects all but the horizontal components
all : Selects all components
Examples
Let us split the mass model of a building into the main facade and a number of
side facades.
Note the orientation of the pivot (the annotated axes).
Building-->
comp(f) {
front : color("#ff0000") Main |
side : color("#0000ff") Side
}
Each face is now the geometry of a new shape; the new shapes' scopes and
pivots depend on the faces' orientation. The x-axis points along the first edge and
the z-axis points along the face normal. The scope's z-dimension is zero.
In the example above, a mass model is divided into front and side facades (Main and Side shapes). Typically, the facades are then
sudivided further into floors. Each of the new Main and Side shapes has its pivot and scope positioned and oriented such that the
facade rules can be written conveniently.
Another important feature of the component split are trim planes. Refer to the CGA shape grammar reference for more information.

The Subdivision Split
The split operation can be used to model shapes and to set up geometry by splitting a larger geometry object to smaller ones. The
split operation is central to create designs with the CGA shape rules.
The basic definition for split is split(axis) { selector : operations } (see CGA Reference).
The following examples show the most important possibilities of the split operation. We will start with a simple example and proceed
with more advanced ones.
Simple Resize
In this introductory example we place a cuboid on a lot and assign its dimensions. First, we define the length of the cuboid as 5.
Then, we run the lot rule, which comprises of a scaling and the inserted geometry. At last, we assign a color in hexadecimal.
attr cuboid_length = 5
Lot -->
s(cuboid_length,1,1) i("builtin:cube") color("#84c0fc")
The cuboid can be simply resized by assigning another value to the parameter cuboid_length.
...
...
Split Example 1: Simple Split

In the following example, the split operation is introduced:
attr green = "#46c820"
attr blue2= "#84c0fc"
Lot -->
s(cuboid_length,1,1) i("builtin:cube") split_example01
split_example01 --> split(x){ 3 : X }
// Value 3 results in a length of three for "X".
// "X" results into a new cuboid with a length of 3.
X --> color("blue2")
The operation "split(x) { 3 : X }" stands for: split a geometry along x-axis, cut it at 3 and replace it with the successive cuboid "X".
"X" gets color "blue2".
Split Example 2: Split and Fill
In this example the geometry with a length of 5 is split at 3. The resulting cuboids are left, green with a length of 3 and right, blue
with a length of 2. The symbol "~1" denotes a float operation. The remaining space of 2 is filled since no other rule is applied and
because the float operation.
attr cuboid_height1 = 2
...
split_example02 --> split(x){ 3 : X | ~1 : X(cuboid_height1) }
// splits into { left geometry with an absolute length of 3 |
// right geometry with a float value of 1 }
X --> color(green) s('1,'1,'1)
// The left X becomes green.
X(a) --> color(blue2) s('1,'a,'1)
// The right X becomes blue and gets a height of 2 through the overload mechanism.
The float value ~20 fills the space between the two absolute Xs.
...
split_example03 --> split(x){ 1: X(1.5) | ~20: Y(1) | 1: X(.5) }
...
The next two examples illustrate what happens if multiple float splits are applied:
...
split_example02 --> split(x){ 3 : X | ~1 : X(cuboid_height1) | ~1 : X(cuboid_height2)}
...
...
split_example02
--> split(x){ 3 : X | ~1 : X(cuboid_height1) | ~1 : X(cuboid_height2) | ~1 : X(cuboid_height3)}
...
If there is no space left for a float operation the corresponding shape is not generated (Z in this case):
...
split_example02 --> split(x){ 5 : X | ~1 : Z }
...
Split Example 3: Split with Absolute Values
This example shows what happens if absolute split values are used ( left 3 and right 1 ). Note that the preceding geometry had a
length of 5. After the split the total resulting length is 4.
...
split_example03 --> split(x){ 3 : X | 1 : X(cuboid_height1) }
...
The effect of absolute values within a scope is shown in the following. The the resulting shape "Y" gets a length of 1 since there is
total length of 5. The rightmost shape "Z" will not be generated at all.
...
split_example03 --> split(x){ 2 : X | 1 : X | 1 : Z | 2 : Y | 1 : Z }
...
No splits will be produced with negative or zero-sized values. Y and rightmost Z is not possible. Leftmost Z will start at 1.5. X is cut
at the total length of 5.
...
split_example03 --> split(x){ 1.5 : X | -2 : Y | 1.5 : Z | 1.5 : X | 0 : Z | 1.5 : X }
...

Working with the repeat split
This method is used to repeat geometry within a given scope. It can be used to insert repetitive elements to create sophisticated
design patterns.
Simple Repeat
In the first example a scope of length 10 is filled repetitively with a floating X and length 2. The asterisk "*" after the bracket
denotes the repetitive split.
...
repeat_example01 --> split(x){ ~2: X }*
...
A simple variation with borders:
...
repeat_example01 --> split(x){ 1: X(2) | {2.7 : X}* | 1: X(3) }
...
The following example rules will produce the same resulting geometry: five cuboids each with a length of 2.
...
repeat_example01a --> split(x){ { 2 : X }* | ~1: X(2) }
repeat_example01b --> split(x){ ~1: X(2) | {2 : X}* }
...
The repetitive X will be evaluated first independently on which side of the split the repetition is denoted. The float value X does not
get any space to be generated.
The following shows that a repeat with absolut values can be ordered by neighboring float controlled X.
...
repeat_example01 --> split(x){ ~1: X | { 2: X(.5) }* | ~1: X }
...
Repeat Pattern Examples

Repeat operations can be used to create patterns. The following example shows that geometric objects can be grouped into a
bracket and repeated.
...
repeat_example01 --> split(x){ ~1: Y | 0.25: X | ~1: Y }*
...
Finally, repeating objects can be inserted within any other geometries like the following example shows.
...
repeat_example01 --> split(x){ 1: X(3) | { ~1: Y | 0.2 : X | ~1: Y }* | 1: X(3) }
...
Using Rhythm for Modeling
In architecture the term rhythm describes the repetitive use of a group of geometric objects in order to establish a recognizable
pattern. A typical scenario is the alternating arrangement of windows and columns in the facades of common high rise office
buildings. Rhythmical patters can be interleaved and composed into higher level patterns.
Examples
The first example shows the repetition of two grouped objects. The last object (right) is cut since the scope ends at a length of 10.
...
rhythm_example01 --> split(x){ { 2: X(2) | 1: Y(1) }* }
...
The next rhythm consists of three objects (X, Y, Z) and two repetition steps.
...
rhythm_example01 --> split(x){ ~2: X(2) | { ~1: Y(1.5) | ~1: Z(1) }* }*
...
The final example for a rhythm pattern consists of four objects (X, Y, Z) and three repetition steps.
...
rhythm_example01 --> split(x){ ~5: X(2) | { ~1: Y(1.5) | { ~1: Y | ~1: Z(1.25) }* }* }*
...
The Parallel Repeat Split
The parallel repeat can be used to produce sub branches within one parenting scope. It can be used to meet for example window
rules of a facade.
Examples
The first example shows the parallel repetition of Y(2) - yellow - and X(2) - light blue:
...
pr_example01 --> split(x){ ~1: X | { ~1 : Y(2) }* | ~1: X | { ~1 : X(2) }* | ~1: X }
...
The next example presents a variation:
...
pr_example01 --> split(x){ 1: X(2) | {2 : X}* | {1 : Y(1)}* | 1: X(3) }
...
Relative Split
For several reasons a designer might want to use ratios between geometric objects to describe a certain kind of geometric style.
Therefore, the relative split can be used. The relative split operates on a scale between zero (0) and one (1).
Example 1: Cut in Half

The following figure shows the next applied rule. The "'0.5: X" introduces the relative split. It divides the actual scope by 2.
...
rel_example01 --> split(x){ '0.5: X | { ~1 :Y }* | 2 : Z | { ~1 :Y }* }
...
Example 2: Golden Section

Common design rules like the Golden Section can be quickly realized and branched. The following rules start with a decomposition
of cuboid with a length of 10. Note that only the length ratio is promoted as a relative value. Rules a and b repeat the relative split
with the Golden Section ratio.
...
rel_example02 --> split(x){ '.382: a | { '.618: b } }
a --> split(x){ '.382: X | { '.618:Y } }
b --> split(x){ '.382: X | { '.618:Y } }
...
Example 3: Composed Golden Section

Further subdivisions can be made with a composition of the rules of example 2.
...
rel_example03 --> split(x){ '.382: a | { '.618: b } }
a --> split(x){ '.382: a | { '.618: c } }
b --> split(x){ '.382: b | { '.618: d } }
c --> split(x){ '.382: X | { '.618: Y } }
d --> split(x){ '.382: X | { '.618: Y } }
...
Insertion of Assets
A typical last step is the insertion of assets, i.e. polygon meshes such as windows, doors etc. This is described in detail in the CGA
Shape Grammar Reference as well as in the Facade Modeling Tutorial

Working with the CGA Editor
The CityEngine includes a powerful editor for the creation and editing of CGA rules. Whenever a rule file (rule files have the
extension *.cga) is opened, it is opened in the CGA editor.
Errors and Warnings
The CGA Editor (top) and the CGA Problems view (bottom). Note the highlighed error (red) on line 193.
In the picture above, a rule file is opened in the CGA Editor; there is a syntax error in the CGA code (line 201: "->" instead of "-->").
The problem is detected automatically and marked red. Note: the position of errors are indicated as small red boxes next to the
scrollbar on the right. More detailed information about the error can be found in the CGA Problems view or by hovering the mouse
cursor over the red error icon on the left:
Errors need to be resolved before applying the rules. It is not possible to generate models if the assigned rule file contains errors.
The CGA Editor also issues warnings:

Warnings aare highlighted in yellow.
In this case, the rule Porte is not defined. This is not necessarily a problem, Porte could be a leaf shape, but probably it is
misspelled and should be "Porta". Warnings just indicate potential problems and do not prevent generation.
Code Completion
The CGA Editor features automatic code completion. At any position in the CGA code, you can press <ctrl + space> and a window
pops up with a number of suggestions which match the current context. Use the cursor keys or the mouse to choose one.
The code completion feature of the CGA Editor: On hitting <ctrl + space>, a number of suggestions matching the current
context are presented.
Important Shortcuts
Very important shortcuts for working with the CGA Editor include:
ctrl+s - save the file (changes must be saved before generation; files with changes are marked with an "*" in the tab)
ctrl+g - generate (the selected objects, i.e. shapes or models)
ctrl+F5 - re-generate all models
ctrl+f - opens "find / search-replace" dialog
ctrl+l - opens "go to line" dialog
ctrl+shift+l - shows all shortcuts
Note: these shortcuts only work if the cga editor is the current view (i.e. its tab is highlighted). They might have different meanings
in different views!
CGA Problems view

On top of static compile errors, the CGA Problems View also shows dynamic runtime errors, i.e. problems encountered during
generation of a model. Such errors / warnings depened on the rule as well as on the initial shape (i.e. its geometry and attributes
such as the seed etc.). The CGA Problems view is a great aid in finding and resolving such problems.In the example below a
number of buildings were generated and two "asset not found warnings" were reported.
To find the according initial shape, double-click on the warning and the shape will be selected and framed. It is a good
idea to hide the models so the underlying shapes are visible. The picture below shows the inital shape for whom the
generation resulted in the "Could not load asset cube_bevel1_side.obj - file not found." warning.
Pitfalls
Make sure the default limit of 100 markers is disabled:
Working with the Model Hierarchy Explorer
The shape tree of a generated model can be interactively explored. To open the Model Hierarchy Explorer, select the "Show Model
Hierarchy" item in the Window menu:
The Model HierarchyExplorer can be opened in the Window menu.
Generate a model, select it and hit the EditModel button in the toolbar:
A generated model can be switched to the edit model; its hierarchy then appears in the Model Hierarchy Explorer.
The model hierarchy (or shape tree) of a model can now be unfolded by using the context menu (right-click) on a tree node:
Use the right-click menu to expand and collapse model hierarchy nodes.
The shape tree of a specific building is defined by the associated rule file and the initial shape.
Part of a CGA rule file and the hierarchy of the generated model.
In the picture above, a snippet from the Candler rule file (which can be found in Shape Grammar Tutorial) is shown on the left and
the according part of the model hierarchy on the right. Note the matching structures (Lot -> Solid -> Front/Side/Back/Roof).
Each node of the model hierarchy can be expanded and collapsed using the right-click menu. Moreover, each shape node can be
selected/deselected with a left click (use the ctrl modifier to select more than one node). It is also possible to directly click into the
model in the 3dView. A number of special rendering modes are available to show the attributes of the selected shapes.
Using the special rendering modes to visualize attributes of the selected shape tree nodes. Note (1) that some nodes
have their shape parameters attached in brackets and (2) the "Set Edit Model Alpha" slider on the top right (under the
mouse cursor).
In the picture above, the two leaves "Sill" and "WindowAsset" are selected, and the rendering mode is set such that the geometry
and the scope of only the two selected shapes are drawn. Additionaly, the "Model Alpha" is set to a very low value, such that the
model is rendered transparently and the selecte shapes are clearly visible. To change the "Model Alpha", click on the "Set Model
Alpha" button and the slider will appear. Let us look at the render mode switches in more detail:
Show scope
If enabled, the selected shape nodes' scopes are drawn (x-axis red, y-axis green, z-axis blue, other scope edges orange). The
line width can be set in the Preferences->General->Grammar Core.
Show pivot
If enabled, the selected shape nodes' pivots are drawn (x-axis red, y-axis green, z-axis blue). The size and line width can be
set in the Preferences->General->Grammar Core.
Show trim planes
If enabled, the selected shape nodes' trim planes are drawn.
Show geometry
If enabled, the selected shape nodes' geometry attribute is drawn (in the drawing mode selected in the viewport).
Derived Image Origin
If enabled, the model's origin is drawn (x-axis red, y-axis green, z-axis blue).
Wavefront OBJ
Format Description
Originally developed by Wavefront Technologies for its Advanced Visualizer animation package, OBJ is an open and widely
adopted geometry definition file format.
It is a simple ascii-based format that only represents 3D geometry - the position of each vertex, the texture coordinate associated
with a vertex, the normal at each vertex, and the faces that make each polygon.
OBJ files can optionally contain a reference to a material library file (MTL). MTL files contain one or more material definitions, each
of which includes the color and texture and other properties of individual materials. These are applied to the surfaces and vertices
of objects. Material files are also stored in ASCII format.
Specific Export Options for OBJ

OBJ has no additional export options (see general export options).
CGA Mapping to OBJ
Geometry
OBJ element CGA feature
v Vertex data from asset meshes.
vn Vertex normal data from asset meshes.
vt Texture coordinates from "colormap" texture channel of asset meshes. Please note, that the per-texture
transformations (see material.colormap.{su, sv, tu, tv, rw}) are NOT included in these texture
coordinates.
f The mesh faces/polygons defined by the vertex, vertex normals and texture coordinates indices from the asset
meshes.
g The face group name. If the mesh comes directly from an inserted asset, the original name will be used. If Mesh
Granularity is set to "merge meshes by material", this name is controlled by the material.name attribute. Else, an
internal name is set dependending on the operation which created the geometry.
s Smoothing groups are not supported and are turned off. Use vertex normals instead.
usemtl Material name and reference into the corresponding MTL file (see Material section below). It is only written, if the
"Materials" export option is enabled.
mtllib Local reference to the corresponding MTL file. It uses the same base name as the OBJ file (but with extension
'.mtl') and is written into the same directory.
Materials
Note: The material definitions are exported into separate MTL files.
MTL element CGA feature
newmtl The material name, corresponds to the usemtl statement in the obj files.
illum If the material of the mesh contains a specular color component equal to (0,0,0) a LAMBERT material is exported
(illum is set to 3). For PHONG materials (specular component != zero) it is set to 4.
Kd Diffuse color, set to the value of material.color.
d Transparency, set to the value of material.color.a.
map_Kd The diffuse texture, set to the value of material.colormap. This statement is only written if a texture file is
assigned to the colormap channel. Optionally, the following uv translation and scaling factors are exported:
If material.colormap.{su,sv} are != 1.0 the -s option is appended with the scaling factors.
If material.colormap.{tu,tv} are != 0.0 the -o option is appended with the translation values.
Ka Ambient color, set to the value of material.ambient.

Ks Specular color, set to the value of material.specular if the material is of type PHONG (illum = 4).
Ns The specular exponent of the phong lighting model, also called "shininess". Set to the value of
material.shininess.
Tf For Maya compatibility, set to (1.0, 1.0, 1.0).
Ni For Maya compatibility, set to 1.0.
Further Reading
Autodesk FBX
Collada DAE
Renderman RIB
Mentalray MI
Autodesk FBX
Format Description
"Autodesk FBX technology is one of the most widely used and supported platform-independent 3D data interchange solutions in
the industry today. FBX plug-ins are included with Autodesk Maya and Autodesk 3ds Max software-providing high levels of
interoperability between these packages - and with Autodesk MotionBuilder software, which supports FBX natively." -- Autodesk
For maximum compatibility, CityEngine supports two versions of FBX: 2009.3 and 2011.3 (with internal file format versions 6.1
and 7.1 respectively). The major difference between the two versions is the support for instanced meshes in FBX 2011.
Specific Export Options for FBX

The FBX exporter supports the following additional settings:
Option Description
Create Shape If enabled, a transformation node is inserted for each shape (i.e. building). Meshes will not be merged by
Groups material across shapes.
File Type If set to binary, the file is stored in binary (native) format.
Embed Textures If enabled, textures are stored inside the binary FBX file.
CGA Mapping to FBX

As the FBX file format is quite verbose, we restrict ourselves to some selected examples for this manual. Please refer to the
documentation provided by Autodesk (http://www.autodesk.com/fbx).
Geometry and Transformation Data

CityEngine FBX Import Autodesk Maya
trigger Exported scene via FBX in Autodesk Maya. Both "One Mesh Per .." options have
--> i("builtin:cube") s(1,1,1)
t(1,0,1) been disabled too avoid merging any assets. In this case, each asset is parented
set(material.colormap, to a transformation node. Else, the transformation is applied to the vertices.
"uvtest.jpg")
setupUV(0, 0.5, 0.5) bakeUV(0)
Multi-Texturing and Layered Texture Nodes

The CityEngine material model multiplies all six textures (if present) with the For FBX, CityEngine exports multiple textures as
diffuse color. This example displays the layering/multiplicaton of "colormap" "layered texture nodes" whose blend modes are set
and "dirtmap". to "multiply".
If at least one texture is set, Autodesk Maya loses the diffuse color settings upon FBX import, the ambient color is retained.
Working with per-texture transformations

The CityEngine features material attributes to Upon FBX import into maya, CityEngine's tu and tv attributes are mapped to
scale, translate and rotate textures independently the "Offset" parameter of maya's place2dTexture nodes, su/sv are mapped to
of the actual texture coordinates stored inside the the "RepeatUV" parameter and rw is mapped to the "Rotate Frame"
assets: parameter.
material.{...}.tu/tv = translate/offset
texture
material.{...}.su/sv = scale/repeat
texture
material.{...}.rw = rotate texture around
face normal
Further Reading
Alias/Wavefront OBJ
Collada DAE
Renderman RIB
Mentalray MI
Autodesk 3DS
Format Description
3DS is one of the file formats used by the Autodesk 3ds Max software. It was the native file format of the old Autodesk 3D Studio
DOS (releases 1 to 4), which was popular until its successor (3D Studio MAX 1.0) replaced it in April 1996. Having been around
since 1990 (when the first version of 3D Studio DOS was launched), it has grown to become a de facto industry standard for
transferring models between 3D programs, or for storing models for 3D resource catalogs (along with OBJ, which is more frequently
used as a model archiving file format).
Specific Export Options for 3DS

3DS has no additional export options (see general export options).
Further Reading
Wavefront OBJ
Autodesk FBX
Collada DAE
Renderman RIB
Mentalray MI
Massive Exporter
Collada DAE
Format Description
"COLLADA is an XML-based schema for digital asset exchange that enables the use of diverse digital-content-creation tools to
author sophisticated assets for use by 3D applications, including graphics, animation, kinematics, physics, and shader effects.
COLLADA represents authored data in multiple forms, enabling the transformation of assets as they journey from content tools that
use high-level descriptions to run-time applications that require optimized, platform-specific representations. The COLLADA
specification, documentation, and sample code is available at the Khronos.org website at www.khronos.org/collada." -- The
Khronos Group
Specific Export Options for Collada

In addition to the general export options, Collada/DAE adds the following switches:
Option Description
Master File All written geometry files will by linked together by a master collada file.
CGA Mapping to Collada

The following table lists the mapping of the major CityEngine elements to Collada elements. Note: the instancing/multi-texture
behavior of Collada is similar to FBX.
CityEngine Collada Example
Whole Scene or Selection Multiple models are collected and referenced in the
<prefix>_master.dae file:
<library_visual_scenes>
<visual_scene id="VisualSceneNode">
<node id="rootInst_lot1697" type="NODE">
<instance_node
url="./model_lot1697.dae#root_lot1697"/>
</node>
</visual_scene>
</library_visual_scenes>
Model/Shape The following elements are stored in a file per lot, e.g.
model_lot1697.dae:
<scene>
<instance_visual_scene url="#VisualSceneNode"/>
</scene>
Leaf Shapes (with references to assets and materials and optional <library_visual_scenes>
<visual_scene id="VisualSceneNode"
transformation matrices) name="scene_lot1697">
<node id="root_lot1697" type="NODE">
<node id="VisualSceneNode1"
name="mat0_CityEngineMaterial_CE"
type="NODE">
<instance_geometry
name="mat0_CityEngineMaterial_CE"
url="#Geometry">
<bind_material>
<technique_common>
<instance_material
symbol="mat0_CityEngineMaterial_CE"
target="#VisualMaterial">
<bind_vertex_input
semantic="cityengine_colormap"
input_semantic="TEXCOORD"
input_set="0"/>
<bind_vertex_input
semantic="cityengine_dirtmap"
input_semantic="TEXCOORD"
input_set="2"/>
</instance_material>
</technique_common>
</bind_material>
</instance_geometry>
</node>
</node>
</visual_scene>
</library_visual_scenes>
CityEngine Assets/Meshes <library_geometries>
<geometry id="Geometry" name="mesh1">
<mesh>
... <triangles> or <polylist> ...
</mesh>
</geometry>
</library_geometries>
CityEngine Materials <library_materials>
<material id="VisualMaterial"
name="mat0_CityEngineMaterial_CE">
<instance_effect url="#Effect"/>
</material>
</library_materials>
<library_effects>
<effect id="Effect">
<profile_COMMON>
<newparam sid="Image-surface">
<surface type="2D">...</surface>
</newparam>
<newparam sid="Image-sampler">
<sampler2D>...</sampler2D>
</newparam>
<newparam sid="Image1-surface">
<surface type="2D">...</surface>
</newparam>
<newparam sid="Image1-sampler">
<sampler2D>...</sampler2D>
</newparam>
<technique sid="common">
<lambert>
<emission><color>0 0 0
1</color></emission>
<ambient><color>0 0 1 1</color></ambient>
<diffuse>
<texture texture="Image-sampler"
texcoord="cityengine_colormap">
...
</texture>
<texture texture="Image1-sampler"
texcoord="cityengine_dirtmap">
...
</texture>
</diffuse>
...
</lambert>
...
</technique>
</profile_COMMON>
</effect>
</library_effects>
CityEngine Textures <library_images>
<image id="Image">
<init_from>./brickwall2.tif</init_from>
</image>
<image id="Image1">
<init_from>./dirtmap.15.tif</init_from>
</image>
</library_images>
Further Reading
Alias/Wavefront OBJ
Autodesk FBX
Renderman RIB
Mentalray MI
Renderman RIB
Format Description
The RenderMan RIB Specification is an API developed by Pixar to describe three dimensional scenes. It includes the RenderMan
Shading Language.
It is a technical specification for a standard communications protocol between modeling programs and rendering programs capable
of producing photorealistic-quality images. In this way, it is similar to PostScript but for describing 3D scenes rather than 2D page
layouts.
The interface was first published in 1988 and has been used for producing visual effects in many block buster movies like "Star
Wars" or "The Lord of the Rings".
Selecting a RenderMan Installation

CityEngine does not write the RIB files itself, but makes use of any installed renderman package (examples are prman, air,
3delight, aqsis, pixie, etc.).
Please set the path to the corresponding shared library in Edit Preferences Export RenderMan RIB Output Library .
Examples for common RIB output libries are listed in the following table (the library extensions are .so/.dylib/.dll for Linux/OS
X/Windows). These libraries are usually found in a subdirectory called "lib":
Renderer Library (w/o extension)

PRMan (>= 14) libprman-xx.x
3Delight lib3delight
Air airdlink
Aqsis libaqsis_ri2rib
Pixie libri
Specific Export Options for RIB

In addition to the general export options, RIB adds the following switches:
Option Description
Misc If enabled, CityEngine will export additional RIB statements to the master rib file (current camera position of
Options "Perspective" camera and default lights) to make the exported rib files directly renderable without the need for
Include additional tools.
Camera
Data
Misc If enabled, CityEngine will instruct the RIB library to write to compressed/binary rib files (not available with every
Options renderman package).
Write
Compressed
Files
CGA Mapping to RIB

This section explains the mapping of the CityEngine geometry and material data to the RIB elements.
The implementation of the RIB exporter in the CityEngine follows the RIB specification version 3.2. The specification is freely
available at http://www.pixar.com.
Geometry
All meshes are translated using the RiPointsGeneralPolygons API call. All non-empty texture coordinate channels are
appended using custom attributes and the numbering of the texture channel is preserved. For example, a single mesh translates
into RIB like this:
PointsGeneralPolygons [ ... ] [ ... ] [ ... ]
"P" [ ... ]
"facevarying normal N" [ ... ]
"st" [ ... ]
"facevarying float [2] uv1" [ ... ]
Any of the N, st, uv1, .., uv6 attributes are optional, depending on the settings of the export options and presence of texture
coordinates in the mesh.
Material/Shader
CityEngine includes a template RSL shader with a lighting model similar to phong. Upon export the shader is renamed and copied
into the target folder, which is handy for quick visualisation tests (also see export option "Make master file renderable"). The
following interface to the shader is used:
surface DefaultCityEngineShader
(
color diffuseColor = color(1.0, 1.0, 1.0);
color ambientColor = color(0.0, 0.0, 0.0);
color specularColor = color(0.0, 0.0, 0.0);
float shininess = 1.0;
string cityengine_colormap = "";
...
float cityengine_colormapScale[2] = {1, 1};
...
float cityengine_colormapTranslate[2] = {0, 0};
...
float cityengine_colormapRotate = 0.0;
...
varying float uv0[2] = {0,0};
...
)
The mapping from CGA material attributes to the interface is as follows. Please refer to the set operation in the CGA reference for
further details.
RIB CGA material Default Value
[shadername] material.shadername "CityEngineShader"
diffuseColor material.color.{r,g,b} 0.7
ambientColor material.ambient.{r,g,b} 0.0
specularColor material.specular.{r,g,b} 0.0
Opacity (via instance attribute) material.color.a * material.ambient.a 1.0 * 1.0
shininess material.shininess 1.0
cityengine_colormap material.colormap (empty string)
... in similar fashion for the other five maps ...
cityengine_colormapScale[2] material.colormap.{su,sv} 1.0
cityengine_colormapTranslate[2] material.colormap.{tu,tv} 0.0
cityengine_colormapRotW material.colormap.rw 0.0
Instances / Transformations
The geometry objects are called via the ObjectInstance RIB directive. In this way assets can be instanced and the same geometry
can appear with different shaders. Use the "Mesh Granularity" setting to control this. Example:
ObjectBegin 1
PointsGeneralPolygons [ ... ]
ObjectEnd
...
AttributeBegin
Transform [ ... ]
Surface "CityEngineShader" "diffuseColor" [ ... shader arguments ... ]
Opacity [ 1.000000 1.000000 1.000000 ]
ObjectInstance 1
AttributeEnd
...
CityEngine Default RSL Shader

The template rsl shader is located in compressed form in the RIB module (*.jar) of your CityEngine installation and therefore not
directly accessible. Here is a listing:
/*
* Default Renderman Shader (phong) for Procedural's CityEngine
* Author: Simon Haegler (simon.haegler@procedural.com)
*
* $Id: DefaultCityEngineShader.sl 3692 2008-11-03 17:45:13Z shaegler $
*/
surface DefaultCityEngineShader
(
color diffuseColor = color(1.0, 1.0, 1.0);
color ambientColor = color(0.0, 0.0, 0.0);
color specularColor = color(0.0, 0.0, 0.0);
float shininess = 1.0;
string cityengine_colormap = "";
string cityengine_bumpmap = "";
string cityengine_dirtmap = "";
string cityengine_map3 = "";
float cityengine_colormapScale[2] = {1, 1};
float cityengine_bumpmapScale[2] = {1, 1};
float cityengine_dirtmapScale[2] = {1, 1};
float cityengine_map3Scale[2] = {1, 1};
float cityengine_colormapTranslate[2] = {0, 0};
float cityengine_bumpmapTranslate[2] = {0, 0};
float cityengine_dirtmapTranslate[2] = {0, 0};
float cityengine_map3Translate[2] = {0, 0};
float cityengine_colormapRotate = 0.0;
float cityengine_bumpmapRotate = 0.0;
float cityengine_dirtmapRotate = 0.0;
float cityengine_map3Rotate = 0.0;
)
{
// helper variables for texture uv transformation
float rotPivot[2] = {0.5, -0.5};
point p1 = point(rotPivot[0], 0, rotPivot[1]);
point p2 = point(rotPivot[0], 1, rotPivot[1]);
// light independent color (useful to debug)
float Kg = 0.0;
color globalColor = color(1,1,1);
// some magic intensity scalings to make it look good :)
float Ka = 0.3;
float Kd = 0.6;
float Ks = 0.1;
// initialize texture color
color tex = color(1,1,1);
// please note:
// this example shader only uses texture layer 0 and 2 and does not apply uv rotation
if (cityengine_colormap != "")
{
float u = (s - cityengine_colormapTranslate[0]) * cityengine_colormapScale[0];
float v = (t - cityengine_colormapTranslate[1]) * cityengine_colormapScale[1];
tex *= color texture(cityengine_colormap, u, v);
}
if (cityengine_dirtmap != "")
{
float u = (uv2[0] - cityengine_dirtmapTranslate[0]) * cityengine_dirtmapScale[0];
float v = (uv2[1] - cityengine_dirtmapTranslate[1]) * cityengine_dirtmapScale[1];
tex *= color texture(cityengine_dirtmap, u, v);
}
// note: the remaining three texture sets are omitted
/* compute shading variables */
normal Nf = faceforward(normalize(N), I);
vector V = -normalize(I);
/*
* now add it all together
*/
Oi = Os * transparency;
Ci = Os * (Cs * tex * ( Kg * globalColor +
Ka * ambientColor * ambient() +
Kd * diffuseColor * diffuse(Nf) ) +
Ks * specularColor * phong(Nf, V, shininess) );
}
Further Reading
Alias/Wavefront OBJ
Autodesk FBX
Collada DAE
Mentalray MI
Mental Images(r) mental ray / RealityServer
Format Description
mental ray is a production-quality rendering application and scene description language developed by mental images (owned by
Nvidia Corp.). It supports ray tracing to generate images and its feature set and maturity is comparable to that of RenderMan.
Specific Export Options for mental ray/RealityServer

In addition to the general export options, MI adds the following switches:
Option Description
Master Group Specify a name for the instance group in the master file (defaults to 'CityEngineSceneRoot")
File Output
The MI exporter will write the following files:
File Name Description

[name]_[id]_geo.mi The mesh data for the current unit "id" ("id" is either the shape name or a positive integer value,
depending on the file granularity setting).
[name]_[id]_instances.mi The instance definitions (material and transform node assignment) for the current unit "id" ("id" is either
the shape name or a positive integer value, depending on the file granularity setting).
[name]_objects.mi Globally shared textures and shaders.
[name]_master.mi Master file to link together the above files.
CGA Mapping to MI elements

Shader names are filtered and may only contain the characters in [a..zA..Z0..9].
The following examples will set name = "pompeii" and id = "0" from the "File Output" table.
CityEngine mental ray Example
Whole Scene or The objects file and the N geometry and instance files are combined via instgroup in the master file. Example
Selection from the master file:
$include "pompeii_objects.mi"
$include "pompeii_0_geo.mi"
$include "pompeii_0_instances.mi"
instgroup "CityEngineSceneRoot"
"pompeii_0"
end instgroup
Model/Shape All assets/meshes of a model are combined using an instgroup element. Example from an instance file:
...
instance "Window_inst" "Window_geo"
transform
1.000000 0.000000 0.000000 0.000000
0.000000 1.000000 0.000000 0.000000
0.000000 0.000000 1.000000 0.000000
0.000000 0.000000 0.000000 1.000000
material ["Window_material"] ()
end instance
...
instgroup "pompeii_0"
"Window_inst"
"Doorelement_inst"
"Stone_inst"
...
end instgroup
Assets Example from the geometry file:
...
object "Wood_geo"
visible on
group
488.140 2.915 -594.004 // vertex data
...
0.000 1.000 0.000 // normal data
...
0.5851 0.0000 0 // texture coordinate data
...
v 3 n 16 t 22 // face vertex data
...
p 0 1 2 3 // face polygon data
...
end group
end object
...
CityEngine Materials Example from the global objects file:

...
color texture "window_tex" "window.jpg"
...
shader "window_tex_shader" "Texture_lookup2d_ext" (
"texture" "window_tex"
)
...
shader "Window_shader" "CityEngineShader" ( // "CityEngineShader" can be modified with
set(material.shadername, ...)
"diffuse" = "window_tex_shader"
)
material "Window_material" = "Window_shader"
end material
...
Further Reading
Alias/Wavefront OBJ
Autodesk FBX
Collada DAE
Renderman RIB
E-On Software Vue VOB
Format Description
Native object format for polygonal meshes of e-on Software's Vue. CityEngine supports Vue 8.5 and higher. We recommend the
latest version of Vue 9.
Specific Export Options for VOB

VOB has no additional export options (see general export options).
Remarks
VOB only supports a single layer of texture coordinates (CGA uv layer 0).
Further Reading
Wavefront OBJ
Autodesk FBX
Collada DAE
Renderman RIB
Mentalray MI
(PRELIMINARY) Manual for Massive(tm) Exporter
Script Based Export is available in CityEngine Pro only.
Introduction
Please note: this manual and the corresponding tutorial expect a fair knowledge of the Massive software from the reader.
In order to guide agents in a scene in Massive, several concepts for repelling, attracting and guiding are available. These methods
often need to be combined and tweaked in order to get the best results. The Massive export feature is meant to help you with the
selection of this combination by making it easy to switch back and forth between the CityEngine modeling environment and your
Massive setting in order to try out different guiding concepts supplied by Massive. Not only can the included Massive exporter help
you choose the right tool set for your setting, but it also makes possible totally accurate placement of spline points, sound-emitting
agents and more in no time, which would be almost impossible to achieve when trying to do it by hand in massive. In the next
section, an overview over the features available, together with a short explanation is given.
Feature Documentation
In order to export any content from the CityEngine and into Massive, stick to the following scheme:
Create terminal shapes for each object that you would like to have available in the Massive exporter. Note that for intermediate
shapes (shapes that have children on their own) a leaf shape carrying the same name can easily created in your rule file which can
then be used for exporting. If you are creating shapes that only serve as basis for exporting to Massive, it might be a good idea to
design your rule file in way that makes it easy to switch those shapes on and off. This can easily be achieved through the use of
attributes and case statements. In the Massive export dialog, create entries in the list to the left for each terminal shape you want to
deal with. Then, with the entry selected, combine the options to the right in order to get the desired features. For short, depending
on your selection these options may result in the creation of a Massive setup file (*.mas), a Massive agent file ( *.cdl), a terrain map
in .tif format or a combination of these. Note that a setup file (*.mas) containing camera and lighting settings will be created in any
case.
In the following, the options available are treated in more detail.
Sound
Particularly useful for: collision avoidance for thin obstacles with preferably about round collision area (e.g. lamp-poles)
Enabling this option creates agent-locators at each shape belonging to the selected shape group. Per default, these locators are
situated at the 2-dimensional center of gravity of the object in the x-z-plane. In order to only take the lower part of the object into
account (e.g. only the lamp-pole instead of the whole lamp), "get convex 2D hull from object" in the color section must be enabled
and "obstacle height" must be set to a value above 0. Note that colors need not be activated for this to have an effect. A sound
emitting agent is created for each terminal shape that has the sound enabled flag on. This allows each object to have separate
frequency and sound-amplitude. The respective .cdl-file is saved into the same directory as the .mas file and is directly included
into the scene.
provided features: Amplitude and Frequency: these values control the values of the agent's two brain nodes: sound.a and sound.f
respectively.
Colors
Particularly useful for: area avoidance/attraction, action initiation, avoiding large obstacles
Taking advantage of the coloring features eventually yields a terrain map in tif format that is closely related to an orthogonal
projection along the y-axis. The features are thus generally to be understood to be performed on the planar projection of the
terminal shapes chosen.
The provided features include:
Frame Offset: performs a parallel-shift to all edges of the respective 2-dimensional shape. Positive values make the
shape 'bigger', negative values accordingly shrink the shape. Units are meters.
Obstacle Heights and 'get convex 2D hull from object': the combination of these two tells the exporter to only use the
outermost of the projected vertices of the object. Units are meters.
Linear Gradient Enabled: creates a linear gradient consisting of an inner and an outer color. The inner color constitutes
a centered line along the vertex-determined direction (see appendix) of a shape. The Outer color lies on the edge of
the shape. Since an alignment can only be reliably determined for shapes with 4 corners, shapes with other than 4
corners are not supported for this.
Offset only largest two sides: only edges parallel to the vertex-determined direction are offset.
Radial gradient: creates a radial gradient with its inner color situated at the center of the convex hull of the object. The
outer color lies on the circle going through the vertex with largest distance to the calculated center.
Remark: The order of the list of the terminal shape names in the exporter is the one used for coloring as well, so make sure an
element that should be drawn "on top" of another is also placed before it.
Massive Export Gui with Color feature tab open
Flow Fields
Particularly useful for: direction suggestions for agents
Flowfield parameters are written to the Massive setup file (.mas). Following Massives policy, flowfield information is only available
to an agents input channel after it has been manually applied in the Massive flowfield dialog. Note that alpha values exported via
the color feature are discarded once the flowfield informations written to the mas file are applied via this dialog, however this is
usually what is desired anyway.
Provided features:
Angle: 0 degrees corresponds to vertex-determined direction (see appendix), 180 degrees equals reverse direction.
Edge Width and Edge Angle: As in Massive, this parameter lets you create a border area with a seperate flowfield angle
setting: 0 degrees results in same angle as flowfield, +90 degrees yields arrows pointing away, while -90 degrees yields
arrows pointing towards the flowfield center. Edge width is relative to flowfield width, where 1 means whole width.
Total Width: relative width of the flowfield with respect to shape width, where a value of 1 yields same width as shape.
Lanes
Particularly useful for: telling agents exact position on street or sidewalk
As with flowfields, lane information is written to the .mas file and is immediately available to all agents in the scene.
Features provided:
Total Width: relative width of the lane with respect to shape width, where a value of 1 yields same width as shape.
Lane Color: Hue of the lane. Note that due to color conversions to a non-RGB colorspace this may yield slightly
different values than via the other color pick dialogs. In general this difference will probably be unnotable, however.
Resulting export in Massive
The exported .mas loaded in Massive, with the color map assigned
Detail view with Sound elements, Flow fields and Lanes.
Further Reading
Wavefront OBJ Exporter
Script Based Exporter (Python)
Script Based Export is available in CityEngine Pro only.
Format Description
The Script Based Exporter executes a python script during export model generation, without actually writing geometry to a file. See
Python Scripting Interface for details.
To export to a geometry format and execute an export script simultaneously, use the desired format exporter and specify the script
in the export dialog option Script based export (Python).
Specific Export Options for Script Based Exporter (Python)

Option Description
Script Workspace path to python script.
Further Reading
Python Reference
Tutorial 13 Scripted Report Export
Command Reference
Classes
CE
class CE
The interface for attributes scripting the CityEngine.
Methods defined here:

__init__(self, obj=None)
__repr__(self)
__str__(self)
addAttributeLayer(self, name, texture=None, heightmap=None)

Adds a new attribute layer to the current CityEngine scene.
@param name: The name of the new attribute layer. [str]
@param texture: The texture to be used for the layer or null if no texture. (default = None). [str]
@param heightmap: The height to be used for the layer or null if no heightmap. (default = None). [str]
@return: The added layer.
@note: # add a new attribute Layer with name 'new attribute layer', and no texture
l = ce.addAttributeLayer('newAttributeLayer')
# add a new terrain attribute Layer with name 'terrain',
# and the files map.png and elevation.png for texture and heightmap
l = ce.addAttributeLayer('terrain', "map.png", "elevation.png")
addGraphLayer(self, name)
Adds a new graph layer to the current CityEngine scene.
@param name: The name of the new graph layer. [str]
@note: # add a new shape Layer with name 'new graph layer'
ce.addGraphLayer('new graph layer')
addShapeLayer(self, name)
Adds a new shape layer to the current CityEngine scene.
@param name: The name of the new shape layer. [str]
@note: # add a new shape Layer with name 'new shape layer'
ce.addShapeLayer('new shape layer')
alignGraph(self, graph, settings=None)

Align graph network.
@param graph: The set of graph objects to align.
@param settings: The align settings. Omit to use default settings. (default = None).
@note: #align the graph layer 'streets' to the 'Heightmap' layer

graph = ce.getObjectsFrom(ce.scene, ce.withName('streets'))
settings = AlignGraphSettings()
settings.setHeightmap('Heightmap')
ce.alignGraph(graph, settings)
alignShapes(self, shapes, settings=None)

Aligns a set of shapes.
@param shapes: The set of shapes to align.
@param settings: The align settings. Omit to use default settings. (default = None).
@note: # align shape of layer 'Lots' to layer 'Heightmap'

lots = ce.getObjectsFrom(ce.scene, ce.withName("'Lots'"))
settings = AlignShapesSettings()
settings.setAlignfunction(AlignShapesSettings.TRANSLATE_TO_MIN)
ce.alignShapes(lots, settings)
cleanupGraph(self, graph, settings=None)

Cleanup graph networks (intersect segments and merge nodes).
@param graph: The initial set of street graph objects to clean.
@param settings: The cleanup settings. Omit to use default settings. (default = None).
@note: # cleanup alls graph layers in scene

cleanupSettings = CleanupGraphSettings()
cleanupSettings.setIntersectEnabled(True)
cleanupSettings.setMergeEnabled(True)
cleanupSettings.setMergingDist(10)
cleanupSettings.setSnapNodesToEdgesEnabled(True)
cleanupSettings.setSnappingDist(10)
graphlayer = ce.getObjectsFrom(ce.scene, ce.isGraphLayer)
ce.cleanupGraph(graphlayer, cleanupSettings)
closeFile(self, workspacePath=None)
Closes the currently open CityEngine scene or given workspace file.
@param workspacePath: Workspace path of the file to close or null to close current scene. (default = None). [str]
@note: # close the rulefile extrude.cga

ce.closeFile('newcity.cej')
convertToStaticShapes(self, objects)
Get nodes from graph segments.
@param objects: A collection of shapes or graph layers to convert to static shapes.
@return: The created mesh layer.
createGraphSegments(self, layer, vertices)

Create connected graph segments.
@param layer: The graph layer to add the segments to, or 'None' in order to create a new layer.
@param vertices: An array of (unstructured) floating point values. [sequence of float]
@return: The list of created graph segments. [sequence]
@note: # create two graph segments on new layer 'streets'
graphlayer = ce.addGraphLayer('streets')
vertices = [400,0,-200,400,0,-280,480,0,-290]
graph = ce.createGraphSegments(graphlayer, vertices)
vertices = [420,0,-220,350,0,-220]
graph = ce.createGraphSegments(graphlayer, vertices)
createShape(self, layer, vertices)

Create shape.
@param layer: The shape layer to add the segments to, or 'None' in order to create a new layer.
@param vertices: An array of (unstructured) floating point values. [sequence of float]
@return: The created shape.
@note: # create an shape by specifying a vertex list
vertices = [0,300,0,0,300,200,300,300,200,300,300,0]
shape = ce.createShape(None, vertices)
ce.setName(shape, "newShape")
delete(self, object=None)
Deletes objects or a workspace file.
@param object: Objects or a file to delete, or null for current selection. (default = None).
@note: # delete all objects in scene
ce.delete(ce.getObjectsFrom(ce.scene))
deleteAttribute(self, objects, name)

Deletes the named object attribute.
@param objects: The objects to delete the attribute from.

@param name: The attribute name. [str]
@note: # delete the attribute height from the currently selected objects
ce.deleteAttribute(ce.selection(), 'height')
export(self, objects, settings, interactive=False)

Export the given objects.
@param objects: The objects to be exported.
@param settings: The export settings.
@param interactive: Run the export interactive (let user finish dialog). (default = False). [True/False]
generateModels(self, shapes, synchronous=True, updateSeed=False)

Generate the models for the selected shapes.
@param shapes: The set of shapes to use for generation.
@param synchronous: If true, the this operation will block until all models are generated. If false, the generation will take place in the background. (default = True). [True/False]
@param updateSeed: If true, the seed will be updated before generation. (default = False). [True/False]
@note: # generate models on selected shapes

ce.generateModels(ce.selection())
get3DViews(self)
Gets the currently open 3D views.
@return: All open 3D views. [sequence]
@note: # print list of currently opened 3D views
views = ce.get3DViews()
print views
getAttribute(self, object, name)

Get the named object attribute or None if the attribute does not exist.
@param object: The object to get the attribute from.

@return: The object attribute or None if the attribute does not exist.
@note: # print value of attribute 'height' of the currently selected object
print ce.getAttribute(ce.selection()[0], 'height')
getAttributeLayerExtents(self, layer)
Returns the X-Z extents of an attribute layer.
@param layer: The attribute layer to get the extents from.
@return: List consisting of four values. [sequence]
@note: # get position and size of the layer "terrain"
l = ce.getObjectsFrom(ce.scene, ce.isLayer, ce.withName("'terrain'"))[0]
print ce.getAttributeLayerExtents(l)
getAttributeList(self, object)
Get a list of object attributes.
@param object: The object get the attribute list from.
@return: A list of object attribute names. [sequence]
@note: # print a list of all attribute names of the currently selected object
print ce.getAttributeList(ce.selection()[0])
getAttributeSource(self, object, name)

Set the attribute source of the given attribute for the given objects.
@param object: The object to get the attribute source from.
@param name: The name of the attribute of which the source will be returned. [str]
@return: result.
getLayerAttributes(self, layer)
Returns the attribute code of the specified layer.
@param layer: The layer to get the attributes from.
@return: Layer attributes. [str]
@note: # print the layer attributes code of the layer "terrain"
print ce.getLayerAttributes(l)
getModelFromShape(self, shape)
Get model from shape.
@param shape: The shape to return the associated initial model from.
@return: result.
getName(self, object)
Get the name of the specified object (if the object has a name).
@param object: The object to get the name from.
@return: The object's name or null if the object does not provide a name. [str]
@note: # print name of selected object
print ce.getName(ce.selection()[0])
getNodesFromGraphSegments(self, segments)
Get nodes from graph segments.
@param segments: The graph segments to obtain the nodes from.
@return: The list of graph nodes. [sequence]
@note: # get graph nodes of the currently selected graph segment and print it to the console
segment = ce.selection()[0]
nodes = ce.getNodesFromGraphSegments(segment)
print nodes
getObjectsFrom(self, container, *filters)

Get child objects from container with optional filters
@param container: The parent container
@param *filters: Optional filter constraints
@return: The filtered set of child objects
@note: # return list of objects from different containers, using optional filters
sceneobjects = ce.getObjectsFrom(ce.selection)
sceneobjects = ce.getObjectsFrom(ce.scene)
sceneobjects = ce.getObjectsFrom(ce.selection, ce.isShape)
layers = ce.getObjectsFrom(ce.scene, ce.isLayer)
layers = ce.getObjectsFrom(ce.scene, ce.isShapeLayer, ce.withName("*Lot*"))
files = ce.getObjectsFrom("/general/scenes/", ce.isFile)
getPosition(self, objects)
Get the position of the specified objects (calculated as the centroid of all objects' vertices).
@param objects: The objects to get the position from.
@return: An list containing the center [x, y, z]. [sequence]
@note: # print the absolite position in world coordinates of the selected object
print ce.getPosition(ce.selection()[0])
getRuleFile(self, shape)
Gets a shape's rule file.
@param shape: The shape to return the rule file from.
@return: result. [str]
@note: # print rule file of selected shape

print ce.getRuleFile(ce.selection()[0])
getSeed(self, shape)
Gets a shape's seed.
@param shape: The shape to return the seed from.
@return: result.
@note: # print seed of selected shape

print ce.getSeed(ce.selection()[0])
getShapeFromModel(self, model)
Get shape from model.
@param model: The model to return the associated shape from.
@return: result.
@note: #get the shape belonging to the selected model to set an object attribute
model = ce.selection()[0]
shape = ce.getShapeFromModel(model)
ce.setAttribute(shape, 'height', 15)
getStartRule(self, shape)
Gets the start rule for the given shape.
@param shape: The shape to return the start rule from.
@note: # print start rule of selected shape

print ce.getStartRule(ce.selection()[0])
getUUID(self, object)
Get the UUID (Universally Unique Identifier) of the specified layer or layer object.
@param object: The layer or layer object to get the UUID from.
@return: The object's UUID or null if the object is not of required type.
@note: # print UUID (unique ID) of selected object

print ce.getUUID(ce.selection()[0])
getVersion(self)
Gets version field. CityEngine version number.
@return: Value of version field. [str]
getVersionMajor(self)
Gets versionMajor field. CityEngine major number.
@return: Value of versionMajor field. [int]
getVersionMinor(self)
Gets versionMinor field. CityEngine minor number.
@return: Value of versionMinor field. [int]
getVersionString(self)
CityEngine version string.
@note: #print long CityEngine version string

print ce.getVersionString()
getVertices(self, object)
Get the vertices of the specified object.
@param object: The object to get the vertices from.

@return: An list of (unstructured) floating point values of the object's vertices. [sequence]
@note: # print the vertix list of the selected object to the console
print ce.getVertices(ce.selection()[0])
getWorkspaceRoot(self)
Gets the workspace root.
@return: The workspace root ('/'). [str]
growStreets(self, graph, settings=None)

Creates street network starting from an initial set of graph objects.
@param graph: The initial set of street graph objects to grow from.
@param settings: The street grow settings. Omit to use default settings. (default = None).
@note: # grow streets on layer 'streets'
streetlayer = ce.getObjectsFrom(ce.scene, ce.withName("streets"))
growsettings = GrowStreetsSettings()
growsettings.setEnvironmentSettingsHeightmap('Heightmap')
growsettings.setEnvironmentSettingsObstaclemap('Obstacle')
ce.growStreets(streetlayer, growsettings)
importFile(self, filesystemPath, importSettings=None, interactive=False)

Imports objects into the current scene or creates a new scene from the import data.
@param filesystemPath: Path to the source file (must be a filesystem path). [str]
@param importSettings: The import settings to apply or null for default settings. (default = None).
@param interactive: Run the import interactively (open dialog and let user finish). (default = False). [True/False]
@return: A list of newly created layers. [sequence]
@note: # import the dxf file 'sesame_streetsketch.dxf' into the scene
settings = DXFImportSettings()
settings.setScale(0.5)
settings.setOffset([-6000,0,0])
ce.importFile(ce.toFSPath("/general/data/sesame_streetsketch.dxf"), settings)
inspect(self, objects)
Opens the inspector and selects the given objects.
@param objects: The objects to inspect.
@note: # show 'sphere.obj' in the inspector view
ce.inspect('/general/assets/sphere.obj')
isBlock(self, object)
Predicate that tests if the given object is a block.
@param object: The object to be tested.
@return: True if the object is a block or false otherwise. [True/False]
isEnvironmentLayer(self, object)
Predicate that tests if the given object is an environment layer.
@return: True if the object is an environment layer or false otherwise. [True/False]
@note: # create a list of all environment layers in the scene and print it
envLayers = ce.getObjectsFrom(ce.scene, ce.isEnvironmentLayer)
print envLayers
isFile(self, workspacePath)
Predicate that tests if the given workspace path is an existing file.
@param workspacePath: Workspace path of the file to test . [str]
@return: True if the given workspace path is an existing file or false otherwise. [True/False]
@note: # print a list of all files in the workspace directory 'general/assets/textures/facade/'
print ce.getObjectsFrom('/general/assets/textures/facade/', ce.isFile)
isFolder(self, workspacePath)
Predicate that tests if the given workspace path is an existing folder.
@param workspacePath: Workspace path of the folder to test. [str]
@return: True if the given workspace path is an existing folder or false otherwise. [True/False]
@note: # print a list of all folder in the workspace directory 'general/assets'
print ce.getObjectsFrom('/general/assets/', ce.isFolder)
isGraphLayer(self, object)
Predicate that tests if the given object is a graph layer.
@return: True if the object is a graph layer or false otherwise. [True/False]
@note: # create a list of all graph layers in the scene and print it
graphLayers = ce.getObjectsFrom(ce.scene, ce.isGraphLayer)
print graphLayers
isGraphNode(self, object)
Predicate that tests if the given object is a graph node.
@return: True if the object is a graph node or false otherwise. [True/False]
@note: # create list of graph nodes and print it to the console
nodes = ce.getObjectsFrom(ce.selection, ce.isGraphNode)
print nodes
isGraphSegment(self, object)
Predicate that tests if the given object is a graph segment.
@return: True if the object is a graph segment or false otherwise. [True/False]
@note: # create list of graph segments and print it to the console

segments = ce.getObjectsFrom(ce.scene, ce.isGraphSegment)
print str(len(segments)) + " street segments in scene"
isInspector(self, view)
Predicate that tests if the given 3D view is an inspector view.
@param view: A 3D view obtained from get3DViews().
@return: True if the given 3D view is an inspector view or false otherwise. [True/False]
@note: # filter inspectors from list of views

inspectorviews = ce.getObjectsFrom(ce.get3DViews(), ce.isInspector)
print inspectorviews
isLayer(self, object)
Predicate that tests if the given object is a layer.
@return: True if the object is a layer or false otherwise. [True/False]
@note: # create a list of all environment layers in the scene and print it
layers = ce.getObjectsFrom(ce.scene, ce.isLayer)
print layers
isModel(self, object)
Predicate that tests if the given object is a generated model.
@return: True if the object is a model or false otherwise. [True/False]
@note: # test if a object is a model

model = ce.getModelFromShape(ce.selection()[0])
if ce.isModel(model) : print "yes"
else : print "no"
isShape(self, object)
Predicate that tests if the given object is a shape.
@return: True if the object is a shape or false otherwise. [True/False]
@note: # count all shapes in scene

shapes = ce.getObjectsFrom(ce.scene, ce.isShape)
print len(shapes)
# test if selected object is a shape
object = ce.selection()[0]
if ce.isShape(object) : print ce.getName(object)+" is a shape"
else : print ce.getName(object) + "is not a shape"
isShapeLayer(self, object)
Predicate that tests if the given object is a shape layer.
@return: True if the object is a shape layer or false otherwise. [True/False]
@note: # create a list of all shape layers in the scene and print it
shapeLayers = ce.getObjectsFrom(ce.scene, ce.isShapeLayer)
print shapeLayers
isViewport(self, view)
Predicate that tests if the given 3D view is a CityEngine viewport.
@param view: A 3D view obtained from get3DViews().
@return: True if the given 3D view is an CityEngine viewport or false otherwise. [True/False]
@note: # filter viewports from list of views

viewports = ce.getObjectsFrom(ce.get3DViews(), ce.isViewport)
print viewports
move(self, objects, t, objectSpace=False, pivot=None)

Move (translate) the current selection or the specified objects.
@param objects: The objects to be moved.
@param t: XYZ translation vector.
@param objectSpace: Transform in object space. (default = False). [True/False]
@param pivot: Set pivot for transformation. (default = None).
@note: # move the selected object in world coordinates by 10 in x and 600 in y axis
t = [10,600,0]
ce.move(object, t)
newFile(self, workspacePath, interactive=False)

Creates a new workspace file.
@param workspacePath: Workspace path of the file to create. [str]

@param interactive: Run the new dialog interactively (let user finish). (default = False). [True/False]
@return: The created file.
@note: # create a new scene city.cej in the current project
ce.newFile('newcity.cej')
openFile(self, workspacePath=None)
Opens a file in the workspace.
@param workspacePath: Workspace path of the file to open or null to show a file dialog. (default = None). [str]
@return: The newly opened window.
@note: # open the scene city.cej in the project general

ce.openFile('/general/scenes/city.cej')
openView(self, view)
Opens workspace view.
@param view: One of ['VIEWPORT','INSPECTOR','NAVIGATOR']. [str]

@note: # open inspector view
ce.openView("INSPECTOR")
refreshWorkspace(self)
Refreshes the workspace.
@note: # refresh the workspace (check for new and modified files)
ce.refreshWorkspace()
rotate(self, objects, r, objectSpace=False, pivot=None)
Rotate the current selection or the specified objects.
@param objects: The objects to be rotated.
@param r: XYZ rotation vector.
@note: # rotate the selected object 70 degrees around the global y axis using its local center
r = [0,70,0]
ce.rotate(object, r)
sampleBooleanLayerAttribute(self, layer, name, x, z)

Returns the sampled value of an layer's boolean attribute at given X-Z location.
@param layer: The layer to sample from.
@param x: The X position. [float]
@param z: The Z position. [float]
@return: Sampled value. [True/False]
@note: # get value of bool attribute "obstacle" in attribute layer "Obstacle" at position x=1000, z=0
obstacleLayer = ce.getObjectsFrom(ce.scene, ce.withName("'Obstacle'"))[0]
print ce.sampleBooleanLayerAttribute(obstacleLayer, "obstacle", 1000, 0)
sampleFloatLayerAttribute(self, layer, name, x, z)

Returns the sampled value of an layer's float attribute at given X-Z location.
@return: Sampled value. [float]
@note: # get value of string attribute "name" in shape layer "LotsSouth" at position x=-500, z=1790
lotLayer = ce.getObjectsFrom(ce.scene, ce.withName("'LotsSouth'"))[0]
print ce.sampleStringLayerAttribute(lotLayer, "name", -500, 1790)
sampleStringLayerAttribute(self, layer, name, x, z)

Returns the sampled value of an layer's string attribute at given X-Z location.
@return: Sampled value. [str]
saveFile(self, workspacePath=None)
Saves an open file.
@param workspacePath: Workspace path of the file to save or null to save the current scene. (default = None). [str]
@note: # save the open scene
ce.saveFile()
scale(self, objects, s, objectSpace=False, pivot=None)

Scale the current selection or the specified objects.
@param objects: The objects to be scaled.
@param s: XYZ scale vector or uniform scale value.
@note: # scale the selected object in world x and z axes using its local center
s = [8,1,7]
ce.scale(object, s)
scene(self)
Gets the current CityEngine scene.
@return: the current CityEngine scene.
@note: # print the name of the currently opened scene

print ce.scene()
#get a list of all shapes in the scene
shapes = ce.getObjectsFrom(ce.scene, ce.isShape)
selection(self)
Gets the current CityEngine selection.
@return: The current CityEngine selection. [sequence]
@note: # print a list of selected objects to the console

print ce.selection()
setAttribute(self, objects, name, value)

Set the named object attribute to the given value(s) for the given objects.
@param objects: The objects to set the attributes to.
@param value: The new attribute value or sequence or map.
@note: # add or overwrite attribute 'area' with value 5 on selected object
ce.setAttribute(ce.selection()[0], 'height', 12)
# add or overwrite attribute array 'streetWidth' on selected object
ce.setAttribute(ce.selection()[0], 'streetWidth', [0,0,12,0])
setAttributeLayerExtents(self, layer, extents)

Returns the X-Z extents of an attribute layer.
@param layer: The attribute layer to set the extents to.
@param extents: An list of four floating point values. [sequence of float]
@note: # set position (0,20) and size (3000,4000 of the layer "terrain"
ce.setAttributeLayerExtents(l, [0,20,3000,4000])
setAttributeSource(self, objects, name, source)

Set the attribute source of the given attribute for the given objects.
@param objects: The objects to set the attribute source to.
@param name: The name of the attribute of which the source will be set. [str]
@param source: The new attribute source. Either 'OBJECT' for object source, 'USER' for user source, 'RULE' for rule source, 'DEFAULT' for default source, or an attribute layer for an attribute layer.
@note: # add a new object attribute 'height' with value 5 to the selected shapes and change its source to OBJECT to overwrite the value coming from the rulefile
ce.setAttribute(ce.selection(), 'height', 5)
ce.setAttributeSource(ce.selection(), 'height', 'OBJECT')
setLayerAttributes(self, layer, code)

Set the attribute code of the specified layer.
@param layer: The layer to set the attributes to.
@param code: The function attribute code to be set. [str]
@note: # set the attribute elevation in the layer attribute code of the layer "terrain"
ce.setLayerAttributes(l, "attr elevation = brightness*50")
setName(self, objects, name)

Set the name of the specified object.
@param objects: The objects to set the name to.
@param name: The name to be set. [str]
@note: # set name of selected object to 'new Shape'
ce.setName(ce.selection()[0], 'my Shape')
setPosition(self, objects, position)

Set the position of the specified objects.
@param objects: The layer or layer objects to set the position to.
@param position: An list containing the center [x, y, z] .
@note: # set the ansolute position in world coordinates of the selected object
position = [0,0,1000]
ce.setPosition(object, position)
setRuleFile(self, shapes, workspacePath=None, hasToExist=False)

Assigns a rule file to shapes.
@param shapes: The set of shapes to assign the rule file to.
@param workspacePath: The workspace path of the CGA rule file to assign, or None to interactively select a file. (default = None). [str]
@param hasToExist: Assign the CGA rule file only if it exists. (default = False). [True/False]
@note: # assign the rulefile extrude.cga to all selected shapes
ce.setRuleFile(ce.selection(), 'extrude.cga')
setSeed(self, shapes, seed=None)

Sets the seed of shapes.
@param shapes: The set of shapes to set the seed.
@param seed: The new seed to be set or None to reset the seed. (default = None).
@note: # set seed of selected shape to 1234
ce.setSeed(ce.selection()[0], 1234)
setSelection(self, object)
Sets the current CityEngine selection to the given object(s).
@param object: The objects to select.
@note: # select shape with name 'new Shape'

shapes = ce.getObjectsFrom(ce.scene, ce.withName("'new Shape'"))
ce.setSelection(shapes)
setStartRule(self, shapes, rule)

Sets the start rule for the given shapes.
@param shapes: The set of shapes to set the start rule.
@param rule: The new start rule. [str]
@note: # set start rule of selected shape to 'Park'
ce.setStartRule(ce.selection()[0], 'Park')
setVertices(self, object, vertices)

Set vertices of the specified object.
@param object: The object to set the vertices to.
@param vertices: An list of (unstructured) floating point values. The size of the array must be the same as the size of array that getVertices returns. [sequence of float]
@note: # modify the vertices of the selected object by specifying a vertex list
vertices = [10,0,0,0,0,20,30,0,40,50,0,0]
ce.setVertices(ce.selection()[0], vertices)
subdivideShapes(self, shapes, settings=None)

Subdivides a set of shapes.
@param shapes: The set of shapes to subdivide.
@param settings: The subdivision settings. Omit to use default settings. (default = None).
@note: # subdivide shapes in scene
shapes = ce.getObjectsFrom(ce.scene, ce.isShape, ce.withName("'Block 1'"))
subdsettings = SubdivideShapesSettings()
subdsettings.setLotAreaMax(800)
ce.subdivideShapes(shapes, subdsettings)
toFSPath(self, workspacePath)
Converts the local (workspace) path to an absolute file system path.
@param workspacePath: Workspace path to convert to a absolute file system path. [str]
@return: An absolute file system path. [str]
@note: # print the absolute path of the file 'city.cej' to the console
print ce.toFSPath('city.cej')
waitForUIIdle(self)
Wait until the user interface is idle (e.g. no UI action is running and all animations have finished).
@note: # pause script until frame() finishes

views = ce.getObjectsFrom(ce.get3DViews())
views[0].frame()
ce.waitForUIIdle()
print "frame finished"
withName(self, pattern)
Matches for a given file name pattern.
@param pattern: The pattern. [str]
@return: A matcher for the given pattern.
@note: # get a list of all scene objects whose name starts with 'Lot'
lotobjects = ce.getObjectsFrom(ce.scene, ce.withName("'Lot 824*'"))
print lotobjects
# get object whose name is exactly 'new Shape'
lot = ce.getObjectsFrom(ce.scene, ce.withName("'new Shape'"))
print lot
Data and other attributes defined here:

INSPECTOR = 'INSPECTOR'
NAVIGATOR = 'NAVIGATOR'
VIEWPORT = 'VIEWPORT'

Command Reference
Classes
Model
class Model
Model object.

__repr__(self)
__str__(self)
getReports(self)
Get the reports associated with this model.
@return: Returns the reports as a map of lists.

@note: # getReports can only be used in the script based exporter callback functions
# Return the collected list of all reported 'height' values per model during export
def finishModel(exportContextUUID, initialShapeUUID, modelUUID):
reports = model.getReports()['height']

Command Reference
Classes
AlignGraphSettings
class AlignGraphSettings
Graph align settings.
@note: # Settings class used to control parameters for alignGraph algorithm
graph = ce.getObjectsFrom(ce.scene, ce.withName('streets'))
settings = AlignGraphSettings()
ce.alignGraph(graph, settings)

__repr__(self)
__str__(self)
getAlignFunction(self)
Gets AlignFunction field. Specifies the alignment function.
@return: Value of AlignFunction field.
getAlignfunction(self)
Gets Alignfunction field. Specifies the alignment function.
@return: Value of Alignfunction field. ["PROJECT_ALL", "PROJECT_BELOW", "PROJECT_TO_OBJ_AVG", "TRANSLATE_TO_AVG", "TRANSLATE_TO_MAX", "TRANSLATE_TO_MIN"] [str]
getHeightmap(self)
Gets Heightmap field. Specifies the heightmap to align to. Use "y = 0" for alignment to X-Z plane.
@return: Value of Heightmap field. [str]
getOffset(self)
Gets Offset field. Y-Offset to be added to the aligned vertices.
@return: Value of Offset field. [float]
setAlignFunction(self, voidValue)
Sets AlignFunction field. Specifies the alignment function.
@param voidValue: the new value.
setAlignfunction(self, enumValue)
Sets Alignfunction field. Specifies the alignment function.
@param enumValue: the new value ["PROJECT_ALL", "PROJECT_BELOW", "PROJECT_TO_OBJ_AVG", "TRANSLATE_TO_AVG", "TRANSLATE_TO_MAX", "TRANSLATE_TO_MIN"]. [str]
setHeightmap(self, stringValue)
Sets Heightmap field. Specifies the heightmap to align to. Use "y = 0" for alignment to X-Z plane.
@param stringValue: the new value. [str]
setOffset(self, floatValue)
Sets Offset field. Y-Offset to be added to the aligned vertices.
@param floatValue: the new value. [float]

PROJECT_ALL = 'PROJECT_ALL'
PROJECT_BELOW = 'PROJECT_BELOW'
PROJECT_TO_OBJ_AVG = 'PROJECT_TO_OBJ_AVG'
TRANSLATE_TO_AVG = 'TRANSLATE_TO_AVG'
TRANSLATE_TO_MAX = 'TRANSLATE_TO_MAX'
TRANSLATE_TO_MIN = 'TRANSLATE_TO_MIN'

Command Reference
Classes
CleanupGraphSettings
class CleanupGraphSettings
Graph cleanup settings.
@note: # Settings class used to control parameters for cleanupGraph algorithm

cleanupSettings = CleanupGraphSettings()
cleanupSettings.setIntersectEnabled(True)
cleanupSettings.setMergeEnabled(True)
cleanupSettings.setMergingDist(10)
cleanupSettings.setSnapNodesToEdgesEnabled(True)
cleanupSettings.setSnappingDist(10)
graphlayer = ce.getObjectsFrom(ce.scene, ce.isGraphLayer)
ce.cleanupGraph(graphlayer, cleanupSettings)

__repr__(self)
__str__(self)
getIntersectEnabled(self)
Gets IntersectEnabled field.
@return: Value of IntersectEnabled field.
getMergeEnabled(self)
Gets MergeEnabled field.
@return: Value of MergeEnabled field.
getMergingDist(self)
Gets mergingDist field. The maximal distance between two nodes that are merged.
@return: Value of mergingDist field. [float]
getSnapNodesToEdgesEnabled(self)
Gets SnapNodesToEdgesEnabled field.
@return: Value of SnapNodesToEdgesEnabled field.
getSnappingDist(self)
Gets snappingDist field. Before intersections are detected, graph sgement are extended by this distance.
@return: Value of snappingDist field. [float]
setIntersectEnabled(self, voidValue)
Sets IntersectEnabled field.
setMergeEnabled(self, voidValue)
Sets MergeEnabled field.
setMergingDist(self, floatValue)
Sets mergingDist field. The maximal distance between two nodes that are merged.
setSnapNodesToEdgesEnabled(self, voidValue)
Sets SnapNodesToEdgesEnabled field.
setSnappingDist(self, floatValue)
Sets snappingDist field. Before intersections are detected, graph sgement are extended by this distance.

Command Reference
Classes
GrowStreetsSettings
class GrowStreetsSettings
Grow streets settings.
@note: # Settings class used to control parameters for growStreets algorithm

streetlayer = ce.getObjectsFrom(ce.scene, ce.withName("streets"))
growsettings = GrowStreetsSettings()
growsettings.setBasicSettingsPatternofmajorstreets(GrowStreetsSettings.RADIAL)
growsettings.setBasicSettingsPatternofminorstreets(GrowStreetsSettings.RADIAL)
growsettings.setEnvironmentSettingsHeightmap('Heightmap')
growsettings.setEnvironmentSettingsObstaclemap('Obstacle')
ce.growStreets(streetlayer, growsettings)

__repr__(self)
__str__(self)
getAdvancedSettingsAngleoffsetofmajorstreets(self)
Gets AdvancedSettingsAngleoffsetofmajorstreets field. Offset angle which is added to every major street before creation (e.g. to create spiral street patterns).
@return: Value of AdvancedSettingsAngleoffsetofmajorstreets field. [float]
getAdvancedSettingsAngleoffsetofminorstreets(self)
Gets AdvancedSettingsAngleoffsetofminorstreets field. Offset angle which is added to every minor street before creation (e.g. to create spiral street patterns).
@return: Value of AdvancedSettingsAngleoffsetofminorstreets field. [float]
getAdvancedSettingsDevelopmentcenterpreference(self)
Gets AdvancedSettingsDevelopmentcenterpreference field. Development center sampling preference. Corresponds to the number of samples before taking the node which is the nearest to the center.
@return: Value of AdvancedSettingsDevelopmentcenterpreference field. [int]
getAdvancedSettingsMinimalangle(self)
Gets AdvancedSettingsMinimalangle field. If a new street intersects/snaps with the existing streetnetwork and the in-between angle is below this threshold, the new street is dismissed.
@return: Value of AdvancedSettingsMinimalangle field. [float]
getAdvancedSettingsSnappingdistance(self)
Gets AdvancedSettingsSnappingdistance field. New street nodes within this distance to existing streets or nodes are snapped.
@return: Value of AdvancedSettingsSnappingdistance field. [float]
getAdvancedSettingsStreettocrossingratio(self)
Gets AdvancedSettingsStreettocrossingratio field. The approximate ratio between the number of major street and crossings. A high ratio leads to larger quarters.
@return: Value of AdvancedSettingsStreettocrossingratio field. [float]
getBasicSettingsLonglength(self)
Gets BasicSettingsLonglength field. Average length of long streets (for both types major and minor).
@return: Value of BasicSettingsLonglength field. [float]
getBasicSettingsLonglengthdeviation(self)
Gets BasicSettingsLonglengthdeviation field. Length deviation of long streets. New street lengths are between the average length minus this deviation and the average length plus this deviation.
@return: Value of BasicSettingsLonglengthdeviation field. [float]
getBasicSettingsNumberofstreets(self)
Gets BasicSettingsNumberofstreets field. Number of streets to be generated (due to intersections, more objects may emerge).
@return: Value of BasicSettingsNumberofstreets field. [int]
getBasicSettingsPatternofmajorstreets(self)
Gets BasicSettingsPatternofmajorstreets field. Street pattern for major streets.
@return: Value of BasicSettingsPatternofmajorstreets field. ["ORGANIC", "RASTER", "RADIAL"] [str]
getBasicSettingsPatternofminorstreets(self)
Gets BasicSettingsPatternofminorstreets field. Street pattern for minor streets.
@return: Value of BasicSettingsPatternofminorstreets field. ["ORGANIC", "RASTER", "RADIAL"] [str]
getBasicSettingsShortlength(self)
Gets BasicSettingsShortlength field. Average length of short streets (for both types major and minor).
@return: Value of BasicSettingsShortlength field. [float]
getBasicSettingsShortlengthdeviation(self)
Gets BasicSettingsShortlengthdeviation field. Length deviation of short streets. New street lengths are between the average length minus this deviation and the average length plus this deviation.
@return: Value of BasicSettingsShortlengthdeviation field. [float]
getEnvironmentSettingsAdaptionangle(self)
Gets EnvironmentSettingsAdaptionangle field. The maximal angle a street is adapted towards the left or right side.
@return: Value of EnvironmentSettingsAdaptionangle field. [float]
getEnvironmentSettingsAdapttoelevation(self)
Gets EnvironmentSettingsAdapttoelevation field. If true streets adapt to terrain elevation.
@return: Value of EnvironmentSettingsAdapttoelevation field. [True/False]
getEnvironmentSettingsCriticalslope(self)
Gets EnvironmentSettingsCriticalslope field. Streets with slopes higher than this critical slope (in degrees) adapt to elevation.
@return: Value of EnvironmentSettingsCriticalslope field. [float]
getEnvironmentSettingsHeightmap(self)
Gets EnvironmentSettingsHeightmap field. The height map used for the adaption to elevation.
@return: Value of EnvironmentSettingsHeightmap field. [str]
getEnvironmentSettingsMaximalslope(self)
Gets EnvironmentSettingsMaximalslope field. The maximal legal street slope (in degrees), new streets above this threshold are dismissed.
@return: Value of EnvironmentSettingsMaximalslope field. [float]
getEnvironmentSettingsObstaclemap(self)
Gets EnvironmentSettingsObstaclemap field. The obstacle map which defines the environment obstacles.
@return: Value of EnvironmentSettingsObstaclemap field. [str]
getPatternSpecificSettingsCitycenterxradial(self)
Gets PatternSpecificSettingsCitycenterxradial field. X-coordinate of city center of radial streets.
@return: Value of PatternSpecificSettingsCitycenterxradial field. [float]
getPatternSpecificSettingsCitycenterzradial(self)
Gets PatternSpecificSettingsCitycenterzradial field. Z-coordinate of city center of radial streets.
@return: Value of PatternSpecificSettingsCitycenterzradial field. [float]
getPatternSpecificSettingsMaxbendangleorganic(self)
Gets PatternSpecificSettingsMaxbendangleorganic field. Maximal bend angle of organic streets.
@return: Value of PatternSpecificSettingsMaxbendangleorganic field. [float]
getPatternSpecificSettingsMaxbendangleradial(self)
Gets PatternSpecificSettingsMaxbendangleradial field. Maximale bend angle of radial streets.
@return: Value of PatternSpecificSettingsMaxbendangleradial field. [float]
getPatternSpecificSettingsStreetAlignmentradial(self)
Gets PatternSpecificSettingsStreetAlignmentradial field. Alignment of the long radial streets.
@return: Value of PatternSpecificSettingsStreetAlignmentradial field. ["RADIAL", "CENTRIPETAL", "RANDOM"] [str]
getStreetWidthSettingsSidewalkwidthdeviationofmajorstreets(self)
Gets StreetWidthSettingsSidewalkwidthdeviationofmajorstreets field. Width deviation of major street sidewalks.
@return: Value of StreetWidthSettingsSidewalkwidthdeviationofmajorstreets field. [float]
getStreetWidthSettingsSidewalkwidthdeviationofminorstreets(self)
Gets StreetWidthSettingsSidewalkwidthdeviationofminorstreets field. Width deviation of minor street sidewalks.
@return: Value of StreetWidthSettingsSidewalkwidthdeviationofminorstreets field. [float]
getStreetWidthSettingsSidewalkwidthofmajorstreets(self)
Gets StreetWidthSettingsSidewalkwidthofmajorstreets field. Average width of major street sidewalks.
@return: Value of StreetWidthSettingsSidewalkwidthofmajorstreets field. [float]
getStreetWidthSettingsSidewalkwidthofminorstreets(self)
Gets StreetWidthSettingsSidewalkwidthofminorstreets field. Average width of minor street sidewalks.
@return: Value of StreetWidthSettingsSidewalkwidthofminorstreets field. [float]
getStreetWidthSettingsWidthdeviationofmajorstreets(self)
Gets StreetWidthSettingsWidthdeviationofmajorstreets field. New street widths are between the average width minus this deviation and the average width plus this deviation.
@return: Value of StreetWidthSettingsWidthdeviationofmajorstreets field. [float]
getStreetWidthSettingsWidthdeviationofminorstreets(self)
Gets StreetWidthSettingsWidthdeviationofminorstreets field. New street widths are between the average width minus this deviation and the average width plus this deviation.
@return: Value of StreetWidthSettingsWidthdeviationofminorstreets field. [float]
getStreetWidthSettingsWidthofmajorstreets(self)
Gets StreetWidthSettingsWidthofmajorstreets field. Average width of major streets.
@return: Value of StreetWidthSettingsWidthofmajorstreets field. [float]
getStreetWidthSettingsWidthofminorstreets(self)
Gets StreetWidthSettingsWidthofminorstreets field. Average width of side streets.
@return: Value of StreetWidthSettingsWidthofminorstreets field. [float]
setAdvancedSettingsAngleoffsetofmajorstreets(self, floatValue)
Sets AdvancedSettingsAngleoffsetofmajorstreets field. Offset angle which is added to every major street before creation (e.g. to create spiral street patterns).
setAdvancedSettingsAngleoffsetofminorstreets(self, floatValue)
Sets AdvancedSettingsAngleoffsetofminorstreets field. Offset angle which is added to every minor street before creation (e.g. to create spiral street patterns).
setAdvancedSettingsDevelopmentcenterpreference(self, intValue)
Sets AdvancedSettingsDevelopmentcenterpreference field. Development center sampling preference. Corresponds to the number of samples before taking the node which is the nearest to the center.
@param intValue: the new value. [int]
setAdvancedSettingsMinimalangle(self, floatValue)
Sets AdvancedSettingsMinimalangle field. If a new street intersects/snaps with the existing streetnetwork and the in-between angle is below this threshold, the new street is dismissed.
setAdvancedSettingsSnappingdistance(self, floatValue)
Sets AdvancedSettingsSnappingdistance field. New street nodes within this distance to existing streets or nodes are snapped.
setAdvancedSettingsStreettocrossingratio(self, floatValue)
Sets AdvancedSettingsStreettocrossingratio field. The approximate ratio between the number of major street and crossings. A high ratio leads to larger quarters.
setBasicSettingsLonglength(self, floatValue)
Sets BasicSettingsLonglength field. Average length of long streets (for both types major and minor).
setBasicSettingsLonglengthdeviation(self, floatValue)
Sets BasicSettingsLonglengthdeviation field. Length deviation of long streets. New street lengths are between the average length minus this deviation and the average length plus this deviation.
setBasicSettingsNumberofstreets(self, intValue)
Sets BasicSettingsNumberofstreets field. Number of streets to be generated (due to intersections, more objects may emerge).
setBasicSettingsPatternofmajorstreets(self, enumValue)
Sets BasicSettingsPatternofmajorstreets field. Street pattern for major streets.
@param enumValue: the new value ["ORGANIC", "RASTER", "RADIAL"]. [str]
setBasicSettingsPatternofminorstreets(self, enumValue)
Sets BasicSettingsPatternofminorstreets field. Street pattern for minor streets.
@param enumValue: the new value ["ORGANIC", "RASTER", "RADIAL"]. [str]
setBasicSettingsShortlength(self, floatValue)
Sets BasicSettingsShortlength field. Average length of short streets (for both types major and minor).
setBasicSettingsShortlengthdeviation(self, floatValue)
Sets BasicSettingsShortlengthdeviation field. Length deviation of short streets. New street lengths are between the average length minus this deviation and the average length plus this deviation.
setEnvironmentSettingsAdaptionangle(self, floatValue)
Sets EnvironmentSettingsAdaptionangle field. The maximal angle a street is adapted towards the left or right side.
setEnvironmentSettingsAdapttoelevation(self, booleanValue)
Sets EnvironmentSettingsAdapttoelevation field. If true streets adapt to terrain elevation.
@param booleanValue: the new value. [True/False]
setEnvironmentSettingsCriticalslope(self, floatValue)
Sets EnvironmentSettingsCriticalslope field. Streets with slopes higher than this critical slope (in degrees) adapt to elevation.
setEnvironmentSettingsHeightmap(self, stringValue)
Sets EnvironmentSettingsHeightmap field. The height map used for the adaption to elevation.
setEnvironmentSettingsMaximalslope(self, floatValue)
Sets EnvironmentSettingsMaximalslope field. The maximal legal street slope (in degrees), new streets above this threshold are dismissed.
setEnvironmentSettingsObstaclemap(self, stringValue)
Sets EnvironmentSettingsObstaclemap field. The obstacle map which defines the environment obstacles.
setPatternSpecificSettingsCitycenterxradial(self, floatValue)
Sets PatternSpecificSettingsCitycenterxradial field. X-coordinate of city center of radial streets.
setPatternSpecificSettingsCitycenterzradial(self, floatValue)
Sets PatternSpecificSettingsCitycenterzradial field. Z-coordinate of city center of radial streets.
setPatternSpecificSettingsMaxbendangleorganic(self, floatValue)
Sets PatternSpecificSettingsMaxbendangleorganic field. Maximal bend angle of organic streets.
setPatternSpecificSettingsMaxbendangleradial(self, floatValue)
Sets PatternSpecificSettingsMaxbendangleradial field. Maximale bend angle of radial streets.
setPatternSpecificSettingsStreetAlignmentradial(self, enumValue)
Sets PatternSpecificSettingsStreetAlignmentradial field. Alignment of the long radial streets.
@param enumValue: the new value ["RADIAL", "CENTRIPETAL", "RANDOM"]. [str]
setStreetWidthSettingsSidewalkwidthdeviationofmajorstreets(self, floatValue)
Sets StreetWidthSettingsSidewalkwidthdeviationofmajorstreets field. Width deviation of major street sidewalks.
setStreetWidthSettingsSidewalkwidthdeviationofminorstreets(self, floatValue)
Sets StreetWidthSettingsSidewalkwidthdeviationofminorstreets field. Width deviation of minor street sidewalks.
setStreetWidthSettingsSidewalkwidthofmajorstreets(self, floatValue)
Sets StreetWidthSettingsSidewalkwidthofmajorstreets field. Average width of major street sidewalks.
setStreetWidthSettingsSidewalkwidthofminorstreets(self, floatValue)
Sets StreetWidthSettingsSidewalkwidthofminorstreets field. Average width of minor street sidewalks.
setStreetWidthSettingsWidthdeviationofmajorstreets(self, floatValue)
Sets StreetWidthSettingsWidthdeviationofmajorstreets field. New street widths are between the average width minus this deviation and the average width plus this deviation.
setStreetWidthSettingsWidthdeviationofminorstreets(self, floatValue)
Sets StreetWidthSettingsWidthdeviationofminorstreets field. New street widths are between the average width minus this deviation and the average width plus this deviation.
setStreetWidthSettingsWidthofmajorstreets(self, floatValue)
Sets StreetWidthSettingsWidthofmajorstreets field. Average width of major streets.
setStreetWidthSettingsWidthofminorstreets(self, floatValue)
Sets StreetWidthSettingsWidthofminorstreets field. Average width of side streets.

CENTRIPETAL = 'CENTRIPETAL'
ORGANIC = 'ORGANIC'
RADIAL = 'RADIAL'
RANDOM = 'RANDOM'
RASTER = 'RASTER'

Command Reference
Classes
SubdivideShapesSettings
class SubdivideShapesSettings
Shape subdivision settings.
@note: # Settings class used to control parameters for subdivde shapes algorithm
shapes = ce.getObjectsFrom(ce.scene, ce.isShape, ce.withName("'Block 1'"))
subdsettings = SubdivideShapesSettings()
subdsettings.setLotAreaMax(800)
ce.subdivideShapes(shapes, subdsettings)
##exampleRef:CE.getModelFromShape
# print model attached to currently selected shape
shape = ce.selection()[0]
print shape
model = ce.getModelFromShape(shape)
print model

__repr__(self)
__str__(self)
getCornerAngleMax(self)
Gets cornerAngleMax field. Corner angle threshold. If corner angle is below this value, "soft" corners are inserted.
@return: Value of cornerAngleMax field. [float]
getCornerWidth(self)
Gets cornerWidth field. Corner width. Inserted "soft" corners have this width.
@return: Value of cornerWidth field. [float]
getForceStreetAccess(self)
Gets forceStreetAccess field. Factor to guarantee street access. A large value gives preference to splits that result in lots with street access.
@return: Value of forceStreetAccess field. [float]
getIrregularity(self)
Gets irregularity field. Split line irrgularity. Larger values result in split positions more distant from middle point.
@return: Value of irregularity field. [float]
getLotAreaMax(self)
Gets lotAreaMax field. Maximum lot area. If the lot area is less than this value, subdivision stops.
@return: Value of lotAreaMax field. [float]
getLotAreaMin(self)
Gets lotAreaMin field. Minimum lot area. If the lot area is greater than this value, subdivision continues.
@return: Value of lotAreaMin field. [float]
getLotElevation(self)
Gets lotElevation field. Flat or uneven lots.
@return: Value of lotElevation field. ["UNEVEN", "EVEN_MIN", "EVEN_MAX", "EVEN_AVG"] [str]
getLotMinWidth(self)
Gets lotMinWidth field. Minimal lot side length. If violated, the split position is sampled again.
@return: Value of lotMinWidth field. [float]
getOffsetWidth(self)
Gets offsetWidth field. Offset width. When block inwards offset is used to compute subdivision, this is the default depth of the generated lots.
@return: Value of offsetWidth field. [float]
getSeed(self)
Gets seed field. Seed.
@return: Value of seed field. [int]
getSubdivisionOffset(self)
Gets subdivisionOffset field. Use offset algorithm for subdivision.
@return: Value of subdivisionOffset field. [True/False]
getSubdivisionRecursive(self)
Gets subdivisionRecursive field. Use recursive algorithm for subdivision.
@return: Value of subdivisionRecursive field. [True/False]
setCornerAngleMax(self, floatValue)
Sets cornerAngleMax field. Corner angle threshold. If corner angle is below this value, "soft" corners are inserted.
setCornerWidth(self, floatValue)
Sets cornerWidth field. Corner width. Inserted "soft" corners have this width.
setForceStreetAccess(self, floatValue)
Sets forceStreetAccess field. Factor to guarantee street access. A large value gives preference to splits that result in lots with street access.
setIrregularity(self, floatValue)
Sets irregularity field. Split line irrgularity. Larger values result in split positions more distant from middle point.
setLotAreaMax(self, floatValue)
Sets lotAreaMax field. Maximum lot area. If the lot area is less than this value, subdivision stops.
setLotAreaMin(self, floatValue)
Sets lotAreaMin field. Minimum lot area. If the lot area is greater than this value, subdivision continues.
setLotElevation(self, enumValue)
Sets lotElevation field. Flat or uneven lots.
@param enumValue: the new value ["UNEVEN", "EVEN_MIN", "EVEN_MAX", "EVEN_AVG"]. [str]
setLotMinWidth(self, floatValue)
Sets lotMinWidth field. Minimal lot side length. If violated, the split position is sampled again.
setOffsetWidth(self, floatValue)
Sets offsetWidth field. Offset width. When block inwards offset is used to compute subdivision, this is the default depth of the generated lots.
setSeed(self, intValue)
Sets seed field. Seed.
setSubdivisionOffset(self, booleanValue)
Sets subdivisionOffset field. Use offset algorithm for subdivision.
setSubdivisionRecursive(self, booleanValue)
Sets subdivisionRecursive field. Use recursive algorithm for subdivision.

EVEN_AVG = 'EVEN_AVG'
EVEN_MAX = 'EVEN_MAX'
EVEN_MIN = 'EVEN_MIN'
UNEVEN = 'UNEVEN'

Command Reference
Classes
View3D
class View3D
3D view.

__repr__(self)
__str__(self)
frame(self, objects=None)
Frame the given objects.
@param objects: The objects to frame or null to frame all objects. (default = None).
@note: # Frame objects in scene

views = ce.getObjectsFrom(ce.get3DViews())
views[0].frame()
setCameraAngleOfView(self, angle)
Sets the camera angle of view in degrees.
@param angle: Angle of view. [float]
@note: # set cameras angle fo view

ce.get3DViews()[0].setCameraAngleOfView(50)
setCameraPerspective(self, perspective=True)
Sets the camera to persepctive mode.
@param perspective: Set camera to perspective mode. (default = True). [True/False]
@note: # set camera to orthographic mode

ce.get3DViews()[0].setCameraPerspective(False)
setCameraPosition(self, x, y, z)
Sets the camera position in world coordinates.
@param x: X coordinate. [float]
@param y: Y coordinate. [float]
@param z: Z coordinate. [float]
@note: # place camera at position (100,100,100)
views = ce.getObjectsFrom(ce.get3DViews(), ce.isViewport)
views[0].setCameraPosition(0, 200, 0)
setCameraRotation(self, x, y, z)
Sets the camera rotation in degrees.
@param x: X axis rotation. [float]
@param y: Y axis rotation. [float]
@param z: Z axis rotation. [float]
@note: # reset camera rotation
ce.get3DViews()[0].setCameraRotation(-15,0,0)
snapshot(self, filesystemPath, width=-1, height=-1)

Make a snapshot of this 3D viweport.
@param filesystemPath: Path to the destination image (must be a filesystem path). [str]
@param width: Width of snapshot. (default = -1). [int]
@param height: Height of snapshot. (default = -1). [int]
@note: # snapshot current inspector view
views = ce.getObjectsFrom(ce.get3DViews(), ce.isInspector)
if len(views) < 1 : print "no inspector view found"
else :
views[0].frame()
ce.waitForUIIdle()
views[0].snapshot(ce.toFSPath('snapshot.png'))

The Python Scripting Interface greatly enhances the possibilities of the CityEngine. Many tasks can be automatized using
specific Python commands.
1. Python Scripting Interface

2. Commands by Category
3. Command Reference
See also
Tutorial 10 Python Scripting
Tutorial 13 Scripted Report Export
Command Reference
Classes
CEJImportSettings
class CEJImportSettings
CEJ import settings.
@note: # Settings class used to control parameters for CEJ import
settings = CEJImportSettings()
ce.importFile(ce.toFSPath("spherecity_01.cej"), settings)

__repr__(self)
__str__(self)
getFile(self)
Gets File field.
@return: Value of File field. [str]
getMerge(self)
Gets Merge field.
@return: Value of Merge field. ["ADD", "REPLACE_BY_ID", "REPLACE_BY_NAME", "REPLACE_LAYER_BY_ID", "REPLACE_LAYER_BY_NAME"] [str]
load(self, name)
Load the named settings from the current scene file.
@param name: The name of the settings to load. [str]

@return: result.
save(self, name)
Save the named settings to the current scene file.
@param name: The name of the settings to save. [str]
setFile(self, stringValue)
Sets File field.
setMerge(self, enumValue)
Sets Merge field.
@param enumValue: the new value ["ADD", "REPLACE_BY_ID", "REPLACE_BY_NAME", "REPLACE_LAYER_BY_ID", "REPLACE_LAYER_BY_NAME"]. [str]

ADD = 'ADD'
REPLACE_BY_ID = 'REPLACE_BY_ID'
REPLACE_BY_NAME = 'REPLACE_BY_NAME'
REPLACE_LAYER_BY_ID = 'REPLACE_LAYER_BY_ID'
REPLACE_LAYER_BY_NAME = 'REPLACE_LAYER_BY_NAME'

Command Reference
Classes
DAEImportSettings
class DAEImportSettings
COLLADA import settings.

__repr__(self)
__str__(self)
getFile(self)
Gets File field.
load(self, name)

@return: result.
save(self, name)
Sets File field.

Command Reference
Classes
DXFImportSettings
class DXFImportSettings
DXF import settings.
@note: # Settings class used to control parameters for DXF import

settings = DXFImportSettings()
ce.importFile(ce.toFSPath("data/batchExportTests/lots.dxf"), settings)
ce.importFile(ce.toFSPath("data/batchExportTests/graph.dxf"), settings)

__repr__(self)
__str__(self)
getFile(self)
Gets File field.
getOffset(self)
Gets Offset field.
@return: Value of Offset field. [sequence of float]
getScale(self)
Gets Scale field.
@return: Value of Scale field. [float]
load(self, name)

@return: result.
save(self, name)
Sets File field.
setOffset(self, floatArrayValue)
Sets Offset field.
@param floatArrayValue: the new value. [sequence of float]
setScale(self, floatValue)
Sets Scale field.

Command Reference
Classes
OBJImportSettings
class OBJImportSettings
OBJ import settings.
@note: # Settings class used to control parameters for OBJ import

settings = OBJImportSettings()
ce.importFile(ce.toFSPath("data/batchExportTests/streetshapes.obj"), settings)

__repr__(self)
__str__(self)
getFile(self)
Gets File field.
load(self, name)

@return: result.
save(self, name)
Sets File field.

Command Reference
Classes
OSMImportSettings
class OSMImportSettings
OSM import settings.
@note: # Settings class used to control parameters for OSM import

settings = OSMImportSettings()
settings.setOffset([-13614232,-4540818])
ce.importFile(ce.toFSPath("data/osm/sf_marina.osm"), settings)

__repr__(self)
__str__(self)
getFile(self)
Gets File field.
getOffset(self)
Gets Offset field.
getProjection(self)
Gets Projection field.
@return: Value of Projection field. ["DisableProjection", "AlbersProjection", "EquidistantAzimuthalProjection", "AiryProjection", "AitoffProjection", "AugustProjection", "BipolarProjection", "BoggsProjection", "BonneProjection", "CassiniProjection", "CentralCylindricalProjection", "CollignonProjection", "CrasterProjection", "DenoyerProjection", "Eckert1Projection", "Eckert2Projection", "Eckert4Projection", "Eckert5Projection", "PlateCarreeProjection", "EquidistantConicProjection", "EulerProjection", "FaheyProjection", "FoucautProjection", "FoucautSinusoidalProjection", "GallProjection", "GnomonicAzimuthalProjection", "GoodeProjection", "HammerProjection", "HatanoProjection", "KavraiskyVProjection", "LagrangeProjection", "LarriveeProjection", "LaskowskiProjection", "LambertConformalConicProjection", "LambertEqualAreaConicProjection", "LinearProjection", "LoximuthalProjection", "LandsatProjection", "MBTFPSProjection", "MBTFPPProjection", "MBTFPQProjection", "MercatorProjection", "MillerProjection", "MolleweideProjection", "Murdoch1Projection", "Murdoch2Projection", "Murdoch3Projection", "NellProjection", "NicolosiProjection", "PerspectiveProjection", "ObliqueMercatorProjection", "OrthographicAzimuthalProjection", "PerspectiveConicProjection", "PolyconicProjection", "PutninsP2Projection", "PutninsP4Projection", "PutninsP5Projection", "PutninsP5PProjection", "QuarticAuthalicProjection", "RobinsonProjection", "RectangularPolyconicProjection", "SinusoidalProjection", "StereographicAzimuthalProjection", "TCCProjection", "TCEAProjection", "TransverseMercatorProjection", "URMFPSProjection", "VanDerGrintenProjection", "VitkovskyProjection", "Wagner1Projection", "Wagner2Projection", "Wagner3Projection", "Wagner4Projection", "Wagner5Projection", "Wagner7Projection", "WerenskioldProjection", "WinkelTripelProjection", "UTMProjection"] [str]
getProjectionSettingsCenterLatitude(self)
Gets ProjectionSettingsCenterLatitude field.
@return: Value of ProjectionSettingsCenterLatitude field. [float]
getProjectionSettingsCenterLongitude(self)
Gets ProjectionSettingsCenterLongitude field.
@return: Value of ProjectionSettingsCenterLongitude field. [float]
getProjectionSettingsEllipsoid(self)
Gets ProjectionSettingsEllipsoid field.
@return: Value of ProjectionSettingsEllipsoid field. ["SPHERE", "BESSEL", "CLARKE_1866", "CLARKE_1880", "AIRY", "WGS_1960", "WGS_1966", "WGS_1972", "WGS_1984", "KRASOVSKY", "EVEREST", "INTERNATIONAL_1967", "GRS_1980", "MERIT", "SOVIET", "IAU", "APPL_PHY", "NAVAL_WEAPON", "MODIFIED_AIRY", "ANDRAE", "AUSTRALIAN", "GRS", "BESSEL_NAMIBIA", "COMM", "DELAMBRE", "ENGELIS", "EVEREST_1948", "EVEREST_1956", "EVEREST_1969", "EVEREST_SS", "FISCHER", "FISCHER_MOD", "FISCHER_1968", "HELMERT", "HOUGH", "INTERNATIONAL_1909", "KAULA", "LERCH", "MAUPERTIUS", "PLESSIS", "SOUTHEAST_ASIA", "WALBECK", "NAD27", "NAD83"] [str]
getProjectionSettingsFalseEasting(self)
Gets ProjectionSettingsFalseEasting field.
@return: Value of ProjectionSettingsFalseEasting field. [float]
getProjectionSettingsFalseNorthing(self)
Gets ProjectionSettingsFalseNorthing field.
@return: Value of ProjectionSettingsFalseNorthing field. [float]
getProjectionSettingsScaleFactor(self)
Gets ProjectionSettingsScaleFactor field.
@return: Value of ProjectionSettingsScaleFactor field. [float]
getProjectionSettingsStandardparallel1(self)
Gets ProjectionSettingsStandardparallel1 field.
@return: Value of ProjectionSettingsStandardparallel1 field. [float]
getProjectionSettingsTrueScaleLatitude(self)
Gets ProjectionSettingsTrueScaleLatitude field.
@return: Value of ProjectionSettingsTrueScaleLatitude field. [float]
getScale(self)
Gets Scale field.
load(self, name)
@return: result.
save(self, name)
Sets File field.
Sets Offset field.
setProjection(self, enumValue)
Sets Projection field.
@param enumValue: the new value ["DisableProjection", "AlbersProjection", "EquidistantAzimuthalProjection", "AiryProjection", "AitoffProjection", "AugustProjection", "BipolarProjection", "BoggsProjection", "BonneProjection", "CassiniProjection", "CentralCylindricalProjection", "CollignonProjection", "CrasterProjection", "DenoyerProjection", "Eckert1Projection", "Eckert2Projection", "Eckert4Projection", "Eckert5Projection", "PlateCarreeProjection", "EquidistantConicProjection", "EulerProjection", "FaheyProjection", "FoucautProjection", "FoucautSinusoidalProjection", "GallProjection", "GnomonicAzimuthalProjection", "GoodeProjection", "HammerProjection", "HatanoProjection", "KavraiskyVProjection", "LagrangeProjection", "LarriveeProjection", "LaskowskiProjection", "LambertConformalConicProjection", "LambertEqualAreaConicProjection", "LinearProjection", "LoximuthalProjection", "LandsatProjection", "MBTFPSProjection", "MBTFPPProjection", "MBTFPQProjection", "MercatorProjection", "MillerProjection", "MolleweideProjection", "Murdoch1Projection", "Murdoch2Projection", "Murdoch3Projection", "NellProjection", "NicolosiProjection", "PerspectiveProjection", "ObliqueMercatorProjection", "OrthographicAzimuthalProjection", "PerspectiveConicProjection", "PolyconicProjection", "PutninsP2Projection", "PutninsP4Projection", "PutninsP5Projection", "PutninsP5PProjection", "QuarticAuthalicProjection", "RobinsonProjection", "RectangularPolyconicProjection", "SinusoidalProjection", "StereographicAzimuthalProjection", "TCCProjection", "TCEAProjection", "TransverseMercatorProjection", "URMFPSProjection", "VanDerGrintenProjection", "VitkovskyProjection", "Wagner1Projection", "Wagner2Projection", "Wagner3Projection", "Wagner4Projection", "Wagner5Projection", "Wagner7Projection", "WerenskioldProjection", "WinkelTripelProjection", "UTMProjection"]. [str]
setProjectionSettingsCenterLatitude(self, floatValue)
Sets ProjectionSettingsCenterLatitude field.
setProjectionSettingsCenterLongitude(self, floatValue)
Sets ProjectionSettingsCenterLongitude field.
setProjectionSettingsEllipsoid(self, enumValue)
Sets ProjectionSettingsEllipsoid field.
@param enumValue: the new value ["SPHERE", "BESSEL", "CLARKE_1866", "CLARKE_1880", "AIRY", "WGS_1960", "WGS_1966", "WGS_1972", "WGS_1984", "KRASOVSKY", "EVEREST", "INTERNATIONAL_1967", "GRS_1980", "MERIT", "SOVIET", "IAU", "APPL_PHY", "NAVAL_WEAPON", "MODIFIED_AIRY", "ANDRAE", "AUSTRALIAN", "GRS", "BESSEL_NAMIBIA", "COMM", "DELAMBRE", "ENGELIS", "EVEREST_1948", "EVEREST_1956", "EVEREST_1969", "EVEREST_SS", "FISCHER", "FISCHER_MOD", "FISCHER_1968", "HELMERT", "HOUGH", "INTERNATIONAL_1909", "KAULA", "LERCH", "MAUPERTIUS", "PLESSIS", "SOUTHEAST_ASIA", "WALBECK", "NAD27", "NAD83"]. [str]
setProjectionSettingsFalseEasting(self, floatValue)
Sets ProjectionSettingsFalseEasting field.
setProjectionSettingsFalseNorthing(self, floatValue)
Sets ProjectionSettingsFalseNorthing field.
setProjectionSettingsScaleFactor(self, floatValue)
Sets ProjectionSettingsScaleFactor field.
setProjectionSettingsStandardparallel1(self, floatValue)
Sets ProjectionSettingsStandardparallel1 field.
setProjectionSettingsTrueScaleLatitude(self, floatValue)
Sets ProjectionSettingsTrueScaleLatitude field.
Sets Scale field.

AIRY = 'AIRY'
ANDRAE = 'ANDRAE'
APPL_PHY = 'APPL_PHY'
AUSTRALIAN = 'AUSTRALIAN'
AiryProjection = 'AiryProjection'
AitoffProjection = 'AitoffProjection'
AlbersProjection = 'AlbersProjection'
AugustProjection = 'AugustProjection'
BESSEL = 'BESSEL'
BESSEL_NAMIBIA = 'BESSEL_NAMIBIA'
BipolarProjection = 'BipolarProjection'
BoggsProjection = 'BoggsProjection'
BonneProjection = 'BonneProjection'
CLARKE_1866 = 'CLARKE_1866'
COMM = 'COMM'
CassiniProjection = 'CassiniProjection'
CentralCylindricalProjection = 'CentralCylindricalProjection'
CollignonProjection = 'CollignonProjection'
CrasterProjection = 'CrasterProjection'
DELAMBRE = 'DELAMBRE'
DenoyerProjection = 'DenoyerProjection'
DisableProjection = 'DisableProjection'
ENGELIS = 'ENGELIS'
EVEREST = 'EVEREST'
EVEREST_1948 = 'EVEREST_1948'
EVEREST_SS = 'EVEREST_SS'
Eckert1Projection = 'Eckert1Projection'
EquidistantAzimuthalProjection = 'EquidistantAzimuthalProjection'
EquidistantConicProjection = 'EquidistantConicProjection'
EulerProjection = 'EulerProjection'
FISCHER = 'FISCHER'
FISCHER_1968 = 'FISCHER_1968'
FISCHER_MOD = 'FISCHER_MOD'
FaheyProjection = 'FaheyProjection'
FoucautProjection = 'FoucautProjection'
FoucautSinusoidalProjection = 'FoucautSinusoidalProjection'
GRS = 'GRS'
GRS_1980 = 'GRS_1980'
GallProjection = 'GallProjection'
GnomonicAzimuthalProjection = 'GnomonicAzimuthalProjection'
GoodeProjection = 'GoodeProjection'
HELMERT = 'HELMERT'
HOUGH = 'HOUGH'
HammerProjection = 'HammerProjection'
HatanoProjection = 'HatanoProjection'
IAU = 'IAU'
INTERNATIONAL_1909 = 'INTERNATIONAL_1909'
KAULA = 'KAULA'
KRASOVSKY = 'KRASOVSKY'
KavraiskyVProjection = 'KavraiskyVProjection'
LERCH = 'LERCH'
LagrangeProjection = 'LagrangeProjection'
LambertConformalConicProjection = 'LambertConformalConicProjection'
LambertEqualAreaConicProjection = 'LambertEqualAreaConicProjection'
LandsatProjection = 'LandsatProjection'
LarriveeProjection = 'LarriveeProjection'
LaskowskiProjection = 'LaskowskiProjection'
LinearProjection = 'LinearProjection'
LoximuthalProjection = 'LoximuthalProjection'
MAUPERTIUS = 'MAUPERTIUS'
MBTFPPProjection = 'MBTFPPProjection'
MBTFPQProjection = 'MBTFPQProjection'
MBTFPSProjection = 'MBTFPSProjection'
MERIT = 'MERIT'
MODIFIED_AIRY = 'MODIFIED_AIRY'
MercatorProjection = 'MercatorProjection'
MillerProjection = 'MillerProjection'
MolleweideProjection = 'MolleweideProjection'
Murdoch1Projection = 'Murdoch1Projection'
NAD27 = 'NAD27'
NAD83 = 'NAD83'
NAVAL_WEAPON = 'NAVAL_WEAPON'
NellProjection = 'NellProjection'
NicolosiProjection = 'NicolosiProjection'
ObliqueMercatorProjection = 'ObliqueMercatorProjection'
OrthographicAzimuthalProjection = 'OrthographicAzimuthalProjection'
PLESSIS = 'PLESSIS'
PerspectiveConicProjection = 'PerspectiveConicProjection'
PerspectiveProjection = 'PerspectiveProjection'
PlateCarreeProjection = 'PlateCarreeProjection'
PolyconicProjection = 'PolyconicProjection'
PutninsP2Projection = 'PutninsP2Projection'
PutninsP5PProjection = 'PutninsP5PProjection'
QuarticAuthalicProjection = 'QuarticAuthalicProjection'
RectangularPolyconicProjection = 'RectangularPolyconicProjection'
RobinsonProjection = 'RobinsonProjection'
SOUTHEAST_ASIA = 'SOUTHEAST_ASIA'
SOVIET = 'SOVIET'
SPHERE = 'SPHERE'
SinusoidalProjection = 'SinusoidalProjection'
StereographicAzimuthalProjection = 'StereographicAzimuthalProjection'
TCCProjection = 'TCCProjection'
TCEAProjection = 'TCEAProjection'
TransverseMercatorProjection = 'TransverseMercatorProjection'
URMFPSProjection = 'URMFPSProjection'
UTMProjection = 'UTMProjection'
VanDerGrintenProjection = 'VanDerGrintenProjection'
VitkovskyProjection = 'VitkovskyProjection'
WALBECK = 'WALBECK'
WGS_1960 = 'WGS_1960'
WGS_1966 = 'WGS_1966'
WGS_1972 = 'WGS_1972'
WGS_1984 = 'WGS_1984'
Wagner1Projection = 'Wagner1Projection'
WerenskioldProjection = 'WerenskioldProjection'
WinkelTripelProjection = 'WinkelTripelProjection'

Command Reference
Classes
SHPImportSettings
class SHPImportSettings
Shape file import settings.
@note: # Settings class used to control parameters for Shape (SHP) import
settings = SHPImportSettings()
settings.setProjection(SHPImportSettings.DisableProjection)
ce.importFile(ce.toFSPath("data/batchExportTests/graphsouth.shp"), settings)
ce.importFile(ce.toFSPath("data/batchExportTests/lotssouth.shp"), settings)

__repr__(self)
__str__(self)
getFile(self)
Gets File field.
getOffset(self)
Gets Offset field.
getProjection(self)
Gets Projection field.
Gets ProjectionSettingsCenterLatitude field.
Gets ProjectionSettingsCenterLongitude field.
Gets ProjectionSettingsEllipsoid field.
Gets ProjectionSettingsFalseEasting field.
Gets ProjectionSettingsFalseNorthing field.
Gets ProjectionSettingsScaleFactor field.
Gets ProjectionSettingsTrueScaleLatitude field.
getScale(self)
Gets Scale field.
load(self, name)
@return: result.
save(self, name)
Sets File field.
Sets Offset field.
Sets Projection field.
Sets ProjectionSettingsCenterLatitude field.
Sets ProjectionSettingsCenterLongitude field.
Sets ProjectionSettingsEllipsoid field.
Sets ProjectionSettingsFalseEasting field.
Sets ProjectionSettingsFalseNorthing field.
Sets ProjectionSettingsScaleFactor field.
Sets ProjectionSettingsTrueScaleLatitude field.
Sets Scale field.

AIRY = 'AIRY'
ANDRAE = 'ANDRAE'
BESSEL = 'BESSEL'
COMM = 'COMM'
ENGELIS = 'ENGELIS'
EVEREST = 'EVEREST'
FISCHER = 'FISCHER'
GRS = 'GRS'
GRS_1980 = 'GRS_1980'
HELMERT = 'HELMERT'
HOUGH = 'HOUGH'
IAU = 'IAU'
KAULA = 'KAULA'
LERCH = 'LERCH'
MERIT = 'MERIT'
NAD27 = 'NAD27'
NAD83 = 'NAD83'
PLESSIS = 'PLESSIS'
SOVIET = 'SOVIET'
SPHERE = 'SPHERE'
WALBECK = 'WALBECK'
WGS_1960 = 'WGS_1960'
WGS_1966 = 'WGS_1966'
WGS_1972 = 'WGS_1972'
WGS_1984 = 'WGS_1984'

Command Reference
Classes
A3DSExportModelSettings
class A3DSExportModelSettings
3DS model export settings.

__repr__(self)
__str__(self)
getGeneralApplicationExport(self)
Gets GeneralApplicationExport field. Wrap the exported geometry inside a RealityServer application.
@return: Value of GeneralApplicationExport field. ["NONE", "CREATE", "UPDATE"] [str]
getGeneralExportedContent(self)
Gets GeneralExportedContent field. Defines the exported content (e.g. falls back to shapes if model generation attributes are not valid).
@return: Value of GeneralExportedContent field. ["MODEL", "FALLBACK", "SHAPE"] [str]
getGeneralLocation(self)
Gets GeneralLocation field. Path to the export location.
@return: Value of GeneralLocation field. [str]
getGeneralName(self)
Gets GeneralName field. Base name used for exported files.
@return: Value of GeneralName field. [str]
getGranularityCreateShapeGroups(self)
Gets GranularityCreateShapeGroups field. Create a group/transformation node per shape. Note that generated geometry is only merged inside a shape if enabled.
@return: Value of GranularityCreateShapeGroups field. [True/False]
getGranularityFile(self)
Gets GranularityFile field. Specifies the partition of the generated geometry into files.
@return: Value of GranularityFile field. ["ONE_FILE", "PER_INITIAL_SHAPE"] [str]
getGranularityFileSizeLimitMB(self)
Gets GranularityFileSizeLimitMB field. Specifies the size limit in megabytes per exported file (value 0 = maximum size 2GB). Please note: The size is measured on the unoptimized geometry, i.e. the final size may vary. The check is only performed per input shape.
@return: Value of GranularityFileSizeLimitMB field. [int]
getGranularityMesh(self)
Gets GranularityMesh field. Specifies the processing of meshes.
@return: Value of GranularityMesh field. ["AS_GENERATED", "PER_MATERIAL", "INSTANCED"] [str]
getMaterialsCollectTextures(self)
Gets MaterialsCollectTextures field. Collects all used textures and copies them into the target folder. All texture references are adjusted accordingly.
@return: Value of MaterialsCollectTextures field. [True/False]
getMaterialsIncludeMaterials(self)
Gets MaterialsIncludeMaterials field. Exports material definitions (e.g. color, textures, ...).
@return: Value of MaterialsIncludeMaterials field. [True/False]
getMeshComponentsNormalsIndexing(self)
Gets MeshComponentsNormalsIndexing field. Choose indexed (shared) or separated normals per face vertex.
@return: Value of MeshComponentsNormalsIndexing field. ["NORMALS_INDEXED", "NORMALS_SEPARATED"] [str]
getMeshComponentsNormalsType(self)
Gets MeshComponentsNormalsType field. Exports vertex or face normals (both are stored as vertex normals in exported file).
@return: Value of MeshComponentsNormalsType field. ["VERTEX_NORMALS", "FACE_NORMALS"] [str]
getMeshComponentsTextureCoordinates(self)
Gets MeshComponentsTextureCoordinates field. Choose which - if any - texture coordinate layers to export.
@return: Value of MeshComponentsTextureCoordinates field. ["UV_NONE", "UV_FIRST", "UV_ALL"] [str]
getMeshComponentsVertexIndexing(self)
Gets MeshComponentsVertexIndexing field. Choose indexed (shared) or separated vertices between faces.
@return: Value of MeshComponentsVertexIndexing field. ["VERTICES_INDEXED", "VERTICES_SEPARATED"] [str]
getMiscOptionsBatchBehavior(self)
Gets MiscOptionsBatchBehavior field. Specifies how files should be written during the export run. The log file will be written anyways.
@return: Value of MiscOptionsBatchBehavior field. ["OVERWRITE", "SKIP_EXISTING_FILES", "DRY_RUN"] [str]
getMiscOptionsEmbedTextures(self)
Gets MiscOptionsEmbedTextures field. Embeds the textures inside the binary fbx file.
@return: Value of MiscOptionsEmbedTextures field. [True/False]
getMiscOptionsFileType(self)
Gets MiscOptionsFileType field. Specifies geometry file type.
@return: Value of MiscOptionsFileType field. ["TEXT", "BINARY"] [str]
getMiscOptionsIncludeCameraData(self)
Gets MiscOptionsIncludeCameraData field. Adds the minimal set of commands (e.g. camera) to the master file to make it directly renderable.
@return: Value of MiscOptionsIncludeCameraData field. [True/False]
getMiscOptionsMasterFile(self)
Gets MiscOptionsMasterFile field. Write master scene file (if supported).
@return: Value of MiscOptionsMasterFile field. [True/False]
getMiscOptionsMasterGroup(self)
Gets MiscOptionsMasterGroup field. Name of master group (if supported).
@return: Value of MiscOptionsMasterGroup field. [str]
getMiscOptionsScript(self)
Gets MiscOptionsScript field. Python script to use for export callbacks.
@return: Value of MiscOptionsScript field. [str]
getMiscOptionsShapeNameDelimiter(self)
Gets MiscOptionsShapeNameDelimiter field. Delimiting character for resolution of shape name clashes.
@return: Value of MiscOptionsShapeNameDelimiter field. [str]
getMiscOptionsTransformationType(self)
Gets MiscOptionsTransformationType field. Specifies geometry file type.
@return: Value of MiscOptionsTransformationType field. ["NONE", "VCITY1"] [str]
getMiscOptionsWriteCompressedFiles(self)
Gets MiscOptionsWriteCompressedFiles field. Enable compression of written files.
@return: Value of MiscOptionsWriteCompressedFiles field. [True/False]
getMiscOptionsWriteExportLog(self)
Gets MiscOptionsWriteExportLog field. Write log file with statistics about this export session.
@return: Value of MiscOptionsWriteExportLog field. [True/False]
getOptimizationsMergenormalswithinprecision(self)
Gets OptimizationsMergenormalswithinprecision field. Finds parallel normals (using the precision distance) and shares their index.
@return: Value of OptimizationsMergenormalswithinprecision field. [True/False]
getOptimizationsMergetexturecoordinateswithinprecision(self)
Gets OptimizationsMergetexturecoordinateswithinprecision field. Finds identical texture coordinates (using the precision distance) and shares their index.
@return: Value of OptimizationsMergetexturecoordinateswithinprecision field. [True/False]
getOptimizationsMergeverticeswithinprecision(self)
Gets OptimizationsMergeverticeswithinprecision field. Finds co-incidental vertices (using the precision distance) and shares their index.
@return: Value of OptimizationsMergeverticeswithinprecision field. [True/False]
getOptimizationsNormalPrecision(self)
Gets OptimizationsNormalPrecision field. Specifies the minimal difference between normals.
@return: Value of OptimizationsNormalPrecision field. [float]
getOptimizationsReprojectUVs(self)
Gets OptimizationsReprojectUVs field. Replaces all texture coordinates on the first layer with planar coordinates projected along the world-y-axis.
@return: Value of OptimizationsReprojectUVs field. [True/False]
getOptimizationsTextureCoordinatePrecision(self)
Gets OptimizationsTextureCoordinatePrecision field. Specifies the minimal distance between texels.
@return: Value of OptimizationsTextureCoordinatePrecision field. [float]
getOptimizationsTriangulateMeshes(self)
Gets OptimizationsTriangulateMeshes field. Triangulate resulting meshes (eg. needed for Google Earth (tm) Collada import).
@return: Value of OptimizationsTriangulateMeshes field. [True/False]
getOptimizationsVertexPrecision(self)
Gets OptimizationsVertexPrecision field. Specifies the minimal distance between vertices.
@return: Value of OptimizationsVertexPrecision field. [float]
load(self, name)
@return: result.
save(self, name)
setGeneralApplicationExport(self, enumValue)
Sets GeneralApplicationExport field. Wrap the exported geometry inside a RealityServer application.
@param enumValue: the new value ["NONE", "CREATE", "UPDATE"]. [str]
setGeneralExportedContent(self, enumValue)
Sets GeneralExportedContent field. Defines the exported content (e.g. falls back to shapes if model generation attributes are not valid).
@param enumValue: the new value ["MODEL", "FALLBACK", "SHAPE"]. [str]
setGeneralLocation(self, stringValue)
Sets GeneralLocation field. Path to the export location.
setGeneralName(self, stringValue)
Sets GeneralName field. Base name used for exported files.
setGranularityCreateShapeGroups(self, booleanValue)
Sets GranularityCreateShapeGroups field. Create a group/transformation node per shape. Note that generated geometry is only merged inside a shape if enabled.
setGranularityFile(self, enumValue)
Sets GranularityFile field. Specifies the partition of the generated geometry into files.
@param enumValue: the new value ["ONE_FILE", "PER_INITIAL_SHAPE"]. [str]
setGranularityFileSizeLimitMB(self, intValue)
Sets GranularityFileSizeLimitMB field. Specifies the size limit in megabytes per exported file (value 0 = maximum size 2GB). Please note: The size is measured on the unoptimized geometry, i.e. the final size may vary. The check is only performed per input shape.
setGranularityMesh(self, enumValue)
Sets GranularityMesh field. Specifies the processing of meshes.
@param enumValue: the new value ["AS_GENERATED", "PER_MATERIAL", "INSTANCED"]. [str]
setMaterialsCollectTextures(self, booleanValue)
Sets MaterialsCollectTextures field. Collects all used textures and copies them into the target folder. All texture references are adjusted accordingly.
setMaterialsIncludeMaterials(self, booleanValue)
Sets MaterialsIncludeMaterials field. Exports material definitions (e.g. color, textures, ...).
setMeshComponentsNormalsIndexing(self, enumValue)
Sets MeshComponentsNormalsIndexing field. Choose indexed (shared) or separated normals per face vertex.
@param enumValue: the new value ["NORMALS_INDEXED", "NORMALS_SEPARATED"]. [str]
setMeshComponentsNormalsType(self, enumValue)
Sets MeshComponentsNormalsType field. Exports vertex or face normals (both are stored as vertex normals in exported file).
@param enumValue: the new value ["VERTEX_NORMALS", "FACE_NORMALS"]. [str]
setMeshComponentsTextureCoordinates(self, enumValue)
Sets MeshComponentsTextureCoordinates field. Choose which - if any - texture coordinate layers to export.
@param enumValue: the new value ["UV_NONE", "UV_FIRST", "UV_ALL"]. [str]
setMeshComponentsVertexIndexing(self, enumValue)
Sets MeshComponentsVertexIndexing field. Choose indexed (shared) or separated vertices between faces.
@param enumValue: the new value ["VERTICES_INDEXED", "VERTICES_SEPARATED"]. [str]
setMiscOptionsBatchBehavior(self, enumValue)
Sets MiscOptionsBatchBehavior field. Specifies how files should be written during the export run. The log file will be written anyways.
@param enumValue: the new value ["OVERWRITE", "SKIP_EXISTING_FILES", "DRY_RUN"]. [str]
setMiscOptionsEmbedTextures(self, booleanValue)
Sets MiscOptionsEmbedTextures field. Embeds the textures inside the binary fbx file.
setMiscOptionsFileType(self, enumValue)
Sets MiscOptionsFileType field. Specifies geometry file type.
@param enumValue: the new value ["TEXT", "BINARY"]. [str]
setMiscOptionsIncludeCameraData(self, booleanValue)
Sets MiscOptionsIncludeCameraData field. Adds the minimal set of commands (e.g. camera) to the master file to make it directly renderable.
setMiscOptionsMasterFile(self, booleanValue)
Sets MiscOptionsMasterFile field. Write master scene file (if supported).
setMiscOptionsMasterGroup(self, stringValue)
Sets MiscOptionsMasterGroup field. Name of master group (if supported).
setMiscOptionsScript(self, stringValue)
Sets MiscOptionsScript field. Python script to use for export callbacks.
setMiscOptionsShapeNameDelimiter(self, stringValue)
Sets MiscOptionsShapeNameDelimiter field. Delimiting character for resolution of shape name clashes.
setMiscOptionsTransformationType(self, enumValue)
Sets MiscOptionsTransformationType field. Specifies geometry file type.
@param enumValue: the new value ["NONE", "VCITY1"]. [str]
setMiscOptionsWriteCompressedFiles(self, booleanValue)
Sets MiscOptionsWriteCompressedFiles field. Enable compression of written files.
setMiscOptionsWriteExportLog(self, booleanValue)
Sets MiscOptionsWriteExportLog field. Write log file with statistics about this export session.
setOptimizationsMergenormalswithinprecision(self, booleanValue)
Sets OptimizationsMergenormalswithinprecision field. Finds parallel normals (using the precision distance) and shares their index.
setOptimizationsMergetexturecoordinateswithinprecision(self, booleanValue)
Sets OptimizationsMergetexturecoordinateswithinprecision field. Finds identical texture coordinates (using the precision distance) and shares their index.
setOptimizationsMergeverticeswithinprecision(self, booleanValue)
Sets OptimizationsMergeverticeswithinprecision field. Finds co-incidental vertices (using the precision distance) and shares their index.
setOptimizationsNormalPrecision(self, floatValue)
Sets OptimizationsNormalPrecision field. Specifies the minimal difference between normals.
setOptimizationsReprojectUVs(self, booleanValue)
Sets OptimizationsReprojectUVs field. Replaces all texture coordinates on the first layer with planar coordinates projected along the world-y-axis.
setOptimizationsTextureCoordinatePrecision(self, floatValue)
Sets OptimizationsTextureCoordinatePrecision field. Specifies the minimal distance between texels.
setOptimizationsTriangulateMeshes(self, booleanValue)
Sets OptimizationsTriangulateMeshes field. Triangulate resulting meshes (eg. needed for Google Earth (tm) Collada import).
setOptimizationsVertexPrecision(self, floatValue)
Sets OptimizationsVertexPrecision field. Specifies the minimal distance between vertices.

AS_GENERATED = 'AS_GENERATED'
BINARY = 'BINARY'
CREATE = 'CREATE'
DRY_RUN = 'DRY_RUN'
FACE_NORMALS = 'FACE_NORMALS'
FALLBACK = 'FALLBACK'
INSTANCED = 'INSTANCED'
MODEL = 'MODEL'
NONE = 'NONE'
NORMALS_INDEXED = 'NORMALS_INDEXED'
NORMALS_SEPARATED = 'NORMALS_SEPARATED'
ONE_FILE = 'ONE_FILE'
OVERWRITE = 'OVERWRITE'
PER_INITIAL_SHAPE = 'PER_INITIAL_SHAPE'
PER_MATERIAL = 'PER_MATERIAL'
SHAPE = 'SHAPE'
SKIP_EXISTING_FILES = 'SKIP_EXISTING_FILES'
TEXT = 'TEXT'
UPDATE = 'UPDATE'
UV_ALL = 'UV_ALL'
UV_FIRST = 'UV_FIRST'
UV_NONE = 'UV_NONE'
VCITY1 = 'VCITY1'
VERTEX_NORMALS = 'VERTEX_NORMALS'
VERTICES_INDEXED = 'VERTICES_INDEXED'
VERTICES_SEPARATED = 'VERTICES_SEPARATED'

Command Reference
Classes
A3DSExportTerrainSettings
class A3DSExportTerrainSettings
3DS terrain export settings.
@note: # Settings class used to control parameters for exporting terrain to 3DS
terrain = ce.getObjectsFrom(ce.scene, ce.withName("'Heightmap'"))
exportSettings = A3DSExportTerrainSettings()
ce.export(terrain, exportSettings)

__repr__(self)
__str__(self)
load(self, name)
@return: result.
save(self, name)

BINARY = 'BINARY'
CREATE = 'CREATE'
DRY_RUN = 'DRY_RUN'
MODEL = 'MODEL'
NONE = 'NONE'
SHAPE = 'SHAPE'
TEXT = 'TEXT'
UPDATE = 'UPDATE'
UV_ALL = 'UV_ALL'
UV_NONE = 'UV_NONE'
VCITY1 = 'VCITY1'

Command Reference
Classes
DAEExportModelSettings
class DAEExportModelSettings
COLLADA model export settings.

__repr__(self)
__str__(self)
load(self, name)
@return: result.
save(self, name)

BINARY = 'BINARY'
CREATE = 'CREATE'
DRY_RUN = 'DRY_RUN'
MODEL = 'MODEL'
NONE = 'NONE'
SHAPE = 'SHAPE'
TEXT = 'TEXT'
UPDATE = 'UPDATE'
UV_ALL = 'UV_ALL'
UV_NONE = 'UV_NONE'
VCITY1 = 'VCITY1'

Command Reference
Classes
DAEExportTerrainSettings
class DAEExportTerrainSettings
COLLADA terrain export settings.
@note: # Settings class used to control parameters for exporting terrain to COLLADA
exportSettings = DAEExportTerrainSettings()

__repr__(self)
__str__(self)
load(self, name)
@return: result.
save(self, name)

BINARY = 'BINARY'
CREATE = 'CREATE'
DRY_RUN = 'DRY_RUN'
MODEL = 'MODEL'
NONE = 'NONE'
SHAPE = 'SHAPE'
TEXT = 'TEXT'
UPDATE = 'UPDATE'
UV_ALL = 'UV_ALL'
UV_NONE = 'UV_NONE'
VCITY1 = 'VCITY1'

Command Reference
Classes
DXFExportGraphSettings
class DXFExportGraphSettings
DXF graph export settings.
@note: # Settings class used to control parameters for exporting graphs to DXF
graph = ce.getObjectsFrom(ce.scene, ce.withName("'Streetnetwork'"))
exportSettings = DXFExportGraphSettings()
exportSettings.setExportWidth(True)
exportSettings.setFilename(ce.toFSPath("data/batchExportTests/graph.dxf"))
ce.export(graph, exportSettings)

__repr__(self)
__str__(self)
getExportWidth(self)
Gets exportWidth field. Export total street width into dxf line thinkness field.
@return: Value of exportWidth field. [True/False]
getFilename(self)
Gets filename field. Path to the export location.
@return: Value of filename field. [str]
load(self, name)
@return: result. [DXFExportGraphSettings]
save(self, name)
setExportWidth(self, booleanValue)
Sets exportWidth field. Export total street width into dxf line thinkness field.
setFilename(self, stringValue)
Sets filename field. Path to the export location.

Command Reference
Classes
FBXExportModelSettings
class FBXExportModelSettings
FBX model export settings.

__repr__(self)
__str__(self)
load(self, name)
@return: result.
save(self, name)

BINARY = 'BINARY'
CREATE = 'CREATE'
DRY_RUN = 'DRY_RUN'
MODEL = 'MODEL'
NONE = 'NONE'
SHAPE = 'SHAPE'
TEXT = 'TEXT'
UPDATE = 'UPDATE'
UV_ALL = 'UV_ALL'
UV_NONE = 'UV_NONE'
VCITY1 = 'VCITY1'

Command Reference
Classes
FBXExportTerrainSettings
class FBXExportTerrainSettings
FBX terrain export settings.
@note: # Settings class used to control parameters for exporting terrain to FBX
exportSettings = FBXExportTerrainSettings()

__repr__(self)
__str__(self)
load(self, name)
@return: result.
save(self, name)

BINARY = 'BINARY'
CREATE = 'CREATE'
DRY_RUN = 'DRY_RUN'
MODEL = 'MODEL'
NONE = 'NONE'
SHAPE = 'SHAPE'
TEXT = 'TEXT'
UPDATE = 'UPDATE'
UV_ALL = 'UV_ALL'
UV_NONE = 'UV_NONE'
VCITY1 = 'VCITY1'

Command Reference
Classes
MIExportModelSettings
class MIExportModelSettings
mental ray model export settings.

__repr__(self)
__str__(self)
load(self, name)
@return: result.
save(self, name)

BINARY = 'BINARY'
CREATE = 'CREATE'
DRY_RUN = 'DRY_RUN'
MODEL = 'MODEL'
NONE = 'NONE'
SHAPE = 'SHAPE'
TEXT = 'TEXT'
UPDATE = 'UPDATE'
UV_ALL = 'UV_ALL'
UV_NONE = 'UV_NONE'
VCITY1 = 'VCITY1'

Command Reference
Classes
MIExportTerrainSettings
class MIExportTerrainSettings
mental ray terrain export settings.
@note: # Settings class used to control parameters for exporting terrain to MI
exportSettings = MIExportTerrainSettings()

__repr__(self)
__str__(self)
load(self, name)
@return: result.
save(self, name)

BINARY = 'BINARY'
CREATE = 'CREATE'
DRY_RUN = 'DRY_RUN'
MODEL = 'MODEL'
NONE = 'NONE'
SHAPE = 'SHAPE'
TEXT = 'TEXT'
UPDATE = 'UPDATE'
UV_ALL = 'UV_ALL'
UV_NONE = 'UV_NONE'
VCITY1 = 'VCITY1'

Command Reference
Classes
OBJExportModelSettings
class OBJExportModelSettings
Wavefront OBJ model export settings.

__repr__(self)
__str__(self)
load(self, name)
@return: result.
save(self, name)

BINARY = 'BINARY'
CREATE = 'CREATE'
DRY_RUN = 'DRY_RUN'
MODEL = 'MODEL'
NONE = 'NONE'
SHAPE = 'SHAPE'
TEXT = 'TEXT'
UPDATE = 'UPDATE'
UV_ALL = 'UV_ALL'
UV_NONE = 'UV_NONE'
VCITY1 = 'VCITY1'

Command Reference
Classes
OBJExportShapeSettings
class OBJExportShapeSettings
Wavefront OBJ shape export settings.
@note: # Settings class used to control parameters for exporting shapes to OBJ
streetshapes = ce.getObjectsFrom(ce.scene, ce.withName("'Street Shapes'"))
exportSettings = OBJExportShapeSettings()
exportSettings.setFilename(ce.toFSPath("data/batchExportTests/streetshapes.obj"))
ce.export(streetshapes, exportSettings)

__repr__(self)
__str__(self)
getFilename(self)
load(self, name)
@return: result. [OBJExportShapeSettings]
save(self, name)

Command Reference
Classes
OBJExportTerrainSettings
class OBJExportTerrainSettings
Wavefront OBJ Terrain export settings.
@note: # Settings class used to control parameters for exporting terrain to OBJ
exportSettings = OBJExportTerrainSettings()

__repr__(self)
__str__(self)
load(self, name)
@return: result.
save(self, name)

BINARY = 'BINARY'
CREATE = 'CREATE'
DRY_RUN = 'DRY_RUN'
MODEL = 'MODEL'
NONE = 'NONE'
SHAPE = 'SHAPE'
TEXT = 'TEXT'
UPDATE = 'UPDATE'
UV_ALL = 'UV_ALL'
UV_NONE = 'UV_NONE'
VCITY1 = 'VCITY1'

Command Reference
Classes
ScriptExportModelSettings
class ScriptExportModelSettings
Export context for script-based shape and model export.

__repr__(self)
__str__(self)
load(self, name)
@return: result. [ScriptExportModelSettings]
save(self, name)

BINARY = 'BINARY'
DRY_RUN = 'DRY_RUN'
NONE = 'NONE'
TEXT = 'TEXT'
VCITY1 = 'VCITY1'

Command Reference
Classes
RIBExportModelSettings
class RIBExportModelSettings
RIB export settings.

__repr__(self)
__str__(self)
load(self, name)
@return: result.
save(self, name)

BINARY = 'BINARY'
CREATE = 'CREATE'
DRY_RUN = 'DRY_RUN'
MODEL = 'MODEL'
NONE = 'NONE'
SHAPE = 'SHAPE'
TEXT = 'TEXT'
UPDATE = 'UPDATE'
UV_ALL = 'UV_ALL'
UV_NONE = 'UV_NONE'
VCITY1 = 'VCITY1'

Command Reference
Classes
RIBExportTerrainSettings
class RIBExportTerrainSettings
RIB export settings.
@note: # Settings class used to control parameters for exporting terrain to RIB
exportSettings = RIBExportTerrainSettings()

__repr__(self)
__str__(self)
load(self, name)
@return: result.
save(self, name)

BINARY = 'BINARY'
CREATE = 'CREATE'
DRY_RUN = 'DRY_RUN'
MODEL = 'MODEL'
NONE = 'NONE'
SHAPE = 'SHAPE'
TEXT = 'TEXT'
UPDATE = 'UPDATE'
UV_ALL = 'UV_ALL'
UV_NONE = 'UV_NONE'
VCITY1 = 'VCITY1'

Command Reference
Classes
SHPExportGraphSettings
class SHPExportGraphSettings
Shapefile graph export settings.
@note: # Settings class used to control parameters for exporting graphs to SHP
graph = ce.getObjectsFrom(ce.scene, ce.withName("'StreetnetworkSouth'"))
exportSettings = SHPExportGraphSettings()
exportSettings.setProjection(SHPExportGraphSettings.DisableProjection)
exportSettings.setFilename(ce.toFSPath("data/batchExportTests/graphsouth.shp"))
ce.export(graph, exportSettings)

__repr__(self)
__str__(self)
getFilename(self)
Gets Filename field. Path to the export location.
@return: Value of Filename field. [str]
getProjection(self)
Gets Projection field. Projection method.
Gets ProjectionSettingsCenterLatitude field. Latitude of projection center.
Gets ProjectionSettingsCenterLongitude field. Longitude of projection center.
Gets ProjectionSettingsEllipsoid field. Ellipsoid used for projection.
Gets ProjectionSettingsFalseEasting field. False easting.
Gets ProjectionSettingsFalseNorthing field. False northing.
Gets ProjectionSettingsScaleFactor field. Scale factor.
Gets ProjectionSettingsStandardparallel1 field. Standard parallel 1.
Gets ProjectionSettingsTrueScaleLatitude field. True scale latitude.
load(self, name)

@return: result.
save(self, name)
Sets Filename field. Path to the export location.
Sets Projection field. Projection method.
Sets ProjectionSettingsCenterLatitude field. Latitude of projection center.
Sets ProjectionSettingsCenterLongitude field. Longitude of projection center.
Sets ProjectionSettingsEllipsoid field. Ellipsoid used for projection.
Sets ProjectionSettingsFalseEasting field. False easting.
Sets ProjectionSettingsFalseNorthing field. False northing.
Sets ProjectionSettingsScaleFactor field. Scale factor.
Sets ProjectionSettingsStandardparallel1 field. Standard parallel 1.
Sets ProjectionSettingsTrueScaleLatitude field. True scale latitude.

AIRY = 'AIRY'
ANDRAE = 'ANDRAE'
BESSEL = 'BESSEL'
COMM = 'COMM'
ENGELIS = 'ENGELIS'
EVEREST = 'EVEREST'
FISCHER = 'FISCHER'
GRS = 'GRS'
GRS_1980 = 'GRS_1980'
HELMERT = 'HELMERT'
HOUGH = 'HOUGH'
IAU = 'IAU'
KAULA = 'KAULA'
LERCH = 'LERCH'
MERIT = 'MERIT'
NAD27 = 'NAD27'
NAD83 = 'NAD83'
PLESSIS = 'PLESSIS'
SOVIET = 'SOVIET'
SPHERE = 'SPHERE'
WALBECK = 'WALBECK'
WGS_1960 = 'WGS_1960'
WGS_1966 = 'WGS_1966'
WGS_1972 = 'WGS_1972'
WGS_1984 = 'WGS_1984'

Command Reference
Classes
SHPExportShapeSettings
class SHPExportShapeSettings
Shapefile shape export settings.
@note: # Settings class used to control parameters for exporting shapes to SHP
lots = ce.getObjectsFrom(ce.scene, ce.withName("'LotsSouth'"))
exportSettings = SHPExportShapeSettings()
exportSettings.setProjection(SHPExportShapeSettings.DisableProjection)
exportSettings.setFilename(ce.toFSPath("data/batchExportTests/lotssouth.shp"))
ce.export(lots, exportSettings)

__repr__(self)
__str__(self)
get3DOptions(self)
Gets 3DOptions field.
@return: Value of 3DOptions field. ["NONE", "POLYGONZ", "MULTIPATCH"] [str]
getFilename(self)
Gets Filename field. Path to the export location.
@return: Value of Filename field. [str]
getProjection(self)
Gets Projection field. Projection method.
Gets ProjectionSettingsCenterLatitude field. Latitude of projection center.
Gets ProjectionSettingsCenterLongitude field. Longitude of projection center.
Gets ProjectionSettingsEllipsoid field. Ellipsoid used for projection.
Gets ProjectionSettingsFalseEasting field. False easting.
Gets ProjectionSettingsFalseNorthing field. False northing.
Gets ProjectionSettingsScaleFactor field. Scale factor.
Gets ProjectionSettingsTrueScaleLatitude field. True scale latitude.
load(self, name)
@return: result.
save(self, name)
set3DOptions(self, enumValue)
Sets 3DOptions field.
@param enumValue: the new value ["NONE", "POLYGONZ", "MULTIPATCH"]. [str]
Sets Filename field. Path to the export location.
Sets Projection field. Projection method.
Sets ProjectionSettingsCenterLatitude field. Latitude of projection center.
Sets ProjectionSettingsCenterLongitude field. Longitude of projection center.
Sets ProjectionSettingsEllipsoid field. Ellipsoid used for projection.
Sets ProjectionSettingsFalseEasting field. False easting.
Sets ProjectionSettingsFalseNorthing field. False northing.
Sets ProjectionSettingsScaleFactor field. Scale factor.
Sets ProjectionSettingsTrueScaleLatitude field. True scale latitude.

AIRY = 'AIRY'
ANDRAE = 'ANDRAE'
BESSEL = 'BESSEL'
COMM = 'COMM'
ENGELIS = 'ENGELIS'
EVEREST = 'EVEREST'
FISCHER = 'FISCHER'
GRS = 'GRS'
GRS_1980 = 'GRS_1980'
HELMERT = 'HELMERT'
HOUGH = 'HOUGH'
IAU = 'IAU'
KAULA = 'KAULA'
LERCH = 'LERCH'
MERIT = 'MERIT'
MULTIPATCH = 'MULTIPATCH'
NAD27 = 'NAD27'
NAD83 = 'NAD83'
NONE = 'NONE'
PLESSIS = 'PLESSIS'
POLYGONZ = 'POLYGONZ'
SOVIET = 'SOVIET'
SPHERE = 'SPHERE'
WALBECK = 'WALBECK'
WGS_1960 = 'WGS_1960'
WGS_1966 = 'WGS_1966'
WGS_1972 = 'WGS_1972'
WGS_1984 = 'WGS_1984'

Command Reference
Classes
VOBExportModelSettings
class VOBExportModelSettings
VOB model export settings.

__repr__(self)
__str__(self)
load(self, name)
@return: result.
save(self, name)

BINARY = 'BINARY'
CREATE = 'CREATE'
DRY_RUN = 'DRY_RUN'
MODEL = 'MODEL'
NONE = 'NONE'
SHAPE = 'SHAPE'
TEXT = 'TEXT'
UPDATE = 'UPDATE'
UV_ALL = 'UV_ALL'
UV_NONE = 'UV_NONE'
VCITY1 = 'VCITY1'

Command Reference
Classes
VOBExportTerrainSettings
class VOBExportTerrainSettings
VOB terrain export settings.
@note: # Settings class used to control parameters for exporting terrain to Vue Objects (VOB)
exportSettings = VOBExportTerrainSettings()

__repr__(self)
__str__(self)
load(self, name)
@return: result.
save(self, name)

BINARY = 'BINARY'
CREATE = 'CREATE'
DRY_RUN = 'DRY_RUN'
MODEL = 'MODEL'
NONE = 'NONE'
SHAPE = 'SHAPE'
TEXT = 'TEXT'
UPDATE = 'UPDATE'
UV_ALL = 'UV_ALL'
UV_NONE = 'UV_NONE'
VCITY1 = 'VCITY1'

Command Reference
Function
noUIupdate(f)
Decorator to mark a function as non-UI updating.
By decorating a function with @noUIupdate: the function
will be executed on the UI thread thus preventing UI updates.
@note: # mark setAttributes() to run faster without UI updates
@noUIupdate
def setAttributes():
for shape in ce.getObjectsFrom(ce.selection, ce.isShape):
ce.setAttribute(shape, 'height', 15)
if __name__ == '__main__':
setAttributes()
Command Reference
Classes
AlignShapesSettings
class AlignShapesSettings
Shape align settings.
@note: # Settings class used to control parameters for alignShape algorithm
settings = AlignShapesSettings()
settings.setAlignfunction(AlignShapesSettings.TRANSLATE_TO_MIN)
ce.alignShapes(lots, settings)

__repr__(self)
__str__(self)
getAlignFunction(self)
Gets AlignFunction field. Specifies the alignment function.
@return: Value of AlignFunction field.
getAlignfunction(self)
Gets Alignfunction field. Specifies the alignment function.
@return: Value of Alignfunction field. ["PROJECT_ALL", "PROJECT_BELOW", "PROJECT_TO_OBJ_AVG", "TRANSLATE_TO_AVG", "TRANSLATE_TO_MAX", "TRANSLATE_TO_MIN"] [str]
getHeightmap(self)
Gets Heightmap field. Specifies the heightmap to align to. Use "y = 0" for alignment to X-Z plane.
@return: Value of Heightmap field. [str]
getOffset(self)
Gets Offset field. Y-Offset to be added to the aligned vertices.
@return: Value of Offset field. [float]
setAlignFunction(self, voidValue)
Sets AlignFunction field. Specifies the alignment function.
setAlignfunction(self, enumValue)
Sets Alignfunction field. Specifies the alignment function.
@param enumValue: the new value ["PROJECT_ALL", "PROJECT_BELOW", "PROJECT_TO_OBJ_AVG", "TRANSLATE_TO_AVG", "TRANSLATE_TO_MAX", "TRANSLATE_TO_MIN"]. [str]
setHeightmap(self, stringValue)
Sets Heightmap field. Specifies the heightmap to align to. Use "y = 0" for alignment to X-Z plane.
setOffset(self, floatValue)
Sets Offset field. Y-Offset to be added to the aligned vertices.

PROJECT_ALL = 'PROJECT_ALL'
PROJECT_BELOW = 'PROJECT_BELOW'
PROJECT_TO_OBJ_AVG = 'PROJECT_TO_OBJ_AVG'
TRANSLATE_TO_AVG = 'TRANSLATE_TO_AVG'
TRANSLATE_TO_MAX = 'TRANSLATE_TO_MAX'
TRANSLATE_TO_MIN = 'TRANSLATE_TO_MIN'

Command Reference
Classes
DXFExportShapeSettings
class DXFExportShapeSettings
DXF shape export settings.
@note: # Settings class used to control parameters for exporting shapes to DXF
exportSettings = DXFExportShapeSettings()
exportSettings.setFilename(ce.toFSPath("data/batchExportTests/lots.dxf"))
ce.export(lots, exportSettings)

__repr__(self)
__str__(self)
getFilename(self)
load(self, name)

@return: result. [DXFExportShapeSettings]
save(self, name)

Command Reference
Classes
MassiveExportSettings
class MassiveExportSettings
MASSIVE export settings.

__repr__(self)
__str__(self)
load(self, name)
@return: result.
save(self, name)

BINARY = 'BINARY'
CREATE = 'CREATE'
DRY_RUN = 'DRY_RUN'
MODEL = 'MODEL'
NONE = 'NONE'
SHAPE = 'SHAPE'
TEXT = 'TEXT'
UPDATE = 'UPDATE'
UV_ALL = 'UV_ALL'
UV_NONE = 'UV_NONE'
VCITY1 = 'VCITY1'

Prepare a new Project
Setup new Project and Scene

As a first step, we will create a new CityEngine project.
File New... CityEngine CityEngine project

Hit Next , name the project FirstCity and hit Finish
A new project has been created and shows up in the Navigator (by default located in the upper left corner of the CityEngine
window). The default folders that store your project data like assets, rules and scenes are already present.
Next, we create a new scene:
File New... CityEngine CityEngine scene

Make sure the correct project folder is set (/FirstCity/scenes), name the scene firstcity_01.cej and hit Finish
Our workspace now contains a new empty project with a scene file:
Copy Rules and Assets

Later in this tutorial, we need rule files and assets for the generation of the building models. We copy these files from the tutorial
projects.
First, we import the Tutorial 1 project into the current workspace.
Download and import the tutorial projects (or only Tutorial 1) into your workspace. See Work with the tutorials how to
get the tutorial files.
Next, we copy the necessary files from the downloaded Tutorial 1 project into our new project.
Locate the asset folder of Tutorial 1.

Use copy and paste ( Ctrl+C and Ctrl+V ) to copy all files and folders in the asset folder into the assets folder of
your new project.
Also copy the rule file building.cga from the rules folder into the rules folder of the new project.
Your navigator should now look similar to the following screenshot
Now, we are ready to create the street network and the building shapes in part 2.
Streets and Building Shapes
Creating a Street Network

First, we are going to create a street network.
Click in the viewport to make it active.

Graph Grow Streets...
For the city we want to create we use the default settings.
Hit Apply , and Close the dialog.
Click on the Frame All button on the Viewport's top menu (or press a ) to zoom out and view all of your newly
created street network in the Viewport.
Your viewport should display a street network with default building shapes similar to the one below.
It is now time to also take a first look at the Scene Editor. Note how a new layer Streetnetwork 1 has been created.
Modifying the Shape Creation Parameters
We will now change a few of the shape creation parameters to make the scene more interesting.
Make sure you see the complete scene by pressing a in the viewport.
With the left mouse button pressed, draw a rectangle from right-to-left around the whole scene to select all elements.
Go to the Inspector at the far right of the CityEngine window and click on the "Blocks" tab.
Open the "Block Parameter" shelf. You should now see the shape creation parameters.
Set subdivisionRecursive to false
Set subdivisionOffet to true
Set lotAreaMin to 300
Set lotAreaMax to 600
Set offsetWidth to 20
Note how the building shapes have been updated in the scene.
Continue with part 3 to learn how to assign CGA rules to the building shape and finally create the building models.
Create a street network
Tutorial Setup
Import the project Tutorial_02_Streets into your CityEngine workspace (see How to work with the tutorials)
Create a new scene File New .. CityEngine scene in the folder scenes of the street Tutorial project
Create an obstacle Layer

In urban environments there are many restrictions on the placement of streets. There might be lakes, rivers
or parks where no streets should appear. In the CityEngine, you can create an obstacle layer to control this
behaviour.
Obstacle map
Create a new map layer Layer New Map Layer...
Select Obstacle and hit Next
Select the file obstacles.png from the maps folder as Heightmap file
Set the X and Z size to 3000
Make you sure the alignment is set to centered

Hit Finish
Settings for the Obstacle Map Layer
Tip: If you don't see the obstacle map in the viewport, switch to textured shading mode on the top left corner of the viewport.
Create a terrain Layer
The Streets we want to create should follow an elevated terrain. This is achieved by creating a Terrain Layer
that's a greyscale heightmap.
Elevation map
Select Terrain and hit Next
Select the file elevation.jpg from the maps folder for heightmap
Select the file topo.png from the maps folder as Texture file
Set max. elevation to 250
set the X and Z size to 3000

Hit Finish
The settings for the Terrain Layer
Select the Obstacle map layer and change the Display Offset to -15 in the Inspector ( Window Inspector ). This prevents
overlaid drawing (Z-flickering) of the two map layers in the viewport
Grow street
It's time to let those streets grow.
Start the street growth dialog via Graph Grow Streets...
Change the number of streets to 1500
Select your Terrain Layer in the Terrain drop down
Select your obstacle map in the Obstacle map dropdown
Hit Apply
Attributes for the street generation growth dialog

Disable lot creation
We are only interested in streets now. Therefore,
Select all scene elements Select Select All

Select the Blocks tab in the Inspector
Set the shapeCreation parameter to false by clicking on the Off/On Switch
This will disable creation of lot shapes in blocks
Attributes for the street generation growth dialog
If you are dealing with large street networks, it might help to disable shape creation on streets to increase performance.
Simply select a set of streets and nodes, and set the shapeCreation parameter in their Inspector tabs to Off to disable shape
creation of streets and crossings.
Interactive street editing

Generated street networks can be modified interactively:
To create more streets in empty areas, select one ore more streets nearby, in the street grow dialog adjust the
number of streets you want to be created and and hit apply again
Select streets you want to remove and delete them via Edit Delete
To manually create new street segments, use the Graph Edit Tool
Use the transform modifiers to translate, rotate and scale individual streets or groups of street segments.
Changing street shape parameters

Select one or more street segments
Open the Segment tab in the Inspector
Change the street width by setting the streetWidth parameter
Street parameters
Street widths changed
Readjust elevation
The terrain elevation appears to be too high.
Select the Terrain Layer in the Scene Editor
Open the Layer Attributes pane
Change the max height value of the elevation attribute from 250 to 220
The inspector view of a terrain layer
You can change all other Map Layer attributes here too. If you have a different height map for example, choose your new
map, the terrain in the viewport changes accordingly.
Now you need to realign your street network to the new terrain.
Select the street network in the Scene Editor
Open the graph align dialog: Graph Align Graph...
Set the align function to Project All
Choose the layer Terrain
Hit Finish to align the graph elements
At the end of part 1 of this tutorial, your scene should look similar to this.
To distinguish the black street network from the dark parts of the map, you can select the streets or change the wireframe
color in Preferences Viewport
The final street network
Align terrain to shapes

Using Layer Align Terrain... CityEngine terrains can adapt to shapes.
Select all street shapes in the scene

Open the graph align dialog: Layer Align Terrain...
Use the defaults and hit Finish
The final street network
Changes in the adapted terrain are visible mor clear when wireframe is enabled on the terrain.
Select the terrain layer in the scene editor

In the Inspectors layer attribute pane, set Wireframe Alpha to 0.3
Use the defaults and hit Finish
Make sure wireframe mode is enabled in the 3D viewport settings (viewport top toolbar) or shortcut 7
Changing light direction can also help to display terrain details more clearly.
The aligned terrain with and without shapes
A quick way to check the modifications is to enable and disable elevationDelta in the Inspector (with the terrain selected).
Original and adapted

terrain
The original heightmap used for the terrain is not modified.
Terrain Resolution
When creating a terrain from a heightmap, the resolution of the heightmap defines the terrain's resolution. This can manually be
adjusted in the Inspector's layer attribute pane (with the terrain selected)
Terrain resolution settings
A higher resolution can help to increase the precision of the aligned terrain.
Be aware that high terrain resolution might lead to decreased 3D viewport performance (depending on your graphics
hardware).
Alternatively, you can also open scene Tutorial_02_Streets/scenes/streetTutorial_01.cej to see the result of this tutorial's first
part.

Advanced street network patterns
Tutorial Setup
Create a new scene File New .. CityEngine scene in the folder scenes of the street Tutorial project
Advanced street networks

Up to now we have only used very basic settings for the street network creation. This tutorial gives you some ideas and inspiration
on the range of street networks that can be made with the CItyEngine.
Change the pattern style during street growth

Start the street growth dialog via Graph -> Grow Streets...
Change both pattern dropdowns to RADIAL and hit apply
Change both pattern dropdowns to RASTER and hit apply
You will get a street network with radial streets in the center and raster-style streets in the outskirts
Connect two street networks

Hide the current street network graph layer by clicking on its eye symbol in the Scene Editor
Start the street growth dialog via Graph -> Grow Streets...
Change both pattern dropdowns to RADIAL and hit apply
Select the add tool (or shortcut G ) and create a separated single street
Select the cursor tool (or shortcut Q ) and select the new street
In the Street Growth dialog, change both pattern dropdowns to RASTER and hit apply
Note how Raster streets reaching the radial network are connected
Create a separated single street First growth phase with raster pattern
Second growth phase with raster pattern The two networks are connected
Note that only street segments which are on the same layer can be connected. Check the selected layer in the Scene Editor
before you add new streets or let streets grow.
Different street pattern Examples

Below 8 examples of street networks created with different patterns and patterns mixes are shown. Use the settings from the street
growth dialog image to recreate those patterns, or open Tutorial_02_Streets/scenes/streetTutorial_addPatterns.cej to see this
street networks.
01 Raster Pattern
02 Radial Pattern
03 Organic Pattern
04 Radial major streets with raster pattern on minors
05 Organic circle pattern
06 Honeycomb style
07 The "Glasses"
08 Organic distribution of rasters
Map Control Tutorial Part 1 :
Understanding CGA rule parameters
Tutorial Setup
Import the project Tutorial_03_MapControl into your CityEngine workspace (see How to work with the tutorials)
Open scene Tutorial_03_MapControl/scenes/mapcontrolTutorial_01.cej
What's in there already?

The opened scene already contains 2 map layers (Terrain and Water) and a street network layer with lot shapes. Have a look at
the Street Tutorial for details about how to create such a scene.
Where do rule parameters come from?

If you select a single lot now and check its attributes in the Inspector ( Window Inspector ), there are no rule parameters
assigned (the Rule Parameter pane is empty). This will change as soon as we assign a rule file to the lot.
Select the lot layer in the Scene Editor

Shapes Assign Rule File... and select the rule file rules/simpleBuildingShells_01.cga
Select a single lot again. Now there a attributes visible in the Inspector view, namely height.
CGA Attribute height in the Inspector
Where did they come from? As soon as you assign a rule file to a shape (in our case a lot), the attributes of the rule file are visible
as rule parameters of the lot. The entry Rule in the Source column shows that the value is taken form the rule file.
Click on the blue Rule File link in the Inspector to open the assigned rule file. On the very top the attribute height is defined:
// height value
attr height =80
This value is used in the rule file to define the height of the building. Now reselect the lot and generate the building
Shapes Generate
and you get a building 80 metres high.
Now change the height value in the Inspector from 80 to 150. Note how the Source column entry changes from Rule to User. The
rule parameter height for this building is now overruled by the value set in the Inspector. All other untouched lots still use the
height value from the rule file.
Regenerate the building and note how the building height has changed. At the end of part 1 of this tutorial, your scene should look
similar to this.
Alternatively, you can also open scene Tutorial_03_MapControl/scenes/mapcontrolTutorial_02.cej to see the result of this
tutorial's first part.

Control the skyline of your city
Continue from part 1 or open scene Tutorial_03_MapControl/scenes/mapcontrolTutorial_02.cej
The skyline map

If you generate some buildings with the current settings, your city would look similar to this.
Buildings with no height controls
This is not very convincing - a nice skyline would improve the look. Instead of setting the CGA shape attributes by hand like in part
1, we're now going to use the skyline map below to control the height of all buildings at once.
Skyline map and corresponding topography map

The red channel of the skyline map represents the height of the buildings in this area. Comparing the skyline map to the
topography map, you notice that we want to create a skyline that forms around the corner of the lake. There is also a second center
in the city on the top left.
Create the skyline map layer

Name the Layer "Skyline", select Mapping and hit Next
Select the file skylineMap.png from the maps folder for Mapping file

Create a new mapping attribute by clicking on the new attribute button
Name the attribute "height"

We want the red channel of the image to be interpreted as height, so select red from the channel dropdown
Buildings heights should vary between 10 (0% red) and 200 (100% red) meters. Enter therefore 10 for Minimum and
200 for Maximum value
Hit Finish to create the map layer
Adjust the display offset of your new map layer in the Inspector view to bring it to a position with better visibility. Use the
alpha value to give it some transparency.
Because we chose the attribute name height that is already present in our rule file, we can control the rule parameter with our
skyline map. Reassign the rule file to your lots to tell the CityEngine to do the connection.
Select all lots

In the Inspector's Rule Parameter pane, choose Skyline from the dropdown in the Source column
Mapped CGA Attribute height, controlled via map layer Skyline
After setting the source to the skyline layer, the value shows a ? sign. This means that the selection containts different values
(all lots shapes have different height values)
Select a single lot and have another look at its attributes in the Inspector view. The Source value of the height parameter changed
to Skyline, the name of the skyline map layer. In the Value column you see the value that is evaluated from the skyline image.
Mapped CGA Attribute height, controlled via map layer Skyline
Now select some lots around the bay area and generate the buildings
Drag-select some lots

Shapes Generate
Skyline controlled by the skyline map
This is starting to look good, but we will improve it using some more advanced techniques from the CGA grammar. Have a look at
the file rules/simpleBuildingShells_02.cga . (Double-click the file in the Navigator). Look for the following function:
// calc height with variation

getHeight(area) =
case area > 600 : rand(0,40)+height
case area > 200 : rand(0,40)+height/2
else: rand(15,30)
Instead of mapping the height value from the skyline directly to the building height, the above user-defined function is used which
does the following (see the CGA Shape Grammar Tutorial for details about CGA rules and functions)
High building will be created on big-area lots only

A random value is added to the incoming map value to give the skyline some variation

Shapes Assign Rule File... and select the rule file rules/simpleBuildingShells_02.cga
Shapes Generate
At the end of part 1 of this tutorial, your scene should look similar to this.
Skyline created using map values combined with CGA grammar commands
Alternatively, you can also open scene Tutorial_03_MapControl/scenes/mapcontrolTutorial_03.cej to see the result of this part of
the tutorial.

Map-controlled land-use types of buildings
Tutorial Setup
Continue your work from part 2 of this tutorial or open Tutorial_03_MapControl/scenes/mapcontrolTutorial_03.cej
Controlling land-use types for buildings

A city often has areas of specific land-use types. This part describes how to set the attributes for three different land-use types. The
map below marks commercial areas in blue, industrial areas in red and residential areas in green.
Land-use map and topography map
Create the landuse map layer

Before creating the map layer, have a look at the rule file rules/simpleBuildingShells_03.cga. Look for the 3 CGA attributes
// land-use type
attr t_industrial = 0
attr t_commercial = 0
attr t_residential = 0
The map layer we are going to create needs to have attributes with matching names
Hide the Skyline Layer by clicking on the eye symbol in the Scene Editor
Name the Layer "Landuse Types", select Mapping and hit Next
Select the file areatypes.png from the maps folder for Mapping File

Create 3 mapping attribute by clicking on the new attribute button
Name the first attribute "t_industrial" and select red from the channel dropdown
Name the second attribute "t_residential" and select green from the channel dropdown
Name the third attribute "t_commercial" and select blue from the channel dropdown
We will evaluate these parameters in the rule file again, therefore the default Minimum and Maximum values 0 and 1
are a good generic mapping for future use
Hit Finish to create the map layer
Adjust the display offset of your new map layer in the Inspector view to bring it to a position with better visibility. Use the
alpha value to give it some transparency.
Select the new map layer and check its attributes in the Inspector view. Check that the three CGA attributes have correct mappings.
If you want to change some of the settings of the map layer later, use this viewer.
Now the values of the Land-use map are going to be evaluated
Select all lots

Assign Rule File rules/simpleBuildingShells_03.cga
set the source of the landuse parameters to the layer Landuse Type
Mapped CGA Attributes for land use types
Before we do the final building generation, have another look in the rule file rules/simpleBuildingShells_03.cga and locate the
color declarations and the function landuseTypeColor
// color declarations
red = "#ffaaaa"
green = "#aaffaa"
blue = "#aaaaff"
white = "#ffffff"
// Functions
landuseTypeColor =
case t_industrial > 0.5 : red
case t_commercial > 0.5 : blue
case t_residential > 0.5 : green
else : white
This function analyses the values coming from the land-use map and returns a color accordingly. If the map coming from the map
is bigger than 0.5, the corresponding land-use color is returned, red for industrial, blue for commercial and green for residential
buildings. By using the color operation
color(landuseTypeColor)
that is calling the land-use color function, the color is applied to the generated buildings. Now generate all buildings in the scene.
Hit the generate button from the top toolbar
The final buildings colored by their land-use type
Alternatively, you can also open scene Tutorial_03_MapControl/scenes/mapcontrolTutorial_04.cej and generate the buildings to
see the result of this tutorial part.
Import Streets Tutorial:
Create and Import Street Data
CityEngine Street Networks

CityEngine street networks are attributed graphs, consisting of graph nodes (crossings) and graph edges (street segments). They
can either be generated with the street grow feature, created inside the CityEngine or imported via am external file such as DXF.
Preparing Street Data for the CityEngine

For this example, the main road structure for a seaside city has been sketched in Illustrator using its path and geometry tools.
A street network sketched with Adobe Illustrator
Export .dxf file from external CAD applications

When exporting the street network, make sure units are fitting the CityEngine unit system, which interprets numbers in
imported files as meters always. You might want to open the .dxf in an text editor and look for the vertex data to see
what dimensions are written out. In this example, we set an export scale of 1 pixel equals 10 units to get the dimensions
we needed (see export options screenshot)
...
AcDb2dVertex
10
1244.99951171875
20
234.998046875
30
0.0
0
VERTEX
...
Vertex data generated by Illustrator's DXF file export

Suggested options in Illustrator's DXF file export dialogue.
Import .dxf file into the CityEngine

Open the scene file sesame_01.cej
Locate the .dxf file sesame_streetsketch.dxf in the data folder
Right-click the file and choose Import...
Select CityEngine Layers DXF Import
The data Layer (Layer 2) is already added as Graph layer to be imported.
DXF import settings to import sesame_street data
Make sure Run Graph Cleanup Tool after Import is checked

Hit Next
Set merging distance to 5
Hit Finish
Graph Cleanup Settings
A new Graph Layer called sesame_streetsketch appears in the Scene Editor.
The imported street network in the CityEngine
Alternatively, you can open the scene file sesame_02.cej to get the scene with the imported data.
Grow minor streets

Once the major streets are imported, you can start to refine the street network and grow the minor streets in between.
The Street Grow Algorithm in the CityEngine tries to fill existing closed blocks, so you can iteratively fill the street
blocks with streets.
Focus the street block you want to create minor streets
Create two single small streets using the graph edit tool . This a) specifies the general
orientation of the streets in the block and b) defines a starting node for the Street Grow Algorithm
Manually creating street segments
Switch back to the selection tool and select the newly created small street segments.
Bring the Street Grow Dialog up Graph Grow Streets...
Select the desired patterns and hit Finish
Repeat these steps to fill the street blocks.
Continuously filling a block using the street grow tool
The scene file sesame_03.cej contains the finished street network.
Final Result
The scene file sesame_12.cej contains a finished street network with extracted and subdivided lots as seen in the
image below.
Sesame City with generated minor streets and extracted building footprints
Sesame City with simple building and vegetation models

Import Streets Tutorial:
Create and Import Street Data from OpenStreetMaps (OSM)
CityEngine Street Networks

CityEngine street networks are attributed graphs, consisting of graph nodes (crossings) and graph edges (street segments). They
can either be generated with the street grow feature, drawn inside the CityEngine or imported from files. This tutorial is about
importing street networks from OpenStreetMap's OSM format.
OpenStreetMap
"OpenStreetMap is a project aimed squarely at creating and providing free geographic data such as street maps to anyone who
wants them." --openstreetmap.org
OSM is a XML-based format to describe vector data used in a map. It defines three basic types such as nodes, ways and closed
ways which are used to describe all the other elements:
Nodes: The dots that are used for drawing segments between.
Ways: An ordered list of nodes, displayed as connected by line segments in the editor.
Closed Ways: Closed ways are ways which go in a complete loop. They are used to describe areas like parks, lakes or
islands.
Export an OSM file from OpenStreetMap
Point your browser to http://www.openstreetmap.org and locate the

area you are interested in.
Click on the "Export" tab and select "OpenStreetMap XML Data" as
format to export.
Save the file into the data/ folder of your current CityEngine project.
Optionally, export to map format as well to get a background map.
OSM Projection
To render maps from the lat.long vector data, OSM uses a slightly modified Mercator projection. To correct the incorrect scale
coming from this cylindrical projection, the median latitude needs to be set into the field True Scale Latitude in the OSM import
dialog.
Import an OSM file into the CityEngine

Open the a new scene file File New... CityEngine CityEngine scene
Locate the OSM file zurich_bellevue.osm in the data folder
Select CityEngine Layers OSM Import
In the OSM dialog, set Projection to Mercator.
In the Projection settings, set True Scale Latitude to 47.364125 (the median Latitude of the osm data)
In the node list, below the "highway" node, select the layers as shown below
Make sure Map OSM tags Run Cleanup Tool after Import is checked
and hit Next
GIS data is stored with different projections. This example uses Mercator projection on OSM data which lines up correctly with
images exported from OSM or Google Maps satellite imagery. If you need to align OSM data to other GIS data such as a
Heightmap, make sure you use the correct projection settings on import to make sure OSM data is projected the same way.
OSM import settings to import zurich_bellevue data
The second page of the import wizard shows the default OSM tag mapping. This will map OSM street classes to street and
sidewalk widths.
Use the defaults and hit Next
OSM tag mapping dialog
The third page shows graph cleanup options

Disable Intersect Segments
Enable Snap Nodes to Segments
Set Snapping Distance to 1
Enable Merge Nodes
Set Merging Distance to 1
Hit Finish
Imported streets might contain invalid or unclean graphs. This is why we used the Graph Cleanup Tool on import. You can
also call the Cleanup Tool afterwards using Graph Cleanup Graph... , and try different parameters to intersect street
segments and merge vertices and get cleaner data.
Cleanup Graph settings to import zurich_bellevue data
Two new layers (street network and shapes) appear in the Scene Editor.
The imported OSM data in the 3D viewport
Imported data
We are only interested in the street data here, hide the shape layer using the eye icon in the Scene editor.
Attribute mapping
Select a street an look at the street parameters in the inspector. On the example shown below, a street with highway type
pedestrian has assigned street and sidewalk width parameters according to the layer attribute mapping from the imported OSM
Layer zurich_bellevue 22.
Mapped layer attributes of a selected street segment shown in the Inspector
Create lot shapes

Shape creation is disabled on blocks and streets after importing. Therefore,
Select all scene objects
In the Blocks tab in the Inspector, set shapeCreation to On
Make sure shapes are set to visible in the top toolbar
Conflicting street segments leading to empty blocks

Imported osm data often is not very clean, and leads to conflicts (e.g. overlapping streets). The image above shows some conflicts.
Open blocks are indications of unconnected segments or overlapping streets which can lead to invalid blocks. There are different
ways to deal with such conflicts:
Play around with the cleanup parameters

Try to select less streets below the highway layer in the import dialog
Set street and sidewalk widths to smaller values (resulting in ess overlapping streets)
Manually clean up the street network after import by combine or removing nearby crossings, nearby parallel streets
OSM street data may contain street segments on different height levels. As this information is not available in the OSM tags,
CityEngine imports all data on the same height. Intersecting segments using the Graph cleanup tool might therefore lead to
incorrect intersections.
Cleaning a specific area
Unconnected segments
Select surroundign edges and nodes

Graph Cleanup Graph..
Adjust cleanup settings
Hit Finish
Cleanup settings
Select the blocks and make sure ShapeCreation ist enabled on the blocks
Cleaned area with valid blocks and subdivided lots
Result
as shown in file osm_01_lots.cej
Zurich Downtown with extracted blocks and generic subdivision
Adding a map layer

If have exported a map image along with the osm file (or have a map image with lat/long coordinates), this can be aligned to the
street data. To calculate the required position and scale values, you can use the OSM calculator sheet.
Alternatively, you can also use the provided Python script to calculate the values.
In the scripts folder, open the Python script osmCalculator.py (doubleclick opens the Python editor)
In the main clause of the script (at the very end), set your osm file, e.g. "data/zurich_bellevue.osm".
Run the script: Menu Python Run Script
Show the console: Menu Window Show Console
The console should read
** OSM Data From File**
minlat: 47.35139
minlong: 8.52228
maxlat: 47.37686
maxlong: 8.55769
True Scale Latitude: 47.364125

Lat Scale: 0.677336734494
X-Offset: 643201.884433
Z-Offset: -4060637.18563
X-Size: 2666.95769697
Z-Size: 2832.13875917
The Offset and Size values can be used to scale and place a map layer according to the osm data.
Create a new map layer with the calculated values:
Menu Layer New Map Layer...
New map layer dialog with the calculated values
Map aligned to OSM street data
Final Result
The scene file osm_03_models.cej contains the entire scene with street network, lots and map and a simple CGA file assigned
to the lot shapes.
See the result in the picture below.
Zurich Downtown with simple building models

Import Shapes Tutorial Part 1:
Create and Import Lots
CityEngine Lots
Beside the possibility to automatically create lots from street networks, lots can also be imported into the CityEngine. This is
especially important in cases where one needs exact lots, e.g. historically correct footprints of buildings in archaeology. The
CityEngine supports import of lots as polygon data in the .obj format. This tutorial provides some example files and hints how to
create files valid for the import.
Creating Lots using an external software

Lots can also be created inside CityEngine using the Create Shape Tool.
Obj file export is supported by almost every 3D modeling application. In this tutorial Maya was used to create the polygons. With
Maya's Create Polygon Tool, arbitrary polygons can be drawn by adding the vertex points. There are three important issues to
consider when modeling polygons that are to be used as CityEngine lots.
Creating a lot polygon in Maya
1. The CityEngine interprets the order of the vertices to distinguish the orientation of the lot. Draw polygons in counter-
clockwise manner to create a lot facing upwards. (This is the normal case, as e.g. an extrusion of the lot should go
upwards)
2. If the front facade of your future building should be distinctable, make sure the first edge you draw represents the side
of the front facade. The CityEngine lets you add special rule to the front facade, which will be the face that comes from
the first edge of the lot polygon.
3. Pay attention to the dimensions. Some tools might have different units or export units to obj differently.
Check the .obj file in a text editor to see the exported dimensions. The CityEngine always interprets numbers as meters.
v 299.143746 0.000000 117.566621

v 285.129154 0.000000 104.719897
v 275.202134 0.000000 116.398733
v 289.216726 0.000000 126.909692
...
Vertex data from example .obj file

Tip: Creating lot polygons from background images
Manually
created lot polygons using a aerial image using Maya
Export .obj file

Make sure your modeled footprint polygons are not grouped before exporting, but in flat non-hierarchical structure.
Lot polygons in
flat ungrouped hierarchy shown in Maya's Hypergraph view
Check groups in the export options. Materials are not needed for the lot polygon export.
Obj export settings for lot polygon export (Maya)
Import .obj file into the CityEngine

Open the scene file 01_footprints_01.cej
Locate the .obj file pompeii_footprints.obj in the data folder
Select CityEngine Layers OBJ Import and hit Next
Hit Finish
A new Shape Layer called pompeii_footprints appears in the Scene Editor. Both the object names and the start rules of the Lots
are taken form the object names in the obj file. In this case, polySurface10 for example.
Assign rule file

We will now generate simple buildings on the imported footprints. The rule file markFaces.cga colors the front faces red.
Remember that the front faces of our imported footprints are defined by the first edge of the lot polygons.
Lot -->
extrude(10)
comp(f){front : color("#ff0000") Frontface. | all : Face. }
Simple rule to mark front faces red
Select all footprints in the 3D viewport

In the inspector, set the start rule to Lot
Select the layer pompeii_footprints
Shapes Assign Rule File... CityEngine CityEngine scene and select the CGA file Shapes Generate or
Ctrl-g to generate the buildings
The extruded footprints, with the front faces marked red

Import named lots
Named Lots
Externally modeled lot polygons can be assigned a name that after importing can be used as start rule and therefore to trigger a
specific rule.
SphereCity lots
For this example, a part of a sphere has been created in Maya. All faces are single objects. They are named after specific areas on
the spheres, as displayed in the image below. The areas' names are Residential, Commercial, Industrial, Park and Street.
The Spherecity Model in a Maya viewport displaying the different areas in colors
A single face (a future lot) is named with the area type followed by an underscore and an index. After importing the SphereCity
model into the CityEngine, the name up to the first underscore will automatically be used as start rule. The face called Street_21 for
example will get the start rule Street.
Lot polygons of the SphereCity model in Maya's Hypergraph view
Have a look at the prepared obj file SphereCity_IS.obj . Select it in the Navigator and preview it in the Inspector view.
The SphereCity obj model displayed in the Inspector view

Open a new scene file. File New... CityEngine CityEngine scene and hit Next
Name the file 02_SphereCity_01.cej and hit Next
Locate and select the .obj file sphereCity_IS.obj in the data folder
Hit Finish
A new Shape Layer called SphereCity_IS appears in the Scene Editor. Select a single lot and check the start rule in the
Inspector that has been assigned automatically from the object's name.
A single selected and its assigned start rule in the Inspector
Assign rule file

If you look into the prepared rule file spherecity_01.cga (double-click it in the Navigator), you'll find starting rules for all the area
types. Let's generate the models now.
Select the layer sphereCity_IS
Shapes Assign Rule File... CityEngine CityEngine scene and select the CGA file spherecity_01.cga
from the rules directory
Shapes Generate or Ctrl-g to generate the buildings
SphereCity with generated models
The file
02_spherecity_02.cej contains the imported model with the rule file assigned and ready to generate the models.
Import Volumes
Importing volumes as Shapes

In some cases it is easier to model volumes in a external application than to describe them with the CGA grammar. This tutorial
shows how a crude building volume modeled in Maya can be imported into the CityEngine, and how its facades can then be refined
using CGA rules.
The building model

The building volume in the image below has been modeled with conventional methods in Maya. It is exported as an .obj file and will
be imported in the next step.
The building volume modeled in Maya

Name the file 03_ImportVolume_01.cej and hit Next
Locate and select the .obj file Building_1.obj in the data folder
Hit Finish
A new Shape Layer called Building_1 appears in the Scene Editor. S
Writing the rule file

The building volume's name Building_1 already defines its start rule Building. We therefore need to have Building as the starting
rule. We need to align the coordinate system of the imported model to the CityEngines yUp system. This is done with the help of
the CGA command alignScopeToAxes() . Afterwards, we can identify the different faces of the imported volume with the
component split comp(f) . We use the top selector for the roof faces, and the side selector for the facades. All we do at this step
is color the Roof shape to see that the faces are identified correctly.
Building -->
alignScopeToAxes(y)
comp(f){top : color("#ff0000") Roof. | side : Facade. }
Select the layer Building_1

Shapes Assign Rule File... CityEngine CityEngine scene and select the CGA file
importedVolume_01_markFaces.cga from the rules directory
The imported building volume generated with a simple rule to identify the faces.
Red : top faces (Roof) ; Grey : side faces (Facades)
Once the faces are identified correctly, we can continue the rule set on them. As these faces are modeled outside the CityEngine,
their orientation is not necessarily the way we need it for our rule operations. For the Facade rule we therefore start with the CGA
command alignScopeToGeometry(zUp, auto) . With this operation, the scope of the Facade shape is aligned to its lowest edge,
with z facing forward. This ensures that we operate with identically oriented scopes on all Facade faces.
Facade --> alignScopeToGeometry(zUp, auto) split(y){3.5 : Groundfloor | {~3 : Floor}* }
The rule file importedVolume_02_facades.cga has a set of rules that add more details to the building's facades. Refer to the
ShapeGrammar tutorials to get help about writng CGA rules. Generate the building now again using this rule set.
Select the layer Building_1
Shapes Assign Rule File... CityEngine CityEngine scene and select the CGA file
importedVolume_02.cga from the rules directory
The final imported buiding volume with facade rules applied
The scene file

03_importVolume_02.cej contains the imported model with the rule file assigned, ready to generate the models.
Import Textured Assets
In case you have pre-modelled, textured asset you want to use in your scene, they can be imported as well.
Supported formats are Wavefront obj and Collada dae
Import .dae file into the CityEngine

Name the file 04_ImportVolume.cej and hit Next
Locate and select the .obj file tower.dae in the data folder
Select CityEngine Layers DAE Import and hit Next
Hit Finish
A new Shape Layer called tower_1 appears in the Scene Editor.
A textured collada asset imported as a shape
Applying a CGA rule

If required, imported shapes can be processed further with CGA rules.
Assign rule file landmark.cga

Generate the model
The imported asset processed with two CGA rules

Basic Shape Grammar Tutorial Part 1:
Simple Building
This tutorial introduces the basics of CityEngine's CGA Shape Grammar. You will analyze a finished rule file which contains all
steps to create a basic building.
See Tutorial 14 for a demonstration how a similar building can be created using the visual CGA editor.
Tutorial Setup
Import the project Tutorial_06_Basic_Shape_Grammar into your CityEngine workspace (see How to work with the
tutorials)
Open scene Tutorial_06_Basic_Shape_Grammar/scenes/01_SimpleBuilding.cej
Simple Building
We will construct a simple building with a typical facade. The result of part 1 will look like this:
Select the lot (or the model if it's already generated) in the 3D viewport, and have a look in the Inspector (in case it is not open yet,
open it via Window Inspector )
Assigned rule file and start rule in the Inspector
Two important parameters are found here:
The Rule File contains a link to the rule file rules/simpleBuilding.01.cga. This rule file will be executed when the
generation is triggered.
The Start Rule defines the first rule that is executed within the rule file. In this case the start rule is Lot.
Let's get to the CGA rule file now:
Either click on the rule file link in the Inspector or double-click the file rules/simpleBuilding.01.cga in the Navigator
to open the file in the CGA Editor.
The Simple Building Ruleset

Building attributes are normally defined on the very beginning of the rule file (although they can be put anywhere in the rule file).
These attributes are used through the whole rule set and appear in the CGA Attribute Mapping Area of the Inspector, where their
values can be set and modified outside the CGA Grammar Editor as well.
attr groundfloor_height = 4
attr floor_height = 3.5
attr tile_width = 3
attr height = 11
attr wallColor = "#fefefe"
The window asset used for the creation of the simple building is defined here. The actual asset is loaded from the project's
assets folder, found in the Navigator.
// geometries
window_asset = "facades/window.obj"
The actual creation of the building starts now. Our first rule is called Lot. Remember the assigned start rule in the Inspector. The
mass model is created with the extrude operation:
Lot -->
extrude(height) Building
Usually in the next step, such a mass model can be divided into its facades by applying the component split.
Building -->
comp(f){ front : FrontFacade | side : SideFacade | top: Roof}
This rule splits the shape named Building, the mass model, into its faces by applying a component split. This results in a front
shape (usually the main front facade with entrance), several side shapes as Facades, and a Roof shape
Afterwards, the facades can be modeled. The typical facade modeling workflow looks as follows: In a first step, the facade can be
decomposed into Floors. Afterwards, the floors are further broken down into elements we call Tiles (floor subdivisions). A tile
consist usually of wall and window elements. This subdivision scheme can be implemented in the CGA shape grammar as follows:
Hierarchical decomposition of a facade into floors and tiles.
FrontFacade -->
split(y){ groundfloor_height : Groundfloor | { ~floor_height: Floor }* }
The rule FrontFacade splits the front face into a groundfloor shape of height 4 and a repeat of floor shapes of approximate
height 3.5 (note the tilde operator ~). Note that especially for front facades, the appearance of the ground floor is often different
from the other floors. They differ not only due to the fact that they have an entrance, but often also due to different sized floor
heights, different window appearances, other colors and so on.
SideFacade -->
split(y){ groundfloor_height: Floor | { ~floor_height: Floor }* }
The SideFacade rule splits the side facades into floor shapes. Therefore, the subdivision split is performed in the same way to
assure that the floor heights are in sync with the front facade
Floor -->
split(x){ 1: Wall
| { ~tile_width: Tile }*
| 1 : Wall }
The Floor rule is a typical example of a subdivision of a floor into tiles of approximate width 3. To make the floor design slightly
more interesting, we also split away a wall element of width 1 on each side.
Groundfloor -->
split(x){ 1: Wall
|{ ~tile_width: Tile }*
| ~tilewidth: EntranceTile
| 1: Wall }
The rule Groundfloor refines the groundfloor shape with a similar subdivision split, with the difference that an entrance is placed
on the right. The following figure depicts the extruded mass model on the left side and the described decomposition into floors and
tiles on
These rules decompose the initial mass model shape on the left into floors and tiles as shown on the right.
After the initial facade structure has been defined, the tiles can be modeled:
Tile -->
split(x){ ~1 : Wall
| 2 : split(y){ 1: Wall | 1.5: Window | ~1: Wall }
| ~1 : Wall }
The rule Tile defines the appearance of the tile by splitting along x- and y-axis (with a nested split). Note that in this design that the
wall elements are floating (with tilde) and that the window has a fixed size: 2 in width and 1.5 in height.
EntranceTile -->
split(x){ ~1 : SolidWall
| 2 : split(y){ 2.5: Door | ~2: SolidWall }
| ~1 : SolidWall }
The rule EntranceTile defines the entrance shape in a similar way as the tile shape (but obviously with no wall on the bottom),
resulting
Finally, the last rules replace the geometry of the Window, Door and Wall shape with the corresponding assets, positions them
and set the texture:
Window -->
s('1,'1,0.4)
t(0,0,-0.25)
i(window_asset)
Door -->
s('1,'1,0.1)
t(0,0,-0.5)
i("builtin:cube")
Wall -->
color(wallColor)
SolidWall -->
color(wallColor)
s('1,'1,0.4)
t(0,0,-0.4)
i("builtin:cube:notex")
Via the operation t(x,y,z), the current shape is translated -0.25 in the z-direction. This way the windows and textures are set back
0.25 meters into the facade. Afterwards the insert operation i(objectname) inserts an asset into the current scope. If the dimensions
are not set like in the Window or Door rules, the sizes are adapted automatically - otherwise the given dimensions are used. Via the
operation s(x,y,z) the size of the scope can be set in the Wall rule. The width and height of the scope are not affected since relative
coordinates are used: the x and y dimensions of the current scope are scaled by one ('1) resulting in no change. The z dimension is
set to -0.4 resulting in a wall with a thickness of 0.4 meters (pointing inwards).
Simple Building with window assets inserted
Continue with part 2 to learn how to add textures the Simple Building.
Simple Building Texturing
In the second part of the tutorial, you will earn how to quickly apply textures to window and wall elements of the Simple Building.
Tutorial Setup
Continue from part 1 or
Now open the rule file.

Use the rule you created from part 1 or
Double-click the file Tutorial_06_Basic_Shape_Grammar/rules/simpleBuilding.01.cga in the Navigator to open the
CGA rule editor.
Texture Declaration
Like the assets, we define the textures we will use on the top of the rule file. The textures are loaded from the assets folder. Add
the following lines to your rule file below /* Assets *****
// textures
frontdoor_tex = "facade/shopdoor.tif"
wall_tex = "facade/brickwall2.tif"
dirt_tex = "facade/dirtmap.15.tif"
roof_tex = "roof/roof.tif"
Nine different window textures are prepared in the project's assets/facade folder. Instead of listing all 9 texture names as single
assets, the following function returns one of the nine window textures in the asset folder.
Add the following line to the rule file:
randomWindowTexture = fileRandom("*facades/textures/window.*.tif")
Now, add the two lines in red to the Frontfacade and the Sidefacade rule:
Frontfacade -->
setupProjection(0, scope.xy 1.5, 1, 1)
split(y){ groundfloor_height : Groundfloor | { ~floor_height: Floor }* }
Sidefacade -->
split(y){ groundfloor_height: Floor | { ~floor_height: Floor }* }
The setupProjection() command prepares the UV coordinate projections on the facades for color (channel 0) and dirt map
(channel 2), projected onto the scopes xy plane, therefore scope.xy, is set as second parameter.
The brick texture (channel 0) will be repeated every 1.5m in X and every 1m in Y axis, whereas the dirt map (channel2) will span
over the whole facade and therefore uses scope.sx and scope.sy as size parameters.
Add a new rule Roof:

Roof -->
texture(roof_tex)
projectUV(0)
The Roof rule prepares the UV coordinates to go over the whole roof face, sets the roof texture and applies the texture
coordinates to the geometry.
Again, add the red lines to the subsequent rules:
Window -->
s('1,'1,0.4)
t(0,0,-0.25)
texture(randomWindowTexture)
i(window_asset)
Door -->
s('1,'1,0.1)
t(0,0,-0.5)
texture(frontdoor_tex)
i("builtin:cube")
For Window and door elements, we only set the colormap to the desired texture. For the window, we use the getWindowTex()
function with a random index to get one of the 9 window textures.
Wall -->
color(wallColor)
texture(wall_tex)
SolidWall -->
color(wallColor)
s('1,'1,0.4)
t(0,0,-0.4)
texture(wall_tex)
Wall and SolidWall use the UV's prepared in the Facade Rules. Beside chosing the textures for color and dirt channel, we also
need to project the UV's on those two channels.
Final model with textures on walls and assets

A simple building design generated with the CGA shape grammar. The final model consists of roof and wall (flat
polygons) plus the assets for door and windows. Top: final building model. Middle: close-up view of the same model.
Bottom: the ruleset applied onto arbitrary mass models.
Continue with part 3 , adding Level Of Detail

Adding Level of Detail
In this part of the tutorial, we will add a simple level of detail (LOD) mechanism to our Simple Building. We will be able to reduce
the complexity (polygon count) of the model which is helpful when we want to create bigger areas of Simple Buildings.
Tutorial Setup

Use the rule you created in part 2 or
CGA rule editor.
Adding LOD Attribute

We add a new attributes LOD to the existing attributes in the cga file:
attr LOD = 1
In this example, we will only define two levels of detail.

LOD 0 : Low level of detail, low complexity
LOD 1 : High level of detail, high complexity
The Simple Building we modeled already will be our high resolution model. We will now create a low-res version in a few easy
steps.
Taking another look at our current model, we notice that we can save polygons mainly on the window assets. We will use textured
planes instead of the complex window asset. Add the red lines to the Window rule:
Window -->
case LOD > 0 :
s('1,'1,0.4)
t(0,0,-0.25)
i(window_asset)
else :
We added a condition to the Window rule: in case the LOD value is bigger than 0 (our high-res), we use the old, hi-res window
asset. Otherwise (LOD equals zero), we do not load the window asset but use a simple plane coming from the facade. Similar with
the Door Rule: We load a simple plane instead of a cube
Door -->
case LOD > 0 :
s('1,'1,0.1)
t(0,0,-0.5)
else :
And one more time for the SolidWall Elements: Because we got rid of the inset of the door, we dont need solid elements anymore
SolidWall -->
case LOD > 0 :
color(wallColor)
s('1,'1,0.4)
t(0,0,-0.4)
texture(wall_tex)
else :
Wall
With the building selected, have a look in the attribute field of the inspector. You'll see our new LOD attribute listed here. Change
the value to 0. The source field changes from Rules to Value. This means that on the next generation of the building the LOD value
in the rule file will be set by the value 0 in the inspector.
The new LOD attribute in the Inspector
Generate the building to get the low level version shown below:
Simple Building in LOD 0
Displaying the model with wireframe on shaded (press 7 ) and untextured (press (press 5 ), the differences are clearly visible.
Press d to show the headup display containing the polygon count. We reduced the model from 3699 to 475 polygons.
Polygon Comparison LOD 0 vs LOD 1
Part 4 adds random variation to your simple buildings.

Random Variation of Building Attributes
The last part of this tutorial shows how to add variation to generated buildings by defining random attributes.
Tutorial Setup

Use the rule you created in part 3 or
CGA rule editor.
Adding Random Attributes

We will add variation to three of our building attributes: A random tile width between 2.5 to 6 meters, a random building height
between 8 and 35 meters, and three colors that are chosen randomly for each building.
attr tile_width = rand(2.5, 6)
attr height = rand(8, 35)
attr wallColor = 33% : "#ffffff"
33% : "#999999"
else : "#444444"
Since we will generate a larger number of buildings, change the default LOD value from 1 to 0.
attr LOD = 0
Select the layer Lots 2

Generate the buildings: Shapes Generate
Simple Buildings with variations in building attributes

Facade Modeling Tutorial Part 1:
Modeling the Facade Structure
This tutorial shows how to model a building from a picture and introduces some more complex CGA techniques. In the first part,
you will learn how to create the basic structure of the facade with CGA rules.
Tutorial Setup
Import the project Tutorial_07_Facade_Modeling into your CityEngine workspace (see How to work with the tutorials)
Open scene Tutorial_07_Facade_Modeling/scenes/FacadeModeling_01.cej
Facade Modeling
This tutorial explains how to write a set of CGA rules to recreate a facade form a real-world photograph. The facade we're going to
model is shown on the picture below. We will continuously analyze the photograph in more detail as we proceed extending the rule
set.
You will learn how to analyze an existing real-world facade and how to transfer its structure into CGA grammar rules, and how
premodeled assets can be used in CGA rules.
Photograph
Creating the rule file

Make sure the container is set correctly (Tutorial_07_Facade_Modeling/rules), name the file myFacade_01.cga
and hit Finish
A new CGA file is created, and the CGA Editor is opened. It is empty except some header information ( /* .... */ ) and the
version tag version "2010.1".
Volume and Facade

The actual creation of the building starts now. First, the mass model is created with the extrude operation. We will use an attribute
for the building height. Add the attribute height to the beginning of the rule file.
attr height = 24
and write the starting rule using the extrude command and call the shape Building
Lot --> extrude(height) Building
For this example we are only interested in the facade, so we use the component split to get rid of all faces except the front face,
and call the Frontfacade rule next.
Building --> comp(f) { front : Frontfacade}
Floors
Ledge analysis
The front facade is split horizontally into the different floors, each with height floor_height . The Floor shape is parameterized with
the split.index, which is the floor index. This parameter will be passed to to subrules to decide what elements to create on specific
floors. For the top floor, we set the floorindex to 999. This allows us to identify this floor easily.
Note the repeating split for the mid floors: This will allow the building to adapt dynamically to different building heights, and fill the
remaining vertical space with mid floors.
Again, we define some attributes for the floor dimensions:
attr groundfloor_height = 5.5

attr floor_height = 4.5
and add the rule
Frontfacade -->
split(y){ groundfloor_height : Floor(split.index) // Groundfloor
| floor_height : Floor(split.index) // First Floor
| floor_height : Floor(split.index) // Second Floor
| {~floor_height : Floor(split.index)}* // Mid Floors
| floor_height : Floor(999) // Top Floor, indexed with 999
| 0.5 : s('1,'1,0.3) LedgeAsset} // The top ledge just below the roof
We are now going to generate our facade for the first time:
Select the lot in the 3D viewport
Assign the rule file via Shapes Assign Rule File ... , select your cga file ( myFacade_01.cga ) and hit Ok
Hit the generate button on the top toolbar (or press Ctrl-g )
The Result should look like the image below. Not very exciting, but we're not finished yet.
The facade after splitting the floors

Floor Ledges
Ledge analysis
Now, floors are split now into ledge and tile shapes. Bottom ledges are specific to floors, we therefore use the parameter floorindex
for this rule.
The ground floor (floorindex 0) has not ledges and therefore calls Tiles only
Because windows start at floor level, no bottom ledge for the second floor. The balcony on this floor will be taken care
of in a later step.
All other floors have bottom ledge, tile and top ledge area
Floor(floorindex) -->
case floorindex == 0 :
Subfloor(floorindex)
split(y){~1 : Subfloor(floorindex) | 0.5 : TopLedge}
else :
split(y){1 : BottomLedge(floorindex) | ~1 : Subfloor(floorindex) | 0.5 : TopLedge}
Floors with ledge splits
Subfloor
Subfloor analysis
Subfloors consist of small wall areas on left and right edges and repeating tiles in between.
Add another attribute on top
attr tile_width = 3
and add the rule

Subfloor(floorindex) -->
split(x){ 0.5 : Wall(1)
| { ~tile_width : Tile(floorindex) }*
| 0.5 : Wall(1) }
At this point, we added a parameterized Wall shape. This is important for a later step when we will texture the facade. Looking at
the facade photograph, we differ between three wall styles:
1: dark bricks with dirt texture,
2: bright bricks with dirt texture,
othwerwise: dirt texture only. This is mainly needed for fassade assets that do not have a brick structure.
As you see from the following rule, the wall styles produce identical output. In a later step, we will add different textures to the wall
types.
Wall(style) -->
// dark bricks with dirt
case style == 1 :
color(wallColor)
// bright bricks with dirt
case style == 2 :
color(wallColor)
// dirt only
else :
color(wallColor)
Floors split into tiles
Tile
Tile analysis
Apparently, tiles are very homogeneous on this facade. We only need to differ between the ground floor tiles and the upper floors.
We use the attributes door_width and window_width to set the different split dimensions:
attr door_width = 2
attr window_width = 1.4
Tile(floorindex) -->
split(x){ ~1 : SolidWall
| door_width : DoorTile
| ~1 : SolidWall }
else :
split(x){ ~1 : Wall(getStyle(floorindex))
| window_width : WindowTile(floorindex)
| ~1 : Wall(getStyle(floorindex)) }
For the ground floor tiles, a new shape SolidWall was added. This is necessary, as doors in the ground floor are inset from the
facade. To avoid holes between door and wall, we use a solid wall element there by inserting a cube with a certain thickness.
Because we will use this thickness again in a later Door rule, we define it as a const variable wall_inset . Declaring values that
are used more than once is a good idea as it ensures that the same value is taken in different rules.
const wall_inset = 0.4

SolidWall -->
s('1,'1,wall_inset) t(0,0,-wall_inset)
Wall(1)
We declared a function to get the wall style from the floor index. Looking at the facade, we see that we have dark textures on the
ground and first floor, and bright textures on the others. The function getStyle maps the floor index to the corresponding wall style.
getStyle(floorindex) =
case floorindex == 0 : 1
case floorindex == 1 : 1
else : 2
Facade after tile split
Continue with part 2 to learn how to use assets on this facade.

Inserting Assets
The second part of the Facade Modeling Tutorial is all about using premodeled assets on the facade.
Open scene file Tutorial_07_Facade_Modeling/scenes/FacadeModeling_02.cej
Open CGA file Tutorial_07_Facade_Modeling/rules/facade_02.cga
Assets
Looking at the photograph of the facade we are going to model, we find the following needed assets:
Window: Used for the window elements
Round Windowtop: ornament above window
Triangle Windowtop: ornament above window
Half arc: used for arcs on ground floor
Ledge: used for all ledges
Modillion: used for window ornaments and arc ornament on ground floor
The assets we are going to use
These assets are already present in the assets folder of the tutorial project. You can preview these assets inside the CityEngine in
the Inspector by selecting the desired asset in the Navigator.
The triangle window ornament asset in the Inspector preview
Asset Declarations
It is a good idea to have all the asset declarations in the same place, we therefore add these lines below the attribute declarations
into our rule file.
const window_asset = "facades/elem.window.frame.obj"
const round_wintop_asset = "facades/round_windowtop.obj"
const tri_wintop_asset = "facades/triangle_windowtop.obj"
const halfarc_asset = "facades/arc_thin.obj"
const ledge_asset = "facades/ledge.03.twopart_lessprojection.obj"
const modillion_asset = "facades/ledge_modillion.03.for_cornice_ledge_closed.lod0.obj"
Window
Up to now we already have the rules ready for the exact placement of the window assets. Just call the Window shape in the
WindowTile rule:
WindowTile(floorindex) --> Window
and add the following rule to scale, position and insert our window asset, and a glass plane behind.
Window -->
s('1,'1,0.2) t(0,0,-0.2)
t(0,0,0.02)
[ i(window_asset) Wall(0) ]
Glass
Facade with window assets inserted

Window Ornaments
Window analysis
Looking at the facade picture again, things are a bit more complicated: There are different windows (or window elements) on the
different floors. We therefore need to extend our WindowTile rule and trigger shapes specific to the floor index:
No special ornaments on the first and the top floors (indices 1 and 999), therefore only Window is invoked.
On the second floor, we insert an additional Shape WindowOrnamentRound. Because this element should be aligned to
the top border of the Window, we translate the current Scope upwards the y-axis with '1
The other window tiles (on the mid floors) get an additional WindowLedge shape, as well as the ornament
WindowOrnamentTriangle, again translated along Y.
WindowTile(floorindex) -->
case floorindex == 1 || floorindex == 999 : Window
case floorindex == 2 : Window t(0,'1,0) WindowOrnamentRound
else : Window WindowLedge t(0,'1,0) WindowOrnamentTriangle
Instead of using the final assets directly, we will insert proxy cubes first. This way we can easier set the dimensions for the real
assets. We can use the built-in cube asset for this case.
We set the dimensions, center the scope on the x-axis, insert the cube and color it for better visibility
WindowOrnamentTriangle -->
s('1.7, 1.2, 0.3) center(x) i("builtin:cube") color("#ff0000")
# set dimensions for the triangle window element and insert it

WindowOrnamentRound -->
s('1.7, 1.2, 0.4) center(x) i("builtin:cube") color("#00ff00")
WindowLedge -->
s('1.5, 0.2, 0.1) t(0,-0.2,0) center(x) i("builtin:cube") color("#0000ff")
Window ornaments with colored cubes as proxies
Exchanging Proxies with Real Assets

Dimensions of our window ornaments seem reasonable, so we insert the actual assets instead of the cube. For the WindowLedge,
we will stick with the cube.
WindowOrnamentTriangle -->
s('1.7, 1.2, 0.3) center(x) i(tri_wintop_asset)
s('1.7, 1.2, 0.4) center(x) i(round_wintop_asset)
Window ornament assets inserted
We are still not finished with the windows on the second floor: The round window ornaments are missing the side pillars. We
therefore add a new split command to the WIndowOrnamentRound rule we just added before. This line will prepare the scopes for
the following modillion asset.
s('1.7, 1.2, 0.4) center(x) i(round_wintop_asset) Wall(0)
split(x){~1 : PillarModillion | window_width : NIL | ~1 : PillarModillion }
Dimensions are set, and the modillion asset is inserted. Note that by applying the relative negative translation ('-1) in y-direction,
the asset's top is aligned to the bottom face of the ornament.
PillarModillion -->
s(0.2,'1.3,'0.6) t(0,0,'-1) center(x) i(modillion_asset)
Window ornament pillar assets inserted
Doors
Doortile structure
The door tile is split vertically into door, arc and top area. To ensure non-elliptic arcs, the height of the arc area need to be half the
width of the door (the current x scope):
DoorTile -->
split(y){~1 : Door | scope.sx/2 : Arcs | 0.5 : Arctop}
On the top area, a wall element and and overlayed modillion asset are inserted.
# Adds wall material and a centered modillion

Arctop -->
Wall(1)
s(0.5,'1,0.3) center(x) i(modillion_asset) Wall(1)
The arcs area is split again, and two arc assets are inserted. Now we use the variable wall_inset we defined earlier. Note that we
need to rotate the right halfarc to orient it correctly.
Arcs -->
s('1,'1,wall_inset) t(0,0,-wall_inset)
Doortop
i("builtin:cube")
split(x){ ~1 : ArcAsset
| ~1 : r(scopeCenter,0,0,-90) ArcAsset}
Finally, we set the Wall shape on Doortop and door and insert the actual arc asset:
Doortop --> Wall(0)
Door --> t(0,0,-wall_inset) Wall(0)
ArcAsset --> i(halfarc_asset) Wall(1)
Door tiles with assets inserted
Ledges
Let's head over to the ledges now. We need rules for top and bottom ledges. Top ledges use a simple wall stripe, bottom ledges
need to be distinguished on the different floors, with the actual ledge asset inserted.
TopLedge --> WallStripe
BottomLedge(floorindex) -->
case floorindex == 1 : split(y){~1 : Wall(0) | ~1 : s('1,'1,0.2) LedgeAsset}
case floorindex == 999 : split(y){~1 : WallStripe | ~1 : s('1,'1,0.2) LedgeAsset}
else : WallStripe
WallStripe --> split(x){ 0.5 : Wall(1) | ~1 : Wall(2) | 0.5 : Wall(1) }
LedgeAsset --> i(ledge_asset) Wall(0)

Ledge assets inserted
Balcony
What's left? Right, the balcony. Head way back to the Floor rule and add the shape Balcony to the second floor case:
split(y){~1 : Tiles(floorindex) Balcony | 0.5 : TopLedge}
Again we will start with a simple proxy first to ensure the placement and the dimensions of the balcony.
Balcony -->
s('1,2,1) t(0,-0.3,0) i("builtin:cube") color("#99ff55")
A cube proxy visualizes the position and scale of the future balcony
Balcony analysis
The balcony box is now split into its components: beams, floor and railing.
Balcony -->
s('1,1.5,1) t(0,-0.3,0) i("builtin:cube") color("#99ff55")
split(y){0.2 : BalconyBeams
| 0.3 : BalconyFloor
| 1 : RailingBox }
Balcony cube split into balcony components
The beams supporting the balcony are created with a repeating split
BalconyBeams -->
split(x){ ~0.4 : s(0.2,'1,'0.9) center(x) Wall(0) }*
The BalconyFloor shape only triggers the Wall rule.

BalconyFloor --> Wall(0)
Using the component split on the RailingBox, we extract the necessary faces for the balcony railings.
# Get the front, left and right components (faces) of the RailingBox shape
RailingBox -->
comp(f){front : Rail | left : Rail | right : Rail}
Balcony with beams and railing faces
Finally, we set the dimension insert a cube to create the balcony rails
Rail -->
s('1.1,'1,0.1) t(0,0,-0.1) center(x) i("builtin:cube") Wall(2)
Finished balcony with solid railings
Final Fassade with Geometry Assets

Final facade model with assets
Final facade model exported and rendered in Blender
Now you have the final model, try apply the rule on different lot shapes, or play around with the user attributes found in the
inspector to modify your facade design.
Continue with part 3 to learn how to apply textures on this facade.

Texturing the Facade
This part of the Tutorial shows techniques to texture your Facade.
Open scene file Tutorial_07_Facade_Modeling/scenes/FacadeModeling_03.cej
Open CGA file Tutorial_07_Facade_Modeling/rules/facade_03.cga
Texture Assets
On top of the rule file, we add the textures that are going to be used as attributes:
const wall_tex = "facades/brickwall2.tif"
const wall2_tex = "facades/brickwall2_bright.tif"
const dirt_tex = "facades/dirtmap.15.tif"
const doortop_tex = "facades/doortoptex.jpg"
For the window and door textures we use a function to get the texture string, thus we do not have to list all textures separately.
getWindowTex(inst) = "facade/window." + inst + ".jpg"
getDoorTex(inst) = "facades/textures/doortex." + inst + ".jpg"
Setup the Global UV Coordinates

Texturing with the Shape Grammar consists of three commands:
1. setupProjection(): define the uv coordinate space
2. set(material.map): set a texture file
3. projectUV(): apply the UV coordinates
We will add two texture layers on the facade, a brick texture and a dirt map. Because we want to have consistent texture
coordinates over the whole facade, we need to do the UV setup on the Facade rule. To be able to test our texturing setup
beforehand, we will add a new intermediate rule FrontfacadeTex.
Change the Building rule to:
Building --> comp(f) { front : FrontfacadeTex}
and create a new rule

FrontfacadeTex -->
setupProjection(0, scope.xy, 2.25, 1.5, 1)
projectUV(0)
setupProjection(0, scope.xy, 2.25, 1.5, 1) defines the texture coordinates for the texture channel 0 (the color channel). The
UV coordinates will be projected along the scopes xy plane and repeated every 2.25 units in x and every 1.5 units in y direction.
We set the colormap to "builtin:uvtest.png" , which is a texture to quickly check UV coordinates. We finally apply the UV
coordinates by baking the UV coordinates for channel 0. Generate the facade to see the UV setup.
Testing the colormap UVs on the facade
Now, we add the UV setup for the dirt channel:

FrontfacadeTex -->
projectUV(0)

set(material.dirtmap, "builtin:uvtest.png")
projectUV(2)
This texture should span over the whole facade. We therefore use the relativ operators '1 and '1 for the UV setup, which are the
dimensions of the facade. Generate the facade again to get the following result.
Testing color and dirt UVs on the facade
If you're curious how the facade will look like with the actual textures, exchange the builtin uvtest texture with the real ones:
FrontfacadeTex -->
texture(wall_tex)
projectUV(0)
setupUProjection(2, scope.xy, '1, '1)

projectUV(2)
Testing color and dirt UVs on the facade.
Left: Brick texture; Center: Dirt Texture; Right: Brick and dirt texture combined
The UV coordinates seem to be ok for the facade. For the actual building, we only need the UV's setup at this point, so change the
FrontfacadeTex rule to:
FrontfacadeTex -->
Frontfacade
Our old Frontfacade rule now has UV coordinates set up correctly for the subsequent elements.
Texturing the Walls

Remember how we already added a style parameter to the Wall rule? Now we will profit from this. We want to have three wall
styles with different textures. Change the Wall rule to the following:
Wall(style) -->
// dark bricks with dirt
case style == 1 :
color(wallColor)
texture(wall_tex)
// bright bricks with dirt
case style == 2 :
color(wallColor)
texture(wall2_tex)
// dirt only
else :
color(wallColor)
projectUV(2)
And voila: All wall elements are textured.

Facade with textured wall elements
Texturing the Window Asset

For the window asset, we want to use a set of window textures to color the glass plane. We therefore need to setup the UV
coordinates to span the whole glass shape, this is done by using '1 for both x and y direction. We call the getWindowTex function
we defined earlier with a random value between 0 and 7. The ceil() command rounds the random value to the next integer
value, which is what we need for the texture call.
Glass -->
setupProjection(0,scope.xy, '1, '1)
projectUV(0)
texture(randomWindowTex)
Additionally, we will add specularity to the glass.

Glass -->
projectUV(0)
texture(randomWindowTex)
set(material.specular.r, 1) set(material.specular.g, 1) set(material.specular.b, 1)
set(material.shininess, 4)
Texturing the door shapes

The door planes are textured just like the window glass.
Doortop -->
texture(doortop_tex)
projectUV(0)
Door -->
t(0,0,wall_inset)
texture(randomDoorTex)
projectUV(0)
The final facade with all textures applied

Mass Modeling Tutorial Part 1:
Mass Modeling : L and U Shapes
This tutorial shows how mass models of buildings can be create with the ShapeGrammar. Typical architectural volume shapes
like L and U masses will be created.
Tutorial Setup
Import the project Tutorial_08_Mass_Modeling into your CityEngine workspace (see How to work with the tutorials)
Open scene Tutorial_08_Mass_Modeling/scenes/MassModeling_01.cej

Make sure the container is set correctly (Tutorial_08_Mass_Modeling/rules), name the file myMass_01.cga and hit
Finish
A new CGA file is created, and the CGA Editor is opened.
Version 1
We start with a very simple L-Shape.
attr height = rand(30,60)
attr wingWidth = rand(10,20)
Lot --> LShape
LShape -->
shapeL(wingWidth,wingWidth) {shape : LFootprint }
LFootprint --> extrude(height) Mass
LotInner --> OpenSpace
The shapeL command creates a L shape footprint, with dimensions ranging between 10 and 20. The second rule LFootprint then
extrudes the L-Shape to its height.
LotInner will simply apply OpenSpace, leaving the lot shape as is.
Now apply the rule to the lots:

Select your rule file ( myMass_01.cga ) from the rules directory and hit Ok
And generate the buildings:

Select some of the lots in the 3D viewport
Single extuded L-Shape volume
Simple L-Shapes on a small city part
The L-shaped mass models seem to work, however they do not look very convincing. First of all, we need more variation.
Version 2
The current L-Shape's side wing is always positioned on the left side of the main mass. Using rotateScope we can change the L-
Shape to be on the right side as well.
Change the red lines in the LShape rule using the probability operator % to improve the L-Shape to have its side wing either on the
left or the right side.
LShape -->
50% : shapeL(wingWidth,wingWidth) {shape : LFootprint }
else : rotateScope(0,90,0) shapeL(wingWidth,wingWidth) {shape : LFootprint
With the help of the convexify command, we can split the L-Shape into its wings, and change the height of the two wings. Again we
use random probability to add variation.
LFootprint -->
75% : extrude(height) Mass
else : convexify comp(f){0 : extrude(height) Mass | all : extrude(height*0.7) Mass}
Varying L-Shapes
Side wings now appear on left and right side, and are varying in height. The L-Shapes are ok now, however we need different
shapes now.
Version 3
We will add a UShape now. Call UShape instead of LShape in the starting Lot rule:
Lot --> UShape
Similarily we use the shapeU command:

UShape -->
shapeU(wingWidth,wingWidth*0.7,wingWidth*0.7) { shape : UFootprint }
UFootprint --> extrude(height) Mass
and with some variation as well:

UShape -->
80% : rotateScope(0,180,0) shapeU(wingWidth,wingWidth*0.7,wingWidth*0.7) { shape : UFootprint }
else: shapeU(wingWidth,wingWidth*0.7,wingWidth*0.7) { shape : UFootprint }
UShapes
Looking at the buildings in the resulting image, one notices that U-Shapes do not work well on all lots. We will correct this in
version 4.
Version 4
The height distribution is not convincing.To have better control over the building heights, we add a condition to the height attribute.
Only big area lots should be allowed to create high buildings.
attr height =
case geometry.area < 1000: rand(20,50)
else: rand(50,150)
We add a new rule LUShapes to control what shape is created on which lots.
U-Shapes work best on shapes that are wider than deep. Or in CGA language, where scope.sx is bigger than scope.sy. In the
other case, we only trigger L-Shapes
LUShapes -->
case scope.sx > scope.sz :
60% : UShape
else : LShape
else: LShape
Both L and U Shapes do not work well on non rectangular lots. The next case statement makes sure UShape and LShape are only
created on approximately rectangular lots (with a tolerance of 15 degrees). Otherwise, we call a new footprint rule.
LUShapes -->
case geometry.isRectangular(15):
case scope.sx > scope.sz :
60% :UShape
else : LShape
else: LShape
else: BasicFootprint
Extruded lot shapes will be too big compared to the L and U Shapes. We therefore add an negative offset to the BasicFootprint.
This will also help to make more space between individual buildings.
BasicFootprint --> offset(-5,inside) extrude(height) Mass

L and U Shapes combined
Continue with part 2 to learn how to use recursion in the Shape Grammar for mass modeling.
Mass Modeling Tutorial Part 2 :
Mass Modeling using Recursion
This tutorial shows how to model repetetive building elements using recursive Shape Grammar calls.
Tutorial Setup

Finish
Version 1
height =
case geometry.area > 1000: rand(50,200)
else: rand(20,50)
Lot --> Tower
Tower --> extrude(height) Envelope
Envelope --> RecursiveSetbacks
The attribute height creates a random value for the building height. The starting rule Lot calls Envelope, which extrudes the
footprint to the towers envelope. Envlope calls the Recursion rule.
For the subsequent recursive rules, we need to additional variables. lowHeight and scale . The latter needs to be constant for a
building, we therefore define it as an attribute.
lowHeight = 50% : 0.4 else: 0.6 // switching between these two values creates visually appealing
setbacks
attr scale = rand(0.75,0.9) // has to be constant
The rule RecursiveSetbacks splits the mass, as long as it is higher than two floors, into a lower part Mass with relative height
lowHeight. The upper remaining part generates the shape Setback. In case the RecursiveSetbacks shape is smaller than two
stories the remaining part is set to floorheight in height and a Mass shape is generated.
attr floorheight = rand(4,5)
RecursiveSetbacks -->
case scope.sy > 2*floorheight :
split(y){ 'lowHeight : Mass | ~1: Setback }
else:
s('1,floorheight,'1) Mass
The Setback rule scales and centers the shape and recursively invokes the RecursiveSetbacks rule.
Setback -->
s('scale,'1,'scale) center(xz) RecursiveSetbacks
Now apply the rule to the lots:


The resulting shapes are shown below:
Generated models using recursive Shape Grammar calls
Version 2
Using an external cylinder asset, we can very easily create round versions of our recursive towers. Modify the rule Tower as
follows:
Tower -->
20% : i("cyl.obj") RecursiveSetbacks
else: RecursiveSetbacks
else: RecursiveSetbacks
In 20% of all towers, we insert a cylinder asset instead of using the implicit cube as underlying shape.
Mixing rectangular and round recursion towers
Continue with part 3 where we will modify the lot parcels with setbacks.
Mass Modeling Tutorial Part 3 :
Adapting the parcel with setbacks
In this part we will apply setbacks to the lot shapes.
Tutorial Setup

Finish
Street setback
attr height =
case geometry.area > 1000: rand(50,200)
else: rand(20,50)
attr distanceStreet =
20% : 0
else : rand(3,6)
Lot --> Parcel

LotInner --> OpenSpace
Parcel -->
setback(distanceStreet)
{ streetSide: OpenSpace
| remainder: Footprint }
Footprint --> extrude(height)
OpenSpace --> color("#77ff77")
The Parcel rule applies a setback on all street sides of the lot, and forwards this area to the OpenSpace rule. The inner part, away
from street sides is forwarded to Footprint, which extrudes to a random height.
the streetSide selector evaluates the shapes streetWidth object attributes, which is automatically set for lots created from
blocks but might not be present on manually created shapes.

Select a lot in the 3D viewport

Shapes Generate or Ctrl-g to generate the building
Parcel with streetside setback
Buildings distance
We now add a similar setback to control distance between buildings. Add the attr distanceBuildings, modify the Parcel rule, and add
a new rule SubParcel as shown below.
attr distanceBuildings =
30% : 0
else : rand(4,8)
Parcel -->
setback(distanceStreet)
{ streetSide: OpenSpace
| remainder: SubParcel }
SubParcel -->
setback(distanceBuildings/2)
{ noStreetSide: OpenSpace
| remainder: Footprint }
SubParcel with again apply a setback, but this time on the non-street edges.
Save the cga file
Select some lots in the 3D viewport
Select a generated model and play around with the rule parameters distanceBuildings and distanceStreet. You can set the values
on a single selected model or simultaneously multiple selected models.
To reset the user-defined value back to the random value coming from the rule file, chaneg the Source from User back to Rule.
Rule Parameters distanceBuildings and distanceStreet manually set in Inspector
The resulting setback parcels
Continue with part 4 where we will combine our mass models from part 1 and 2 with the setback parcels, and add texture facades.
Combine masses and setbacks
We now combine the results from part 1 to 3.
Tutorial Setup

Open the rule file massmodeling_03.cga , and save it as myMass_04.cga
Import LU shapes and tower mass rules

add two import commands.
import lushapes : "massmodeling_01.cga"
import towers : "massmodeling_02.cga"
and modify the Footprint rule
Footprint -->
25% : towers.Tower
else : lushapes.LUShape
else:
25%: towers.Tower
else : offset(-5,inside) lushapes.BasicFootprint
Save the rule file


The resulting shapes are shown below:

City with mixed LU Shapes (from part 1) and tower shapes (from part 2) and setback parcels from part 3
Continue with part 5 to add textured facades.

Add Textured Facades
Learn how to add simple textured facades to our mass models.
Tutorial Setup

Open the rule file massmodeling_04.cga , and save it as myMass_05.cga
We want to add simple textured facades to our mass models. We need a function that randomly selects one of our 12 facade
texture tiles.
const randomFacadeTexture = fileRandom("*facade_textures/f*.tif")
To be able to correctly map the texture tiles to our facade, we define to functions that calculate the actual floor height and tile width.
With the help of these functions, we ensure that no texture tiles are cut off at the edge of the facade.
attr floorheight = rand(4,5)
actualFloorHeight =
case scope.sy >= floorheight : scope.sy/rint(scope.sy/floorheight)
else : scope.sy
actualTileWidth =
case scope.sx >= 2 : scope.sx/rint(scope.sx/4)
else : scope.sx
With the help of the component split, we get the facade components from our mass models.
Mass -->
comp(f){ side: Facade | top: Roof. }
Now we need to tell our imported rules to use this Mass rule:
towers.Mass --> Mass
lushapes.Mass --> Mass
Finally, we setup the UV coordinates on the facade, define the texture file using the randomFacadeTexture function and project the
UV's.
Facade -->
setupProjection(0, scope.xy, 8*actualTileWidth, 8*actualFloorHeight)
texture(randomFacadeTexture)
projectUV(0)
Save the rule file


Advanced Shape Grammar Tutorial:
Complex Facade Patterns
This tutorial shows how to model a building from a picture and introduces some more complex CGA techniques.
Tutorial Setup
Import the project Tutorial_09_Advanced_Shape_Grammar into your CityEngine workspace (see How to work with
the tutorials)
Open scene Tutorial_09_Advanced_Shape_Grammar/scenes/ComplexPatterns.cej
Generate the building

This tutorial explains how to create a set of CGA rules to recreate a building form a real-world photograph. The facade we're going
to model can be seen on the picture below. Due to the tricky patterns of the tile and window layout in this example we will need
some more advanced CGA mechanisms like nested repeat splits and parameter passing.
Facade Photograph
The final building
In case you want to generate the building beforehand,
Select one of the lots in the 3D viewport
Facade analysis
When planning a new CGA rule, it is helpful to shortly sketch the crude layout and define some of the shape names before starting
to write the rules.
The facade we want to model consists mainly of three floor types, Top, Ground and Upper Floors. The lower floors are made of
tiles containing windows, whereas the top floor only contains window elements. Every second of the lower floors is identical, wo
we'll have to pass the this index (the floorIndex ) with the Floor shape to create the correct look (tile and window alignment) for a
specific floor.
Due to the pattern of the tiles, we define an intermediate DoubleTile shape, which contains two Tile shapes and which will be
helpful once we're encoding the floor patterns.
Floor and Tile Structure
Next, we define the detailed subshapes in a tile. It consists of two main parts. The MilkGlass and the Window shape, whereas the
second again contains a Blind on the top and an embedded Subwindow shape. The position of these elements depend on the
horizontal position of the tile on the floor, so we need to store this position index (we will call it tileIndex) as a parameter of the
Tile shape to be able to place the subshapes correctly.
Window Tile Structure
Double-click the file Tutorial_09_Advanced_Shape_Grammar/rules/complexpatterns_01.cga in the Navigator to

open the CGA editor and to see the rules that creates our facade
Attributes, variables and assets

Attributes are defined on the very beginning of the rule file. These attributes are used through the whole rule set and can also be
set and modified via the Inspector Windows Inspector outside the CGA Grammar Editor
// User Attribute
attr buildingH = 27 // building height
attr floorH = 3.5 // floor height
attr groundfloorH = floorH + 1 // groundfloor height
attr balconyDepth = 2
attr ledgeH = 0.3 // ledge height
attr windowW = 2.5 // window width
attr milkGlassW = windowW/2 // milkglass blend width
attr blindH = 0.8 // blind height
attr frameW = 0.07 // frame width
attr borderwallW = 0.3 // width of border wall stripe
attr nSymmetries = 2
Other variables and assets are defined in the following block.

tileW = windowW + milkGlassW // total tile width
barDiameter = 0.04
// assets
cyl_v = "cylinder.vert.8.notop.tex.obj"
cyl_h = "cylinder.hor.8.notop.tex.obj"
window_tex = "1_glass_2_blue.tif"
milkGlass_tex = "blend_tex.png"
// colors
brightblue = "#86b1c7"
darkblue= "#33556c"
red = "#5c3f40"
grey ="#6b7785"
white = "#ffffff"
Volume modeling
The actual creation of the building starts now. First, the mass model is created with the extrude operation. The top floor is split from
the main part and split again to create the set-back balcony.
Lot -->
extrude(buildingH) // extrude the building
split(y){ ~1: MainPart | floorH : UpperPart } // split top floor from lower floors
UpperPart -->
split(z){ ~1: TopFloor | balconyDepth : Balcony }
Component splits are applied then to the different colume parts to distinguish the front, side and top faces and trigger facade, wall
and roof rules.
MainPart -->
comp(f){ front : Facade | side : Wall | top : Roof }
TopFloor -->
comp(f){ front : Floor(-1) | side : Wall | top : Roof }
The dimensions of the balcony are set. The railing will be placed on the faces of the current shape, so we use a component split to
get the front, left and right faces for the Railing rule.
Balcony -->
s(scope.sx-2*borderwallW,0.7,scope.sz-borderwallW) center(x)
comp(f){ front : Railing | left : Railing | right : Railing }
The crude building shape after volume modeling

Facade and floors
We now subdivide the front facade further. The first split subdivides the facade into a ground floor part and a set of upper floors
with the help of a repeating split {...}* . The tilde sign ~ before the split size (e.g. ~groundfloorH) allows a flexible height and
ensures matching floors with now holes in the facade. By passing the split index split.index (which represents the floor index) as
a parameter, we can later trigger specific floor features.
Facade -->
split(y){ ~groundfloorH : Floor(split.index) | { ~floorH : Floor(split.index) }* }
Every floor has a narrow Wall area on its left and right borders. We create this with a simple split in x-direction.
Floor(floorIndex) -->
split(x){borderwallW : Wall | ~1 : FloorSub(floorIndex) | borderwallW : Wall }
Depending on the floor index, special horizontal elements are now created for every floor with horizontal split commands:
The ground floor has a special lower wall element, as well as a small ledge on top.
The upper floors only feature a top ledge.
The top floor has no additional elements and triggers the TileRow shape directly.
We'll be using the floor index again in a later rule, so we pass it again as a parameter with the TileRow shape.
FloorSub(floorIndex) -->
case floorIndex == 0 : // ground floor with index 0.
split(y){ 1 : Wall | ~1 : TileRow(floorIndex) | ledgeH : Wall}
case floorIndex > 0 : // upper floors
split(y){ ~1 : TileRow(floorIndex) | ledgeH : Ledge }
else : // topfloor with index -1.
TileRow(floorIndex)
Facade with floor and ledge splits
Tiles
We're now going to split the floors into tiles. For the top floor things are easy: there is now special pattern, just repeating window
elements. To adress these tiles later on, we again mark them with the parameter -1.
To create the special repeating pattern for the main floors, we create an intermediate shape called DoubleTile. To align the window
elements correctly in a later step, we need the floor and the tile index ( split.index ), which we pass as parameters.
TileRow(floorIndex) -->
case floorIndex == -1 : // top floor
split(x){ ~windowW : Tile(-1) }*
else : // main floors
split(x){ ~tileW*nSymmetries : DoubleTile(floorIndex,split.index) }*
The combination of floor and tile index determines the alignment of the windows. We therefore have two rules with repeating splits
with different order of the MilkGlass and the Tile shape.
DoubleTile(floorIndex,tileIndex) -->
case tileIndex%2 + floorIndex%2 == 1 : // windows are right-aligned
split(x){ ~milkGlassW : MilkGlass | ~windowW : Tile(tileIndex) }*
else : // windows are left-aligned
split(x){ ~windowW : Tile(tileIndex) | ~milkGlassW : MilkGlass }*
We first setup the texture coordinates for the future window texture. The whole Tile shape is then split horizontally into window
frames and the center part. The center part is again split, this time vertically into Frame, Window, Blind and Bracing.
Tile(tileIndex) -->
setupProjection(0,scope.xy,scope.sx,scope.sy)
split(x){ frameW : Frame Bracing // left window frame and bracing
| split(y){ frameW : Frame
| ~1 : Window(tileIndex)
| frameW : Frame
| blindH : Blind
| frameW : Frame }
| frameW : Frame Bracing } // right window frame and bracing
Floors split into tiles

Windows
For the Window shape, the tile index of the DoubleTile is used to determine the position of the subwindows.
Window(tileIndex) -->
This case will create right aligned subwindows in the left half of the window
case tileIndex%nSymmetries >= 1:

split(x){ ~1 : Subwindow("right") | frameW : Frame | ~1 : Glass }
whereas here left-aligned subwindows in the right half of the window are placed.
case tileIndex%nSymmetries >= 0:
split(x){ ~1 : Glass | frameW : Frame | ~1 : Subwindow("left") }
The tile index -1 representing the top floor windows is now used to create windows with no subwindows.
else:
split(x){ ~1 : Glass | frameW : Frame | ~1 : Glass }
With the help of the parameters "left" or "right", the RedWindow is placed on the correct spot.
Subwindow(align) -->
case align == "left" :
split(x){~3 : RedWindow | ~2 : Glass} // put the RedWindow to the left
else :
split(x){~2 : Glass | ~3 : RedWindow } // and to the right otherwise
The following rule creates the frame and glass elements for the RedWindow shape.
RedWindow -->
split(x){ frameW : RedFrame // left...
| ~1 : split(y){ frameW : RedFrame // ...bottom...
| ~1 :RedGlass
| frameW : RedFrame } // ... top ...
| frameW : RedFrame } // ... and right frame
RedGlass -->
split(y){ ~1 : Glass
| frameW/2 : t(0,0,-frameW) Frame
| ~1 : t(0,0,-frameW) Glass }
Detailed window geometry
Materials
Wall --> color(darkblue)
Blind --> color(grey)
Frame -->
extrude(frameW) color(white) // extrude the frame to the front
RedFrame -->
t(0,0,-frameW) extrude(frameW*4) color(red)
Glass -->
projectUV(0) // apply texture coordinates to current shape geometry
set(material.colormap, window_tex) color(white) // and assign texture and color
MilkGlass -->
s('1,'1,frameW*1.2) i("builtin:cube")
setupProjection(0, scope.xy, scope.sx,scope.sy, 0) set(material.colormap, milkGlass_tex) projectUV(0)
Colored and textured model after applying material rules
Detail elements
We refine the floor ledges by adding a back wall element, a cube to give it some depth, and a second thin cube that servers as a
cover plate
Ledge -->
Wall
[ s('1,'0.9,0.2) i("builtin:cube") Wall ]
t(0,-0.1,0.2) s('1,scope.sy+0.1,0.03) i("builtin:cube") Wall
A horizontal bar is first inserted to create the horizontal part of the railing. By disabling vertical trimming the following vertical corner
bars are prevent from being cut.
The vertical bars are evenly distributed with the help of a repeat split with a floating split width.
Railing -->
[ t(0,scope.sy-barDiameter/2,0) HBar ]
split(x){ ~tileW/3 : VBar }*
Cylinder assets are insterted to create the vertical and horizontal bars
VBar --> s(barDiameter,'1,barDiameter) t(0,0,-barDiameter) i(cyl_v) color(white)
HBar --> s('1,barDiameter,barDiameter) t(0,0,-barDiameter) i(cyl_h) color(white)
The bracing of the windows consits of top and bottom mountings, and a vertical bar in the middle. For the mountings a cube is
inserted, the VBar again triggers the cylinder asset.
Bracing -->
s(barDiameter,'1,0.15) center(x) i("builtin:cube")
split(y){ 0.01 : Wall | ~1 : t(0,0,0.15) VBar | 0.01 : Wall }
Final model with detail elements such as ledges, window bracings and railings added
Now you have the final model, try apply the rule on different lot shapes, or play around with the user attributes found in the
inspector to modify your facade design.
The Candler Building
Tutorial Setup
Import the project ShapeGrammarTutorial into your CityEngine workspace (see How to work with the tutorials)
Open scene Tutorial_09_Advanced_Shape_Grammarscenes/Candler_Building.cej

Double-click the file Tutorial_09_Advanced_Shape_Grammar/rules/candler.01.cga in the Navigator to see the
rules that creates the Candler building
The generated Candler Building

The Parthenon Temple
Tutorial Setup
Import the project ShapeGrammarTutorial into your CityEngine workspace (see How to work with the tutorials)
Open scene Tutorial_09_Advanced_Shape_Grammarscenes/Parthenon.cej

Double-click the file Tutorial_09_Advanced_Shape_Grammar/rules/parthenon.cga in the Navigator to see the rules
that creates the Parthenon Temple
The generated Parthenon Temple

Python Scripting Tutorial:
Part 1 : Console and Editor
The Python Scripting Interface, included in CityEngine 2009 Pro greatly enhances the possibilities of the CityEngine. Many
repeating tasks can be automated such as batched export, multi-setting attributes, simultaneous generation of different models
and many more.
Tutorial Setup
Import the project Tutorial_10_Python_Scripting into your CityEngine workspace (see How to work with the tutorials)
Open scene Tutorial_10_Python_Scripting/scenes/01_PythonScripting.cej
The Python Console

Open a new Python Console
Open the console window WindowShow Console
Open a Python console using the small triangle on the left side of the toolbar
Opening the Python console
Your first CityEngine Python command will be a quick way to select scene elements with a specific name.
Start typing ce.setSelection
Press Ctrl-Space to show the command completion popup
Type the following command
ce.setSelection(ce.getObjectsFrom(ce.scene, ce.withName("*Broadway*")))
Press Enter to execute the command
This will select all scene elements which names contain Broadway.
Command Completion (Ctrl-Space) in the Python console

Broadway street shapes selected
The Python Editor

As soon as you plan to use longer and more advanced Python commands or set of commands, it is helpful to use the Python Editor
in the CityEngine.
Create a new Python script FileNew ... Python Module

In the Python module dialog, browse to the scripts folder of your project
Enter the name myHelpers for your new Python module
Select the Module:Main template
Press Finish
Creating a new Python module
The new Python module myHelpers is now opened in the Python Editor built into the CityEngine.
Add a new function selectByAttribute(attr, value)
def selectByAttribute(attr, value):

objects = ce.getObjectsFrom(ce.scene)
selection = []
for o in objects:
attrvalue = ce.getAttribute(o, attr)
if attrvalue == value:
selection.append(o)
ce.setSelection(selection)
And call it with specific parameters in the main clause of the script.
if __name__ == '__main__':
selectByAttribute("connectionStart","JUNCTION")
pass
To execute the script, PythonRun Script in the menu or press F9 while in the Python editor.
Junction street shapes selected
Running scripts from the console

Alternatively, you can call your helper scripts via the Python console.
In the Python console, add the path to your module to the system path.
Import your module
>>> sys.path.append(ce.toFSPath("scripts"))
>>> import myHelpers
You can now call your helper function in the console in the following way, with arbitrary parameters
>>> myHelpers.selectByAttribute("connectionEnd", "JUNCTION")
Calling the custom selection function
Adding a startup script

Create a new file startup.py in your CityEngine workspace
Add these lines to automatically map you helper script at startup
import sys
sys.path.append({PATH_TO_YOUR_SCRIPTS_DIRECTORY})
import myHelpers
The next time the CityEngine starts, your myHelpers module is loaded automatically. You can call the selection function in the
console in the following way:
>>> startup.myHelpers.selectByAttribute("connectionEnd", "JUNCTION")
You can add arbitrary code into the file startup.py . It is executed when a Python console is opened within the CityEngine.
Continue with Part 2

Part 2 : Setting street widths
Often one wants to increment the street width attribute of many segments. Whereas this can not be accomplished easily in
the GUI, a simple Python script can help
Tutorial Setup
Create new Python script

Create a new rule file File New ... Python Python Module
Choose the projects script folder, name it setStreetWidths and choose Module: Main as template
The rule file has attributes prepared to change the dimension of the building. Instead of manually setting these values, we are going
to write a script that changes the values and batch-generates the different versions of the model.
def incrementStreetWidth(increment):
The incrementStreetWidth() function

This function will increment the streetWidth attribute of all selected street segments by a value specified by the user.
First, the function definition:

We need to get all selected segments, and loop over those

selectedSegments = ce.getObjectsFrom(ce.selection, ce.isGraphSegment)
for segment in selectedSegments:
To calculate the new street width, we need to get the current value first using the command ce.getAttribute(). Note the syntax of the
attribute name with the prefix "/ce/street/": this accesses the user attributes of the object.
oldWidth = ce.getAttribute(segment, "/ce/street/streetWidth")
Finally, we calculate the new street width by adding the user provided parameter increment, and assign the new value to the
segment.
newWidth = oldWidth+increment
ce.setAttribute(segment, "/ce/street/streetWidth", newWidth)
The whole function

''' increment the street width parameter of all selected street segments'''
oldWidth = ce.getAttribute(segment, "/ce/street/streetWidth")
newWidth = oldWidth+increment
ce.setAttribute(segment, "/ce/street/streetWidth", newWidth)
In the main block of the script, add the function call, and choose an increment
if __name__ == '__main__':
incrementStreetWidth(10)
Select a set of street segments

Run the python script (Menu Python Run Script or F9 while in the Python Editor
Street widths incremented by 10
Speeding things up : @noUIupdate

Executing the script above takes a little while to run through. This is due to the fact that script execution in CityEngine runs in a
separate thread and updates the GUI and the 3D viewport after every command. In our case after every setAttribute() call, the
street network is updated, and the 3D viewport is redrawn.
Where in some cases this comes in handy, for the example above execution must be quicker. This can be achieved by add the
@noUIupdate marker above the function definition.
@noUIupdate
Functions marked this way will block GUI update during execution but, depending on what they do, will execute faster by factors.
Be aware that some combination of scripting commands with the @noUIupdate marker may freeze the User Interface.
In case you encounter UI freeze or other unexpected behaviour when using @noUIupdate, modify your scripts so that
@noUIupdate only marks a small and specific function instead of marking your whole script.
The multiplySegmentWidths() function

Our second function will set several attributes at the same time, namely streetWidth, sidewalkWidthLeft and sidewalkWidthRight.
The user can specify a factor to multiply the widths by.
@noUIupdate
def multiplySegmentWidths(factor):
The helper function multiplyAttribute will do the multiplication for the different attributes.
multiplyAttribute(segment, "/ce/street/streetWidth", factor)
multiplyAttribute(segment, "/ce/street/sidewalkWidthLeft", factor)
multiplyAttribute(segment, "/ce/street/sidewalkWidthRight", factor)
def multiplyAttribute(object, attrname, factor):

oldval = ce.getAttribute(object, attrname)
newval = oldval*factor
ce.setAttribute(object, attrname, newval)
The two functions

''' multiply street and sidewalk widths of all selected street segments by factor '''
@noUIupdate
def multiplySegmentWidths(factor):
incrementAttribute(segment, "/ce/street/streetWidth", factor)
incrementAttribute(segment, "/ce/street/sidewalkWidthLeft", factor)
incrementAttribute(segment, "/ce/street/sidewalkWidthRight", factor)
''' multiply attribute of object by factor '''

def multiplyAttribute(object, attrname, factor):
oldval = ce.getAttribute(object, attrname)
newval = oldval*factor
ce.setAttribute(object, attrname, newval)
In the main block of the script, add the function call, and choose a multiplication factor
if __name__ == '__main__':
multiplySegmentWidths(1.5)
Select a set of street segments

All segment widths multiplied by 1.5
Run from console

Instead of setting the function arguments in the Python editor, the above functions can be called easily from the Python console
after importing the script module.
>> scriptpath = ce.toFSPath("scripts")
>> sys.path.append(scriptpath)
>> import setStreetWidths
>> setStreetWidths.multiplySegmentWidths(0.5)
Head over to Part 3

Part 3 : Setting camera from FBX file
This part shows how to import static camera data into CityEngine via FBX export from Maya.
Tutorial Setup
Export camera to FBX (Maya)

In Maya, select the camera you want to export
File Export Selection
In the export dialog, make sure the settings are set as in the picture below
FBX export of the camera in Maya
The camera import script

Our second function will set several attributes at the same time, namely streetWidth, sidewalkWidthLeft and sidewalkWidthRight.
The user can specify a factor to multiply the widths by.
Parsing the FBX file
parse lines and look for id
prepares camera data in array
non-generic, works for specific fbx part only
parse lines from fbx file that store cam data
def parseLine(lines, id):
data = False
for line in lines:
if line.find(id) >=0 :
data = line.partition(id)[2]
break
if data:
data = data[:len(data)-1] # strip \n
data = data.split(",")
return data
def parseFbxCam(filename):
f=open(filename)
lines = f.readlines()
cnt = 0
loc = parseLine(lines, 'Property: "Lcl Translation", "Lcl Translation", "A+",')
rot = parseLine(lines, 'Property: "Lcl Rotation", "Lcl Rotation", "A+",')
return [loc,rot]
Setting CityEngine camera

Gets the CityEngine viewport and calls the position and rotation set functions
def setCamData(data):
viewport = ce.getObjectsFrom(ce.get3DViews(), ce.isViewport)[0]
setCamPosV(viewport, data[0])
setCamRotV(viewport, data[1])
def setCamPosV(v, vec):

v.setCameraPosition(vec[0], vec[1], vec[2])
def setCamRotV(v, vec):

v.setCameraRotation(vec[0], vec[1], vec[2])
Master function
def importFbxCamera(fbxfile):
data = parseFbxCam(fbxfile)
if(data[0] and data[1]) :
setCamData(data)
print "Camera set to "+str(data)
else:
print "No camera data found in file "+file
Calling the Main Block

if __name__ == '__main__':
camfile = ce.toFSPath("data/camera.fbx")
importFbxCamera(camfile)
pass
Your camera should be positioned as in the oicture below. Check the camera position/rotation in the HUD.
Camera trafo displayed in HUD after running the script

Animation curves are not read, only the transformation camera at the frame of exporting.
Camera needs to be exported as single object.
Head over to Part 4

Part 4 : Growing Building Animation
Python Scripts can be used to automate generation or export processes. This exmaple shows how to generate a simple
building animation by setting the building attributes, and exporting the set of resulting models in one step.
Tutorial Setup
Generate the building

Select a lot in the scene
Assign the rule file growingBuilding.cga to the lot
Generate the building ShapesGenerate
Building generated with unmodified attributes
The rule file has attributes prepared to change the dimension of the building. Instead of manually setting these values, we are going
to write a script that changes the values and batch-generates the different versions of the model.
The Animation Script

Create a new Python Main module my_grow_building.py
def growBuilding
This function provides a very simple timeline that loops over to ranges and calls the setAttribute function.
def growBuilding():
for i in range(1,14):
height = 20+i
doStep(i,height,1)
for i in range(15,35):
height = 34
width = i-14
doStep(i,h,width)
def doStep
On the lot object, the two attributes height and width are modified.
def doStep(i,height,width):
object = ce.getObjectsFrom(ce.scene, ce.withName("'Lot1'"))
ce.setAttributeSource(object, "height", "OBJECT")
ce.setAttributeSource(object, "width", "OBJECT")
ce.setAttribute(object, "height", height)
ce.setAttribute(object, "width", width)
Generate(object)
def Generate
Simply generates the building
def Generate(object):
ce.generateModels(object)
main
growBuilding is called in the main clause of the script
if __name__ == '__main__':
try:
growBuilding()
except ScriptError, se:
print "\nTest Error:", se
Batch-generate the building

Select the lot in the scene
Press F9 in the Python Editor to run the script
5 snapshots of the building sequence
Batch Export
Model export is disabled in the Trial versions.
Once we are happy with the generated models, we add an additional function Export ,
def Export(i, object):
dir = ce.toFSPath("models")
file = "building_merge_" + str(i)
settings = OBJExportModel()
settings.setName(file)
settings.setLocation(dir)
ce.export(object, settings)
and replace the Generate call in setAttributes()

def setAttributes(i,height,width):
...
#Generate(object)
Export(i, object)
Find the exported models in the models folder.
Head over to Part 5

Part 5 : Generating an asset library rule file
Having a big number of assets, it might be helpful to look at all of them at a glance. This part of the tutorial shows how a
CGA rule file can be generated automatically that displays the project's assets.
Tutorial Setup
The rule file we are going to write should have the following structure
Lot --> Geometries Textures
Geometries -->
Geometry(assetpath)
Geometry(assetpath)
...
Geometry(asset) --> i(asset)
for the geometry assets, and similar for the texture images.
Create a new Python Main module my_asset_lib.py

Add a new function writeCGALib
def writeCGAlib():
Write header information, the starting rule Lot, and the Geometries rule.
cga = "/*Asset Library Loader : Generated by asset_lib.py*/\n version \"2010.3\"\n\n"
# write start rule

cga += "Lot --> Geometries Textures"
# write rule showing geometries

cga += "\n\nGeometries --> "
Iterate over all obj files in the asset folder, and prepare the rule call Geometry(assetpath) for each asset
# get all .obj files from asset directory, and call their loader
for obj in ce.getObjectsFrom("/", ce.isFile, ce.withName("/Tutorial_10*/assets/*.obj")):
# and write
cga += "\n\t t(2,0,0) Geometry(\""+obj+"\")"
Similar rules are written for the texture assets:

# write rule showing jpg textures
cga += "\n\nTextures --> \n\ts(1,0,0) set(scope.ty,-2) set(scope.tz,0) i(\"xy-plane.obj\")"
# get all .jpg files from asset directory, and call their loader
for jpg in ce.getObjectsFrom("/", ce.isFile, ce.withName("/Tutorial_10*/assets/*.jpg")):
cga += "\n\tt(2,0,0) Texture(\""+jpg+"\")"
Write the actual asset loader rules, and close the file.
#write geometry loader rule

cga += "\n\n Geometry(asset) --> s(1,0,0) i(asset) set(scope.ty,0) set(scope.tz,0)"
#write texture loader rule

cga += "\n\n Texture(asset) --> set(material.colormap, asset)"
Open a file handle for the future .cga file and write the cga content
CGA = open(cgafile, "w")

CGA.write(cga)
CGA.close()
Add a new function assignAndGenerateLib(). It will assign the generated cga file to a scene lot and generate
the model.
def assignAndGenerateLib():
object = ce.getObjectsFrom(ce.scene, ce.withName("'Lot2'"))
ce.refreshWorkspace()
ce.setRuleFile(object, "asset_lib.cga")
ce.generateModels(object)
Finally, call the two functions in the main clause
if __name__ == '__main__':
try:
writeCGAlib()
assignAndGenerateLib()
except ScriptError, se:
print "\nTest Error:", se
Generating the library "model"
In the Python editor, with the file asset_lib.py open, hit F9
Asset Library

Reporting Tutorial
With the CityEngine, you can generate rule-based reports to gain a better understanding of the impact planned. This means
that you not only can visualize your urban master plans but also augment them by generating numerical reports (e.g. Excel
tables via .csv). Like the 3D models, the reports can be generated with the CGA shape grammar. Either the report operations
can be included in the corresponding rules that generate the geometry, or CGA shape grammar rule sets only for reporting can
be created. The report operation has been developed in a way that it allows for the reporting of arbitrary properties of the
building design / master plan. As a consequence, the reporting is completely generic and customisable, e.g. it can include
numbers such as gross floor areas (GFA), number of units, or land use mixes. And by changing the urban design (i.e. re-
generating the models), the reports are updated automatically and instantaneously. In this tutorial we will show an example
scenario where we have build a master plan from scratch, but of course the reporting functionalities are also of great use to
analyse existing geospatial data.
Import the project Tutorial_11_Reporting into your CityEngine workspace (see How to work with the tutorials)
Open scene Tutorial_11_Reporting/scenes/reporting.cej
The scene was built from an OpenStreetMap street network of the Dubai are, which then was extended:
The original Dubai OSM street network after import.

The extended Dubai street network.
From this street network, we created the following scene:
Overview of the scene.
Map layers control the appearance of the city. The interesting one is the layer that controls the land use (see layer Landuse2):
Map layer to control land use (Landuse2).
The bright part in the centre triggers Office buildings, the middle part triggers buildings of mixed land-use (retail, offices, and
residential) and the outer part of residential buildings.
Now, look at the corresponding shape grammar file Tutorial_11_Reporting/rules/reporting.cga
# ---------------------------------------
# Attributes
# ---------------------------------------
attr landuse = 0
attr landuseType =
case landuse > 0.66: "Office"
case landuse > 0.33: "Mixed"
else: "Residential"
attr buildingHeightFactor = 1
attr nFloor =
case landuseType == "Office": ceil(rand(6,15)*buildingHeightFactor)
case landuseType == "Mixed" : ceil(rand(3,12) *buildingHeightFactor)
else : ceil(rand(1,3) *buildingHeightFactor)
attr floorHeight =
case landuseType == "Office": rand(5,6)
case landuseType == "Mixed" : rand(4,5)
else : rand(3,4)
# city attributes
attr greenspacePercentage = 30
attr mixedOffice = 0.2 # 20% of mixed use buildings is office
# display handle
attr onlyMass = false
The land use attribute landuse is mapped on to the (above mentioned) Landuse2 map Layer, and it controls landuseType .
buildingHeightFactor is mapped on to the second map Layer, which together with nFloor and floorHeight controls the
building height.
Now the interesting parameters which the master planner can tune in this example:
greenspacePercentage controls how much of the lots are used as green space in the master plan.
mixedOffice controls how many floors of a "Mixed-Use" building are Offices.
With the rule parameter onlyMass you can change between two visualisations as illustrated in the following for a residential building:
The rule parameter onlyMass
Residential building visualization with onlyMass set to true (top) and false (bottom).
The rule set creates very simple mass models according to the rule-driven dimensions of the footprint by its land use. "Mixed-Use"
buildings are higher than residential buildings and have a ground floor with retail as shown in the next two figures:
Residential / office mixed building visualization with onlyMass set to true (top) and false (bottom).
Note that red planes depict retail floors, green planes depict office floors and blue planes residential floors.
The office buildings are even higher and can have also set-backs:
Office building visualization with onlyMass set to true (top) and false (bottom).
Now, try the following: Select a few lots in the scene and generate them. Via onlyMass you can switch between the
two visualisations.
Set onlyMass to false, select all and press Generate. The whole city is generated.
Generating the whole city.
Simultaneously with the generation, a report is generated. Without deselecting, go to the inspector and open the
Reports pane: Voila - your first report.
When you now look into the rule, you see that the report command has been used to track the gross floor area
(GFA). As you can see in the rule:
The created report.
FloorBottom(type) -->
case type == "Retail":
report("GFA.Retail",geometry.area)
color("#ff4444")
case type == "Office"
|| (type == "Mixed" && split.index < mixedOffice*split.total):
report("GFA.Office",geometry.area)
color("#44ff44")
else:
report("GFA.Residential",geometry.area)
color("#4444ff")
We also used the convenient hierarchical grouping feature to distinct between GFA.RETAIL (area of retail floors), GFA.OFFICE
(office floors), and GFA.RESIDENTIAL (residential floors) The inspector's reports pane then adds also the total GFA for all types
without the need to code it into the rule.
Note: It is important to understand that the inspector always shows the report for the currently selected models.
Select a single model and see the report:

Report for a single model.
Select multiple model and see the report:
Report for multiple models.
In addition, the reports pane in the inspector shows statistic summaries. These can be copy-pasted into Excel and similar.
Alternatively, any customized comma-separated list can be created with the Script-based Export (see Python Scripting Interface in
the manual).
Now, let's get back to designing our city. The previous reports showed that 25.6% of the GFA is office space, which is not enough
for our (hypothetical) design goals. We can increase the office space GFA by adding more office space in mixed-use buildings:
Set the attribute mixedOffice to 0.5 in the whole scene. This results in more office floors (green). The first figure
side shows mixedOffice with 0.2, the second shows mixedOffice with 0.5:
Attribute mixedOffice set to 0.2.

Attribute mixedOffice set to 0.5.
As a consequence, after regenerating the whole scene, the following report results:
The resulting report after changing mixedOffice to 0.5 and selecting all models.
As you can see, the office GFA increased to 44.8% for the whole city. That's how you can use the reports to tune your urban
designs (or also single buildings). You can report any number, all generic, all rule-based. Of course, this is a simple example, but
we hope that you got the idea how to work with reports.
CityEngine GIS Mapping Part 1 :
Extrusion using Height Data
In the first part, we will connect the height data of the imported footprints to a CGA rule and extrude the footprints to their
specified height.
This tutorials requires a basic knowledge of CGA Shape Grammar. In case you haven't yet, consider looking at Tutorial 06
Basic Shape Grammar first.
Tutorial Setup
Import the project Tutorial_12_GIS_Mapping into your CityEngine workspace (see How to work with the tutorials)
Open scene Tutorial_12_GIS_Modeling/scenes/gis_mapping_01.cej
The footprint layer
The building_height attribute

First, select a footprint and open the Attributes area in the Inspector view. You will see that our footprints have an attribute called
building_height.
Some of the footprints have no height attribute set.

The attribute building_height of a footprints shown in the Inspector

We want to use this attribute to control the height of the extrusion in our rulefile.

Make sure the container is set correctly (Tutorial_07_Facade_Modeling/rules), name the file mapping_01.cga and
hit Finish
A new CGA file is created, and the CGA Editor is opened. It is empty except some header information ( /* .... */ ) and the
version tag version "2009.3".
Add a new attribute building_height and initialize it to 0.
attr building_height = 0
and add the first rule
Lot --> extrude(building_height)
and save the rule file.

Select all shapes
Assign the rule file via Shapes Assign Rule File ... , select your cga file ( mapping_01.cga ) and hit Ok
In the Rule Parameters pane of the Inspector, select Object as source for the parameter building_height
Hit the generate button on the top toolbar (or press Ctrl-g )
Some footprints are not extruded
After generation of the models, you will find some footprints that have not been extruded. Select one and look at the attributes in
the Inspector. Some footprints have no attribute building_height, the data was not specified in the imported file.
Some footprints are not extruded
We will adjust our rule to mark buildings with missing height data.
Back in the CGA editor of your rule file, change the Lot rule in the following way:
Lot -->
case building_height > 0 :
extrude(building_height) Mass
else :
color("#ff0000")
A normal extrusion will be done if the height data is set (is not zero), otherwise the footprint will be colored red. It is now easy ti
spot footprints with no height data.
Footprints with no height data marked red
Pick a red footprint and in the value column of the CGA Attribute Mapping area set a height value. The value is added
automatically as an attribute to the footprint, and the building is now extruded in the expected way.
Missing height data added

The final result of part 1
Go on to part 2
Creating the Roofs
Open scene file Tutorial_12_GIS_Modeling/scenes/gis_mapping_02.cej
Satellite Image
The scene already contains two layers with satellite images:
area_satellite : big lores image

center_satellite : small hires image
The two satellite images in the scene
We are going to use the hires image to texture the roofs of the buildings in the hires area.
First we need to split our building mass into its side and top components:
Mass -->
# split building mass into roof and side faces
comp(f){top : Roof | side : Facade}
For now, the Roof rule simply forwards to Rooftex

Roof -->
Rooftex
As mentioned before, we are only going to use the hires image for roof texturing. We therefore need a new attribute in the
center_satellite layer to find out in which area the footprint is located.
Select the layer center_satellite in the Scene Editor
In the attribute area of the Inspector, add the new attribute hires_image
attr hires_image = alpha > 0
The attribute hires_image in the center_satellite layer
This attribute will evaluate to true if the footprint is in the hires area. Add it to the rule file as well with false as default value:
attr hires_image = false
Setting up roof texturing

To correctly project the UV coordinates on the building roofs, we need the size and the position of the satellite map in the scene.
Create 4 new const variables for dimension and position in x an z. The dimensions are found in the Inspector view with the layer
center_satellite selected.
# dimension of the satellite map
const mapdimension_x = 1448.739
const mapdimension_z = 747.632
# offset of the satellite map

const mapoffset_x = 2761.477
const mapoffset_z = 1811.736
Now create a new rule Rooftex. We decide here if we want to apply roof textures or not and create a condition with the hire_image
attribute:
Rooftex -->
case hires_image :
# apply satellite texture
else :
# if building is outside the hires image area, don't texture the roof
In the hires case:
Setup the projection using the world.xy plane as coordinate system and the mapdimension consts as size.
Specify the texture center_satellite.png as colormap
Apply the UV's with projectUV(0)
The UV's need to be translated to the map offsets.
and inverted in v
Rooftex -->
case hires_image :
setupProjection(0, world.xz, mapdimension_x, mapdimension_z)
set(material.colormap, "maps/center_satellite.png")
projectUV(0)
translateUV(0, -mapoffset_x/mapdimension_x, -mapoffset_z/mapdimension_z)
scaleUV(0,1,-1)
else :
X.
Control the hires_image parameter by the map layer:
Select all shapes

In the Rule Parameters pane of the Inspector, select the layer center_satellite as source for the parameter
hire_image
The center_satellite layer mapped
Select some lots around the hires area and generate
Building roofs textured with the satellite map
Better Roof Shapes

The look of buildings from the top can be greatly enhanced if better roof shapes are created instead of just flat roof planes. With the
image center_roof.png is a filtered version of the satellite image and marks buildings with reddish roofs. We use this map to
control where to generate hipped roofs.
The center_roof map
Create a new attribute l
Duplicate the map layer center_satellite , and rename it to center_roofs

In the attribute area of the new layer, add a new boolean attribute roofmap_hipped
attr roofmap_hipped = red > 0.2
Areas with strong red color will evaluate to true.
Back in the rule file, create the same attribute and initialize it to false
attr roofmap_hipped = false
We now need to change the Roof rule to trigger different roof types.
If the footprint is complex (a high vertex count), a hip roof might not give desired results. We therefore trigger a Flatroof
in this case.
If the roofmap_hipped attribute is true, trigger a Hiproof
all other footprints create a Flatroof
Roof -->
case geometry.nVertices > 20 : Flatroof
case roofmap_hipped: Hiproof
else : Flatroof
The Flatroof simply triggers the Rooftex rule we created before.

Flatroof --> Rooftex
Two types of hipped roofs should be created depending on the footprint: Gable roofs or Hip Roofs. After creating the roof shape,
both will call the Rooftex rule as well to apply the roof texture.
Hiproof -->
case geometry.isRectangular(20) :
case scope.sx > 2*scope.sy : roofGable(20,0,0,false,1) Rooftex
else : roofGable(20,0,0,false,0) Rooftex
else : roofHip(20) Rooftex
Before generating the buildings with the new rule, reassign the modified rulefile:
Select all shapes

In the Rule Parameters pane of the Inspector, select the layer center_roofs as source for the parameter
roofmap_hipped
Generate
The center_roofs layer mapped
Gable, hip and flat roof shape controlled via map layer
We need facades. Head over to part 3

Texturing the Facades
Facade Textures
Have a look at the facade textures libary in the folder assets/facadeFotos . These are the images we are going to use to textuer
the facades.
The facade texture library
We will start with projecting these textures straight-forward to the buildings facades.
The attribute fileIndex defines a random index to one of the 29 facades.
attr fileIndex = floor(rand(1,30)) # we have 29 textures (with proper numbering in filenames here)
This function getFacadeTexFile will return the correct image filename depending on the texture
getFacadeTexFile =
case fileIndex < 10 : "facadeFotos/dsc_000" + fileIndex + ".jpg"
case fileIndex < 100: "facadeFotos/dsc_00" + fileIndex + ".jpg"
else : "facadeFotos/dsc_0" + fileIndex + ".jpg"
The Facade rule selects the facade texture, prepares the projection on the facades and projects the UV's
Facade -->
set(material.colormap,getFacadeTexFile)
setupProjection(0,scope.xy,scope.sx,scope.sy)
projectUV(0)
When generating the building, it gets clear that we can do better.

Simple but unrealistic facade texture mapping
Visualizing the UV space
Improve UV Mapping using floor and tile information

The unrealistic mapping results from the fact that our facade textures differ significantly in their actual reial-world size. Whereas
some textures cover only 3 floors, other span over more than 20.
To improve the facade texture mapping, we have to encode the facade properties of the files to be able to map it accordingly. We
are interested in the number of floors and the number of tiles (~=number of windows) of each texture. With this information we can
calculate the scale of the texture mapping both in height and width in a realistic way and do a proper projection.
In our rule we define a matrix that stores which can be accessed by attribute texIndex and the parameter key. For each texture file
the number of floors and tiles is stored.
For example look at first entry: the image dsc_0018.jpg (file with index 18) has 3 floors and 13 tiles. The matrix is sorted by
number of floors.
attr texIndex = floor(rand(1,30)) # instead of fileIndex above
getFacadeTexInfo(key) =
case texIndex==0 : case key=="file":18 case key=="floors":3 else:13
case texIndex==10: case key=="file":13 case key=="floors":5 else:7
else : case key=="file":24 case key=="floors":20 else:24
To apply a fitting facade texture, we need to guess the aproximate number of floors and tiles on our facade model. We therefore
add two const variables that define an average floor height and tile width:
const floorheight = rand(3.5,4.5)

const tilewidth = floorheight/4*3
With the help of our average building dimensions, we define two functions that calculate the number of floors and tiles depending
on the facade height( scope.sy) and width ( scope.sx):
nFloors = ceil(scope.sy/floorheight)
nTiles = ceil(scope.sx/tilewidth)
The previously defined function getFacadeTexFile needs to be updated:

getFacadeTexFile =
case getFacadeTexInfo("file") < 10 :
"facadeFotos/dsc_000" + getFacadeTexInfo("file") + ".jpg"
case getFacadeTexInfo("file") < 100:
else : :
Now we can calculate the correct projections:
Align the texture projection height to the current facade so that the texture floors fit
getFacadeTexProjectionHeight = scope.sy/nFloors*getFacadeTexInfo("floors")
Align the texture projection width to the current facade so that the texture tiles fit
getFacadeTexProjectionWidth = scope.sx/nTiles*getFacadeTexInfo("tiles")
and update the Facade rule accordingly

Facade -->
set(material.colormap,getFacadeTexFile)
setupProjection(0,scope.xy,getFacadeTexProjectionWidth,getFacadeTexProjectionHeight)
projectUV(0)
The resulting UV mapping using floor and tile information...

and the actual textures applied
Improving mapping in height

Our texturing still has room for improvements: Currently we are repeating our texture in width and size to fill the whole facade.
Since the texture is taken randomly, it might happen that we take a texture of a 3-story building onto a skyscraper. we will see
repeating groundfloors/doors over the whole facade:
Texture repeat in height might to unrealistic facades
We need to control what texture is chosen according to the height of the building. Instead of randomly chosing a texture index, we
will change the texIndex attribute to be more intelligent when it comes to selecting the right texture. Because our texture info matrix
is sorted by number of floors, we can select an index in a range depending on the calculated numbers of floors of a building:
attr texIndex =
case nFloors <= 3: floor(rand(0,2))
else : floor(rand(22,29))
Let's assume our building is 4 floors in height. texIndex will now select one of the facade stored at index 2, 3 or 4. If you look at the
texture info matrix once more, you will see that this are the textures covering 4 floors.
Textures now selected depending on building height
Improving texture variability

If you look at the following image, you will notice many identical textures on the buildings. This is caused by our latest height-
dependent texture selection: In our library we only have 2 textures for 3-story buildings, and only 3 for 4-story buildings. Clearly too
much repetition of the same texture.
Too many similar textures
Add a new helper function for probability:
(percentage) = case percentage > rand(100): true else: false
and adjust the texture selection attribute texIndex in the following way:
attr texIndex =
case nFloors <= 3 && prob(50): floor(rand(0,2))
else: floor(rand(22,29))
We now select a fitting texture with a probability of 50%. Otherwise one of the high textures is selected. Because it is spanned over
an area higher than the facade, this will not cause unpleasant effects.
Repeating textures issue solved with probability selection
Final Shot

Analysing Attributes
Additional Shape attributes

Looking into the attributes area of a footprint, you see more data attributes beside the building height information. We will use the
building use data to color our buildings and quickly visualize this additional data.
Add a new attribute building_use. It simply maps the data from the shape's attribute.
attr building_use = ""
Add a new attribute use_analysis., to quickly enable or disable the analyze mode.
attr use_analysis = true
Add a new helper function usage_color which selects a color depending on the building_use.
usage_color =
case building_use == "" : "#f26522" # orange
case building_use == "commercial" : "#0000ff" # blue
case building_use == "residential" : "#00ff00" # green
case building_use == "office" : "#00ffff" # cyan
case building_use == "hospital" : "#ff00ff" # magenta
case building_use == "store" : "#8888ff" # brightblue
case building_use == "depot" : "#ff8888" # brightred
else : "#ffffff" # white
Modify the Lot rule to call the UseAnalysis rule instead of Mass direclty.
Lot -->
case building_height > 0 : extrude(building_height) UseAnalysis
else : color("#ff0000") UseAnalysis
UseAnalysis sets the buildings color using the usage_color function and triggers Mass.
UseAnalysis -->
case use_analysis :
color(usage_color)
Mass
else : Mass
Before generating the buildings with the new rule, reassign the modified rulefile to make sure the new attributes are attached to the
footprints data:
Select all shapes

In the Rule Parameters pane of the Inspector, select Object as source for the parameter building_use
Generate
Buildings colored by their usage
To confortably see how many buildings of what usage are present in your city area, add a report variable to the UseAnalysis rule.
It's name is composed of "UseUnits." and the actual building use. This way building use data will be calculated in percebtage to
each other. In this example we will just count the number of buildings (therefore the second parameter 1). You could also set
geometry.area or geometry.volume to get reports on different data.
UseAnalysis -->
case use_analysis :
color(usage_color)
report("UseUnits."+building_use, 1)
Mass
else : Mass
Generate
Building use data shown in the Report area of the Inspector

Scripted Report Export Part 1 :
Report information of instanced buildings
In the first part, we will use an existing CGA file that distributes instanced buildings in our scene and add report variables to
prepare additional information of the instances used for the Script Based Exporter in part 2.
This tutorials requires a basic knowledge of CGA Shape Grammar as well as the basics of the Scripting API.
All model exporters including the pyton based exporter are not available in the free CityEngine trial version
Goal
We want to write out a text file that contains the necessary data to be able to load the distributed building instances in arbitrary
follow-up applications.
For every instance, the following values should be written:
asset identifier
position in 3 axes
rotation in 3 axes
scale in 3 axes
in the following form:
nr asset xpos xrot xscale ...

0 scifi_building_9.obj -529.4803009 0 1.051229466 ...
1 scifi_building_17.obj 236.6141357 0 0.933861537 ...
...
Tutorial Setup
Import the project Tutorial_13_Scripted_Report_Export into your CityEngine workspace (see How to work with the
tutorials)
Open scene Tutorial_13_Scripted_Report_Export/scenes/reportInstances_01.cej
Preparing a generic report rule in an external CGA file

Although we could add all the necessary reporting commands directly in the CGA file instance_city_01.cga , we will write an
external CGA file with a genereric reporting rule. This way, we will be able to use the reporting rule for arbitrary CGA files.
Create a new rule file File New ... CityEngine CGA Rule File
and name it instanceReporting.cga
Create a new rule InstanceReport. We need a rule parameter asset to be able to report the asset identifier.
InstanceReport(asset) -->
Reporting transformation data
Asset identifier
We simply report the rule parameter asset .
## report asset identifier

report("asset", asset)
Scale
In most cases one needs a scale relative to the original asset size. We therefore cannot report the scope size only, but need to
divide it by the asset size. The original asset size can be queried using the assetInfo() command. assetInfo(asset, "sx")
queries the size in x-axis.
The report commands for the scale are therefore:
## report scale values relative to asset
report("xscale", scope.sx/assetInfo(asset, "sx"))
report("yscale", scope.sy/assetInfo(asset, "sy"))
report("zscale", scope.sz/assetInfo(asset, "sz"))
Rotation
We want to report the rotation in world coordinates, and therefore need to convert the pivot rotation in CityEngine using the
convert() command:
## report position in world coords

report("xpos", convert(x, pivot, world, orient, 0,0,0))
report("ypos", convert(y, pivot, world, orient, 0,0,0))
report("zpos", convert(z, pivot, world, orient, 0,0,0))
Position
Position is the trickiest part. To be able to instance your assets correctly in yout follow-up application, it is crucial to pay attention to
the pivot and the position of the used assets. In our case the assets have their pivot in their center on the ground plane, and are
located on the world origin. See the Maya screenshot below for clarification
Building asset in Maya, displaying pivot and position
Before reporting the position, we will therefore modify the asset scope in the following way: The scope is scaled to a small "needle",
and centered in x an z. This way we make sure the reported position corresponds to the pivot of the asset in Maya.
## scale and center scope
s(0.0001,'1,0.0001) center(xz)
Again, the position needs to be converted to world coordinates:

report("xpos", convert(x, scope, world, pos, 0,0,0))
report("ypos", convert(y, scope, world, pos, 0,0,0))
report("zpos", convert(z, scope, world, pos, 0,0,0))
We have now reported all the required values. To make sure no undesired geometry is displayed in the viewport, we add a NIL
command to the end fo the reporting rule. The final reporting rule:
InstanceReport(asset) -->
## report instance ID
report("asset", asset)
## report scale values relative to asset

report("xscale", scope.sx/assetInfo(asset, "sx"))
report("yscale", scope.sy/assetInfo(asset, "sy"))
report("zscale", scope.sz/assetInfo(asset, "sz"))
## report rotation in world coords

report("xrot", convert(x, pivot, world, orient, 0,0,0))
report("yrot", convert(y, pivot, world, orient, 0,0,0))
report("zrot", convert(z, pivot, world, orient, 0,0,0))
## scale and center scope

s(0.001,'1,0.001) center(xz)

report("xpos", convert(x, scope, world, pos, 0,0,0))
report("ypos", convert(y, scope, world, pos, 0,0,0))
report("zpos", convert(z, scope, world, pos, 0,0,0))
NIL
Using the report rule

Let's get back to our original CGA rule file and use the prepared report rule. On the beginning of the file instance_city_01.cga ,
add the following line to import the prepared report rule file with the id instanceReporting .
import instanceReporting:"instanceReporting.cga"
Now we simply add the InstanceReport rule to the end of our building rule. Make sure to also add the leave rule Asset. after the
insert command to make sure the asset is generated.
Building(asset) -->
s('1,0,'1)
i(asset) Asset.
instanceReporting.InstanceReport(asset)
Generate a building now, and look into the Reports pane of the Inspector, which should look similar to this:
Report variables shown in the Inspector
The Reports pane in the Inspector is only for statistical reports, and does not display all values correctly (e.g. doesn not
display strings). However, it can be used in our case to make sure all required values are reported.
Go on to part 2, where we will process the reported variables with the Script Based Exporter.
Scripted Report Export Part 2 :
The Export Script
We will now process the prepared report data using the Script Based Exporter. For this, we need to create a new Python
script which will do the job.
Python Script Export Template

Create a new python export script from template File New ... Python Python Module
Choose the projects script folder, name it exportInstances and choose Module: Export (Reporting) as template
The Python module wizard
The template script contains four functions. We only need finishModel() and finishExport(), so delete the other two.
Access report data in finishModel()

The array of report variables of the currently processed shape can be accessed in the following way
model.getReports()['asset']
, where 'asset' is the name of the report variable. Because not all generated shapes have an instance on them (e.g. empty ground
shapes or street shapes), we first need to check for the presence of report data using one of the report variables, namely 'asset'.
if(model.getReports().has_key('asset')):
If you look at the CGA rules or the generated buildings in detail, you will notice that some shapes contain more than one instance.
We therefore need to loop over all the reported datasets per shape, byt first getting the length of the 'asset' array. As a first test, we
will print out the report data array to the console:
l = len(model.getReports()['asset'])
for i in range(0,l):
print model.getReports()
Running the Script-based exporter

Select a small set of buildings or lot shapes
Start the script based exporter: File Export ... CityEngine Export Models of selected Shapes and choose
In the Misc. Options tab, browse to the export script exportInstances.py and run the exporter by clicking Finish.
The Ptyhon module wizard
The Python console output should read something of the form:
{'zpos': [-362.6108093261719], 'yrot': [-69.42008209228516], 'asset': ...

{'zpos': [-412.1033630371094], 'yrot': [165.30718994140625], 'asset': ...
...
The Python output console can be opened via Menu Window Show Console
Select output consoles with the console switch dropdown
Adding Globals
Instead of printing the data to the console, we now add a new function processInstance() that will process and collect the report
values. Additionally we add to global variables (outside the finish model function) that collect the data and keep track of the
instance count:
# Globals
gInstanceData = "" # global string that collects all data to be written
gInstanceCount = 0 # global count to enumerate all instances
The finishModel() function

The completed function finishModel()
# Called for each initial shape after generation.

def finishModel(exportContextUUID, initialShapeUUID, modelUUID):
global gInstanceData, gInstanceCount
if(model.getReports().has_key('asset')): # only write t3d entry if report data available

l = len(model.getReports()['asset']) # there might be more than one asset per model, therefore loop
for i in range(0,l):
instanceData = processInstance(model.getReports(),gInstanceCount, i-1)
gInstanceData = gInstanceData+instanceData
gInstanceCount = gInstanceCount+1
The processInstance() function
This function simply returns all the report variables in a tab-separated string.
''' Collect the instance information in a tab-separated string'''
def processInstance(reports, count, index):
## remove path from asset string

asset = reports['asset'][index]
asset = asset.rpartition("/")[2]
text = ""
text+= str(count)+"\t";
text+= str(reports['asset'][index])+"\t";
text+= str(reports['xpos'][index])+"\t";
text+= str(reports['ypos'][index])+"\t";
text+= str(reports['zpos'][index])+"\t";
text+= str(reports['xrot'][index])+"\t";
text+= str(reports['yrot'][index])+"\t";
text+= str(reports['zrot'][index])+"\t";
text+= str(reports['xscale'][index])+"\t";
text+= str(reports['yscale'][index])+"\t";
text+= str(reports['zscale'][index])+"\n";
return text
The finishExport() function

This function is called after the generation of all shapes is finished. We define the filename of the text file containing the instance
map here, and call the writeFile() function.
# Called after all initial shapes are generated.

def finishExport(exportContextUUID):
global gInstanceData, gInstanceCount
## path of the output file

file = ce.toFSPath("models")+"/instanceMap.txt"
## write collected data to file

writeFile(file, gInstanceData)
print str(gInstanceCount)+"instances written to "+file +"\n"
The writeFile() function

adds the header information and writes the collected report string to disk.
''' combining data (header and content) and writing file '''
def writeFile(file, content):
## prepare the head string

head = "nr\tasset\txpos\typos\tzpos\txrot\tyrot\tzrot\txscale\tyscale\tzscale\n"
## combine header and content

content = head + content
## write data to the file

report = open(file, "w")
report.write(content)
report.close()
Running the final script

Select a set of buildings or lot shapes
Start the script based exporter: File Export ... CityEngine Export Models of selected Shapes and choose
In the Misc. Options tab, browse to the export script exportInstances.py and run the exporter by clicking Finish.
The resulting file instanceMap.txt is saved in the model directory of the current project.
nr asset xpos xrot xscale ...

0 scifi_building_9.obj -529.4803009 0 1.051229466 ...
...
Instead of writing a tab-separated text file, you can process the reported data in arbitary ways: E.g. writing a Mel script for
Maya that creates the instances, writing position information to a database or writing you custom ascii-based format.
Additional elements
Thanks to the generic reporting rule, we can now easily extend our CGA rule set with additional instance elements for reporting and
export.
Assign instance_city_02.cga to all shapes in the scene.

Generate some street shapes
This rule file includes bridge elements on the streets.
Bridge asset distributed along streets
Open the CGA rule file instance_city_02.cga
Using the report rule

To export the bridge instances to the instanceMap as well, simply add the InstanceReport rule to the Bridge rule.
Bridge -->
s(1,8,scope.sz+3.2) center(xz)
i(bridge_asset)
s(calcHeight2(scope.sx),calcHeight2(scope.sy),'1)
Bridge.
instanceReporting.InstanceReport(bridge_asset)
nr asset xpos ...

0 bridge3.obj -363.586952209 ...
1 bridge3.obj -313.587295532 ...
...
Visual CGA Part 1 :
Modeling a simple Building
This tutorial introduces the basics of visual programming in the CGA editor. You will use the interactive tools to create a basic
building.
Tutorial Setup
Import the project Tutorial_14_Visual_CGA into your CityEngine workspace (see How to work with the tutorials)
Open scene Tutorial_06_Basic_Shape_Grammar/scenes/01_SimpleBuilding_vcga.cej
Simple Building
We will construct a simple building with a typical facade. The result of part 1 will look like this:
Select the lot in the 3D viewport, and have a look at the Inspector (in case it is not open yet, open it via Window Inspector )
Assigned rule file and start rule in the Inspector
Click on the "Rule File" link. This will open the CGA Editor. If it is not in the visual programming mode already, switch it by clicking
on the visual programming mode button:
CGA editor in visual programming mode.
Now open the context menu by clicking the right mouse button in the background:
and left-click on the "Add Rule" item.
Set the "Rule Name" to Lot and hit OK. A rule node appears in the editor (you might have to hit the "a" key or click on the "frame
all" button to set the view to a convenient zoom level):
Navigation (paning, zooming) in the Visual CGA editor is the same as in the 3DView. See 3D Navigation Essentials.
Next, add an extrude operation to the Lot rule. Right-click on the "Shape" field in the node and select
"Insert"/"Gemoetry"/"extrude(height:float)":
We want to control the extrusion height by an attribute. Right-click on the background and select "Add Attribute...":
In the "Add Attribute" dialog which pops up, set the name to "height", enter "20" for the value and hit ok. Left-click on the "0" value
of the extrude operation and select "height" (i.e. the attribute you just created) from the drop-down list.
We now have a basic rule which can be used to generate a model. Make sure the Lot shape is selected and hit "generate".
Right-click on the Shape field again and choose "Insert"/"Splits"/"comp(compSelector){selector:operations}":

Select the "Shape" operation below the extrude operation and delete it (hit the "Delete" key), we won't need that one anymore.
Then change the component split selector from "all" to "side" (use the drop-down menu which appears on left-click). Right-click on
the "Shape" operation, select "Add Rule...", name it "Facade" and hit ok. Select the "Shape" operation again and delete it. Right-
click on the "comp" field and select "Add Operations..."/"selector : operations". Change the selector from "all" to "top". Your rule
graph should now look like this:
Let's go ahead now and define the Facade rule. Add a "split(axis){size:operations}" operation. Right-click on the new split operation
and add a "selector:operations" from the Operations menu. Change the first entry's selector from "~1" to "5". Right-click on the
second entry and "Add Rule", name it to "UpperFloors", delete the "Shape" operation.
If you hit the generate button again, the generated model should look like this:
Note the vertical split line: the ground floor is 5m high, and the remaining area, the upper floors, will now be defined in the
UpperFloor rule:
The generated model of this rule graph looks like the picture on top of the page.

Visual CGA Part 2 :
Inserting assets and texturing the building
In the second part of the Cisual CGA tutorial we will make use of geometry assets and textures to polish the building and make
it look more realistic.
Tutorial Setup
Open scene Tutorial_06_Basic_Shape_Grammar/scenes/02_SimpleBuilding_vcga.cej or continue from part 1.
The Wall
First we are going to add a wall texture. This involves adding a setupProjection operation to the Facade rule and adding a Wall rule
which uses projectUV and sets a texture. Start with adding the setupProjection operation:
Next, add a Wall rule and replace all the references to "Shape" in the Tile rule. Do this by draging the "Shape" items from the Tile
rule to the Wall rule:
Then add the projectUV and texture operation to the "Wall" rule. Click on the texture operation's value field and go to the file
browser:
In the browser, select the "wall.tif" texture. If you generate the model again the Tiles will look like this:
Next, we are going to add realistic windows. Add a Window rule and connect it to the second y-split-item in the "Tile" rule. Then
insert a "Transformations/s", a "Transformations/t", a "Geometry/i", a "Texturing/setupProjection", a "Texturing/projectUV" and a
"Texturing/texture" operation. Set the s,t and i parameters as shown in the screenhsot below. To set the setupProjection width and
height values, click on the "0", select "float expression" from the drop-down menu and choose the "scope/sx" (resp. "scope/sy")
entry.
Finally, add a "fileRandom" function to the texture operation:
Enter a search query for the fileRandom function: we want a random tif file from all the assets/window/1_rollo..." files: using
"*assets/window/1_rollo_*brown.tif" will find all these files. Hit generate once again:
Finally, let us add some glossy doors on the ground floor. Go to the "Facade" rule, right-click on the first item and select "Add
Rule...". Set the rule's name to "Door" and add the operations as shown in the screenshot below:
This is it, hit generate again and you will se a complete simple building!
Facade Wizard Tutorial Part 1 :
Creating basic facade templates
Tutorial Setup
Import the project Tutorial_15_Facade_Wizard_Tutorial into your CityEngine workspace (see How to work with the
tutorials)
Introduction
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 new CGA rules are resulting, 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
Conclusion
With the Facade Wizard, it is easy to create large pools of facade templates which can always be reused - This is most welcome,
especially in upcoming projects !
It is important to understand that the Facade Wizard allows the user to create facade templates either directly on textured start
shapes (typically a "mass model") or on loaded images (bitmaps). In this first example, we present the former case, where we
import a mass model and create the rules for one of its facades.
Basic Example
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". Choose the OBJ importer and hit
"Finish". The building should now be visible near the origin of the scene.
The mass model as starting point
Enable the Facade Wizard under Window --> Show Facade Wizard. After selecting the short side facade shape by
double clicking it, the "New Facade from Selection" Button is activated. Click it to get an orthogonal view of the
textured facade.
Creating facade templates from an imported textured mass model
EXCURSUS START: Tips for efficient working with the Facade Wizard
For an immeditate update of the geometry produced by the Facade Wizard, choose the option "Immediate Saving and
Generation" in the right mouse button context menu. The generated mesh now reflects all changes in the Facade
Wizard rule creation process.
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!
A building mass model consists of one mesh with multiple faces. If one of the facade faces is selected and a Facade
Wizard rule template file is created (as described below), this file is automatically assigned to the WHOLE building. As
a consequence, the start rule (called "NationalBank" ) of the automatically generated rule set will consist of a
component split (see image below). This splits off all individual faces, depending on their face ID, and then triggers the
corresponding facade rule. Note that the index of a selected face is also displayed in the Inspector.
The main component split triggers the rule file's index-based embedded facade templates
EXCURSUS END: --> We learn that a Facade Wizard rule file can contain multiple facade templates which can easily be
relinked if desired (shown at the end of this part of the tutorial).
At this point, you can start blocking out the main building masses into ground floor, upper floors and roof part (Splits
1). Four vertical splits (Splits 2) define the ground floor: 2 (repetitive) left windows, 1 entry and 2 (repetitive) right
windows. To define repetitive splits, change the split type from single to repetitive by changing the active tool button.
Please note that after splits have been set (Splits 3), you can go back to the split line and edit it's position
interactively to refine the positions. In repetitive splits, the blue areas are the ones being repeated. In our example,
we want it to be the non-lit part. Use the RMB context menu and choose "Set Region". Do the same on both sides of
the entrance.
Defining the Ground Floor splits
For the upper floors, choose again the single vertical split and SHIFT- drag the split line to snap to the splits which
were previously defined on the ground floor level. Set up the 3 remaining horizontal and the 10 vertical repetitive
splits. Define the tile as one of the darker windows by "Setting the Region". In this facade tile, continue with two
single horizontal and vertical splits to isolate the window area. On the roof part, split off the roof ledge ornament.
Nested repetivive splits define a "scalable" upper floor
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
Select the model and generate it to see the volumetric facade.
The final facade rule, generated on it's original mass model face
A typical use case is that the user would like to assign the same facade rule on all the other sides of the building :
To relink the same facade rule to the other facades, double-click the side faces and note down the face indices
which are in our case, it's 0,3,6
In the Visual CGA graph editor, simply click-drag a noodle from NationalBank_0, NationalBank_3 and
NationalBank_6 to the NationalBank_7 rule. If you regenerate the model now once again, you will see that all the
four building sides have the same original side facade from "face 7" assigned.
Relinking the created rule file to all four sides of the same mass model
Part 2 : Advanced Facade Creation

Advanced Facade Creation
Introduction
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. This, we will do in Visual CGA.
Facade Analysis and rule creation

This is the original facade texture file we will be using:
It has a nice set of difficulties which a user will encounter often when creating more complex facades with the Facade Wizard.
Advanced Facade Example
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 VCGA ]
Main facade structure. An analysis of single splits, repetitive splits and rule symmetry
Unlike in the previous example, we start directly by selecting a texture file. Use the "New Facade from Image" button
which looks like a folder icon 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.
Enter a value of 20 for now, we will set this again later.

Setting of the facade's width
EXCURSUS START: Rectify
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 "Rectify" command to create an orthogonal texture. Simply click on four spots
which define the positions of the four texture corners.
Please note that a new texture is saved with the border areas cropped off and then opened in the Facade Wizard.
The "Rectify" command lets the user skew the perspective to create an orthogonal texture
EXCURSUS END: --> We learn that images can be rectified within the CityEngine. This allows a more streamlined process
without having to leave the software.
The next picture shows the first sequence of SINGLE splits. Note that the right vertical upper floor part is left without splits. That
part is the same as on the left side and will be linked later in Visual CGA. 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.
In this first split series, it is important that we define the split types correctly whether the split is absolute or floating.
We want the facade to tile afterwards, so the parts which need an absolute value must be defines as absolute splits.
Take a look at the following picture and see that the first and third upper floor's vertical size was defined as absolute.
TIP: To define whether a split is defined in absolute or floating distance, you can 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, just
hover the mouse 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.
Series of single splits with split type definition (absolute - floating)
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 horizotal 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).
Series of repetitive splits
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.
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
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.
In the RMB context menu, choose "Set Regin Width ..." and enter an appropriate size like 1.2 meters.
Now, 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.
If you did not save yet, save your rule file. It is also recommended to 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.
Create a new rule called MassModel.cga, open it up in the Visual CGA node based rule editor.
Create an attribute called "buildingHeight", with a value of 25.
Create a new rule called "Lot", with an extrude command. Use the previously generated "buildingHeight" attribute for
the extrusion value.
Insert a component split which splits off all "side" faces.
Import the facade template file we just created with the "import" command in the Right Mouse Button context menu.
Drag-and-drop-connect the MassModel's shape to the facade template. This will trigger the previously generated
Facade rule on all sides of a mass model.
Create a FootPrint shape with the Start Rule "Lot", assign to it the MassModel.cga 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 35 [meters].
Custom MassModel rule and triggering the facade template on all side faces
In the following picture, we see those parts (colored yellow) which we left without further detailing beforehand. Now, we will use
VCGA 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.
Generated Facade with parts left which we will relink
Open the Model Hierarchy Window and double click on the generated model in the viewport. You see that the model
turns slightly transparent and we have entered the Edit Model Mode (Button activated in the upper right corner of the
GUI).
Navigate to the correct shape node which depicts the left vertical part of the facade (detailed) and the right yellow
one (blank). [Note that they might be named differently in your specific rule file.]
Write down both rule names and change to the VCGA rule editor.
Edit Model Mode and Model Hierarchy Window: shape Hightlighting
In the VCGA Editor, navigate to the rule of the right facade side and simply drag and drop it onto the correct rule of the left side.
After you have regenerated the model, you see that after relinking, both sides now use the same rule !
Relinking of the rules via drag and drop
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.
Note that unused rules are positioned at a default positions off the main graph tree in the VCGA editor.
Unused rules can be deleted since they are not needed any more.
You have completed part 2 of the tutorial and can enjoy the final model after generating it once again :
Final model for part 2 of this tutorial, with relinked facade parts. Perfect.
Part 3 : LODs and asset insertion

Advanced Facade Creation
Introduction
After having covered the basic creation of facade templates within the Facade Wizard, it's time to think outside the box and explore,
how Visual 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 it's 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" or in short "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
Default LOD definition
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
Tip: 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 master cga file --> attr
LOD = 2
An important question comes up: What can be done if the templates, which can be created with a Facade Wizard, are not enough
detailed - 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 VCGA and the
insertion of custom made assets.
Asset insertion
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
Representing assets for use in the LOD 3
Open the Facade Wizard's facade rule and create four new rules as seen in the next picture with the following
names :
insertArcEntryAsset
insertTriangularPedimentAsset
insertSquarePedimentAsset
addTympanonAsset
New rules to insert the four assets we will use
On all of the four new rules, do the following two steps :
Select the shape node in the new rule and create a case under "Add Operation / Branching / Case condition"
Define the cases as "case LOD == 3"
Insertion of the case conditions which trigger the asset insertion in LOD 3
The rules will now be extended individually with more CGA commands accoding to the next picture. Please note that 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.
The final rule representations for the rules which insert the assets
What is now left to do is to use the Edit Model Mode and VCGA's code highlighting 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.
Insert a new shape at the bottom of the rules and draw the connection to the corresponding one of the four new
rules.
Relinking to the new rule
One last step to take is to use a NIL command to get rid of the geometry which gets textured transparent, since all tympanon
triangles now have their own geometry.
Find the correct rule and use a NIL command to erase those shapes by the time they are created.
Redundant shapes can be NIL-ed in LOD 3
After you have linked all necessary rules, the generated facade will look like this :
Final Facade Wizard rule with all assets inserted of LOD 3
This final picture shows all four LODs next to each other.
Poly counts in this example (facades only): 4, 1288, 6616, 9654. Well done.
Resulting 4 LODs

CGA Shape Reference
material.color shape attribute
Synopsis
float material.color.[r|g|b|a]
string material.color.rgb
The material.color shape attribute controls the diffuse color and the alpha/opacity value of the shape's geometry (a = 0 is fully
transparent, a = 1 is fully opaque).
Related
material attributes
set operation
color operation
Examples
Rainbow building
Lot-->
extrude(20)
set(material.color.g, 0)
split(x) {
2 : set(material.color.r, split.index/split.total)
set(material.color.b, 1.0 - split.index/split.total)
X
}*
The split index is used to generate position dependent colors..

CGA Shape Reference
material.map shape attribute
Synopsis
string material.[colormap|bumpmap|dirtmap]
float material.[colormap|bumpmap|dirtmap].s[u|v]
string material.map[3|4|5]
float material.map[3|4|5].s[u|v]
The material shape attribute consists of 6 texture layers. While only the first three (colormap, bumpmap, dirtmap) are rendered
in the 3D view, all six layers are included in exported shapes (if this is supported by the file format).
Each coordinate layer consists of the file name of the associated texture (material.[colormap|bumpmap |dirtmap] and string
material.map[3|4|5]) and scaling factors in horizontal and vertical directions (material.[colormap|bumpmap|dirtmap].s[u|v] and
material.map[3|4|5].s[u|v] ).
All these attributes can be set and read.

See Asset Search for information about where the texture is searched and Built-in Assets for a list of built-in textures.
Related
set operation
projectUV operation
material attributes
findFirst
Synopsis
float findFirst(string inputString, string matchString)
Returns
First occurrence (position/index) of matchString in the inputString .
This function returns the index of the first occurrence of the matchString in the inputString .
Related
findLast function
getPrefix function
getRange function
getSuffix function
replace function
Examples
findFirst("rule your city with cityengine","city")

# result = 10
# "rule your " = 10 characters; then the match string starts

listClean
Synopsis
stringList listClean(string stringList)
Returns
Returns cleaned stringList .
This function checks if the stringList has the correct ";" at the end.
Related
listAdd function
listFirst function
listIndex function
listItem function
listLast function
listRandom function
listRange function
listSize function
Examples
example.1
listClean("cityengine;rules")
example.2
listClean("cityengine;rules;")

listFirst
Synopsis
string listFirst(string stringList)
Returns
Returns first item in stringList .
This function returns the first item in the stringList .
Related
listAdd function
listClean function
listIndex function
listItem function
listLast function
listRandom function
listRange function
listSize function
Examples
example.1
listFirst("rule;your;city;")
# result = "rule"
example.2
listFirst(fileSearch("/myProject/assets/image*.jpg"))
# result = the image from that directory with the lowest index
listIndex
Synopsis
float listIndex(string stringList, string item)
Returns
Returns index of first occurrence of item.
This function returns the index of the first occurrence of the item in the stringList .
Related
listAdd function
listClean function
listFirst function
listItem function
listLast function
listRandom function
listRange function
listSize function
Examples
example.1
listIndex("rule;your;city;","city")
# result = 2
example.2
listIndex("texture_1.jpg;texture_2.jpg;texture_3.jpg;","texture_1.jpg")
# result = 0
listItem
Synopsis
string listItem(string stringList, float index)
Returns
Returns item at the given index .
This function returns the item of the stringList at the given index .
Related
listAdd function
listClean function
listFirst function
listIndex function
listLast function
listRandom function
listRange function
listSize function
Examples
example.1
listItem("rule;your;city;",2)
# result = "city"
example.2
listItem("texture_1.jpg;texture_2.jpg;texture_3.jpg;",0)
# result = "texture_1.jpg"
listLast
Synopsis
string listLast(string stringList)
Returns
Returns last item in stringList .
This function returns the last item in the stringList .
Related
listAdd function
listClean function
listFirst function
listIndex function
listItem function
listRandom function
listRange function
listSize function
Examples
example.1
listLast("rule;your;city;")
# result = "city"
example.2
listLast(fileSearch("myProject/assets/image*.jpg"))
# result = the image from that directory with the highest index
listRandom
Synopsis
string listRandom(string stringList)
Returns
Returns random item of stringList .
This function returns a random item of the stringList .
Note.1: Getting a random element often is directly combined with a wildcard search. See example.2
Related
listAdd function
listClean function
listFirst function
listIndex function
listItem function
listLast function
listRange function
listSize function
Examples
example.1
listRandom("rule;your;city;")
# result = "rule" or "your" or "city"
example.2
listRandom(fileSearch("/myProject/assets/*.jpg"))
# result = a random .jpg image from that directory.
example.3
listRandom(fileSearch("*.obj"))
# result = a random asset from the whole workspace.

listRange
Synopsis
stringList listRange(string stringList, float index1, float index2)
Returns
Returns items from index1 to index2 (index2 excluded).
This function returns all items in the stringList from index1 to index2 (the index2 item is not included in the resulting list).
Related
listAdd function
listClean function
listFirst function
listIndex function
listItem function
listLast function
listRandom function
listSize function
Examples
example.1
listRange("rule;your;city;with;cityengine;",0,3)
example.2
listRange("texture_1;texture_2;texture_3;texture_4;texture_5;texture_6;",2,3)
# result = "texture_3"
listSize
Synopsis
float listSize(string stringList)
Returns
Returns number of elements in stringList .
This function returns the number of elements in the stringList .
Related
listAdd function
listClean function
listFirst function
listIndex function
listItem function
listLast function
listRandom function
listRange function
Examples
example.1
listSize("cityengine;rules;")
# result = 2
example.2
listSize(fileSearch("/myProject/assets/*.jpg"))
# result = the number of .jpg files in that directory.
listAdd
Synopsis
string listAdd(string stringList, string item)
Returns
Append item to stringList .
This function appends the item to the stringList .
Related
listClean function
listFirst function
listIndex function
listItem function
listLast function
listRandom function
listRange function
listSize function
Examples
example.1
listAdd("rule;your;","city")
example.2
listAdd("rule;your;","city;")
offsetUV operation
Synopsis
offsetUV(uvset, u-offset, v-offset)
Parameters
uvset
attribute.
u-offset (float)
How much offset to add in u direction.
v-offset (float)
How much offset to add in v direction.
The offsetUV operation translates the corresponding texture layer by adding u-offset and v-offset to each of its texture
coordinates.
Related
projectUV operation
scaleUV operation
Shapes
1. What are Shapes
2. Creating and Editing Shapes Manually
Subdividing Shapes
3. Creation of Shapes from Graph Networks
Block Parameters
Street Parameters
Crossing Parameters
Parameter Source
Street Shapes
4. Importing Shapes
5. Exporting Shapes

City Engine Help 2010 3 PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

City Engine Help 2010 3 PDF

Uploaded by

Copyright:

Available Formats

The Quick Start Guide provides a short The CityEngine Manual contains the complete The Tutorials describe

I. Interactive Facade Editing

How to work with the Tutorials

1. CityEngine Basics Tutorial

3. Map Control Tutorial

4. Import Streets Tutorial

5. Import Shapes Tutorial

6. Basic Shape Grammar Tutorial

7. Facade Modeling Tutorial

8. Mass Modeling Tutorial

9. Advanced Shape Grammar Tutorial

10. Python Scripting Tutorial

11. Reporting Tutorial

12. GIS Mapping Tutorial

14. Visual CGA Tutorial

15. Facade Wizard Tutorial

alignScopeToAxes alignScopeToGeometry center color

comp convexify deleteUV extrude

innerRect i (insert) mirror mirrorScope

normalizeUV NIL offset pop

print projectUV push r (scope rotate)

report reverseNormals roofGable roofHip

roofPyramid roofShed rotate rotateScope

rotateUV s (scope size) scaleUV scatter

set setback setPivot setupProjection

shapeL shapeU shapeO split

t (scope translate) taper texture tileUV

translate translateUV trim

comp initialShape material pivot

seedian scope split trim

abs acos asin atan

atan2 ceil cos exp

floor isinf isnan ln

log10 pow rint sin

bool float sel str

count find len substring

geometry.area geometry.du/dv geometry.isConcave geometry.isPlanar

geometry.isRectangular geometry.nEdges geometry.nFaces geometry.nVertices

Assets and Images

assetInfo assetsSortRatio assetsSortSize imageInfo

inside overlaps touches

Simple Types Operations attr const import

CGA Utility Functions Library

String Utility Functions

findFirst findLast getPrefix getRange

String List Utility Functions

listAdd listClean listFirst listIndex

listItem listLast listRandom listRange

File, Asset and Image Utility Functions

assetApproxRatio assetApproxSize assetBestRatio assetBestSize

assetFitSize fileBasename fileDirectory fileExtension

fileName fileRandom imageApproxRatio imageBestRatio

Copyright 2008 - 2010 Procedural Inc.

Introduction to the CityEngine

The CityEngine Features

Procedural Modeling Core

Dynamic City Layouts

The CityEngine Modeling Pipeline

Generating Large-Scale Urban Layouts

Copyright 2008 - 2010 Procedural Inc.

The CityEngine Main Window

CGA Rule Editor

Creating a new CityEngine Scene