CityEngine Help

10/16/2014 CityEngine Help
http://cehelp.esri.com/help/advanced/print.jsp?topic=/com.procedural.cityengine.help/html/toc.html 1/381
CityEngine Help
Contents
1. Quick Start Guide
1.1. CityEngine Overview
1.2. User Interface
1.3. CityEngine Workflow
1.4. Rule-based Modeling
1.5. Model Export
2. Manual
2.1. User Interface
2.1.1. Window Type Overview
2.1.2. The Viewport Window
2.1.2.1. 3D Navigation Essentials
2.1.2.2. Viewing Modes and Display Settings
2.1.2.3. Object Selection
2.1.2.4. Object Edit and Transform Tools
2.1.2.5. Cameras
2.1.2.6. Bookmarks
2.1.2.7. Context Menu
2.1.2.8. Multiple Viewport Windows
2.1.2.9. Keyboard Shortcuts Reference
2.1.3. The File Navigator
2.1.4. The Scene Window
2.1.4.1. Light Layer
2.1.4.2. Panorama Layer
2.1.5. The CGA Editor
2.1.6. The Log View
2.1.7. The Console
2.1.8. The Problems View
2.1.9. The Progress View
2.1.10. The Inspector
2.1.11. Configuring the Windows Layout
2.1.11.1. Predefined Window Layouts
2.1.11.2. Saving and Loading Window Layouts
2.1.11.3. Editors
2.1.11.4. Views
2.1.11.5. Dragging Windows
2.2. CityEngine Preferences
2.2.1. Export
2.2.2. General
2.2.3. Appearance
2.2.4. Editors
2.2.5. Procedural Runtime
2.2.6. Keys
2.2.7. Perspectives
2.2.8. Viewport
2.2.9. Bookmarks
2.2.10. Cameras
2.2.11. Lights
2.2.12. Mouse
2.2.13. 3D Mouse
2.2.14. Touch
2.2.15. Help
2.2.16. Network
2.2.17. Scene
2.3. Project Management
2.3.1. Why Project Management
2.3.2. Using CityEngine Projects
2.3.2.1. Creating a CityEngine Project
2.3.2.2. Creating a CityEngine Scene
2.3.2.3. Folder Organization and File Types
2.3.2.4. Importing Files into a Project
2.3.2.5. Exploring Projects with the File Navigator
2.3.2.6. Editing and Refreshing Assets
2.3.3. The CityEngine Workspace
2.3.3.1. Creating a new Workspace
2.3.3.2. Switching Workspaces
2.3.4. Archiving or Exchanging CityEngine Projects
2.3.4.1. Importing a Project into the Workspace
2.3.4.2. Exporting a Project
2.4. Map Layers
2.4.1. What is a Map Layer
2.4.2. Terrain
2.4.2.1. Aligning Terrains to Shapes
2.4.2.2. Exporting Terrains to geometry or image files
2.4.3. Texture
2.4.4. Other Map Layer Types
2.4.5. Editing Map Layers
2.4.6. Editing Map Layer Attributes
2.4.7. Selection via Image Maps
2.5. Shapes
2.5.1. What are Shapes
2.5.2. Creating and Editing Shapes Manually
2.5.2.1. Aligning Shapes to the Terrain
2.5.2.2. Subdividing Static Shapes
2.5.2.3. Shape Texturing Tool
2.5.3. Creating Shapes from Graph Networks
2.5.3.1. Block Parameters
2.5.3.2. Street Parameters
2.5.3.3. Intersection Parameters
2.5.3.4. Street Shapes
2.5.3.5. Street and Intersection Shape UVs
2.5.3.6. Edit Street Tool
2.5.4. Importing Shapes
2.5.4.1. Creating and Preparing Polygons for Shape Import
2.5.4.2. Importing Shapes from OBJ
2.5.4.3. Importing Shapes from COLLADA DAE
2.5.4.4. Importing Shapes from KMZ / KML
2.5.4.5. Importing Shapes from DXF
2.5.4.6. Importing Shapes from SHP
2.5.4.7. Importing Shapes from OSM
2.5.5. Exporting Shapes
2.5.5.1. Exporting Shapes to SHP
2.5.5.2. Exporting Shapes to DXF
2.6. Street Networks
2.6.1. What are Street Networks
2.6.2. Creating and Editing Street Networks Manually
2.6.3. Growing Street Networks
2.6.4. Aligning Street Networks to the Terrain
2.6.5. Cleanup Graph
2.6.6. Generate Bridges
2.6.7. Fit Street Widths to Shapes
2.6.8. Simplify Graph
2.6.9. Analyze Graph
2.6.10. Importing Graph Networks
2.6.10.1. Importing Graph Segments from DXF
2.6.10.2. Importing Graph Segments from OSM
2.6.10.3. Importing Graph Segments from SHP
2.6.11. Exporting Graph Networks
2.6.11.1. Exporting Graph Segments to SHP
2.6.11.2. Exporting Graph Segments to DXF
2.7. Static Models
2.7.1. What are Static Models
2.7.2. Importing Static Models
2.7.3. Working with Static Models
2.7.4. Aligning Static Models to the Terrain
2.8.1. Basics of Rule-based Modeling
2.8.1.1. Shapes
2.8.1.2. Rule Application
2.8.2. Rule Files
2.8.2.1. Creating a new Rule File
2.8.2.2. Writing a Rule File
2.8.2.3. Assigning a Rule File to a Shape
2.8.2.4. Setting the Start Rule
2.8.2.5. Applying the Rules to generate a 3D Model
2.8.3. Writing Rules
2.8.3.1. Standard Rule
2.8.3.2. Parameterized Rule
2.8.3.3. Conditional Rule
2.8.3.4. Stochastic Rule
2.8.3.5. Attributes
2.8.3.6. Functions
2.8.3.7. Import
2.8.3.8. Comments
2.8.3.9. Handles
2.8.4. Shape Operations
2.8.4.1. Extrusion
2.8.4.2. Transformations
2.8.4.2.1. Coordinate Systems
2.8.4.3. From Volume to Surface with the Component Split
2.8.4.4. The Subdivision Split
2.8.4.4.1. Repeat Split
2.8.4.4.2. Rhythm
2.8.4.4.3. Parallel Repeat
2.8.4.4.4. Relative Split
2.8.4.5. Insertion of Assets
2.8.5. Rule Editing Tools
2.8.5.1. Working with the CGA Editor
2.8.5.2. Working with the Model Hierarchy Explorer
2.8.5.3. Overwriting Attributes with the Inspector
2.8.5.4. CGA Styles
2.8.6. Rule Packages (rpk)
2.9. Importing Data
2.9.1. Importing Data Overview
2.9.2. Collada DAE
2.9.3. DXF
2.9.4. File Geodatabase
2.9.5. KMZ/KML
2.9.6. OBJ
2.9.7. OSM
2.9.8. Shapefile
2.10. Georeferencing
2.10.1. Scene Coordinate System
2.10.2. View Coordinate System
2.10.3. Coordinate System Dialogs
2.10.4. Using Georeferenced Data
2.11. Exporting Models
2.11.1. General Export Reference
2.11.1.1. Overview of Supported Formats
2.11.1.2. Common Export Options
2.11.1.3. Formats Feature Comparison
2.11.2. Supported Formats and Specific Options
2.11.2.1. Esri FileGDB
2.11.2.2. Wavefront OBJ
2.11.2.3. Autodesk FBX
2.11.2.4. Collada DAE
2.11.2.5. Keyhole KMZ / KML
2.11.2.6. CityEngine Web Scene (3ws)
2.11.2.7. Renderman RIB
2.11.2.8. e-on Vue VOB
2.11.2.9. Script Based Exporter
2.11.3. Export Application Notes
2.11.4. CityEngine Web Scenes
2.12. Mapping Attributes
2.12.1. Attributes, Sources and Connections
2.12.2. Mapping Attributes with Connection Editor
2.12.3. Mapping Image Data to Rule Attributes
2.12.4. Mapping Object Attributes via Layer Attribute
2.13. ArcGIS Online / Portal
2.13.1. Share data
2.14. Interactive Facade Editing
2.14.1. Facade Wizard Overview
2.14.2. Crop Image Tool
3. CGA Shape Grammar Reference
3.1. Shape Operations
3.1.1. alignScopeToAxes (Operation)
3.1.2. alignScopeToGeometry (Operation)
3.1.3. center (Operation)
3.1.4. cleanupGeometry (Operation)
3.1.5. color (Operation)
3.1.6. comp (Operation)
3.1.7. convexify (Operation)
3.1.8. deleteHoles (Operation)
3.1.9. envelope (Operation)
3.1.10. extrude (Operation)
3.1.11. i (Operation)
3.1.12. innerRect (Operation)
3.1.13. mirror (Operation)
3.1.14. mirrorScope (Operation)
3.1.15. NIL (Operation)
3.1.16. normalizeUV (Operation)
3.1.17. offset (Operation)
3.1.18. pop (Operation)
3.1.19. print (Operation)
3.1.20. projectUV (Operation)
3.1.21. push (Operation)
3.1.22. r (Operation)
3.1.23. reduceGeometry (Operation)
3.1.24. report (Operation)
3.1.25. reverseNormals (Operation)
3.1.26. roofGable (Operation)
3.1.27. roofHip (Operation)
3.1.28. roofPyramid (Operation)
3.1.29. roofShed (Operation)
3.1.30. rotate (Operation)
3.1.31. rotateScope (Operation)
3.1.32. rotateUV (Operation)
3.1.33. s (Operation)
3.1.34. scatter (Operation)
3.1.35. scaleUV (Operation)
3.1.36. set (Operation)
3.1.37. setback (Operation)
3.1.38. setNormals (Operation)
3.1.39. setPivot (Operation)
3.1.40. setupProjection (Operation)
3.1.41. shapeL (Operation)
3.1.42. shapeU (Operation)
3.1.43. shapeO (Operation)
3.1.44. split (Operation)
3.1.45. t (Operation)
3.1.46. taper (Operation)
3.1.47. texture (Operation)
3.1.48. tileUV (Operation)
3.1.49. translate (Operation)
3.1.50. translateUV (Operation)
3.1.51. trim (Operation)
3.2. Shape Attributes
3.2.1. comp (Attribute)
3.2.2. initialShape (Attribute)
3.2.3. material (Attribute)
3.2.4. material.color (Attribute)
3.2.5. material.map (Attribute)
3.2.6. pivot (Attribute)
3.2.7. scope (Attribute)
3.2.8. seedian (Attribute)
3.2.9. split (Attribute)
3.2.10. trim (Attribute)
3.2.11. uid (Attribute)
3.3. Builtin Functions
3.3.1. abs (Function)
3.3.2. acos (Function)
3.3.3. asin (Function)
3.3.4. atan (Function)
3.3.5. atan2 (Function)
3.3.6. ceil (Function)
3.3.7. cos (Function)
3.3.8. exp (Function)
3.3.9. floor (Function)
3.3.10. isinf (Function)
3.3.11. isnan (Function)
3.3.12. ln (Function)
3.3.13. log10 (Function)
3.3.14. pow (Function)
3.3.15. rint (Function)
3.3.16. sin (Function)
3.3.17. sqrt (Function)
3.3.18. tan (Function)
3.3.19. p (Function)
3.3.20. rand (Function)
3.3.21. bool (Function)
3.3.22. float (Function)
3.3.23. sel (Function)
3.3.24. str (Function)
3.3.25. count (Function)
3.3.26. find (Function)
3.3.27. len (Function)
3.3.28. substring (Function)
3.3.29. geometry.area (Function)
3.3.30. geometry.angle (Function)
3.3.31. geometry.{du|dv} (Function)
3.3.32. geometry.isConcave (Function)
3.3.33. geometry.isClosedSurface (Function)
3.3.34. geometry.isInstanced (Function)
3.3.35. geometry.isOriented (Function)
3.3.36. geometry.isPlanar (Function)
3.3.37. geometry.isRectangular (Function)
3.3.38. geometry.nEdges (Function)
3.3.39. geometry.nFaces (Function)
3.3.40. geometry.nHoles (Function)
3.3.41. geometry.nVertices (Function)
3.3.42. geometry.{uMin|uMax|vMin|vMax} (Function)
3.3.43. geometry.volume (Function)
3.3.44. fileExists (Function)
3.3.45. fileSearch (Function)
3.3.46. assetInfo (Function)
3.3.47. assetsSortRatio (Function)
3.3.48. assetsSortSize (Function)
3.3.49. imageInfo(Function)
3.3.50. imagesSortRatio (Function)
3.3.51. inside (Function)
3.3.52. overlaps (Function)
3.3.53. touches (Function)
3.3.54. convert (Function)
3.3.55. getGeoCoord (Function)
3.3.56. print (Function)
3.4. Simple Types Operations
3.5. Other Keywords
3.5.1. attr keyword
3.5.2. const keyword
3.5.3. import keyword
3.5.4. style keyword
3.5.5. version keyword
3.6. CGA Utility Function Library
3.6.1. findFirst (String Utility Function)
3.6.2. findLast (String Utility Function)
3.6.3. getPrefix (String Utility Function)
3.6.4. getRange (String Utility Function)
3.6.5. getSuffix (String Utility Function)
3.6.6. replace (String Utility Function)
3.6.7. listAdd (String List Utility Function)
3.6.8. listClean (String List Utility Function)
3.6.9. listFirst (String List Utility Function)
3.6.10. listIndex(String List Utility Function)
3.6.11. listItem (String List Utility Function)
3.6.12. listLast (String List Utility Function)
3.6.13. listRandom (String List Utility Function)
3.6.14. listRange (String List Utility Function)
3.6.15. listSize (String List Utility Function)
3.6.16. listTerminate (String List Utility Function)
3.6.17. assetApproxRatio (File Utility Function)
3.6.18. assetApproxSize (File Utility Function)
3.6.19. assetBestRatio (File Utility Function)
3.6.20. assetBestSize (File Utility Function)
3.6.21. assetFitSize (File Utility Function)
3.6.22. fileBasename (File Utility Function)
3.6.23. fileDirectory (File Utility Function)
3.6.24. fileExtension (File Utility Function)
3.6.25. fileName (File Utility Function)
3.6.26. fileRandom (File Utility Function)
3.6.27. imageApproxRatio (File Utility Function)
3.6.28. imageBestRatio (File Utility Function)
3.6.29. colorRamp (Color Utility Function)
3.7. Misc Information
3.7.1. CGA Changelog
3.7.2. Annotations
3.7.3. Asset Search
3.7.4. Builtin Assets and Textures
3.7.5. Texturing
4. Python Scripting
4.1. Scripting Interface Usage
4.1.1. Parameters and Attributes
4.1.2. Settings classes
4.1.3. Script-based Export
4.1.4. Special scripts
4.2. Commands by Category
4.3. Command Reference
4.4. Notes and Changelog
Help
The Quick Start Guide provides a short
overview of the CityEngine's user
interface and workflow possibilities.
The CityEngine Manual contains the
complete reference to the user
interface, the different tools, import and
export, and common practices.
You might take the red pill for the CGA
Shape Grammar Reference and go
straight for the truth of rule-based
modeling.
The Python Scripting Interface
greatly enhances CityEngine's
toolset and allows for the
automatisation of tasks.
Version 2014. Copyright 2008-2014 Esri R&D Center Zurich. All rights reserved.
1. 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-2014 Esri R&D Center Zurich. All rights reserved.
1.1. 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.
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 automate 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 CityEngine is 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.
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 create different variations in
each layer. 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 iterations 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. Unique 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.
1.2. 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 consists of several sub-window components. The
screenshot below shows a typical CityEngine modeling session.
The CityEngine User Interface with a scene opened.1: Scene Editor; 2: Rule Editor; 3: Viewport; 4: Inspector; 5: Navigator 6:
Second Viewport; 7: Log for Errors, 8 : Console
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 Window 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 functions 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 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 different environment, street network and shape layers..
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 already has 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 ( Edit Preferences General 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 object's 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.
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 a 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.
1.3. 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.
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 by clicking:
New ... CityEngine CGA Rule 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.
1.5. 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 for 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\building.obj.
2. CityEngine Manual
Table of Contents
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
Context Menu
Multiple Viewport Windows
Keyboard Shortcut Reference
3. The File Navigator
4. The Scene Window
5. The CGA Editor
6. The Log View
7. The Console
8. The Problems View
9. The Progress View
10. The Inspector
11. Configuring the Windows Layout
12. CityEngine Preferences
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
Map Layers
1. General
2. What is a Map Layer
3. Terrain
Aligning Terrains to Shapes
Exporting Terrains to geometry or image files
4. Texture
5. Other Map Layer Types
6. Working with Map Layers in the Inspector Window
7. Editing Map Layers
8. Editing Layer Attributes
9. Selection via Image Maps
Shapes
1. What are Shapes
2. Creating and Editing Shapes Manually
Aligning Shapes to the Terrain
Subdividing Static Shapes
Shape Texturing Tool
3. Creation of Shapes from Graph Networks
Block Parameters
Street Parameters
Intersection Parameters
Street Shapes
Graph Shape UVs
Street Tool
4. Importing Shapes
Creating and Preparing Polygons for Shape Import
5. Exporting Shapes
Exporting Shapes to SHP
Exporting Shapes to DXF
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. Generate Bridges
7. Fit Widths to Shapes
8. Simplify Graph
9. Analyze Graph
10. Importing Graph Networks
11. Exporting Graph Networks
Static Models
1. What are Static Models
2. Importing Static Models
3. Working with Static Models
4. Aligning Static Models to the Terrain
Rule-based Modeling
1. Basics of Rule-based Modeling
2. Rule Files
3. Writing Rules
4. Shape Operations
5. Rule Editing Tools
6. Rule Packages
Importing Data
1. Import Overview
Georeferencing
1. Scene Coordinate System
2. View Coordinate System
3. Coordinate System Dialogs
4. Georeferenced Data
Exporting Models
1. Export Overview
2. General Export Reference
3. Supported Formats and Specific Options
4. Export Application Notes
5. CityEngine Web Scenes
Mapping Attributes
1. Attributes and Sources
2. Mapping Attributes with Connection Editor
ArcGIS Online / Portal
1. Share data
Python Scripting
1. Python Scripting Interface
2. Commands by Category
3. Command Reference
Interactive Facade Editing
1. Facade Wizard Overview
2. Crop Image Tool
2.1. 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
Context Menu
Multiple Viewport Windows
Keyboard Shortcut Reference
3. The Scene Editor
4. The CGA Editor
5. The Inspector Window
6. The File Navigator
7. The Log View
8. The Console
9. The Problems View
10. The Progress View
11. Configuring the Windows Layout
Predefined Window Layouts
Editors
Views
Dragging Windows
Saving and Loading Window Layouts
12. CityEngine Preferences
13. Shortcut Reference
2.1.1. Window Type Overview
The main window types of CityEngine.
1. Scene editor for scene, layer, and object management
2. CGA rule editor with text and graphical view
3. 3D viewport with a perspective camera
4. Inspector for a detailed view and editing of selected objects
5. Navigator to manage and preview files in the workspace
6. Second 3D viewport with a top camera
7. Log for CityEngine messages; Console for CGA output; Problems for CGA compiler errors and
warnings, Progress for progress reporting of long-running CityEngine operations
8. Console for printed text output
CityEngine supports tabbed windows which can be arranged in arbitrary layouts (see Configuring the Window
Layouts).
2.1.2. 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. Context Menu
8. Multiple Viewport Windows
9. Keyboard Shortcut Reference
2.1.2.1. 3D Navigation Essentials
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.
2.1.2.2. Viewing Modes and Display Settings
The 3D viewport offers many options for viewing modes and display settings. These options are accessed in
the top toolbar of every 3D viewport window.
Layer type visibility

The layer buttons determine which layer types are visible on a per-viewport basis:
Parameter Function Shortcut

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.
F9
Show/Hide Graph Networks
toggles graph network visibility for this viewport. F10

Show/Hide Map Layers
toggles shape visibility for this viewport. F11

Show/Hide Models
toggles model visibility for this viewport. 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.

Frame

Frame
Frame the selection. The camera's point of interest is placed in the
center of the selection and the camera distance is adjusted accordingly.
F
Isolate

isolate
Isolate the current selection, hide unselected objects. I

Camera Menu
Perspective/Orthogonal View toggle between perspective and orthogonal camera view P
Focal Length Choose focal length of camera
Camera Type Choose camera type. more info
Edit Cameras... Create or edit cameras. more info

View Settings
Item Function Shortcut
Scene Light
toggles between the global scene light (see Viewport Preferences) and
the headlight scene illumination.
L
Wireframe
wireframe render mode 4
Shaded
solid shading 5
Textured
textured shading 6
Wireframe on
Shaded/Textured
enable/disable wireframe overlay. 7
Shadows
turns on and off the shadows for generated models. Note that enabling
on shadows on large models may considerably affect rendering
performance.
8
Ambient Occlusion
enable/disable ambient occlusion rendering (more info) 9
Backface Culling
enable/disable backface culling. WIth backface culling enabled, only
faces facing the camera are rendered.

Single-Sided Lighting
enable/disable single-sided lighting. With single-sided lighting disabled,
faces are lit on both sides.

Information Display
toggles the information display. The information display gives some
statistics of the current scene such as number of objects and polygon
count.
D,D
Grid
toggles Grid visibility D,G
Axes
toggles Axes visibility D,A
Compass
toggles Compass visibility D,C
Navigation Display
toggles Navigation display for Cursor Position, grid size and View
Coordinate System
D,N
View Coordinate System
choose a Coordinate System for the Navigation Display

Render modes
A 3D viewport can render its contents in three different modes:
wireframe shaded textured textured with wireframe
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 .
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 .
You can always overlay wireframe independent of the viewing mode by enabling Wireframe on
Shaded/Textured in the View Settings menu or pressing 7 .

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.

Bookmarks Menu
Save Snapshot...
Save snapshot of viewport to image
Stored bookmarks Apply stored camera bookmarks Numpad_X
New Bookmark... Create new camera bookmark. more info
Edit Bookmark... Edit camera bookmarks. more info
2.1.2.3. 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).
Isolating 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 leave isolation mode and show the whole model again.
2.1.2.4. Object Edit and Transform Tools
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
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 yellow "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, the tool
will snap to edges and vertices of other objects. Holding down SHIFT while dragging inhibits snapping.
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.
The Rotate Tool E rotates selected objects and components around the axes (X, Y,
Z). Press SHIFT to snap to 45 degree angles.
The
Move Tool
The
Scale Tool
The
Rotate Tool
Using the Freehand Street Creation Tool G you can paint new streets or extend
existing networks. Refer to Creating and Editing Street Networks Manually for details.
Using the Polygonal Creation Tool G you can draw new streets or extend existing
networks. Refer to Creating and Editing Street Networks Manually for details.
With the Edit Street Tool C you can edit street curve tangents, change street
widths and move nodes. See Edit Street Tool for details.
With the Cleanup Graph Tool C you can clean Graph Networks. See Cleanup
Graph Tool for details.
With the Align Graph To Terrain Tool C you align your Street Network to a Terrain
( Basemap). See Align Graph To Terrain Tool for details.
With the Polygonal Shape Creation Tool S you may create new
polygons and extrude them to create 3D objects. Refer to Creating and Editing Shapes Manually for
details.
With the Rectangular Shape Creation Tool SHIFT+S you may create
new rectangles and extrude them to create 3D objects. See Creating and Editing Shapes Manually.
With the Separate Faces Tool you may create individual objects for every
face. Refer to Creating and Editing Shapes Manually for details.
With the Combine Faces Tool you may merge multiple shapes. See
Creating and Editing Shapes Manually.
With the Cleanup Shapes Tool you may remove unwanted components.
Refer to Creating and Editing Shapes Manually for details.
With the Texture Shapes Tool allows for splitting static shapes. See
Texture Shapes Tool.
With the Align Shapes To Terrain Tool you may create new shapes or
extend existing shapes with new vertices. Refer to Aligning Shapes to the Terrain for details.
With the Align Terrain To Shapes Tool allows for splitting static shapes.
See Aligning Terrains to Shapes.
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 to 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.
2.1.2.5. Cameras
CityEngine supports an arbitrary number of cameras. Multiple cameras are especially useful if you 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.
2.1.2.6. 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
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
Configuration: these values position and orient the camera. You can enter a world coordinate position
Distance to Point of Interest: this value corresponds to the distance between the camera and the POI.
rotation.
2.1.2.7. Viewport Context Menu
Depending on the selection, the viewport's context menu contains different entries. Some of the most
important entries are discussed below.
1. Convert Models to Shapes
2.1.2.8. Multiple Viewport Windows
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.
See also
Configuring the Windows Layout
2.1.2.9. Keyboard Shortcut Reference for the 3D Viewport
The following table summarizes the 3D viewport shortcuts (CityEngine Default Mouse Scheme):
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
D, D Toggle information display visibility
D, N Toggle Navigation Display
D, G Toggle Grid
D, A Toggle Axes
D, C Toggle Compass
F Frame selected
I Toggle isolation
L Toggle scene light / head 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 Reset Camera view
[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 / toggle selection modes
W Select translate tool
E Select rotate tool
R Select scale tool
S Select polygonal shape creation tool
Shift-S Select rectangular shape creation tool
G Select polygonal street creation tool
Shift-G Select manual street creation 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 .
2.1.3. 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 Navigator with the preview of a selected image file
You can open and edit CGA and scene files within CityEngine by double-clicking the corresponding file in the
navigator. The Navigator provides also basic operations such as copying, renaming and deleting files and folders.
Note that you can copy-paste or drag-and-drop files from the operating systems' file explorer directly into
CityEngine's Navigator.
If you modify files in the workspace outside of CityEngine (e.g. by editing a file using the operating systems' file
explorer or an external program), you have to refresh the Navigator. Choose FileRefresh Workspace or simply
hit F5 .
Preview Files in the Navigator
The Navigator can preview selected files. With corresponding buttons (see figure above) you can either choose to
have the preview on the bottom or right side of the file tree depending on your prefered window layout. In the case
of a 3D model such as .dae (Collada) or .obj files, a 3D preview is available which can be tumbled/navigated/framed
as in the 3D Viewport windows. Also a limited set of the 3D Viewport's display option is available such as displaying
the grid, axes or headup display.

Asset Preview

Previewing a selected 3D file in the Navigator
In the case of selecting CGA rule files, a preview of the 3D model is generated. Therefore the Navigator scans the
CGA rule file and guesses its start rule and applies the latter on a default shape. Similar to above, the resulting 3D
model can be tumbled/navigated/framed as in the 3D Viewport windows.

CGA Rule Preview

Previewing a selected rule file in the Navigator

For the rule file preview, the user can select the start rule (left) and the initial shape where it is applied on (right)
In case another start rule has to be applied, the user can manually select it by clicking on the button 'Choose Start
Rule'. Furthermore the user can modify the default shape where the rules are applied. Therefore click on the button
'Select initial shape' which presents a set of typical shapes consisting of horizontal planes ("Base*"), vertical planes
("Facade*") and volumes ("Volume*"). These shapes are very practical to preview the behavior of rule files on
shapes with regular and irregular geometry.

Drag and Drop from Navigator
Several filetypes can be by simple drag-and-drop into the 3D viewport.
Dragging a CGA rule file onto selected shapes.

CGA rule files Select a set of shapes and/or models in the 3D viewport, drag a CGA file and drop it onto the
selection in the viewport. The selected objects will have the CGA file assigned, and models will be generated.
OBJ files Drag an OBJ file into the 3D viewport. The OBJ model will be imported with default settings as a new
static model. The model is placed at the drop spot and appears as a new layer.
Collada DAE files Drag an DAE file into the 3D viewport. The Collada model will be imported with default settings
as a new static model. The model is placed at the drop spot and appears as a new layer.
CityEngine CEJ files Drag a CEJ file into the 3D viewport, and choose what layers to import in the popup window.
DXF files Drag a DXF file into the 3D viewport. The DXF will be imported with default settings.
SHP files Drag a SHP file into the 3D viewport. The SHP file will be imported with default settings.
File Geodatabase Drag a .gdb folder into the 3D viewport. All layers of the file geodatabase will be imported as
individual layers.
See also
Drag and Drop Import

Crop Image Tool (Navigator Context Menu)
Image files such as perspective facade photographs can be rectified with the Crop Image Tool, for use with the
Facade Wizard.
The Crop Image Tool can also be started via ShapesCrop Image from the main menu.

The Crop Image Tool for the image rectification
For details see
Crop Image Tool
2.1.4. 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 various parameters for
scene objects. The scene terrain is also created using a map layer.
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.
Note that the visibility of different object / layer types can also be controlled on a per-viewport basis from the
view settings menu of a 3D viewport window..
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*") to select
matching objects.
Parameter Function
Shape* Matches scene objects whose names start width Shape
"Shape 12" Matches scene objects whose names are exactly Shape 12
Shape* *12 Matches scene objects whose names start width Shape AND end with 12
Whitespace characters in a search query denote a logical AND expression. To match object names with
spaces, put your search query in double quotes ""
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.

2.1.4.1. Light Layer
Configure options for light source for 3D viewports.
The Scene Light layer is a fixed layer in every CityEngine scene. It is automatically added and cannot be deleted.
The SceneLight Layer controls how objects are lit in the 3D viewports.
Light settings can be changed in the Inspector with the Scene Light layer selected:
Parameter Function
Visible Switches between Scene Light and Headlight
Latitude angle of incidence Scene light latitude angle of incidence
Longitude angle of incidence Scene light longitude angle of incidence
Sun intensity Scene light intensity
Ambient intensity Scene light ambient intensity
Shadow attenuation Attenuation of shadows (blend to black)
Ambient occlusion attenuation Attenuation of screen space ambient occlusion (blend to black)
Ambient occlusion radius Unit radius of screen space ambient occlusion samples
Ambient occlusion filter radius Viewport pixel radius of screen space ambient occlusion filter
Ambient occlusion samples Number of screen space ambient occlusion samples
If the scene light is disabled, Latitude angle of incidence, Longitude angle of incidence, Sun intensity, and
Ambient intensity have no relevance. Ambient intensity is always zero in this case.
Ambient Occlusion
CityEngine's Ambient occlusion uses screen space ambient occlusion, a special real-time rendering technique
that approximates ambient light occlusion. Ambient occlusion is a shading method used in 3D computer graphics
which helps add realism by taking into account attenuation of light due to occlusion. Ambient occlusion attempts
to approximate the way light radiates in real life and is especially well suited for outdoor scenes.

Left: Solid shading without ambient occlusion. Right: Ambient occlusion enabled.

Left: Low ambient occlusion radius. Right: High ambient occlusion radius.
2.1.4.2. Panorama Layer
Choose environment and reflection map for 3D viewports.
The Panorama layer is a fixed layer in every CityEngine scene. It is automatically added and cannot be deleted. The
panorama layer contains the background skydome shown in the 3D Viewports.
Panorama settings can be changed in the Inspector with the Panorama layer selected:
Parameter Function
Environment Map
Image to be used as environment map.
The environment map is used to texture the sky in your scene
Reflection Map
Image to be used as reflection map
The reflection map is used on reflections on generated models that have reflection
enabled in their material settings.
Visible
Show or hide the panorama
The directory ce.lib/maps/panoramas contains a selection of panorama maps
2.1.5. The CGA Editor
CGA Editor in split mode, displaying Text and Visual CGA.
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 already has a rule file assigned already. 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.
Use the top toolbar buttons to switch between textual, visual CGA and mixed representation.

The rule editor has syntax highlighting and shows syntax errors (the latter are described in more detail in the
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 .
2.1.6. 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 error conditions (such as out of memory). The properties and values
of each log record are shown in this view. The Log View 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
2.1.7. The Console
You can open the Console window by selecting WindowShow Console from the main menu. The console
window contains different consoles used when working with CityEngine. The top toolbar button switches between
different consoles (if available).
CGA Console
If a CGA command produces textual output (such as the CGA print command), this output will be shown in the CGA
console. This console is available once a CGA print output is produced.
Python output console
The Python Output console is the default output console for python statements that use a print() command. This
console is available once a Python print output is produced.
Python command console
The Python command console to enter Python commands. This console needs to be opened in the top toolbar of
the console window.
2.1.8. The 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 Problems
from the main menu.
In the views settings of the Problems view (triangle in top toolbar), change the Grouping to by Type to have
Problems sorted by Model Errors and Rule Errors.
2.1.9. 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.
2.1.10. 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 object attributes. The inspector is
invoked via WindowInspector in the main-menu, or by pressing ALT+I .
Shape inspector showing the relevant attributes and parameters of the current selection
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.
The inspector not only supports editing of single objects but also a 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 collections of objects.
In addition, the inspector automatically groups object collections by type so that even for heterogeneous collections
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 overlay
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.
2.1.11. 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
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.

Toolbar and Status line
The top toolbar and the status line at the bottom can be shown or hidden individually.
Window Hide Toolbar
Window Hide Status Line
Hiding toolbar and status line gives a less cluttered view of the application and saves screenspace, which can be
helpful e.g. for presentations or demos.

Tasks:
1. Predefined Window Layouts
2. Editors
3. Views
4. Dragging Windows
5. Saving and Loading Window Layouts
2.1.11.1. Predefined Window Layouts
There are a several predefined window layouts available in CityEngine. Window layouts are also called
perspectives and are listed in the WindowLayout sub menu. Choose your preferred layout there.
Available Layouts
Default
Minimal
2 Views Horizontal
2 Views Vertical
4 Views
Standard Rule Editing
Compact Rule Editing
Layout Descriptions
The Default layout has one big perspective view and editors open useful for scene overview and management tasks
like import / export.
The Minimal layout has one big perspective view and some editors open only at the right. This makes it suitable for
presentations.
The 2 Views Horizontal layout is equal to the Default layout but has two views, a perspective at the top and a top
view at the bottom.
The 2 Views Vertical layout is equal to the Default layout but has two views, a perspective at the right and a top
view at the left.
The 4 Views layout is the classical CAD layout with one perspective view, a top, a front and a side view.
The Standard Rule Editing layout has one perspective view and leaves more area for the cga editor. This layout is
especially suited for editing rules and supervising the outcome.
The Compact Rule Editing layout has one perspective view and leaves more area for the cga editor. This layout is
especially suited for editing rules.
2.1.11.2. Saving and Loading Window Layouts
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.
2.1.11.3. Editors
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.
The editors provided by CityEngine are:
CGA shape grammar editor for editing .cga files
Scene editor for editing .cej files
Python editor for editing python scripts
A basic text editor for editing arbitrary text files

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
the CGA Rule Editor open, with 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.
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.
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.

Note: To quickly open a file in the associated editor, hit CTRL+SHIFT+R and type the name of the file you
are looking for.

2.1.11.4. Views
The primary use of Views is to provide navigation of the information inside CityEngine. For example:
The Model Hierarchy 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.
2.1.11.5. 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 :
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.
2.2. CityEngine Preferences
Export
General
Appearance
Editors
Grammar Core
Keys
Perspectives
Viewport
Bookmarks
Cameras
Light
Automatic Exit
Navigation Devices
Mouse
3D Mouse
Touch
Help
Network
ArcGIS Portal URL
Proxy
Scene
2.2.1. Export Preferences
Depending on your CityEngine license, not all options are available.
RealityServer
Parameter Function
RIB output library
Abs. path to RIB library
2.2.2. 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.
2.2.3. 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.
Colors and Fonts
Label Decorations
2.2.4. 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.
Additional Preferences
File Associations
Text Editors
Accessibility
Hyperlinking
Linked Mode
Quick Diff
2.2.5. Procedural Runtime Preferences
The Procedural Runtime preferences page controls various options with respect to rule derivation (model
generation), display, rendering, occlusion and miscellaneous engine arguments.
CGA Compiler
If "Write compiler output to console window" is enabled, the CGA compiler's activities are logged to a
console.
Generate
The maximum derivation depth controls the maximum recursion level of rules (createShape), or the
depth of the shape tree (model hirarchy), respectively.
The maximum derivation width controls the breadth of the shape tree (model hierarchy).
The maximum function call depth controls the maximum recursion level of function calls. This includes
attributes.
The disk cache size controls hom much disk space is used to cache decoded textures between starts of
the city engine. Using the disk cache might reduce memory consumption during runtime because
textures do not need to be decoded (and kept in memory) to find their metadata (scuh as aspect ratio
etc.).
Number of parallel generate threads: Use this to set the number of threads to be used to execute one
generate command.
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 (occluders); this means their models need to be derived for inter-
occlusion queries.
Display Options
Edges size: Defines the display size (thickness) of edges.
Vertices size: Defines the display size (diameter) of vertices.
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.
Trim plane size: Defines the display size of trim planes.
Rendering (affects only generated models)
Disable GL Mipmaps: Some hardware has problems using mipmaps and texture compression together.
If this is the case on your system you can disable GL mipmaps here..
Disable GL Texture Compression: By default, textures are compressed for rendering. This significantly
reduces the memory consumption (typically ratios between 1:6 and 1:4 are achieved, depending on the
texture format) and speed up rendering. However, the texture quality is slightly reduced.
Max texture width/height: Textures which are wider/higher than this value are rescaled to this value in
order to save memory.
Matching profile: Using this popup, you can control render performance versus memory consumption.
For most use cases, "Balanced" is a good choice.
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.
License
Timeout for license server connection in milliseconds.
Logging
Set the Procedural runtime log level: If set to a level less than 6, Procedural Runtime logs errors,
warnings etc. to a console.
2.2.6. 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
2.2.7. 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).
2.2.8. Viewport Preferences
Change appearance and behaviour of 3D viewports.
Parameter Function
Colors
Set various colors for scene elements
Animation time
Set time for camera animations (e.g. when triggering a camera bookmark)
Checkbox
Disable camera during camera navigation. Speed up camera navigation on heavier
scenes.
Line width
Set width for line rendering
2.2.9. Bookmarks
A camera bookmark has the following options:
Perspective: If selected, the camera will give a perspectively correct image. If not selected, the camera
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
Configuration: These values position and orient the camera. You can enter a world coordinate position
Distance to Point of Interest: This value corresponds to the distance between the camera and the POI.
rotation.
rotation.
2.2.10. Cameras
A camera configuration has the following options:
Perspective: If selected, the camera will give a perspectively correct image. If not selected, the camera
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
rotation.
rotation.
2.2.11. Light
Configure options for light source for 3D viewports. Options can also be set in the Inspector with the Light layer
selected.
2.2.12. 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, we suggests using the 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.
2.2.13. 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.
2.2.14. Touch Preferences
The touch preferences allow you to fine-tune the touch navigation in CityEngine.
2.2.15. 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.
2.2.16. Network preferences
Change network settings for Portal URL and Proxy.
ArcGIS Online or Portal
By default CityEngine connects to ArcGIS Online at www.arcgis.com. Set an URL to change the target portal for
sign in and for sharing CityEngine Web Scenes and Rule Packages.
Portal for ArcGIS on-premise installation.
e.g. https://webadaptor.domain.com/arcgis
Setting the URL to an ArcGIS Online organization
e.g. http://jsapi.maps.arcgis.com

HTTP Proxy
Define proxy settings for CityEngine network connections.
2.2.17. Scene preferences
Scene coordinate system
Set or redefine the scene coordinate system. See Georeferencing.
Modifying the scene coordinate system will NOT reproject or relocate the data in your CityEngine scene. It only
redefines the internally stored reference system used for future data imports.
Show handles
Enables or disables handles in this scene. Handles are shown on the currently selected model, if the rule file was
created with handles. See Handles.
2.3. Project Management
1. Why Project Management
2. Using CityEngine Projects
Creating a CityEngine Project
Creating a CityEngine Scene
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
Archiving or Exchanging CityEngine Projects
Exporting a Project
2.3.1. 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 a 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.
2.3.2. 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
2.3.2.1. 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.
2.3.2.2. 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.
2.3.2.3. 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, on which shape grammar rules can be applied. 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.
2.3.2.4. 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 wouldlike 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 wouldlike 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 with Browse.
In the Options area, options are given to:
Overwrite existing resources without warning.
Create complete folder structure (i.e., also create parent folders)
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.
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.
2.3.2.5. 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 also 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.
2.3.2.6. 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.
2.3.3. 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
2.3.3.1. 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.
2.3.3.2. 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 that will be transferred to the new workspace:
Workspace Layout: Opened views, their size, and selected perspectives.
Working Sets: The user defined working sets.
2.3.4. 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
2.3.4.1. Importing a Project into the Workspace
Depending on if the project you wish to use is zipped, or not, there are two options to import the project into your
workspace.
Importing an (Unzipped) Existing Project Folder
If the project is not zipped, you may import it using FileImport/Link Project Folder into Workspace...
In the dialog that appears, select the root folder for the project. This is the folder that contains the scenes, rules and
data folders. Select finish to import the selected project.
Importing Zipped Projects
To import a project file that has been zipped, select FileImport Zipped Project into Workspace... Select the zip
file in the dialog that appears. Select finish to import the zipped project.
Options
You can choose among the following import options for both types of project import:
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 (zip) 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.
This option is not available for zipped projects.
2.3.4.2. 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 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.
2.4. Map Layers
1. What is a Map Layer
2. Terrain
1. Aligning Terrain to Shapes
2. Exporting Terrains to geometry or image files
3. Texture
4. Other Map Layer Types
5. Editing Map Layers
6. Editing Layer Attributes
7. Selection via Image Maps
2.4.1. What is a Map Layer
Map Layers have two main functions:
1. Adding a map object to the scene using image data
2. Creating mappings of image data to various attributes
Two map layers: Terrain layer for the elevation mesh, and a texture layer for the water map
Map Layer Types
Terrain: The terrain layer creates a heightmap mesh as an elevation base for your scene, both for visual
appearance and to align objects.
Texture: The texture layer is used to simply create a flat background map in your scene.
Obstacle: With an obstaclemap you control the areas where the street grow algorithms will work. An
obstaclemap as any other attribute layer that evaluates to a Boolean (true/false) value can also be used
for selection of a range of objects.
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.
Function: An arbitrary mathematical function that can be used for controlling a rule attribute.
2.4.2. Terrain Layer
The Terrain Layer is a special map layer that visualizes the elevation of the scene topography using image
data. It also serves as reference elevation for align operations for scene objects such as shapes or graph nodes.
Creating a Terrain Layer
A terrain layer can be created in the following ways:
1. An image is dragged from the Navigator into the scene
2. A Terrain is imported with File Import... Terrain Import
3. A new Terrain layer is created with Layer New Map Layer... Terrain
These actions trigger the Terrain Dialog

Terrain Dialog

Heightmap File: Choose an image from your workspace which will be used as heightmap mesh / Digital Elevation
Model. Normally this is a greyscale image. When a georeferenced image is selected, elevation and bounds are set
automatically.
Texture File: Choose an image from your workspace which will be used to texture the heightmap mesh. Normally
this is a greyscale image. When a georeferenced image is selected, elevation and bounds are set automatically.
The texture file is applied over the exact extent of the heightmap mesh. It is therefore crucial that your texture
file has the same extent as the heightmap file.
Channel: Choose the source channel from the image that is used to read the data for the elevation. For most
images brightness is the best choice.
Min. elevation: The minimum value / the lower bound for the elevation in meters. For specific images this value is
read automatically from the file.
Max. elevation: The maximum value / the upper bound for the elevation in meters. For specific images this value is
read automatically from the file.
Bounds SIze: The Width and Height of the resulting terrain in meters. When a georeferenced image is selected, this
value is set automatically.
Bounds Offset: The location of the resulting terrain in meters. When a georeferenced image is selected, this value
is set automatically.
Note that the button left of X-Offset can be used to change the reference point for the terrain's position.
16-bit and 32-bit images are supported for heightmap files. The 16/32-bit range is scaled to the elevation
bounds similar as it is done with standard images.
Due to the fact that the images displayed in CityEngine all need to fit in the graphics card memory, it is highly
recommended to use as small images as possible. CityEngine will restrict resolutions to a max of 4000x4000
pixels per image.

Terrain Layer in CityEngine scene
The new terrain is added as a new layer in the scene editor. If the terrain is not visible in the 3D viewport, right-click
on the terrain layer and choose Frame Layer .
Terrain layers (like all map layers) can not be selected in the 3D viewport directly, but only via scene editor.
A terrain layer in the Scene Editor
Terrain with wireframe alpha enabled
Setting terrain parameters in the Inspector
To change the parameters of a Terrain, select the terrain layer in the scene editor, and look for its parameters in the
Inspector.
Map Layer attributes

The map layer attributes of a terrain layer in the inspector.
Attribute Function
Name Layer name
Visible Layer visibility
Color Color value multiplied onto layer
Alpha Transparency of the layer
Elevation Offset Elevation Offset applied to the layer
Bounds
Size The extent of the layer
Offset The location of the layer

Terrain-specific attributes

The terrain 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.
Value filtering The filtering applied to terrain height and sampling. Choice of either none (pixelated), or
smooth (linear) filtering.
Texture The texture image overlayed over the terrain mesh
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.
Further Reading
Align Graph to Terrain
Align Shapes to Terrain
Align Static Models to Terrain
Align Terrain to Shapes
Georeferenced Image Data
2.4.2.1. 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 aligns 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
attributes.
If enabled, for each selected shape cut/fill volumes are approximately calculated. The
values are written 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.
2.4.2.2. 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).
2.4.3. Texture Layer
The Texture Layer is a special map layer that adds an image as a flat map to the scene.
Creating a Texture Layer
A texture layer can be created in the following ways:
1. A Texture is imported with File Import... Texture Import
2. A new Texture layer is created with Layer New Map Layer... Texture
These actions trigger the Texture Dialog

Texture Dialog

Texture File: Choose an image from your workspace which will be used to texture the heightmap mesh. Normally
this is a greyscale image. When a georeferenced image is selected, bounds are set automatically.
Bounds SIze: The Width and Height of the resulting texture in meters. When a georeferenced image is selected,
this value is set automatically.
Bounds Offset: The location of the resulting texture in meters. When a georeferenced image is selected, this value
is set automatically.
Note that the button left of X-Offset can be used to change the reference point for the texture's position.

Texture Layer in CityEngine scene
The new texture is added as a new layer in the scene editor. If the texture is not visible in the 3D viewport, right-click
on the texture layer and choose Frame Layer .
Texture layers (like all map layers) can not be selected in the 3D viewport directly, but only via the scene
editor.
A texture layer in the Scene Editor
Texture layer in 3D viewport
Setting map parameters in the Inspector
To change the parameters of a map, select the map layer in the scene editor, and look for its parameters in the
Inspector.
Texture Layer attributes

The texture layer attributes of a texture layer in the inspector.
Attribute Function
Name Layer name
Visible Layer visibility
Color Color value multiplied onto layer
Alpha Transparency of the layer
Elevation Offset Elevation Offset applied to the layer
Bounds
Size The extent of the layer
Offset The location of the layer
Map The texture image.
Value filtering The filtering applied to the texture. Choice of either none (pixelated), or smooth (linear)
filtering.

Further Reading
2.4.4. Map Layer Types

1. Terrain
2. Texture
3. Obstacle
4. Mapping
5. Function
2.4.5. Editing Map Layers
After selecting a map layer in the scene window, the Inspector allows you to edit map layer parameters.
Parameters of a map layer displayed in the Inspector
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 the '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 Map Layer Functions.

Moving and Scaling Map 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.

Using the scale transfrom tool to rescale a map layer
2.4.6. Editing Map Layer Attributes
Map layers can have their own attributes. These are defined in the Layer Attributes pane of the Inspector, with
the Map Layer selected.
Map 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.
A typical expression of an elevation attribute for a terrain layer
There are two predefined attributes that will be used for street generation and other generative parts of CityEngine:
attr elevation controls the elevation of the heightmap of a terrain layer.
attr obstacle controls the obstacle avoidance of the street generation.

Examples for function layer attributes:
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 =
case u > 0.5:
50%: "industrial"
else: "retail"
else:
"residential"
Define a string attribute that can be used by a CGA
shape grammar rule to control e.g. building appearance.

Layer Attribute Code in Detail
Map 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 has the
coordinates (0, 0) and the upper right corner of the map has 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 (centroid) to the x-z plane.
In the following illustration, the attribute "x" is evaluated at the center of gravity (centroid) 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".
See also
Connection Editor
Mapping Object Attributes via Layer Attribute
Mapping Image Data to Rule Attributes
Attributes and Sources
2.4.7. Selection via Image Maps
If you need to work with selections depending on an map 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 10 meters or higher. Simply add a new attribute that
evaluates to true when elevation is bigger than 10.
attr high = elevation > 10
The new attribute elevation in the terrain layer
Boolean attributes in map layers are automatically added to the selection menu. Right-click in the viewport (or
choose from the top menu),
Select Select Objects in Map Layer terrain: high
The new attribute high is displayed in the selection menu
The resulting selection is shown in the image below:
Shapes above 10 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 map layer with the landusemap, 3 new boolean 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
Shapes in the commercial area are selected
Selection using the u,v coordinates of a map 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 map layer:
attr isIndustrial = landuse == "industrial"
attr isRetail = landuse == "retail"
attr isResidential = landuse == "residential"

This will give you the following additional selection possibilities in the context menu:
2.5. Shapes
1. What are Shapes
2. Creating and Editing Shapes Manually
Subdividing Static Shapes
Shape Texturing Tool
3. Creation of Shapes from Graph Networks
Block Parameters
Street Parameters
Intersection Parameters
Street Shapes
Street and Intersection Shape UVs
Edit Street Tool
4. Importing Shapes
5. Exporting Shapes
2.5.1. 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 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 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.
2.5.2. 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.
Polygonal Shape Creation
Select the Polygonal Shape Creation tool. Click into the viewport to create the first vertex, further clicks create
additional vertices. To finish the shape, you can either click on the first vertex or perform a double click.
Alternatively, press ESC to cancel or Enter to finish drawing.
Simple snapping: By moving the cursor over existing shapes or the terrain you can snap the position to those
objects. A orange rectangle is shown around the cursor when snapping is active. Additionally the snapped
component is highlighted. Snapping can be prevented by hiding layers or using the isolation mode.
Snapping to features: After the first click, multiple snapping features are enabled. These include: Global axes, 90
degree angles, parallel lines, extensions of lines and line midpoints. All snapping features are automatically
intersected to form combined snapping results. While moving the mouse, a orange dashed line is shown whenever
snapping to such a feature occurs. Additionally, symbols are shown to differentiate the features:
Types: (a) global axis or line extension (b) 90 degree (c) parallel (d) midpoint (e) vertex (f) combined
Splitting shapes: When the first and last vertices are snapped to an edge or vertex of the same polygon, and the
whole line is contained in this polygon, the polygon is automatically split into two parts. Here is an example:
Start by creating a simple shape. Then move the cursor over the left edge until it is highlighted in orange, indicating
snapping. Click to create the first vertex, then click another few times in the polygon for further vertices. Snap to the right
edge, and click again, to split the shape.
Automatic closing: When the first point snaps to a shape, and the last point snaps to a line that is indirectly
connected to the first point, the polygon is automatically closed along the indirect connection, as shown here:
Combine versus Add: By default, when you snap to a existing shape while creating a new one, the new shape is
automatically merged with the existing shape. To prevent this, an create separate shapes instead, hold the SHIFT
key while drawing the shape.
Text entry: Click on the numerical input, enter three values and press ENTER . This creates the first point at those
coordinates. You can now move the mouse, the text field shows the length of the line. While moving the mouse, you
can directly start typing, without clicking on the text box, to enter a length or another coordinate. When you enter
one value and press ENTER , the current line is colored magenta, and the length is fixed at this value. A click or
ENTER creates another point, ESC returns to a unrestricted mouse move. Entering three values and pressing
ENTER immediately creates a new point.
3D Shape Creation
Select the Polygonal Shape Creation, and hover over existing polygons. A orange sphere handle is shown centered
on the hovered polygon. Dragging the handle (click and hold the button while moving) creates 3D shapes. When
you release the mouse button, the 3D shape is finished. While dragging, snapping is performed to nearby vertices.
Depending on the shape, multiple arrows can appear. This allows you to create shapes along different directions.
Simply hover the mouse over the desired direction arrow for immediate feedback. There are 4 different types of
directions: 1. global y axis (up) 2. face normal 3. face normal projected on the ground plane 4. special directions
adjacent faces. All directions have a unique color and mouse icons, as shown here:
From left to right: global y axis (up), face normal, face normal projected on the ground plane, special directions adjacent faces
In the 4th case, all edges are extended along their adjacent face while dragging. When the 4th case has the same
direction as another arrow, the arrow is displayed with a slight offset. Here is an example of the difference between
up and special edge direction dragging:
When the shape on the left is dragged along the green arrow, the middle shape is created. However, along the blue arrow, the
right shape is created, extending the adjacent faces.
Force Edge Creation: To force the creation of new edges when starting a 3D drag operation, press the CTRL key.
Draw on handle: If you want to create a line on a position obscured by a handle, hover the mouse for three seconds
over the handle. This causes the handle to disappear, allowing you to draw on this position.
3D Shape Editing
All the previously introduced polygonal operations can also be performed on 3D shapes: Snapping, splitting and
automatic closing. Splitted parts can be moved to further refine the 3D model. Here is an example consisting of a
split, 3D move, another split and move is shown:
3D Edge Move
Select the Polygonal Shape Creation, and hover over existing edges. This shows a orange handle, allowing edge
movements. As with the face dragging, after a click and drag, multiple directions can be shown. These include: 1.
global y axis (up) 2. along adjacent faces 3. along average face normal. Here is an example:
From left to right: Edge move along global y axis, adjacent faces and average face normal.
While moving edges, connected faces are intelligently updated to maintain planarity. Furthermore, the moved edge
is intersected with neighboring polygons. Both features are very useful for creating roofs, as shown here:
Moving one edge automatically updates all orthogonal faces along the connected edges.
Moving the edge along the green axis automatically insets the edge along the existing roof.
Rectangular Shape Creation
Select the Rectangular Shape Creation tool. Click to define the first corner. Move the mouse to preview the resulting
rectangle. A second click then creates the rectangle. This tool behaves very similar to the polygon tool. It supports
automatic splitting, snapping, combine vs. add mode and 3D editing. A convenient feature is the automatic
alignment to edges: When either the start or the end point snaps to a edge, the rectangle is aligned to match this
edge. The following figure shows an example:
From left to right: Create a rectangle using two clicks. Hovering the mouse shows a sphere handle. Dragging this handle
creates a 3D shape. When you snap to an edge, the rectangle is aligned. A further drag operation refines the shape.
Text entry: Click on the numerical input, enter three values and press ENTER . This creates the first point at those
coordinates. You can now move the mouse, the text field shows the dimensions of the rectangle. While moving the
mouse, you can directly start typing. When you enter two values and hit ENTER , a rectangle with this dimensions
is created. If you enter three values and press ENTER , the second point of the rectangle is created at those
coordinates.
Shape Component Manipulation
The following operations directly work on the components of shapes: Polygons (faces), vertices and edges. They
can be used to clean up imported shapes, separate or combine shapes.
Separate Faces
Select a shape, and click Separate Faces. This creates an individual shape for every face. All new shapes are put in
the layer of the original shape.
Combine Shapes
Select multiple shapes, and click Combine Shapes. This creates one shape containing all components of the
selected shapes.
Cleanup Shapes
This tool cleans the geometry of selected shapes. It is very useful to prepare imported meshes for 3D editing.
The 3D editing works best after cleanup is performed, as this ensures correct connectivity information in the
mesh. If you ever encounter problems with 3D editing, try a cleanup operation with the default values.
The Cleanup Shape window with it's cleanup settings
The individual operations are performed in the direction indicated by the dialog, and work as follows:
Merge Vertices: If the distance between two vertices is lower than the threshold, they are combined into
one.
Remove Coplanar Edges: Merge connected coplanar polygons.
No Cleanup on Discontinuous Textures: When the texture coordinates are not continuous for a vertex,
the all operations are skipped for this vertex.
Remove Colinear Vertices: Multiple vertices on one straight line are removed.
Remove Double Faces: Faces with similar vertices are removed.
Remove Zero Faces: Faces with zero size are removed.
Intersect Edges: All edges are intersected, and new vertices are inserted for every intersection point.
Split Coplanar Polygons: Overlapping polygons on the same plane are split along all edges into multiple
non-overlapping polygons.
Distance Tolerance, Angle Tolerance: Tresholds for the above operations.
Example of the Cleanup Tool in action, removing colinear vertices
Further Manipulation Operations
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)
Compute First/Street Edges . This operation automatically calculates the first and street width attributes of the
selected shapes. It works as follows: First it finds the nearest street (within 100m) for every edge of a shape. The
corresponding street width attribute is set to the width of the nearest street. The edge closest to a street is set as the
first edge (edge 0).
Convert models to shapes In order to manually edit CGA generated models, they have to be converted to shapes
first, using this command. Note that after this conversion, changes in attributes and CGA rules do not affect the
shapes anymore.
2.5.2.1. Aligning Shapes to the Terrain
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 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 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.
2.5.2.2. 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:
Details on the parameter values can be found on the block subdivision page.
2.5.2.3. Static Shape Texturing
This tool is used for the manual texturing of shapes and individual faces. For the exact texture mapping,
several modes are available. You can open the tool by drag and dropping an image file from the file navigator
onto shapes, by selecting ShapesTexture Shapes... or by starting the tool from the tool bar
.
Once opened, the tool dialog stays in front of other CityEngine GUI elements, for convenient working.
The Texturing Tool provides a simple and interactive means for texture assignment
Choose a Texture Image
The image the user wants to use as a texture, may be chosen as follows:
Select the Browse/pick... button and browse to the file within the project. The upcoming dialog also
shows (at the bottom) a list of images which are already used in the current selection.
Select or drag-and-drop in an image file from the File Navigator.
Adjust Orientation
Correct the image orientation by the following three options in 'Image Transformation' group:
Rotation: None | 90 counter clock wise | 180 | 90 clock wise
Flip horizontally
Flip vertically
Mapping Mode
(see bottom of page for examples)
There are four modes with according attributes for the texture coordinate mapping, which are specified in the
'Texture Coordinates Mapping' group:
Keep current mapping
Leaves the currently set mapping (no attributes).
Stretch to polygon
This mode is used for stretching the texture across the selected face. Note that if entire shapes are selected, the
texture is stretched across all present coplanar face groups.
Align to: Bottom left corner | Bottom right corner | Top left corner | Top right corner (has only an effect if
one of the repetition numbers is not a whole number).
Horizontal repetitions: number of times the texture is repeated horizontally (decimal number allowed).
Vertical repetitions: number of times the texture is repeated horizontally (decimal number allowed).
Dimension
This mode allows the user to set the actual dimension of the used texture.
Align to: Bottom left corner | Bottom right corner | Top left corner | Top right corner
Absolute texture width: given in meters.
Snap horizontally to bounds: stretches the given texture's width such that it horizontally fits the selected
face with a whole number of repetitions.
Absolute texture height: given in meters.
Snap vertically to bounds: stretches the given texture's height such that it vertically fits the selected face
with a whole number of repetitions.
Projection
This mode is used for the texturing with an aerial image and is always projected from the top. If the image is
georeferenced, it is positioned and stretched accordingly.
Scene Selection Issues
The Texturing Tool acts a little differently depending on the scene selection (colored blue):
Single or multiple face selection: The texture is individually applied to each selected face.
Single or multiple shape selection: The texture is individually applied to each group of coplanar faces
within the selection.
Examples

Stretch to Polygon: using 1.8 horizontal repetitions, 1.3 vertical repetitions with Align to Top left corner

Dimension: using Absolute texture width 5.75, Absolute texture height 8.0, Align to Bottom right corner - and: Snap
horizontally to bounds, so the texture fits exactly three times.
2.5.3. 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, street 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 intersection shapes, see Intersection Parameters
The default start rules for the shapes generated by nodes and segments are specified by their shape
types, see Street and Crossing Shapes
Alternatively, the Street Tool can be used to edit street widths or setup curve handles.
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
Intersection 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 and texturing. For details of the UV
coordiantes, see Street and Intersection Shape UVs.
An example of generated uv coordinates.
2.5.3.1. Block Parameters
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.
Block Parameters can be individually set for each block.
Attributes can be mapped to Default, User, Object or to a map layer. See Mapping Attributes for details.
General Parameters
These parameters are available to all subdivision types.
Parameter Function
shapeCreation If true, shapes are created from the street network.
type The subdivision algorithm to use, as illustrated below.

Recursive
Subdivision creates rectangular lots by repeatedly
splitting the block.
Offset Subdivision creates lots only
within a given distance from the street
edges of the block.
Skeleton Subdivision creates street-aligned lots that
always have access.
No Subdivision doesn't perform
subdivision on this Shape.
alignment This parameter is only used if the initial shapes are uneven. This sets the alignment of the
lot over the terrain. There are four numeric options, as illustrated below.
Valid values are [0,1,2,3]

0.
Uneven. The lots follow the terrain, given
uneven heights. .

1.
Minimum. The lots lie at their lowest point of the
terrain that they cover.

2.
Maximum. The highest point of the lot is
used.

3.
Average. The average height of the lot is used.
seed An integer seed to control randomness.
Specific Parameters
Recursive Subdivision
The recursive subdivison technique is the default. It subdivides the block into rectangular lots of various sizes.
Parameter Function
lotAreaMin
lotAreaMax
The lower and upper bounds of the area of lots obtained after subdivision.
Given in absolute area units
Subdivision obtained for smaller lotAreaMin
and lotAreaMax values.
Subdivision obtained for larger lotAreaMin and
lotAreaMax values.
Subdivision obtained when the difference
between lotAreaMax and lotAreaMin is small.
Subdivision obtained when the difference
between 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
Subdivision obtained for a smaller lotWidthMin
value.
Subdivision obtained for a larger lotWidthMin
value.
irregularity The relative deviation of the split line from the middle point of the center of the 'oriented
bounding box' (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]
Subdivision obtained for an Irregularity value
close to 0.
Subdivision 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.
Subdivision obtained for a forceStreetAccess
value close to 0.
Subdivision obtained for a forceStreetAccess
value close to 1.0.
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.
Subdivision obtained for a smaller cornerWidth
value.
Subdivision 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
Subdivision obtained for a smaller cornerAngle
value.
Subdivision obtained for a larger cornerAngle
value.
Offset Subdivision
A block which uses offset subdivision is offset to create a fixed width strip along the street edges, which is then
subdivided into lots.
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.
Subdivision obtained for a smaller offsetWidth
value.
Subdivision obtained for a larger offsetWidth
value.
subdivisionRecursive After the offset routine, there is an option to also run the recursive subdivision on the
result. This is controlled by the same set of parameters as the recursive subdivision
scheme.
lotAreaMin
lotAreaMax
lotWidthMin
irregularity,
forceStreetAccess,
cornerWidth,
cornerAngleMax
See above.
Skeleton Subdivision
Skeleton subdivision attempts to subdivide a block such that every lot has access to the street. The sides of the lots
are perpendicular to the roads they are adjacent to.
Parameter Function
lotWidthMin The ideal length of street front that each lot should possesses. This is increased or
decreased by several other processes. A low lot width relative to the block size may create
many narrow lots.
Subdivision obtained for a lotWidthMin value of
15.
Subdivision obtained for a lotWidthMin value of
30.
sliceSearchDist This value represents a choice between lots with regular edges perpendicular to the roads
(a value of 0.0), or fewer verticies in the output (a value of 1.0). When the block is sliced
into lots, this parameter determines how far we search as a fraction of the lot width.
Subdivision obtained for a smaller
sliceSearchDist value.
Subdivision obtained for a larger
sliceSearchDist value.
cornerAlignment Skeleton subdivided lots face their nearest streets. At the corner of two streets, one will
normally take priority. The corner alignment determines how this priority is assigned, either
by Street length or by Street width.
Street width: the widest street takes priority. If
the streets have similar average widths, the
street length is used instead.
Street length: the longest street takes priority.
lotAreaMin After subdivision, lots with a small area are repeatedly combined with their neighbours until
they are larger than this minimum. This reduces the number of smaller lots, but may create
lots of more irregular shape.
Given in absolute area units
irregularity As this parameter increases, it introduces a stochastic element into the lot width and lot
edge direction.
Subdivision obtained for a smaller irregularity
value.
Subdivision obtained for a larger irregularity
value.
No Subdivision
This simple subdivision technique subdivides the block into a single lot of the same shape. There is an option to
remove the lot's corners.
Parameter Function
cornerWidth, See above.
cornerAngleMax
Advanced
Description of Algorithms
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.
Skeleton subdivision algorithm
The skeleton subdivision algorithm uses the straight skeleton (below, top left) to identify the center lines of the block.
Given a set of skeleton faces, we identify those whose street edges are adjacent and of a similar curvature (below,
top right). These faces are then grouped together. For each corner, the alignment priority (see cornerAlignment)
determines how we assign the corner sections of these face-groups (below, bottom left). Finally each of the face-
groups are sliced in a direction perpendicular to their street edges to create lots, and small lots are merged together
until they are larger than lotAreaMin.
Successive steps of the skeleton subdivision algorithm
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.
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 generated street width object attributes in the inspector.
The first edge of a lot is the edge with maximal street width.
2.5.3.2. 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
The following parameters are available for the user to control the resulting street shapes:
General Parameters
Parameter Function
shapeCreation If true, shapes are created from the street segment.
Street Width and Offset Parameters
Parameter Function
streetWidth Defines the width of the main street shape.
streetOffset Defines the distance the geometry will be offset from the center line.
sidewalkWidthLeft Defines the width of the left sidewalk.
sidewalkWidthRight Defines the width of the right sidewalk.
sidewalkWidthRight Defines the width of the right sidewalk.
Precision Parameter
Parameter Function
precision Graph nodes are interpolated using Bezier splines, resulting in curved streets. This
parameter defines the spline sampling precision, i.e. 0 leads to a minimal and 1 to a
maximal number of spline sampling points.
Lane Width Parameter
Parameter Function
laneWidth Determines the width of lanes used for UV texture mapping of streets.
Street widths are given in absolute length units, precision is given in a normalized [0, 1] range.
Auto-generated connection attributes
Connection attributes provide basic information about the underlying graph and give context information. CGA rules
may want to access the following attributes.
Left: A street shape selected in the viewport. Right: The generated connection object attributes in the inspector.
Parameter Value
connectionStart Hints as to the adjacent geometry at the start or end of a street segment shape. Values
include: STREET, CROSSING, JUNCTION, JUNCTION_ENTRY, DEAD_END,
FREEWAY, FREEWAY_ENTRY and ROUNDABOUT
connectionEnd
sidewalkSide Which side of the street this Sidewalk shape is on, relative to the street direction: either
Left or Right. SidewalkSide is only added to sidewalk shapes.
Connection attributes are object attributes of the graph segment and are inherited to the shape. Note the italic
font in the shape's inspector.
2.5.3.3. Intersection Parameters
Intersection Parameters can be individually set for each graph node.
The parameters for Intersection Shape creation can be specified through the intersection parameter panel in the
inspector.

Parameter panel for intersection shape creation
Several parameters are available for the user to control the resulting intersection shapes. Intersection parameters
define the type of the intersection (crossing, junction, roundabout, freeway or smart) and specify geometry details
like the radius of the arcs for instance.
General Parameters
Parameter Function
shapeCreation If true, shapes are created from the graph node.
type Specifies the type of the intersection. Crossing, junction, roundabout or freeway. Smart
automatically chooses between these types.
Crossing
Junction
Roundabout Freeway
Common Parameters
Parameter Function
precision Specifies the level of detail.
Value must be in the range [0, 1].
Crossing shapes with precision = 0.1. Crossing shapes with precision = 0.3.
minArcRadius The minimal arc radius. For freeways a higher value (>20) is better suited.
Given in absolute length units.
Crossing shapes with minArcRadius = 0. Crossing shapes with minArcRadius = 5.
cornerStyle Either Arcs or Straight. When set to the latter, blocks get simpler.
Border
with cornerStyle set to Arcs.
Border
with cornerStyle set to Straight.
angleThreshold Minimum angle between streets before they automatically start bending to avoid each other. It is
ignored for freeways.
Crossing with angleThreshold set to 30. Note the streets
bending to avoid each other.
Crossing with angleThreshold set to 10.
Roundabout Parameters
In addition to the above parameters, roundabout creation uses the following values:

Additional parameters for roundabout creation
Parameter Function
innerRadius Defines the radius of the inner circle (the so-called island shape).
streetWidth Defines the width of the roundabout street lane.
A
roundabout with innerRadius = 5 and streetWidth =
10.
A
roundabout with innerRadius = 10 and streetWidth =
5.
Both values are given in absolute length units.
Principle Street Selection
The junction and freeway intersection types make use of the principle street to determine the intersection geometry.
The principle street does not alter the smart junction behaviour.

Left: Two junctions with different principle streets. Right: Two freeway intersections with different principle streets. In each
case the principle streets are drawn in a darker shade of grey.
The principle street is specified using either the street tool, or by setting the object attribute principleStreetStart
or principleStreetEnd on adjacent streets as appropriate.
Examples
Simple curve
Valence-two nodes (nodes between 2 graph segments) usually lead to curves or links between the segments.

A simple curve.
For valence-one (nodes at the end of a row of segments / cul-de-sac)or valence-two nodes it does not matter
whether the type is crossing or junction.
Dead end street
By setting the type of a valence-one node to roundabout, one can model a so-called cul-de-sac.

A dead end or so-called cul-de-sac.
Junction
Junctions, as opposed to crossings, don't break a major street. Minor streets are connected to the major street by
junction entries.

A simple junction with two junction entries (left and right).
The two segments with the maximal street widths are automatically treated as major street.
Auto-generated connection attributes
Connection attributes provide basic information about the underlying graph and give context information. CGA rules
may want to access the following attributes.
Parameter Value
valency The number of street segments adjacent to a street node. Valency is added to all
intersection shapes.
sidewalkSide Which side of the street this Sidewalk shape is on, relative to the street direction: either
Left or Right. SidewalkSide is only added to Sidewalk shapes.
Connection attributes are object attributes of the graph node and are inherited to the shape. Note the italic font
in the shape's inspector.
2.5.3.4. Street and Crossing Shapes
Default Start Rules
Street and intersection shapes generated within the CityEngine consist of different shape types. Each shape type is
defined by its start rule.
Standard start rules are: Street, Sidewalk, Crossing, Junction, Freeway, FreewayEntry, Roundabout,
RoundaboutIsland, and Joint.
The shape types are illustrated in the following figure.
An example street network (above), and default shape types (below).
Color Shape start rule Created by
Street Street
Sidewalk Street, and all intersection types
Joint Intersections with only 2 adjacent streets
Crossing Crossing or Smart intersections
Junction Junction or Smart intersections
Freeway Freeway or Smart intersections
FreewayEntry Freeway or Smart intersections
Roundabout Roundabout or Smart intersections
RoundaboutIsland Roundabout or Smart intersections
Note: Shapes have by default no rule file assigned. Therefore, if you like to work with these default start rules
you have to define the CGA rules "Street", "Sidewalk", "Crossing", "Junction", "Freeway", "FreewayEntry",
"Roundabout", "RoundaboutIsland", and "Joint". These rules will be the starting point for geometry generation.
Street Shape UV Values
For details of the UV coordiantes, see Street and Intersection Shape UVs.
Reset Shape Attributes
Since start rules can be overridden, users may want to use the Reset Shape Attributes tool to revert the start rules
to the default values. To execute the tool, select a set of shapes and then choose GraphReset Shape
Attributes from the main menu.
Conflicts
Because the internal shape creation algorithm computes the intersection shapes for each node individually, conflicts
can occur. Usually, conflicts occur when the distance between two nodes is very small. In this case, at least one
node is located inside the shape of a neighbor node.
Conflicting segments are marked with a red dashed line. The error color can be changed in the Viewport
Preferences.
There is a conflict (red dashed line) because a street node is
inside a crossing.
The conflict has been resolved by running the Graph
Cleanup Tool.
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 parameters (i.e. street width), see Street Parameters and Intersection
Parameters.
Use the Street Tool to edit curves, change street widths or move nodes.
Which action to choose depends on the required level of control. It's a tradeoff between automation and quality of
the result.
2.5.3.5. Street and Intersection Shape UVs
UV coordinates are generated for each shape. They can be used for UV Splits and texturing. Up to three UV sets
are supplied for each shape to describe different surface parameterisations.
An example of generated UV coordinates for street, intersection and lot shapes
Street UVs
There are three sets of UVs for street shapes.
Street UV Set 0
The first UV set provides a set of street lanes. The central region of the geometry is normalised along its length from
0 to 1, and across its width by 0 to the number of lanes. The number of lanes is specified by the street parameters.
In the below images we see a street shape between a crossing (bottom) and roundabout (top). The left image
illustrates the U values using shades of grey, while the right image illustrates the V values.
An example of street UV set 0 coordinates
The entry and exit of a street shape are parameterised to blend with the central region. For example the entry
(above, blue) and exit (green) u-values are oriented and scaled to match the central region (red). The entry has
negative U values, and the exit has U values greater than 1.
Street UV Set 1 and 2
UV Sets 1, and 2 provide distance fields from the start of the entry, and end of the exit respectively. This information
is provided in the U channel. The V channel is undefined. In the below image the street direction is from the bottom
to the top, and shows the orientation of UV Set 1 (left) and UV Set 2 (right).
An example of street UV set 1 and 2 coordinates
Sidewalk shapes UV Set 0
The sidewalk shapes only provide a UV set 0. This is stitched to the street-side edge of the geometry; all street-
adjacent edges have v values of 0.
An example of sidewalk UV set 0 coordinates
Intersection UVs
Intersection shapes that are street-like use the same UV set 0 parameterisation as streets, without entries or exits.
These shapes are Joint, Junction, Roudabout, Freeway and FreewayEntry. In general intersection shapes do not
have other UV sets, with the exception of FreewayEntry.
Similarly, intersection sidewalk shapes use the same UV set 0 parameterisation as street sidewalk shapes.
The remaining shapes use a rectilinear projected UV set 0. These shapes are RoundaboutIsland and Crossing.
Freeway Entries
Freeway entries supply a UV set 1 to identify the "inside" edge shape that adjoins another street shape. The edge V
= 0 is always on the inside of the freeway intersection.
An example of UV set 1 on freeway entry shapes
2.5.3.6. Edit Street Tool
The Edit Street Tool offers intuitive handles to graphically edit street width, sidewalk width and overall
curvature.
Entering the Edit Street Tool
To enter the Edit Street Tool, activate the Edit Street Tool Button in the Toolbar (above the Viewport). You can also
enter the Edit Street Tool by hitting the c key shortcut or using the menu Graph Edit Streets/Curves .

Entering the Street Edit Tool
If you can not find the button, the Toolbar may be hidden --> Window / Show Toolbar.
Straight vs. Smooth
Streets can be created either straight (default) or smoothly curved. To quickly toggle between the two states, use
the Graph Set Curve Straight and Graph Set Curve Smooth commands in the 'Graph' Menu or in the
Right Mouse Button Context Menu.

Straight vs. Smooth segment interpolation
To automatically choose between those types, you can use Graph Curves Auto Smooth... . Here you have two
parameters: Threshold angle determines the minimum angle for curve smoothing. When Horizontal optimize is set,
streets in front of slopes are set to straight, in order to prevent oscillations.
Street Editing
Once the Graph Edit Streets/Curves tool is activated, handles are displayed for selected streets or nodes.
There are two types of handles : Curve handles and street width handles. When a single node is selected, only the
curve handle is shown. When a single street is selected, a combined curve and street width handle is displayed.
When selecting multiple streets, only the street width handle is shown.

Left: Curve hadle. Right: Curve and street width handle.
In order to lock the direction, hold the SHIFT key before dragging a curve handle.
Curve Handles
Each graph segment has two curve handles, one attached at the start and end nodes of the segment. The green
handles drive the start and end direction of the street. The yellow circle allows moving the node. The dashed blue
line (which is only visible when the mouse hovers over one of the curve handles) indicates the local weight of the
curve.
For Advanced users: The spline is mathematically defined by the two end points of the dashed blue lines, plus
the segment's start and end points.
To edit either the horizontal or vertical components of a curve handle, the user just needs to change the viewing
angle relative to the segment node. A steep angle lets the user edit the horizontal component, a glancing viewing
angle the vertical component.

Editing horizontal or vertical handle components depending on the viewing angle
The green circle of the curve handle indicates the smoothing type of the node (smooth, straight or manual direction).
Clicking on a green circle while holding CTRL toogles between types.

Indication of node type in green circle: (left) smooth with automatic directions (middle) straight (right) smooth with manual
directions
The segmentation of the street shapes defines the segmentation of the neighboring lot shapes. Thus, the user
should keep an eye on the overall number of segments per curve to avoid issues such as e.g. narrowly
subdivided facades.
Principle Street Handles
When an intersection has the type Freeway or Junction, and has three or more connecting streets, the curve
handles are accompanied by principle street handles. These allow the principle street at an intersection to be edited,
changing the intersection geometry.

Dark green principle street handles (above, left) indicate that the default principle street will be chosen. Once a principle
street is specified manually, the handles are coloured light green (right).
Specify the desired principle streets by dragging a principle street handle from one street to another.
Dragging any principle street handle into the yellow circle with clear the principle street at the intersection,
resulting in the default behaviour.
Street Width Handles
Editing the different dimensions of a street can easily be done with the StreetWidth handle. The width of the street
shape plus the widths of the right and left sidewalks can be driven individually by dragging the small green
rectangles. Symmetrical adjustments are performed by holding SHIFT while dragging. The big green rectangle is
the combined width handle. Dragging it changes street width and sidewalk width simultaneously.
StreetWidth Handle. Left: When zoomed in, sidewalk and street handles and a combined width handle is shown. Right:
Zoomed out, only the combined width handle is shown.
Street width parameters can be set numerically as well in the street parameters.
2.5.4. 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 GDB
6. Import Shapes from OSM
2.5.4.1. Creating and Preparing Polygons for Shape Import
Beside the option to automatically create lots from street networks, lots can also be imported into the CityEngine.
Typically this 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 an option to apply a uniform scaling of the imported data.
In addition, the remarks about asset formats for the insert shape operation also apply here.
2.5.4.2. Importing Data 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. Additionally, a little preview from all sides is provided.
Import Settings
OBJ import has a few options as listed below.
File
Press Browse... to open a file dialog to select an .obj file to import.
Import as static model
When checked, the file will be imported 'as is' and will not be modifiable by cga rules.
Scale
Size factor applied to the imported object.
Offset
Adds the specified offset to the imported object.
Center Sets the offset such that the object is centered on the scene's origin.
Reset Sets the offset back to zero.
2.5.4.3. Importing Data from COLLADA DAE
Collada DAE
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 a few options as listed below.
File
Press Browse... to open a file dialog to select an .dae file to import.
Import as static model
When checked, the file will be imported 'as is' and will not be modifiable by cga rules. Otherwise, Start Shapes will
be created from the provided (if available: textured) polygons, ready to be used with CGA rules.
Scale
Size factor applied to the imported object.
Offset
Adds the specified offset to the imported object.
Center Sets the offset such that the object is centered on the scene's origin.
Reset Sets the offset back to zero.
2.5.4.4. Importing Data from KMZ / KML
KMZ / KML
Keyhole Markup Language (KML, ZIP-version: KMZ) is an XML based language for the description of
geospatial data for Google Earth and Google Maps. KML is a standard of the Open Geospatial Consortium. The
user can create 3D content by the means of Google Sketchup or download e.g. building models from Google
Warehouse.
A brief format description
KML-documents may contain geospatial data either in vector or raster form. Vector objects like points, lines,
polygons and entire models in the COLLADA format (DAE) are defined as "Placemark" elements; airborne and
satellite imagery are modeled as "groundOverlay" elements.
Besides the geometry, Placemark elements may involve name, description, predefined style, angle and distance of
view, a time stamp, but also other data e.g. from a geoinformation system. The same holds for GroundOverlay
elements, where instead of the geometry a coordinates section has to be defined for georeferencing.
Within CityEngine
At the time CityEngine supports only Placemarks defining a 'Model', which in turn refer to a COLLADA DAE
model.
The following Model attributes are read: 'name', 'altitudeMode', 'Location', 'Orientation', 'Scale'. In a Model the
georeference is stored in the Location attribute consisting of 'longitude', 'latitude' in degrees and 'altitude' in meters.
The geographical coordinate system is always the 'WGS84'.
When pressing the Finish -button and the current CityEngine scene's coordinate system is not yet set, a dialog will
show up proposing the UTM-zone corresponding to the given longitude.
Import Settings
KMZ / KML import has no options. Simply select a ".kmz" file, a ".kml" file or a folder containing one or more ".kml"
files by clicking on the Browse... button. When importing ".kmz", only a single file may be imported at once.
For KMZ as well as KML files, the easiest way to import is by first dragging either the KMZ file(s) or the folder
containing the KML file and associated files into the CityEngine workspace from your file manager (e.g. Windows
Explorer), and then importing it from there. KMZ as well as KML importers (below) work on the CityEngine
workspace.
A single selected KML file
A folder containing KML files has been selected
A single selected KMZ file
2.5.4.5. Importing Data 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.
CityEngine imports the following entity types
as shapes: Circle, LwPolyline (must be closed), Polyline (must be either closed or polyface mesh) and
Insert.
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.
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 .
Graph Settings
Note: The following settings are only of interest when importing graph networks.
Run Generate Bridges Tool after Import
If enabled, the Generate Bridges Tool is executed on a following wizard page.
Run Simplify Graph Tool after Import
If enabled, the Simplify Graph Tool is executed on a following wizard page.
Run Graph Cleanup Tool after Import
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.
Create Street/Intersection Shapes from Graph
If enabled, the shape creation parameter of the graph nodes and segments will be enabled and street shapes are
created.
Create Block/Lot Shapes from Graph
If enabled, the shape creation parameter of potentially created street blocks will be enabled and shapes are created.
2.5.4.6. Importing Data from SHP Files
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.
Shapefile support is not available in all CityEngine versions.
Import Settings
The shapefile import wizard.
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, PolygonM, Multipatch, Point, PointZ. Other types are imported as graph segments.
Shapefiles containing points can also be imported. In this case, a marker (0.1x0.1m quad) is created for each
point.
Shape file polygons containing "negative" polygons that cut holes into polygons are not supported yet, and will
be imported as normal shapes instead of "holes".
Coordinates System
The importer reads the .prj projection file of the shapefile. If successful, the corresponding coordinate system
is displayed in the dialog. Otherwise, a pop-up dialog asks the user to choose a coordinate system.
Graph Settings
created.
Map Shape File Attributes
If enabled, an imported graph layer will contain the following layer attribute code:

The shape attribute mapping function code displayed in the Inspector after import.
This mapping controls the width of the street shapes generated from the graph center lines. In the default behaviour,
the object attribute width is used to determine the resulting street width, and defaults to 8 if no object attribute is
found.
Advanced users can edit the default mapping code by changing the cga code in the file shp.ceattr , located
in /ce.lib/rules/ .

Using Attributes from SHP file
A SHP file has an 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 Object, which denotes that the CGA attribute height is controlled by
the object attribute of the lot.
New mapped CGA attribute height after assigning a rule file
2.5.4.7. Importing Data 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.
Import Settings

The osm import dialog with a checked highway layer for graph import

The osm import dialog with a checked area layer for shape import
File
Press Browse to open a dialog to select a .osm file to import.
Element Listing
Lists the layers and OSM ways contained in the selected OSM file. Select the element you want to import.
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.
You may select multiple OSM layers per import session. Then, all ways which are converted into graph
segments 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.
Graph Settings
The following settings are only of interest when importing graph networks.
Map OSM tags to street widths
If enabled, street and sidewalk widths are mapped from tags contained in the osm file. See below.
created.
OSM Tag Mapping
If Map OSM tags to street widths is checked, the created layer will contain the following layer attribute code:

The osm tag mapping function code.
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 'bellevue') of a selected street segment in the inspector.
The function code can be edited after import in the inspector when selecting the street layer.
Advanced users can edit the default mapping code by changing the cga code in the file osm.ceattr , located
in /ce.lib/rules/ .
2.5.5. 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 using OBJ Model Exporter
2.5.5.1. Exporting Shapes to SHP
Shapefile
data and the database file (.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 3D options, as shown below. As usual, presets can be saved and
applied.
Options include filename and 3D options.
File
Press Browse to open a dialog to select a .shp file to export.
3D Options
The following table illustrates the influence of this option:
3D Option Shapefile Type Data
none Polygon 2D
PolygonZ PolygonZ 3D
Multipatch Multipatch 3D
Note: The exporter does not write a .prj projection file. The data is always stored in cartesian coordinates in the
current scene coordinate system.
2.5.5.2. Exporting Shapes to DXF
DXF
by Autodesk. A 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 .
2.6. 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. Generate Bridges
7. Fit Street Widths
8. Simplify Graph
9. Analyze Graph
10. Importing Graph Networks
11. Exporting Graph Networks
2.6.1. 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.
The visibility of the sub-layers Network and Blocks can be toggled by clicking on the eye icon on the left side of
the labels.
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 clicking on the dashed line.
2.6.2. 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.
Street Creation Tools
Select the Freehand / Polygonal Street Creation 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 the start or end snap point is on an existing
segment, the segment is 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.
If the Freehand tool is selected, keep the left mouse button pressed and drag the mouse. If the Polygonal tool
is selected, click and release the left mouse button to set the start node of a new street. Then move the mouse to
choose the end node, and click and release the left mouse button again.
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, using the Polygonal tool.
Street Creation Settings
Settings for new streets can be controlled by using the Street Creation Settings dialog. To open the dialog, choose
Graph Street Creation Settings... from the main menu.
Default street creation settings.
Settings include street width, block subdivision type, automatic graph cleanup, alignment to terrain and model
generation. The settings can be understood as the current "brush". Presets are available to store a number of
"brushes". Note that these settings are stored individually for each scene.
General
.
Parameter Function
Re-use settings from neighbors If enabled, settings are copied from neighbor streets, if available. If an existing
street is extended, settings are typically copied from that segment.
Apply graph cleanup If enabled, after each editing operation the graph cleanup tool is executed. Note
that the settings for graph cleanup can be controlled by choosing Graph
Cleanup Graph... from the main menu. See Cleanup Graph Networks.
Align terrain If enabled, terrain layers are automatically aligned to new streets.
Street Parameters
Parameter Function
Street width The street width.
Street center offset The offset from the centerline of the street. The offset direction is perpendicular to
the street direction.
Left sidewalk width The left sidewalk width.
Right sidewalk width The right sidewalk width
Precision The precision for shape creation.
laneWidth Determines the approximate width for lanes. Used for the automatic setup of 'UV
texture coordinates' on dynamic street shapes.
Block Generation
Parameter Function
Subdivision type The subdivision type for shape creation of new blocks.
See Block Parameters
Rule-based Model Generation
Parameter Function
Rule file If set, this rule file assigned to all new street shapes.
Apply rule-based model
generation
If enabled, model generation is automatically triggered.
Edit Street Tool
The Edit Street Tool offers additional control over street editing, in combination with street shapes.
2.6.3. Growing Street Networks
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.
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 obstaclemaps 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 (valence = number of outgoing graph segments) equal to
2 and a crossing node is one with valence greater than 2.
Development Center
Preference
If large, street nodes near the center are developed more likely than nodes
outside. The center is defined as the center of mass of all selected nodes. If small,
all nodes are equally likely to be developed.
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 obstaclemaps.
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 terrains of the
scene are listed. A terrain is an attribute map which defines the float attribute
elevation.
Obstaclemap If an obstaclemap is selected, the new street nodes avoid the obstacles. The
street algorithm is able to avoid and circumnavigate obstacles. In the combo box,
all obstaclemaps are listed. An obstaclemap is an attribute map which defines the
boolean attribute obstacle.
Street growth with obstaclemap.
Adaption 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
Streets
The street width deviation for major streets. The street width is randomly set within
the interval [Width of Major Streets - Width Deviation of Major Streets, Width of
Major Streets + Width Deviation of Major Streets].
Sidewalk Width of Major
Streets
The average sidewalk width of a major street. See Sidewalk Width Deviation of
Major Streets.
Sidewalk Width Deviation of
Major Streets
The sidewalk width deviation for major streets. The sidewalk width is randomly set
within the 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 street. See Width Deviation of Minor Streets.
Width Deviation of Minor
Streets
The street width deviation for minor streets. The street width is randomly set within
the interval [Width of Minor Streets - Width Deviation of Minor Streets, Width of
Minor Streets + Width Deviation of Minor Streets].
Sidewalk Width of Minor
Streets
The average sidewalk width of a minor street. See Sidewalk Width Deviation of
Minor Streets.
Sidewalk Width Deviation of
Minor Streets
The sidewalk width deviation for minor streets. The sidewalk width is randomly set
within the interval [Sidewalk Width of Minor Streets - Sidewalk Width Deviation of
Minor Streets, Sidewalk Width of Minor Streets + Sidewalk Width Deviation of
Minor Streets].
2.6.4. Aligning Street 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.
2.6.5. 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, merge and/or resolve shape conflicts) 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.
Horizontal Snapping Distance:
The maximal horizontal distance between a node and a target segment. Only meaningful if the option
above is checked.
Vertical Snapping Distance:
The maximal vertical 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.
Horizontal Merge Distance:
Nodes that are closer than this distance in a horizontal direction are merged into one. Only meaningful if
the option above is checked.
Vertical Merge Distance:
Nodes that are closer than this distance in a vertical direction are merged into one. Only meaningful if
the option above is checked.
Resolve Conflicting Shapes:
When checked, the tool collapses all street segments which cause street shape conflicts. This is
executed iteratively until no more conflicts exist.
Segments with the smallest minimal adjacent node valence are collapsed first, i.e. this 'segment
valence' determines the order of the segment collapse iteration.
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
Resolve Conflicting Shapes
2.6.6. Generate Bridges
Imported or manually created street networks often lack elevation data, which is necessary for the 3D display of
crossing streets. The Generate Bridges tool can automatically create such data. It can by executed using the main
menu menu: GraphGenerate Bridges... . It operates either on the current street selection or on all streets when
nothing is selected.

Note that the wider street is kept naturally at it's original level, while the thinner street is raised. Also, please
note that new street nodes are inserted at the correct distances from the crossing point, defined by the maximal
defined slope. The vertical tangent components are automatically adjusted.
(left) Original Streets (right) Applying the Generate Bridges tool adds elevation data.
An other simple example.

Generate Bridges Settings
After starting the tool, the following dialog is shown:
The Generate Bridges tool dialog.
Level height
Vertical distance to be set between two crossing streets. Note that the 'Ramp maximum slope'
influences the resulting node elevations.
(left) Original (right) Level height = 20
Object attribute for level
(optional) The height coordinate can be calculated from specific object attributes of streets. The height
coordinate is set to "Level height" multiplied with the indicated attribute name. Attributes can either
originate from imported data or be manually assigned, allowing full control of the vertical street layering.
(left) Original (right) Manually set level attributes enable full control of vertical street layering.
Only apply level when streets cross
Sometimes, imported GIS data, such as OSM data, may contain faulty attribute values that cause the
creation of elevated parts of streets. This option activates or deactivates the vertical alignment in
regions, where actually no other streets cross the street of interest.
(left) Original, with faulty 'level' attribute value. (middle) Option unchecked. (right) Option checked.
Object attribute for absolute height
(optional) In contrast to the object attribute for level, this attribute allows direct specification of absolute
heights. When a street has this attribute, the level height is ignored.
Ramp maximum slope
Maximum slope of ramps (vertical climb per horizontal unit).
(left) Original (middle) Maximum slope = 0.2 (right) Maximum slope = 1.0
Bridge join preference
If a street contains multiple bridges in a row, they are linked together according to this value. Low
values: unlikely to join, high values: always join.
(top) Original (bottom left) Bridge join = 0.1 (bottom right) Bridge join = 1.0
Lock non-zero heights
Do not change height of nodes with non-zero position.
Allow tunnels
Allow tunnels (streets below zero height). Note that this is quite a rare state to construct. Note also that
the Shadow Plane is rendered at smallest (thus negative) elevation value.
(left) Original (right) Solved with tunnels.
Use visible terrain
Treat all heights as relative above terrain (if any). This causes bridges to follow the terrain.
(left) Use visible terrain (right) Ignore visible terrain
2.6.7. Fit Street Widths to Shapes
Often, datasets with street center lines do not have width attributes. Using the Fit Widths to Shapes tool lets the user
easily adjust them accordingly. It can by executed using the main menu menu: GraphFit Widths to Shapes... .
(left) Original streets do not line up with the footprint shapes. (right) Widths and offsets are adjusted to touch the footprints.
Parameters
The Fit Widths to Shapes dialog.
Max Street Width
Maximum width the streets will be fitted to. When the calculated width is larger than this parameter, the
street is left unchanged.
Min Street Width
Minimum width the streets will be fitted to. When the calculated width is smaller than this parameter, the
street is left unchanged.
Sidewalk Scale
Determines if sidewalks widths are retained ("Do Not Change") or scaled proportionally to the street
("Scale Proportionally").
Adjust Street Offsets
Determines if the street offsets should be adjusted to better fit the static shapes.
Additional Margin
This allows to increase the margin between streets and static shapes.
(left) Original (right) Additional Margin = 3
2.6.8. Simplify Graph
Street graphs often contain a lot of contiguous short straight streets, which can be simplified to longer curved streets
with this tool. It can by executed using the main menu menu: GraphSimplify Graph... . It operates either on the
current street selection or on all streets when nothing is selected.

(top) Street with unnecessary nodes (bottom) simplified version
Parameters
Threshold Angle
Angle in degrees. Streets with a higher angle than this form boundaries between fitted curves.
(top) Input street (middle) Threshold = 10 (bottom) Threshold = 50
2.6.9. Analyze graph
Graph networks can be analyzed by computing global integration, local integration and inbetween centrality.
For each street these three values are computed and stored as object attribute "integrationGlobal",
"integrationLocal" and "inbetweenCentrality". The values can be visualized or used to approximate street widths.
The default analyze graph settings.
In order to open the dialog, select a set of graph segments or a graph layer and choose Graph Analyze
Graph... from the main menu.
Settings
Mode: Three modes are available:
Calculate analysis only (as object attribute): For each street the three analysis values
global integration, local integration and inbetween centrality are computed. These values
are stored as object attributes.
Visualize analysis (assign rule): Computes the three analysis values and assigns a
visualization rule file to the street shapes. Model generation is automatically triggered. The
visualization can be configured by selecting street shapes and using the inspector.
Set street width (based on integration): Computes the three analysis values and maps
the local integration to the range specified by Street Width Min and Street Width Max. After
running the tool, select the street layer to see/change the mapping code in the layer
attributes in the inspector.
Depth of local integration: The number of 90 degree turns to take into account to compute the local
integration value.
Street Width Min: Street width lower bound, only used in Set street width mode.
Street Width Max: Street width upper bound, only used in Set street width mode.
Definitions
All shortest paths between all selected street segments are computed. The shortest path cost function is the sum of
all angles between the segments along the path.
Global integration
For each street segment, the shortest paths to all other segments are summed up. Each sum is then divided by the
square of the number of segments. Next, each value is inverted. Finally, the values are normalized so that each
value is in the range zero to one.
Local integration
For each street segment, the shortest paths to all other segments which are closer than (Depth of local integration)
90 degree turns are summed up. Each sum is then divided by the square of the number of visited segments. Next,
each value is inverted. Finally, the values are normalized so that each value is in the range zero to one.
Inbetween centrality
For each street segment, the number of shortest paths which pass this segment is computed. Then, the values are
normalized so that each value is in the range zero to one.
Example
The global integration of a typical street network.
2.6.10. 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, SHP or FileGDB files:
1. Importing data from DXF
2. Importing data from OSM
3. Importing data from SHP
4. Importing data from GDB
2.6.11. 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
2.6.11.1. Exporting Graph Segments to SHP
Shapefile
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 shapes: For a shape specific description please visit:
Exporting Shapes to SHP
Export Settings
The export dialog consists of the filename and the 3D options, as shown below. As usual, presets can be saved and
applied.
Filename and 3D options.
File
Press Browse to open a dialog to select a .shp file to export.
3D Options
The following table illustrates the influence of this option:
3D Option Shapefile Type Data
none Polyline 2D
PolylineZ PolylineZ 3D
Note: The exporter does not write a .prj projection file. The data is always stored in cartesian coordinates in the
current scene coordinate system.
2.6.11.2. Exporting Graph Segments to DXF
DXF
by Autodesk. A 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.
By DXF Export settings
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.
2.7. Static Models
1. What are Static Models
2. Importing Static Models
3. Working with Static Models
4. Aligning Static Models to the Terrain
2.7.1. What are Static Models
Static Models are any geometrical models imported 'as is', which will not be modified within CityEngine neither
by CGA rules nor by changing textures or individual vertices. They are just positioned and scaled. The data in the
imported files is only read and never written. Usually, such models are generated in one of the 3D design tools
like 3ds Max, Cinema 4D, Houdini, ArchiCAD, etc.
Static models are imported from the file formats: OBJ, DAE, KMZ/KML
Please refer to:
Importing Static Models
Working with Static Models
Aligning Static Models to the Terrain
2.7.2. Importing Static Models
Importer Selection
In order to import static models from an external source, select FileImport... from the main menu. Choose
City Engine Layers and select one of the appropriate file format importers:
DAE Import
KML Import
KMZ Import
OBJ Import
Click Next and depending on the file format, different options will be available for import.
Imports can also be performed by Drag-and-Dropping the file directly into the 3d viewport. Depending on
whether the file contains geolocation data ( kml / kmz ), the file is either automatically placed at the correct
geolocated coordinates or at the mouse position ( ground plane ).
KMZ / KML Imports are always done as static models, whereas DAE and OBJ files may be imported as static
model or as shapes.
Import details on supported file formats
Import Static Models from OBJ
Import Static Models from COLLADA DAE
Import Static Models from KMZ / KML
Also refer to
Importing Shapes
What are Static Models
2.7.3. Working with Static Models
Static models still may be modified by a few operations after importing. The attribute 'static' means, that
vertices may not be modified individually, textures may not be changed and cga rules may not be applied.
Transform Tools
A static model can be positioned and scaled as you wish within the scene by the means of the Move Tool (W), the
Scale Tool (E) and the Rotate Tool (R).
Images of the three transform tools (f.l.t.r): Move Tool, Scale Tool and Rotate Tool
In the Inspector
Here some object attributes may be changed as described below:
Parameterization in the inspector
To change the attributes use either the text fields on the left or the switches and buttons on the right.
Attribute Description
Asset_File The static model may be replaced by any model file of the supported types OBJ,
DAE and KML.
Material_Colorize The model may be colorized for e.g. making it more visible among other models.
Type in the color code in Hex format (#RRGGBB) or click the color bar for a color
dialog.
Material_Transparent Lets other models behind be seen through this one.
Pos_Bottom_Align Forces the model's origin (pivot) to align to its bottom.
Pos_Center Moves the model's origin (pivot) to its center. If Pos_Bottom_Align is set, the
vertical center is overridden.
Pos_zUp Some models are created in a z-up coordinate system instead of CityEngine's y-
up system. Use this switch in order to correct this.
Also refer to
2.7.4. Aligning Static Models to the Terrain
Static models alignment is a tool to align static models to arbitrary terrains (map layers with attribute
"elevation" defined) or to the y=0 level. All currently selected static models and all static models of the selected
layers are aligned.
Non-aligned static models (all have the the same y-coordinate)
versus static models aligned to a terrain.
In order to align the selected static models, select the menu entry LayerAlign Static Models to Terrain... and
the dialog below is shown:
The static model alignment settings
These parameters control the alignment:
Heightmap - 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.
Complete the alignment operation by pressing Finish .
Also refer to
Aligning Terrains to Shapes
1. Basics of Rule-based Modeling

2. Rule Files
3. Writing Rules
4. Shape Operations
5. Rule Editing Tools
6. Rule Packages (rpk)
2.8.1. 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
2.8.1.1. 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 are the most
important shape attributes:
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.
2.8.1.2. 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:
2.8.2. 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 of the typical steps necessary to work with rule files is given.
Table of Contents
Creating a new Rule File
Writing a Rule File
Assigning a Rule File to a Shape
Setting the Start Rule
Applying the Rules to generate a 3D Model
2.8.2.1. 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 ( /* ....
*/).
2.8.2.2. 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 .
2.8.2.3. 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:
Drag and drop rule file
Select a number of shapes (either in the 3D Viewport or in the Scene view) and drag and drop the
desired rule file from the File Navigator onto the selection in the 3D viewport.
Toolbar button:
Select a number of shapes (either in the 3D Viewport or in the Scene view) and hit the Assign button.
Assign button in the inspector:
Select a number of shapes (either in the 3D Viewport or in the Scene view) and hit Assign...
Shapes top menu:
Select a number of shapes (either in the 3D Viewport or in the Scene view) and select Shapes
Assign Rule Files...
(as well in right-click context menu in the viewport and in the Scene Editor)
Rule file context menu:
Select a number of shapes (either in the 3D Viewport or in the Scene view), right-click the rule file in the
File Navigator and choose Assign To ; All Selected
Assign Rule from CGA Editor:
Set the cursor in the CGA file to the Rule you want to set as Start Rule, and click Assign Rule in the
CGA editor top toolbar to set the rule file and the current rule to all selected shapes.
Assigning a rule file via top toolbar
Assigning a rule file via context menu
Assigning rule file and start rule from CGA Editor
In addition to the rule file, a shape requires a valid start rule to trigger the model generation. If no valid start
rule is found while a rule file is being assigned, the Start Rule Selector pops up.

2.8.2.4. Setting the Start Rule
In addition to the rule file, a shape requires are valid start rule to trigger the model generation. If no valid start
rule is found while a rule file is being assigned, the Start Rule Selector pops up.
Start Rule
A Start Rule is required for rule file model generation. The Start Rule can be set manually, or set from the Start Rule
Dialog. The Start Rule Dialog is shown
When the Select... Start Rule button is clicked in the Inspector
when a rule file is assigned to shapes with an empty or invalid start rule (invalid means no rule is found
in the rule file that matches the start rule)
Start Rule Dialog
The Start Rule Dialog displays all rules that can be applied as start rules.

Rules that are marked as start rules (see CGA annotations are displayed in bold. Intermediate rules (rules that are
referenced from parent rules) are displayed in italic.
The Start Rule Dialog

Depending on the selected shapes and their start rules, the Start Rule Dialog shows the options to
Overwrite invalid start rules: Set selected start rule to all shapes with invalid or empty start rule
Overwrite all start rules: Set selected start rule to all shapes
Choose Skip or Cancel if you don't want any Start Rules to be modified.

CityEngine tries to automatically detect and suggest start rules from a rule file. Use the annotation @StartRule
to explicitly mark a rule as a start rule. More on CGA annotations.

Setting the Start Rule manually
The start rule can be set on shapes via the Inspector. Select a set of shapes, locate the Start Rule field in the Shape
tab of the Inspector, and type in the desired Start Rule. Note that no model will be generated if an invalid start rule is
set.

Default Start Rules
Shapes generated inside CityEngine from a street network (by block subdivision or street shape
creation) have their start rule set to a default value during creation (Lot, LotInner, Street, Sidewalk, ...).
These start rules can be reset to their initial value with Graph Reset Shape Attributes
Shapes created manually with the Create Shape Tool have their start rule set to Init by default
Shapes which are imported from a .obj file (arbitrary geometries) have their start rule set to the obj
group name by default.
2.8.2.5. 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.

2.8.3. 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
Styles
Import
Functions
Comments
Handles
2.8.3.1. 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.
Rules can be annotated to control their visibility in the user interface. See "Annotations".

2.8.3.2. 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 Envelope 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.

2.8.3.3. 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).

2.8.3.4. 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.

2.8.3.5. 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 shape basis; this can be done in
the Rules pane in the inspector.
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.

See Mapping Parameters for details how to use different sources to control input of rule attributes.
The display of attributes in the Inspector can be controlled by CGA annotations.
Interactive Handles can be used to edit attributes in the 3D view.

2.8.3.6. 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 be 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.

2.8.3.7. 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,attributes and functions of the imported rule file available under the given prefix.
Example
Combining two 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
CGA Reference
import
2.8.3.8. Comments
Comments can be added to CGA source code by either line comments with the characters // or #
// a comment
# another comment
or block comments with /* ...... */
/* block comments
can be used to write
multi-line comments
*/
or inline comments
Lot -->
Garden House /*Garage*/ Fence
...
comp(f){front : F | /* side : S | */ top : T}

2.8.3.9. Handles
Handles allow users to edit the value of the selected object's attributes in the 3D view. They are created by adding
the @Handle annotation to an attribute.
Handles can be enabled or disabled for the current scene in the Preferences dialog, under the heading Scene. By
default handles are enabled.
Examples
The above handles were created using the following attribute annotations:
@Handle("shape=Cube axis=y")
attr height = 30
@Handle("shape=Cube axis=x")
attr width = 30
@Handle("shape=Cube axis=z")
attr depth = 30
Lot -->
s(width, 0, depth)
extrude(height)
Cube
The option shape=Cube specifies a model's shape to attach the handle to, while axis= specifies a scope-specific
direction for the handle.
Handles adapt their positions based on the camera viewpoint, so that they are always visible:
Thin gray extension lines connect the handle to the shape that it is measuring.
Handles can be applied to a wide range of objects.
The above handle was created using the following attribute annotation:
@Handle("shape=TreeCenter axis=y reference=center slip=screen")
attr height = 30
The advanced options reference= and slip= specify the handle's position and movement as the camera moves.
Adding many handles, or adding handles to complex models may lead to low framerates on low-end hardware.
General Options
Each option taken by @Handle is separated by a space character. There are no other space characters in the
option list.
The default options in the below table are marked with an asterisk. If any option is omitted, the default value is
taken. The only option that must be specified is shape=.
Option Description
shape=
shape_name^argument_count
where shape_name is given by the name of the rule that created the shape, and argument_count
is the number of arguments that the rule takes.
If ^argument_count is omitted, ^0 is assumed. An asterix allows referencing anonymous leaf
shapes, e.g.: shape=Box*^3.
type=
linear*|angular|toggle|selector
Selects the type of handle to create. Handles with a linear type are used for editing float values
that represent distances, the angular type for float attributes that represent angles, the toggle type
for boolean attributes and selector type for attributes with the @Range annotation.
Linear
Angular
Toggle
Selector
Additional options specific to each type are given below.
align=
topLeft|left|bottomLeft|bottom|bottomRight|right|topRight|top|outside*|inside
Selects a screen direction as the offset direction preference for a reference handle. outside
selects the nearest location outside of the model's silhouette, while inside does not move the
handle from the reference location.
linear example of align=left
linear example of align=right
toggle example of align=topLeft
toggle example of align=right
minDisplaySize=
pixels
If the size of a handle is below pixels, it is not shown. Users can override this behaviour by
pressing the command key (OS X) or control (PC / Linux).
The size of a handle with linear type is the screen-length. The size of an angular handle is the
distance between the zero degrees, and the handle. The size of toggle or selector handles is the
screen length of the shape's scope's shortest edge.
extensionLines=
scope*|silhouette|fade|off
Specifies the style of the extension lines associated with a handle.
Clockwise from bottom right: extensionLines=scope, extensionLines=fade,
extensionLines=off and extensionLines=silhouette.
The below image shows typical use cases for the different extension line types. Scope (left) is
used to highlight embedded features, silhouette (middle) with obvious features to avoid cluttering
the geometry, and fade (right) for irregular shapes.
translate=
{translate_x,translate_y,translate_z}
Gives a scope-relative translation of the handle. For example translate={3,0,0} translates the
handle by 3 * scope.sx in the direction of the scope's x axis.
Linear Type Options
Linear handles are assumed to be associated with a scope edge. The length of the linear handle is given by the
scope edge specified by axis. If the value of the attribute is not the same as the length of the scope edge, indirect
mode is used. Indirect mode is indicated by dashed handles, and allows the handle to move when being dragged.
Option Description
reference=
edges*|center|origin|radial
Specifies the location of the reference handles. In the below images, the shape origin is in the
bottom right of the screen. These reference handles are moved to their offset position using the
align= option.
Note that the location of radial handles depends on the camera position.
reference=edges reference=center
reference=origin reference=radial
Typical use cases are reference=edges for boxes or cuboid geometry (as shown in the first
example on this page), reference=center for the length of cylindrical or spherical objects (such as
the tree's height in the second example), reference=radial for the width of cylindrical objects (such
as the dead tree model above), and finally reference=origin when a feature is one dimensional, or
when the exact position of a handle must be specified.
axis=
y*|x|z|-x|-y|-z
Selects the shape's scope axis to position the handle along. A negative axis reverses the direction
of the handle.
repeat=
chain*|none
Chained linear handles will be clustered into a single continuous chain. Linear handles of several
different attributes with the same orientation may be grouped onto one chain if there is sufficient
space.
Left: repeat=chain, right: repeat=none
If repeat=none, CityEngine determines an appropriate location for the handle, preferring locations
with short extension lines, and long linear handles.
slip=
scope*|screen
This option specifies the directions that reference handles may be offset in. For example the length
of cylindrical objects is best specified using slip=screen, while the dimensions of a cuboid should
use slip=scope.
This option has no effect if align=inside
In the below image we see that slip=scope causes the handle to align itself to the edges of the
scope as the camera moves. In contrast slip=screen maintains a constant offset direction,
independent of camera location.
Left, middle: slip=scope, right: slip=screen
It is recommended that cuboid objects use slip=scope, while cylindrical or spherical objects will use
slip=screen. While it is possible to use either of these options in any case, following these
recommendations presents a consistent and intuitive interface to users.
drawMode=
doubleArrow*|sphere
A linear handle has two options for the rendering of terminators.
Left: drawMode=doubleArrow, right: drawMode=sphere
Angular Type Options
Angular handles allow the user to manipulate angles. Typically a combination of axis= and translate= are used to
position the handle in the appropriate location.
Option Description
reference=
edges|center*|origin
bottom right of the screen.
reference=origin
axis=
y*|x|z|-x|-y|-z
Selects the shape's scope axis to position the angular handle's origin along. A negative axis
reverses the direction of rotation.
The red, green and blue lines are the x, y and z axes. For example axis=x rotates around the x axis towards
the z axis. The angular handles each have an attribute value of 30 degrees.
Toggle and Selector Type Options
Toggle and selector types share layout options.
Option Description
reference=
edges|center*|origin|radial
bottom right of the screen.
Note that the location of radial handles depends on the camera position.
reference=origin reference=radial

2.8.4. 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
2.8.4.1. 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.
2.8.4.2. 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 vectorscope.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 used in the CGA 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
centered (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
2.8.4.2.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 initial 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 arithmetic's 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
2.8.4.3. 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 eitherf for faces,e
for edges orv for vertices. Theselector 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 vertical 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.

2.8.4.4. 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 creating 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 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 are 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 }
...

2.8.4.4.1. 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 absolute 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) }
...
2.8.4.4.2. 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 patterns 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) }* }* }*
...
2.8.4.4.3. 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) }
...
2.8.4.4.4. 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 } }
...
2.8.4.5. 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.

2.8.5. 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 CGA Editor
Working with the Model Hierarchy Explorer
Overwriting Attributes with the Inspector
CGA Styles
2.8.5.1. 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.
Rule Errors and Warnings
The CGA Editor (top) and the Problems view (bottom). Note the highlighed error (red) on line 195.
In the picture above, a rule file is open in the CGA Editor; there is a syntax error in the CGA code (line 195: "->"
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
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 are highlighted in yellow.
In this case, the rule WallsDone is not defined. This is not necessarily a problem. Warnings just indicate potential
problems and do not prevent generation.
If your Problems View looks different you might need to configure it.
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!
Problems View
On top of Rule Errors (static compile errors), the Problems View also shows Model Errors (dynamic runtime
errors), i.e. problems encountered during generation of a model. Such errors / warnings depend on the rule as well
as on the initial shape (i.e. its geometry and attributes such as the seed etc.). The 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.
Model Errors are reported during model generation.
To find the according model/shape, double-click on the warning and the model plus shape will be selected and
framed. The picture below shows the inital shape and the generated model for whom the generation resulted in the
"Could not load asset cube_bevel1_side.obj - file not found." warning.
Double-clicking a Model Error selects and zooms to the culprit model. Note that the "isolate selection" button was used to
hide all other models.
Configuration
The Problems View can be configured according to your taste and needs. Here are the settings recommended by
the CGA core grinders:
Group the errors by their type (i.e. separate Rule Errors and Model Errors):
Sort the errors by their Location (i.e. by their initial shape):
Make sure the default limit of 100 markers is disabled:
2.8.5.2. 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 Inspect Model 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 the Tutorials) 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 select 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).
2.8.5.3. 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:
Rule attribute height displayed in Inspector
The display of attributes in the Inspector can be controlled by CGA annotations.
You can now click on the attribute value and edit the value. Let's say you type in 30 (or use the slider to modify the
value)
Rule attribute height set to user value 30
By entering a value, the attribute has changed to a user value, displayed in bold.

Assuming your shape has an object attribute height that should be used to control the rule attribute, bring up the
Connection Editor by clicking on the connection icon , choose Object attribute and hit OK .
The rule attribute height is now connected to the object attribute with the same name. The value is displayed in italic
and marked with (Object). The value used for CGA generation is taken from the object attribute.
Rule attribute height connected to Object Attribute
During rule assignment, object attributes with names that match a rule attribute get connected automatically.
Details on mapping attributes
See Mapping Attributes for more details on connecting rule attributes to object attributes or map layers (Layer
attributes).
Multi Assign
It is possible to manually assign a value to multiple initial shapes in a convenient way. Let's say we selected two
initial shapes that have a rule file assigned with the attributes height, roofColor and roofType
Multiple initial shapes can be selected in the Scene view or the Viewport.
In the Inspector, the attributes of all selected lots can now be manipulated. If you change the height value to 20,
both selected shapes will have their height value changed.
The attributes of all selected initial shapes can be manipulated in the inspector.
Now select one shape (or model) only, and change the roofColor to a different value. If both models are selected
afterwards, the value of roofColor is displayed as a question mark ?, stating that the two selected models do not
share the value for this attribute.
Attributes with different values are displayed as "?".
2.8.5.4. CGA Styles
CGA styles are a comfortable way to store and reuse sets of rule parameters.
Style Manager
Select a shape with a rule file assigned, and open the Style Manager by pressing the Style Button in the Rule Tab in
the Inspector.
Style button in the Inspector, with Default Style selected
The Style Manager displaying 4 facade styles
The Style Manager displays all available styles in its rule set. A rule file that has no styles defined shows only one
style (the default style).
To assign a style to the selected shapes, select the desried style and hit ok (or doubleclick the style).
Delete a style by pressing the red cross in the top right corner of a style.
Toolbar options
Display styles as tiles or list
Frame views
Choose camera
Viewport settings

Creating a new Style
Creating a new style stores the current parameter set to a style. To create a new style, select your desired shape or
model, and press the button next to the style button.


The Plus button starts the create style dialog
Parameter Function
Style name Use a unique name for your style. An existing style with the same name will be overwritten
Based on The reference style which the new style is based on. This can either be the Default Style
or the current style (if one is applied)
Description An optional description for the style
When the new style is created by pressing OK :
All all user-set attributes are converted to Default (Rule) values for the new style (all user-set attributes
"baked" into the new style). Mapped attributes (mapped to Object Attributes or Map Layer) will keep
their connections.
The new created style is applied to the selected shapes
The new style is now available in the Style Manager as well

Style Context Menu
Operations on styles are available as well from a context menu. Right-click in the attribute area of a rule file to bring
up the context menu:
Style context menu
Parameter Function
Select Style Selecting one of the available styles from a list
Create new style ... Create a new style, bring up the create style dialog
Delect current Delete current style
Reset user attributes of rule file Reset all user-set attributes of this rule file to its default (Rule) values
Reset all attributes of rule file Reset all user-set and mapped attributes of this rule file to its default (Rule) values

Styles in CGA rule file
When a new style is created using the create style wizard, the active CGA rule file is modified, a new style section is
created at the bottom of the rule file.
Depending on the creation options, a different set of attributes are added to the new style.
Note in particular that in case a new style is created based on an existing style, with the option set to Create style
with user attributes only, the new style extends the parent.
A new style is created based on the default style:
All user-set attributes are added as attributes to the new style, with their user value set as initial value
(Default Rule value)
A new style is created based on its current style:
The new style extends the previous one. Only attributes that are different from the base style are added
as attributes to the new style, attributes from the base style are inherited.
attr mColor = "#ff0000"
attr height = 1
Lot -->
color(mColor)
extrude(height)
style Design1
attr mColor = "#006600"
attr height = 2
style Design1_2 extends Design1
attr mColor = "#99ff99"
Of course can just as well be added and modified in the CGA text editor instead of using the style wizard. Please
see styles in the CGA reference for more information.

2.8.6. Rule Packages (rpk)
What is a Rule Package
A 'rule package' is a compressed package, containing compiled (binary) CGA rule files, plus all needed referenced
assets and data.
Rule packages are an easy way to share procedural rules in a handy single file. For finding the package content, the
rules are analyzed. Note that with CGA, one can create very complex asset dependencies, so it cannot be
guaranteed that in every case, all assets are included. In doubt, add the files manually (see 'Additional Files' below).
Creating a Rule Package locally on your machine
1. Locate the target CGA rule in the Navigator.
2. Right-click on the .cga file and choose Share As...
3. The Rule Package dialog box appears: Name your RPK.
4. Click 'Save package to file' (Note the sharing tab disappears) and set the file path.
5. Decide if you want the CGA source code (human readable text files) to be included.
6. Fill out the item description
7. Remove proposed files and folders, or add new ones. This enforces the packaging of specific assets.
8. Click Analyze to validate your RPK for any errors or issues. You must validate and resolve all errors
before you can save it to disk or share it to ArcGIS Online. If any issues are discovered, an error will be
reported. You have to fix the error before you can continue.
9. Click 'Share' to save the file to disk.
Publish to ArcGIS online
ArcGIS Online is an online platform to share maps and geographic information with others. CityEngine allows you to
easily share RPKs with others by publishing them to your ArcGIS Online content.
Help on signing into ArcGIS Online / Portal and other details can be found here.

1. Locate the target CGA rule in the Navigator.
2. Right-click on the .cga file and choose Share As...
3. The Rule Package dialog box appears: Name your RPK.
4. Take the same steps as descibed above under 'Creating a Rule Package locally on your machine' for
the Item Description and Additional Files.
5. Click on the 'Sharing' tab.
6. CityEngine will ask you to log in with your AGOL account, unless you're already logged in.
7. Set the groups with whom you want to share the PRK with.
8. Analyze the RPK for it's validity, then click 'Share' to upload the RPK onto AGOL.
RPKs can be uploaded to other ArcGIS portals as well. See Sharing data on a different Portal

2.9. Importing Data
1. Importing Data
2. Formats
1. Collada DAE
2. DXF
3. File Geodatabase
4. KMZ/KML
5. OBJ
6. OSM
7. Shapefile
2.9.1. Importing Data
Drag and Drop import
The most convenient way to import data into a CityEngine scene is to drag a file from the Navigator into the 3D
viewport. When importing this way, no import dialog is shown, the default import parameters are automatically
applied. Supported file formats for drag and drop import include:
File Type Drag and Drop import behaviour
.dae import as static model
.dxf Imports as shapes and/org graph segments
.gdb imports all supported layer types, as shapes, point shapes or graph networks
.kml imports all referenced dae objects as static models
.kmz imports all referenced dae objects as static models
.obj import as static model
.osm imports all layers, as shapes and/or graph segments
.shp imports as shapes, point shapes multipatch shapes or graph networks
Drag and Drop import of image data
Dragging an image file from the Navigator into a 3D viewport brings up the Terrain Dialog.
Placement of data after drag and drop import
Georeferenced data such as kml, gdb and shp is placed at its georeferenced location. Data with no georeferenced
information is placed at the drop spot, taking the data's origin as pivot.
Import via Menu
Import via menu can be started by Right-mouse Import... on a file in the Navigator, or via menu File
Import... In contrast to Drag and Drop import, each import format will present a file dialog with additional options.
See below for the format-specific options.
Depending on the file format, imported data results in different object types in CityEngine:
Supported file formats for Shape Import
COLLADA DAE
DXF
FGDB
OBJ
OSM
SHP
Supported file formats for Static Model Import
COLLADA DAE
KMZ / KML
OBJ
Supported file formats for Graph Import
FGDB
DXF
OSM
SHP
Supported file formats for Terrain and Texture Import
Terrain Import
Texture Import

2.9.4. Importing Data from File Geodatabase
File Geodatabase
The ESRI File Geodatabase (FGDB) is a file-based database for vector and raster data. It can be identified as
folder with the suffix .gdb. For example, myDatatbase.gdb
FGDB support is not available in all CityEngine versions.
Import Settings
The FileGDB import wizard.
File
Press Browse to open a dialog and browse to the .gdb file you want to import.
Element Listing
After opening a file, the dialog shows the layers in the file geodatabase. For each layer, there is additional info like
feature type, feature count, import status and layer projection. The following feature types are supported:
Point
Polygon
Polyline
Multipatch (with textures)
Table (data only imported indirectly via relationship classes)
Relationship Classes (used to import related data from tables)
Each FDGB layer is imported as a separate layer. Layer types that are not supported are marked with the sign,
and will not be imported.
File geodatabase file polygons containing "negative" polygons that cut holes into polygons are not supported
yet, and will be imported as normal shapes with a special "isHole" object attribute.
Select / deselect all
Selects / deselects all layers.
Coordinates System
The importer reads the projection of each layer. If successful, the corresponding coordinate system is
displayed in the dialog.
Graph Settings
created.
Map Shape File Attributes
If enabled, an imported graph layer will contain the following layer attribute code:

The shape attribute mapping function code displayed in the Inspector after import.
This mapping controls the width of the street shapes generated from the graph center lines. In the default behaviour,
the object attribute width is used to determine the resulting street width, and defaults to 8 if no object attribute is
found.
The function code can be edited after import in the inspector when selecting the imported layer.
Advanced users can edit the default mapping code by changing the cga code in the file shp.ceattr , located
in /ce.lib/rules/ .
Import Fields from Related Tables
If enabled, attributes from tables that are related to the layer that is being imported are transferred to the imported
shapes as object attributes. By default, attribute names from the related tables are maintained.
Prefix Fields from Related Tables with Table Name
If enabled, attribute names from related tables are prefixed with the table name to prevent name clashes.
This option should not be used when authoring rules for the ArcGIS CityEngine tools, as these only work with
un-prefixed attribute names.

Feature selection
Use Selection Query and Envelope
If enabled, an attribute selection query and envelope can be used to reduce the number of imported features from
each selected feature class.
Selection Query
A list of "All Available Feature Class Fields" can be viewed and used to build a SQL query.
For example: SELECT * WHERE edits = yes
Selection Envelope
Set the size (Width, Height) and reference point (X-Offset, Y-Offset) of the selection envelope.
Using Attributes from FGDB
Attributes of features are imported along with the feature itself. After a successful import, these attributes appear in
the Inspector in the Object Attributes tab.
A set of imported shape attributes as displayed in the Inspector.
Once a CGA rule file with matching attributes is assigned to this shape, the matching object attributes are connected
to the rule file and will control the generation of models. See also Mapping attributes.
2.10. Georeferencing
1. Scene Coordinate System
2. View Coordinate System
3. Coordinate System Dialogs
4. Georeferenced Data
2.10.1. Scene Coordinate System
The Scene Coordinate System defines your scene's reference coordinate system for georeferenced data
import, export and HUD information.
Default Scene Coordinate System
A CityEngine scene can have a Scene Coordinate System (SCS) set. By default the SCS is set to CityEngine CS,
the default CityEngine coordinate system.
A new CityEngine scene in default Coordinate System CityEngine CS [meters]
Setting the Scene Coordinate System
When working with georeferenced data, it is often important that your scene has a valid georeferenced coordinate
system set. There are three ways to set your scene's coordinate system:
1. Setting a Coordinate System when Georeferenced Data is added to the scene
2. Setting a Coordinate System when creating a new scene
3. Changing the Scene Coordinate System in the preferences
1. Setting a Coordinate System when georeferenced data is added to the scene
As soon as georeferenced data is imported into a CityEngine scene, a Scene Coordinate System is required to
locate it correclty. CityEngine automatically pops up the Scene Coordinate System Dialog on your first import of
georeferenced data. Taking the data that is going to be imported into account, the dialog suggests a matching scene
coordinate system.
2. Setting a Coordinate System when creating a new scene
When creating a new CityEngine scene, you have the option to set your Scene Coordinate System in the new scene
wizard. The Scene Coordinate System Dialog appears when you hit Choose...
Setting a Scene Coordinate System when creating a new CityEngine scene
3. Changing the Scene Coordinate System in the preferences
The Scene Coordinate System can be set or changed in the CityEngine preferences Scene Scene coordinate
system. Hit the Scene coordinate system button to launch the Scene Coordinate System Dialog
When changing the Scene Coordinate System, no reprojection is applied to the content of the scene. Using
this option only changes the scene's reference system, used for viewing coordinates as well as for future data
imports.
Please note that CityEngine currently does not support Datum-Transformations. Thus, please project /
reproject your data to match the target SCS before importing into a CityEngine scene.
Scene Coordinate System Preferences
Once a Scene Coordinate System is set, it is displayed in the status line. Also, the information in the headup display
of a 3D viewport changes according to the Scene Coordinate System.
The Scene Coordinate System displayed in the 3D viewport HUD and the status line
In CityEngine the Scene Coordinate System can only be a projected coordinate system (no geografic
coordinate systems).
2.10.2. View Coordinate System
Change the View Coordinate System to display HUD information in different coordinate systems.
View Coordinate System
A CityEngine scene with a Scene Coordinate System displays information in the 3D viewport headup display in the
current Scene Coordinate System:
The Scene Coordinate System displayed in the 3D viewport HUD and the status line

If a Scene Coordinate System is set, the user can choose the displayed coordinate system for a 3D viewport in the
viewport settings menu View Coordinate System
CityEngine CS [meters] CityEngine coordinates y-up, meters
Scene CS [feet] Current Scene Coordinate System in feet
Scene CS [meters] Current Scene Coordinate System in meters
UTM Universal Transverse Mercator
MGRS Military Grid Reference System
Long/Lat [decimal degrees] Longitude / Latitude in decimal degrees
Long/Lat [degrees min sec] Longitude / Latitude in degrees, minutes and seconds
View Coordinate System Menu
After changing the View Coordinate System, the headup display shows the coordinates in the chosen Coordinate
System, as well as the View Coordinate System. Note that the status line still displays the Scene Coordinate
System, which remains unchanged.
View Coordinate System changed to UTM

2.10.3. Coordinate System Dialogs
The Coordinate System Dialog lets you choose a Coordinate System for the scene and for imported data.
Choosing a coordinate system
The coordinate system chooser dialog is used both to
Select a Scene Coordinate System and
(if required) select a coordinate system for georeferenced data
Make sure to check the window title if you are unsure what the selected coordinate system is used for.

Select Scene Coordinate System
Use the Select Scene Coordinate System dialog to set the Scene Coordinate System. Browse through the
coordinate systems or use the search field to select the desired coordinate system.
When this dialog appears during the first import of georeferenced data, the previously selected coordinate system
for data import is suggested.
If you do not need a georeferenced coordinate system, the option No Projection Raw Data in Meters is
normally a good choice.
Select Scene Coordinate System Dialog
The Scene Coordinate System can only be a projected coordinate system, hence the geographic coordinate
systems are not available in this dialog.

Select data coordinate system
The data coordinate system pops up whenever georeferenced data is going to be imported, and no projection
details are found with the data.
Usually you will see a coordinate system suggested (normally the Scene Coordinate System) when this dialog
appears, whch normally is a good choice.
Select Data Coordinate System Dialog

Using the search field
Use the search expression field to filter the list of coordinate systems and search for a coordinate system by name
or authority code. Use the wildcard character * to define your search query. To reset the search filter and show all
available coordinate systems again, clear the search field and hit Enter (or the search button on the right)
The search field filters available coordinate systems

Load coordinate system from a prj file
When the required coordinate system is not available in the list, you choose a new projection by browsing to an
arbitary .prj file. Use the folder button on the top left to bring up the file dialog, and browse to the .prj file.
This feature also allows you to define your own custom coordinate system by creating your own .prj file with the
desired parameters.
Top-left button to load coordinate system from file

Custom Coordinate Systems
If a projection definition is found that can't be matched to one of the predefined coordinate systems, CityEngine
adds it as a new custom coordinate system. These have their authority set to USER, and an incremental number for
authority code.
Various custom user-added coordinate systems
2.10.4. Importing Georeferenced Data
How does CityEngine handle georeferenced data on import
Vector Data
All georeferenced vector data is reprojected to the Scene Coordinate System during import.
1. Georeferenced vector data requires a coordinate system on import, if no such data is found, the Select
data coordinate system Dialog pops up during import which lets the user choose the coordinate system
for the data.
2. If no Scene Coordinate System is defined for the scene previous to the data import, the Select Scene
Coordinate System Dialog pops up and lets the user set the Scene Coordinate System.
Shapefiles (.shp)
CityEngine looks for a .prj file with the same name in the same folder.
File Geodatabase (.gdb)
The coordinate system is read per layer of the gdb dataset.
KML/KMZ
KML/KMZ lat/lon data is always interpreted as WGS 1984.
When KML/KMZ dat is imported into a scene with no coordinate system set, UTM with matching zone is suggested
as Scene Coordinate System.
OpenStreetMap (.osm)
OSM lat/lon data is always interpreted as WGS 1984.
When OSM data is imported into a scene with no coordinate system set, UTM with matching zone is suggested as
Scene Coordinate System.
Image data is considered to be georeferenced if
it contains embedded georeferencing metadata
a world file is found that belongs to the image
a prj file is found that belongs to the image
No reprojection nor rotation is applied to image data on import. The image's coordinate system is used only as
reference system for location, extent and unit (translate and scale transformation) for the image data during import.
It is therefore important to have image data ready in the target coordinate system before importing into CityEngine.
(See behaviour for GeoTiffs below.)

Reference Coordinate System
CityEngine looks for a .prj file with the same name in the same folder to use as coordinate system for the data. If no
.prj file is found, the Select data coordinate system Dialog pops up and lets the user choose the coordinate system
for the data.
Map Extent
CityEngine looks for a world file (e.g. .jgw, tfw) in the same folder to read the extent of the data. The world file data
is interpreted in the unit found in the coordinate system of the data, and calculated accordingly if required.
If no world file is found, size and position of the map can be entered manually in the Map Layer Dialog.
Elevation range
CityEngine looks for minimum and maximum range values in the metadata embedded in the image. The range data
is interpreted in the unit found in the coordinate system of the data, and calculated accordingly if required.
If no elevation range is found, the elevation range of the map can be entered manually in the Map Layer Dialog.
Elevation range data is only used when the image is used as height map.
GeoTiff (.tif, .tiff with embedded metadata)
GeoTiff data is handled the same way as other georeferenced image data with the following differences:
If a coordinate system is defined with authority and code (e.g. ESRI:102132) in the GeoTiff metadata
tags, this information is used to set the data's coordinate system, and has precedence over a .prj file.
If no world file is present, the GeoTiff metadata tags are searched for map extent data. If present, the
data is treated the same way as in the world file case.

Parameters for location, extent and elevation range can still be entered manually for non-georeferenced
images in the Map Layer Dialog
2.11. 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. Esri FileGDB
5. Wavefront OBJ
6. Autodesk FBX
7. Collada DAE
8. Keyhole KMZ / KML
9. CityEngine Web Scene (3ws)
10. Renderman RIB
11. e-on Vue VOB
12. Script Based Exporter (Python)
13. Export Application Notes
2.11.1. General Export Reference
1. Supported Formats & Typical Usage
2. General Export Options
3. Formats Feature Comparison
Supported Formats & Typical Usage
Format Features/Typical Usage
Esri FileGDB Common file format for GIS workflows. Export to multipatch/multipoint/point/polyline geometry
types into a File-Geodatabase. Textures are supported.
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. Does not support instancing.
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).
Collada DAE Exports into a large number of DCC tools and rendering engines with support for asset-
instancing, layered-textures & file-referencing.
Keyhole KMZ / KML Exports into georeferenced earth browsers like ArcGlobe or Google Earth. Such models are
shared e.g. in Google Warehouse.
CityEngine Web
Scene (WebGL)
Exports scene to a CityEngine Web Scene file (.3ws). CityEngine Web Scenes can be
viewed in a web browser using CityEngine Web Viewer.
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-like template
shader, which allow for direct rendering without the need for any additional scene-setup tools.
Script Based
Export (Python)
Allows for execution of arbitrary Python commands during batch export.

Export dialog for the FBX Model Exporter
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.
See below for a comparison of the different formats with respect to material and shading features.
General Settings
Option Description
Output Path Path to the export location. The path must exist.
Base Name The base name of the exported files. Various suffixes will be appended depending on the other
export settings.
Export
Geometry
Models with Shape Fallback (Default)
If model generation fails, it will export the start shape geometry.
Models
Ignore the shape, if the model generation fails.
Shapes
Only export the start shape geometry.

Terrain Layers
Do not export any terrain layers (Default)
Export all visible terrain layers
Export all selected terrain layers
Export all terrain layers

Simplify
Terrains
Uses the reduceGeometry CGA operation to simplify the terrain geometry prior to export. This can
take a considerable amount of time, especially on higher resolution terrains - use with care.

Granularity Settings
Option Description
File Granularity
One file as long as Memory Budget is not exceeded
The geometry data is written into a single file if Memory Budget is zero, else Memory
Budget 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.
One file per start shape
Exports one geometry file per shape.
Memory Budget Maximum geometry file size in megabytes. See remarks above.
Mesh Granularity
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 (Default)
Inserted assets/meshes (see CGA insert operation) will be preserved and instanced.
Meshes generated by the grammar will be merged by material.

Geometry Settings
Option Description
Vertex Normals 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
Do not write any UV's
No texture coordinates will be exported.
Only write first layer of UV's
Only the first layer of texture coordinates will be exported (see CGA material attributes)
Write all UV layers
All layers will be exported
Local Offset
The local offset is computed for each individual shape.
None: Disable local offest
Model Centroid: use centroid of the generated model as offset,
Model Centroid Bottom: use centroid projected on bottom bound of the generated model as
offset,
Shape Centroid: use centroid of the shape as offset
Shape Centroid Bottom: use shape centroid projected on bottom bound as offset
Local and Global offsets can be queried in the Script-based export callback methods.
Global Offset Global offset for generated geometry
Set offset for x, y and z axes (Cartesian coordinate values).
Vertex Precision These values can be used to reduce the floating point precision of different geometry data
prior to the actual file output ( used to reduce file size in OBJ )
Merge ... within
precision
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.
Faces with holes Write as holes (available for Collada only): Write the actual hole information.
Triangulate faces with holes: Triangulate the face with holes if the export format doesn't
support holes natively.
Discard holes: Discard the hole information (ignore holes)
Convert holes to faces: Convert the holes to actual faces (creates coplanar faces)
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).
Texture Settings
Option Description
Collect Textures All referenced textures will be exported into the export target folder and the file references will be
adapted.
Miscellaneous Settings
Option Description
File Type
Choose among Binary or Text (ascii) based file creation.
Embed
Textures
Choose to reference the file path (Default) or embed the texture files within the binary file (FBX).
Shape
Name
Delimiter
This character will be used to resolve clashes in the shape names. Example for delimiter "_": {"shape",
"shape", "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... .
Existing
Files
Overwrite existing files
No file check is performed prior to writing the geometry files, all files are overwritten.
Skip existing files
Existing files (geometry, material and texture files) are not overwritten.

Other
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

Formats Feature Comparison
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
FileGDB No No No No Yes No
OBJ No No No No Yes No
FBX Yes (Note 1) No Yes Yes Yes No
DAE Yes No Yes (Note 2) Yes Yes (Note 3) Yes
KMZ / KML Yes No Yes (Note 2) Yes Yes (Note 3) Yes
3ws No Yes No Yes No No
RIB Yes Yes Yes Yes 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.
Note 5: Alembic support is experimental.
Further Reading
Export Quick Start: Step-by-step Guide
Esri FileGDB
Wavefront OBJ
Autodesk FBX
Collada DAE
Keyhole KMZ / KML
Renderman RIB
Export Application Notes
2.11.2. Supported Model Export Formats
1. Esri FileGDB
2. Wavefront OBJ
3. Autodesk FBX
4. Collada DAE
5. Keyhole KMZ / KML
6. CityEngine Web Scene (3ws)
7. Renderman RIB
8. e-on Vue VOB
9. Script Based Exporter (Python)
2.11.2.1. Exporting to Esri File Geodatabase
Format Description
The ESRI File Geodatabase (FGDB) is a file-based database for vector and raster data. It can be identified as folder
with the suffix .gdb. For example, myDatabase.gdb .
CityEngine only exports datasets of the type "FeatureClass".
Export Options for FileGDB
Choose which attribute data is exported. Options are:
Model Reports: report information generated by rules
Object Attributes: original object attributes
In addition to the global export options, the FileGeodatabase exporter contains an additional export page with the
following settings:
Export Layer: Include or exclude any selected layers from export.
Layer Name: Adjust the name of the selected layers. This will determine the name of the written
FileGDB dataset.
Feature Granularity: Choose the number of features which are created from a single CityEngine shape.
One Feature Per Shape: All geometry, attributes and reports generated for a single start
shape are merged and written into a single feature.
One Feature Per Leaf Shape: The geometry, attributes and reports of each leaf shape are
written to a separate feature.
Feature Class: Choose how existing feature classes are handled.
Replace Feature Class: deletes the current Feature Class and creates a new one.
Update Feature Class: if objects (based on OBJECTID) exist in the feature class, geometry
and attributes are updated on export. If the object does not exist, it is appended to the
feature class.
Update Feature Class Geometry: only the geometry of the existing feature is updated.
Further Reading
Export Quick Start: Step-by-step guide
General Export Reference

2.11.2.2. Wavefront OBJ Export
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 or
reflectivity) it is set to 4.
Kd Diffuse color, set to the value of material.color.
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).
d Opacity, set to the value of material.opacity.
map_d Opacity map, set to the value of material.opacitymap.
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
2.11.2.3. Autodesk FBX Export
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
CityEngine supports FBX 2014.1 (internal file format version 7.4.0).

Get the plugins for 3DS MAX and Maya here:
http://usa.autodesk.com/adsk/servlet/pc/item?id=10775855&siteID=123112

Specific Export Options for FBX
The FBX exporter supports the following additional settings:
Option Description
Create Shape Groups If enabled, a transformation node is inserted for each shape (i.e. building). Meshes will
not be merged by 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/products/fbx/overview).
Geometry and Transformation Data
CityEngine FBX Import Autodesk Maya
trigger
--> i("builtin:cube") s(1,1,1) t(1,0,1)
texture("uvtest.jpg")
setupProjection(0,scope.xy,'.5,'.5)
projectUV(0)

Exported scene via FBX in Autodesk Maya. Both "One
Mesh Per .." options have been disabled to avoid merging
any assets. In this case, each asset is parented to a
transformation node. Else, the transformation is applied to
the vertices.
Multi-Texturing and Layered Texture Nodes
The CityEngine material model multiplies all six textures (if
present) with the diffuse color. This example displays the
layering/multiplicaton of "colormap" and "dirtmap".
For FBX, CityEngine exports multiple textures
as "layered texture nodes" whose blend modes
are set 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
scale, translate and rotate textures
independently of the actual texture coordinates
stored inside the assets:
material.{...}.tu/tv = translate/offset
texture
material.{...}.su/sv = scale/repeat
texture
material.{...}.rw = rotate texture
around face normal
Upon FBX import into maya, CityEngine's tu and tv attributes are
mapped to the "Offset" parameter of maya's place2dTexture
nodes, su/sv are mapped to the "RepeatUV" parameter and rw is
mapped to the "Rotate Frame" parameter.
Further Reading
2.11.2.4. Collada DAE Export
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
CityEngine supports OpenCollada (871).

Get the plugins for 3DS MAX and Maya here:
https://github.com/KhronosGroup/OpenCOLLADA/wiki/OpenCOLLADA-Tools
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.
Vertex Indexing Choose between indexed polygon vertices or separated vertex copies per polygon.
CGA Mapping to Collada / Examples
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
transformation matrices)
<library_visual_scenes>
<visual_scene id="VisualSceneNode" 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 Bump/Normal Maps Because of a restriction of COLLADA, CityEngine bump and normal maps are
exported as BUMP maps in the effect extra tag:
<effect id="MyEffect">
<profile_COMMON>
<technique sid="common">
<lambert>...</lambert>
<extra>
<technique>
<bump>
<texture>...</texture>
</bump>
</technique>
</extra>
</technique>
</profile_COMMON>
</effect>

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
Keyhole KMZ / KML
2.11.2.5. Keyhole KMZ / KML Export
Format Description
Keyhole Markup Language (KML) is an XML notation for expressing geographic annotation and visualization within
Internet-based, two-dimensional maps and three-dimensional Earth browsers. KML was developed for use with
Google Earth, which was originally named Keyhole Earth Viewer. It was created by Keyhole Inc, which was acquired
by Google in 2004. KML is an international standard of the Open Geospatial Consortium. Google Earth was the first
program able to view and graphically edit KML files. Other projects such as Marble have also started to develop
KML support.. [this is an excerpt from the Wikipedia KML page ].
KML-documents may contain geospatial data either in vector or raster form. Vector objects like points, lines,
polygons and entire models in the COLLADA format (DAE) are defined as "Placemark" elements; airborne and
satellite imagery are modeled as "groundOverlay" elements.
Besides the geometry, Placemark elements may involve name, description, predefined style, angle and distance of
view, a time stamp, but also other data e.g. from a geoinformation system. The same holds for GroundOverlay
elements, where instead of the geometry a coordinates section has to be defined for georeferencing.
Please refer to the Keyhole KML reference page for the full format description.
CityEngine at the time just supports the use of KMZ / KML for three dimensional models referring to a Collada
DAE file, where KML determines geographic position, orientation and scale of that model.
Specific Export Options for KMZ / KML
In addition to the general export options, Keyhole KMZ / KML adds the following switches:
Option Description
Altitude Mode Controls what altitude tags are written to the kml/kmz files
clampToGround: Aligns the object to the ground, altitude is ignored.
absolute: ignores the actual ground elevation. Note that here the ground elevation and
the altitude have to coincide precisely.
Write Compressed Files If set, the written KML file is put into a KMZ archive file along with the other needed files
like the DAE file(s) and texture images.
Heading Correction ArcGlobe, Google Earth and other earth browsers interpret the Collada DAE file's content
differently: for the case of Google Earth the Heading Correction switch has to be turned on
for having correct results.
Vertex Indexing Choose between indexed polygon vertices or separated vertex copies per polygon.
Placemark Locations Exact spatial references per model: Unprojects placemark locations per shape.
Recommended for unconnected objects (such as buildings) for bigger areas.
Optimized Model placement: Optimizes placemark locations to ensure correct relative
positions (unprojection only in the lead shape, other shapes are referenced relatively).
Recommended for connected objects (such as streets) over small areas.
Use the KML export presets Google Earth Compatibility or Arc Globe Compatibility to set recommended
options for these programs.
CityEngine's KML Output
When saving some selected objects by the name "MyPlacemarks", the exporter will write the file
"MyPlacemarks.kml"; next to it, there will be a folder named MyPlacemarks.kml-files containing the associated DAE
file and textures. Here is what the KML file will look like:
Example KML File Output
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2" xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:gx="http://www.google.com/kml/ext/2.2" xmlns:kml="http://www.opengis.net/kml/2.2">
<Document>
<name>MyPlacemarks</name>
<Folder>
<Placemark>
<name>aPlacemark</name>
<Model>
<altitudeMode>clampToGround</altitudeMode>
<Location>
<longitude>-75.17193217718045</longitude>
<latitude>39.95381194059072</latitude>
<altitude>10.82616576552391</altitude>
</Location>
<Orientation>
<heading>0.0</heading>
<tilt>0.0</tilt>
<roll>0.0</roll>
</Orientation>
<Scale>
<x>1.0</x>
<y>1.0</y>
<z>1.0</z>
</Scale>
<Link>
<href>MyPlacemarks.kml-files/aPlacemark.dae</href>
</Link>
</Model>
</Placemark>
<Placemark>
<name>anotherPlacemark</name>
...
</Placemark>
...
</Folder>
<Document>
</kml>

Further Reading
Collada DAE
2.11.2.6. Exporting to CityEngine Web Scene (3ws)
Format Description
CityEngine Web Scene (3ws) is a custom, web-optimized format that can be shared on ArcGIS online and viewed
with the CityEngine Web Viewer.

Select the content you want to export in the 3D Viewport, and start the exporter.
File Export Models... CityEngine Web Scene
Specific Export Options for 3ws
In addition to the general export options, the Web Scene export has an additional export page which allows to
control settings of individual layers:

Export
Checkboxes denote if a layer's contents are exported. The initial state of this checkbox depends on the 3D viewport
selection, before the export dialog is opened.
Layer Name
The layer name, as it is set in the CityEngine scene.
Layer Group
Layers can be combined to layer groups: All layers with the same group name are collected in a Layer Group. In
CityEngine Web Viewer, only one layer of a group is visible at a time (exclusive visibility). Furtermore, all layer
groups enable Swipe View in CityEngine Web Viewer.
You can name your CityEngine scene layers to automatically have their layer group set by using the pattern
GROUPNAME.LAYERNAME.
Layer State
Parameter Function
Backdrop Layer will not appear in layer pane, is always visible.
Visible Layer appears in layer pane and can be set visible or hidden. Initial state is visible.
Hidden Layer appears in layer pane and can be set visible or hidden. Initial state is
hidden..
Interaction
Parameter Function
Scene settings Use global option set in Object Interaction in first export dialog page
Locked Objects in this layer will not be selectable. All objects are combined to a single
entity. Therefore locked layers contain a way smaller object count than pickable
layers, which can often improve performance in the Web Viewer.
As all objects are combined, per-object metadata can not be written (No Metadata
option only).
Pickable Objects in this layer will be selectable, all objects are exported as single entities
(features). High object count in a layer can decrease performance, it is therefore
recommended to only set layers to pickable where required.
Metadata
Parameter Function
Scene settings Use global option set in Object Metadata in first export dialog page
All Write both object attributes and reports to object metadata.
Attributes Write object attributes to object metadata.
Reports Write generated report data to object metadata
None Do not include object attributes nor report data..
Texture Quality
Parameter Function
Scene settings Use global option set in Textures in first export dialog page
High Quality Convert all layer textures to JPG with high quality
Medium Quality Convert all layer textures to JPG with medium quality
Low Quality Convert all layer textures to JPG with low quality
Half Sized Resize all layer textures by 50% and convert to medium quality JPG
Compact Resize all layer textures to 50% size but with a maximum of 256x256 pixels and
convert to low quality JPG
Original Textures Use original textures (Note: only JPG and PNG textures are supported in Web
Viewer. Other textures formats will appear black)
No Textures Do not include textures in layer objects.
In all Texture Quality modes except "Original Textures" the texture size will be limited to 2048 pixels.
Other 3ws export features
Bookmarks defined in a CityEngine scene will be exported directly to a Web Scene, and are available in
the bookmarks menu of CityEngine Web Viewer. Note that different camera angles are not supported at
the moment, Web Viewer displays all views and view bookmarks with the default CityEngine angle (54
degrees).
The current camera position and direction before starting the export is stored to the Web Scene and
used as initial view in CityEngine Web Viewer.
The current shadow and ambient occlusion settings of a CityEngine scene are exported to the .3ws file,
and are used as initial values in the Web Viewer. Be careful with enabling shadow and ambient
occlusion before exporting, as on some machines Web Viewer might not support direct or diffuse
shadows, or will get a performance impact.
As initial settings are stored during export, changing options (such as shadow settings) in Web Scene preview
will not change the intial configuration of the Web Scene.
Export tricks and tips
Due to browser limitations and to ensure compatibility on less powerful systems we recommend to keep
Web Scene size (size of .3ws file) below 15MB. Reduce your Web Scene size by
choose a smaller extent for export (select less objects)
Use a smaller terrain resolution (512x512 or less). Terrain resolution can be set in Inspector
pane of Terrain Layer, Layer Attributes, terrain resolution u and v.
finetune Texture quality export options (use compact or half-sized)
or manually convert your textures to lower-resolution JPG or PNG and use texture quality
Original
set export option Interaction to locked where pickability is not required
reduce the geometric complexity of the models (e.g. lower level of detail, less details on
streets).
By default, terrain geometry is simplified during export. This can take a while for complex terrains. To
speed up this process,
use a smaller terrain resolution (recommended 512x512). Terrain resolution can be set in
Inspector pane of Terrain Layer, Layer Attributes, terrain resolution u and v.
disable Simplify Terrain Meshes in Main export options Optimizations (not
recommended, as this will increase .3ws file size)
When setting Texture quality to Original Textures, make sure the layer only uses JPG and PNG
textures. Other formats are not supported by WebGL, and will appear black in the Web Viewer.
When preparing Web Scenes for a wider audience, keep in mind that a Web Scene might not run as
fluent (or not at all) on other, less powerful systems (less memory, less powerful graphics card). Reduce
the exported extent and 3ws file size to ensure wider compatibility.
Further Reading

2.11.2.7. Renderman RIB Export
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 libraries 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
Options
Include
Camera
Data
If enabled, CityEngine will export additional RIB statements to the master rib file (current camera
position of "Perspective" camera and default lights) to make the exported rib files directly renderable
without the need for additional tools.
Misc
Options
Write
Compressed
If enabled, CityEngine will instruct the RIB library to write to compressed/binary rib files (not available
with every renderman package).
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;
float reflectivity = 0.0;
string diffuseMap = "";
string diffuseMap1 = "";
string specularMap = "";
string opacityMap = "";
string bumpMap = "";
string normalMap = "";

float diffuseMapScale[2] = { 1, 1 };
float diffuseMap1Scale[2] = { 1, 1 };
float specularMapScale[2] = { 1, 1 };
float opacityMapScale[2] = { 1, 1 };
float bumpMapScale[2] = { 1, 1 };
float normalMapScale[2] = { 1, 1 };

float diffuseMapTranslate[2] = { 0, 0 };
float diffuseMap1Translate[2] = { 0, 0 };
float specularMapTranslate[2] = { 0, 0 };
float opacityMapTranslate[2] = { 0, 0 };
float bumpMapTranslate[2] = { 0, 0 };
float normalMapTranslate[2] = { 0, 0 };

float diffuseMapRotate = 0.0;
float diffuseMap1Rotate = 0.0;
float specularMapRotate = 0.0;
float opacityMapRotate = 0.0;
float bumpMapRotate = 0.0;
float normalMapRotate = 0.0;
varying float uv1[2] = { 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 (diffuseMap != "")
{
float u = (s - diffuseMapTranslate[0]) * diffuseMapScale[0];
float v = (t - diffuseMapTranslate[1]) * diffuseMapScale[1];
tex *= color texture(diffuseMap, u, v);
}
if (diffuseMap1 != "")
{
float u = (uv2[0] - diffuseMap1Translate[0]) * diffuseMap1Scale[0];
float v = (uv2[1] - diffuseMap1Translate[1]) * diffuseMap1Scale[1];
tex *= color texture(diffuseMap1, u, v);
}
/* compute shading variables */
normal Nf = faceforward(normalize(N), I);
vector V = -normalize(I);
/*
* now add it all together
*/
Oi = Os;
Ci = Os * (Cs * tex * ( Kg * globalColor +
Ka * ambientColor * ambient() +
Kd * diffuseColor * diffuse(Nf) ) +
Ks * specularColor * phong(Nf, V, shininess) );
}
Further Reading
2.11.2.8. E-On Software Vue VOB Export
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 11.5.
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
2.11.2.9. 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 Scripting Interface
Python Reference
2.11.3. 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 Interoperability 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 (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 - Multi-Texturing
Cinema 4D OBJ, DAE - Multi-Texturing
Deep Exploration OBJ, FBX, DAE
Google Earth (Windows) DAE, KML + Triangulate, - Multi-Texturing
Google Earth (Linux) DAE, KML + Triangulate, - Textures, - Materials
Houdini OBJ, FBX - Multi-Texturing
Lightwave OBJ
Polytrans OBJ, FBX, DAE
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
Note #4: 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. With CityEngine 2013 and later, 32 bit systems are no more supported.
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).
Note #5: Known Interoperability Limitations and Issues
CityEngine Export Limitations
Esri FileGDB
Textures are exported without alpha channels.
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
FBX: At least the FBX plugin 2013 is needed to get correct UV transformation order.
COLLADA: All texture placement nodes which are assigned to the same texture file are merged
together (i.e. all texture placements end up with the same parameters).
DeepExploration
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
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.
Note #6: General 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
Wavefront OBJ
Autodesk FBX
Collada DAE
Keyhole KMZ / KML
Renderman RIB
2.11.4. CityEngine Web Scene
CityEngine Web Scene (3ws) is a custom, web-optimized format that can be viewed with CityEngine Web
Viewer and shared on ArcGIS online for simple sharing.
Workflow
1. Export CityEngine scene to a Web Scene (.3ws)
Export CityEngine scenes to a Web Scene file using the CityEngine Web Scene exporter.
2. Preview Web Scene
After export, preview your Web Scene locally to make sure it contains the desired data.
3. Publish to ArcGIS online
Web Scenes can be published to ArcGIS online where you can easily share them with the world.
Or save Web Scene and Viewer to package file
Save a Web Scene package to a file and publish it manually to your own webserver.

CityEngine Web Viewer displays a Web Scene
Additional details to CityEngine Web Viewer, system requirements and troubleshooting hints can be found in the
ArcGIS online help.
2.12. Mapping Attributes
1. Attributes and Sources
2. Mapping Attributes with the Connection Editor
3. Mapping Image Data to Rule Attributes
4. Mapping Object Attributes via Layer Attributes
2.12.1. Attributes, Sources and Connections
Attributes and Parameters
Depending on their type, CityEngine scene objects can have a varying set of attributes, used for operations on the
object. As an example, a node object has a set of Intersection Parameters that control the creation of its crossing
shapes.

Crossing Parameters displayed in the Inspector
Attribute Sources and Display
These attributes can have different sources, which allows connecting the values of the attributes in various ways.
Sources can be of the types
Default
Object
Shape
User
Layer
The easiest way to create connections and set sources is using the Connection Editor.
Default
The algorithm-specific default value is used, marked with (Default). In case of rule attributes, the default value is
marked with (Rule), stating that the default value is defined by the initial value of the attribute in the rule file.
Object
The value is taken from the corresponding object attribute. The value is displayed in italic, and marked with (Object).
Shape
A rule attribute can use a shape source to take it's value from the parent shape. For example a street shape may
sample the street segment's streetWidth. The value is displayed in italic, and marked with (Shape).
User
A value that is entered by the user. It is displayed in bold. As soon as the user sets a value (or uses a slider) in the
Inspector, the value changes to user source.
Layer
The value is connected to a layer, or to be more exact, to a layer attribute. The value is displayed in italic, and
marked with the source layer in brackets. See Layer Attributes for details.

Whenever you enter a value to a parameter or attribute, it will automatically change to user source.

Example street parameters

Street parameters with different sources (blue box)
shapeCreation default value
streetWidth connected to layer Streetnetwork
streetOffset user specified value
sidewalkWidthLeft connected to object attribute (below)
sidewalkWidthRight connected to layer Meshes
precision default value
laneWidth user specified value
Example Rule attributes

Rule attributes with different sources (blue box)
height default value from rule file
lanes user specified value
minArcRadius set from intersection shape (above), where it is sampled from another layer
precision set from intersection shape (above), where it is the default value
speedLimit connected to layer Meshes
valency connected to object attribute (below)
List/Table Editor
For special sets of object attributes there is a "Edit List" dialog. This is the case for:
Attributes of type string which contains a ';' seperated list (each item needs to be terminated with a ';').
Attributes with a common prefix in the name are combined into one table editor.
These cases are auto-detected and the "Edit List" button is shown.

Shape Object Attributes with Edit List button (right)
Clicking on the button opens up an editor which allows for convenient excel-editing of the lists.
Edit Lists dialog which enables table-like editing
2.12.2. Mapping Attributes with Connection Editor
Object Parameters in CityEngine can be controlled from various sources. The Connection Editor helps to
create these attribute connections.
Connection Editor
To edit the connection on a specific attribute, locate the attribute in the Inspector, and click on the connection icon
to start the Connection Editor.
Starting the Connection Editor for minArcRadius by clicking on the Connect icon.
The Connection Editor displayed for attribute minArcRadius
Default value
Reset the attribute to it's default value. Depending on the attributes type this will reset to the default value of the
algorithm (e.g. Street Shape creation) or to the default value from the rule file (Rule Parameter).
User-defined value
Use the user-defined value on your attribute. If a user value has been set earlier, the old value is used, otherwise
the current value will be set as user value.
Setting a user value is normally done by entering a value directly in the Inspector.
Object attribute
Connect your attribute to an object attribute. This option is only available if
1. the scene object has an object attribute with a matching name
2. the type of the object attribute matches the required type of the attribute (e.g. streetWidth requires a
float or int type, whereas a string type won't work)
Shape parameter
Connect your attribute to the parent shape parameter. This option is only available if
1. it is a rule file attribute
2. the rule file is attached to a shape of an intersection, street, or block (a lot)
3. the attribute has the same name as a shape parameter
4. the type of the shape parameter matches the required type of the attribute (e.g. streetWidth requires a
float or int type, whereas a string type won't work)
Layer attribute
Connect your attribute to Layer Attributes from arbitrary layers. Choose the source layer from the upper dropdown
menu, and the desired Layer Attribute from the lower dropdown menu.
Each layer will provide a list of its available layer attributes, consisting of
Channel attributes for Map Layers: the color channels (red, blue, green, alpha, brightness, ...) of the
layers image. Marked as (Map Channel).
Object attributes: Object attributes of objects in the source layer. Marked as (Object attribute).
Other attributes: Existing expressions or mappings. Marked as (Layer attribute) or (Expression).
Layer connections are shared for all objects per layer, means you will change the behaviour for all connected
attributes in this layer that share the same name.
If a layer attribute with the same name as your attribute already exists, be aware that your new mapping might
override the existing one.
2.12.3. Mapping Image Data to Rule Attributes
Map 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 from 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.
The image below is going to be used as source image to control the height of a set of buildings.
Image to be used as skyline map

Assume you are starting from a scene with a set of building footprints like in the image below:
A set of building footprints
All shapes have a rule file assigned that extrudes the footprints to a certain height
attr height = 30
Lot --> extrude(height)
Creating the map layer
Create a new mapping layer, choose your skyline map, set the bounds to fit your scene, and add a new attribute
skylineValue. Its range will define the range of the building heights.
Settings for skyline layer
Skyline layer added to the scene
Connection Editor
Select all footprint shapes, and click on the connection icon for rule attribute height in the Inspector. Choose layer
attribute, select the new Skyline map layer and the attribute skylineValue
Connecting rule attribute height to Skyline Map Layer
Building heights controlled from Map Layer

2.12.4. Mapping Object Attributes via Layer Attribute
Layer Attributes
Every layer (Except the Scene Light and the Panorama layer) can have an arbitary set of layer attributes defined.
Whereas map layers normally use their image data as source for layer attributes, vector data layers can query their
vector objects to layer attributes.
Object Attribute Mapping
Layer attributes can be used to map object attributes of its scene objects to attributes with different names, or to
objects on other layers.
For simple cases, attribute mapping can be done conveniently using the Connection Editor
Object attributes of nodes, segments and shapes can be mapped via layer attributes using the command
getObjectAttr(Object_Attribute, Should_Sample)
This command searches matching object attributes within the layer that the object attribute is created for.
If the Should_Sample argument is false, only the shape's object attributes will be examined. If Should_Sample is
true (the default value), and the shape has no such object attribute, overlapping shapes in the attribute layer will be
sampled for the specified Object_Attribute.
If you use the object attribute width on street segments to control the width of created street shapes (the street
parameter streetWidth), getObjectAttr allows the attribute layer to obtain the value from other objects.
attr streetWidth = getObjectAttr("width")
To use this layer attribute set the source of the streetWidth parameter in the Street Parameters pane to its own
layer.
A more complex example is shown below:
streetWidth attribute mapped from object attribute width
The layer attribute streetWidth can now be used to control the street width of street shapes.
When importing osm, shape or gdb data, a predefined set of layer attributes is automatically created on the
imported layers. Select the new layers and show or modify the created layer attributes in the inspector.

See also
Editing Map Layer Attributes

2.13. Publish a CityEngine Web Scene to ArcGIS Online / Portal
ArcGIS Online / Portal for ArcGIS
ArcGIS Online is an online platform to share maps and geographic information with others. You can share all kinds
of geographic information: maps, map layers, features, editing templates (using layer packages), imagery, and
analytic results. Once you signed up on ArcGIS Online, you can use your own personal online ArcGIS workspace in
the cloud, where you can share data packages as well as search for and find others' content, which you can use in
ArcGIS for Desktop.
Operations for signing into the portal and share data are located in CityEngine's Main MenuFile
Sign In
To sign into the portal, click FileSign In . After successful signin, the menu item will change to Sign out, followed
by your user name.

Sharing data from CityEngine
In CityEngine, you can directly share CityEngine Web Scenes and Rule Packages to an ArcGIS Portal. CityEngine
will walk you through the process of preparing, packaging, and sharing the information online.
1. In the menu, choose FileShare as...
2. browse to the file you want to share (supported file types are.3ws, .cga, *.cgb, *.rpk)
3. the package dialog guides you through the sharing process
Share CityEngine Web Scenes (3ws)
Share Rule Packages (rpk)

Sharing data on a different Portal
By default CityEngine targets the main ArcGIS Online portal at www.arcgis.com. If you belong to an organzation on
ArcGIS Online, or if you want to share your data to an on-premise installation of Portal for ArcGIS, define a different
portal URL in CityEngine network preferences.

2.14. Facade Wizard
1. Facade Wizard Overview
2.14.1. Facade Wizard Overview
Example facade created with the Facade Wizard in about 5 minutes.
CityEngine features 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 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 is necessary to manually define 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 or theight can be specified at any time using the context menu's "Set Region Width / Height..."
entry.
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.
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.
2.14.2. Crop Image Tool
The Crop Image Tool provides an intuitive and effective means for the preparation of facade textures from
ground based facade images - perspective correction and region selection are done in one step. Starting with a
provided facade bounds guess the facade or an element of interest is selected, adjusted visually in a self-
explaining way while watching the result in real time. It is opened by selecting ShapesCrop Image... from the
main menu or Crop Image... from the context menu on an image file in the File Navigator.

The Crop Image Tool has two viewports: on the left the perspective frame is manipulated and on the right the result may be
observed directly
Interface
The Crop Image Tool is divided into left and right:
On the left the source image is loaded with the Source Image... button. The viewport displays the
original image with the perspective frame on top. That frame may be adjusted in order to crop the
facade or element of choice.
The right viewport shows the perspectively corrected frame selection from the left. When adjusted
readily, the output image is stored with Destination Image...
Perspective frame manipulation
Corners: Drag the corners directly into position.
Corner handles: Adjust the horizontal or the vertical side line of a corner while keeping the other side
line as is.
Side line: Move that side line perspectively in parallel.
Zoom and Pan
In both viewports:
Zoom: Mouse wheel.
Pan: Move mouse while pressing middle mouse button and ALT .
3. CGA Shape Grammar Reference
Operations Shape Attributes Builtin Functions Other Keywords CGA Utilities Misc Information
Operations
Geometry Creation

i (insert)

extrude

envelope

taper

roofGable

roofHip

roofPyramid

roofShed

innerRect
Geometry Subdivision

split

comp

offset

setback

shapeL

shapeU

shapeO

scatter
Geometry Manipulation

cleanupGeometry

convexify

deleteHoles

reverseNormals

setNormals

mirror

reduceGeometry

trim
Texturing

texture

setupProjection

projectUV

translateUV

scaleUV

normalizeUV

tileUV

rotateUV

deleteUV
Transformations

t (scope translate)

translate

s (scope size)

r (scope rotate)

rotate

center
Scope

alignScopeToAxes

alignScopeToGeometry

rotateScope

setPivot

mirrorScope
Flow Control

pop push NIL
Attributes

set

color

report

print
Shape Attributes
Shape Attributes are properties of the current shape. They can always be read (like functions) and some of them
can be set with the set operation.
comp initialShape material pivot
scope seedian split trim
uid
Builtin Functions
Functions always return a value and do not alter the current shape (with the exception of probability functions which
change the state of the shape's random number generator).
Math Functions
abs acos asin atan
atan2 ceil cos exp
floor isinf isnan ln
log10 pow rint sin
sqrt tan
Probability Functions
p rand
Conversion Functions
bool float sel str
String Functions
count find len substring
Geometry Functions
geometry.area geometry.angle geometry.{du|dv} geometry.isClosedSurface
geometry.isConcave geometry.isInstanced geometry.isOriented geometry.isPlanar
geometry.isRectangular geometry.nEdges geometry.nFaces geometry.nHoles
geometry.nVertices geometry.
{uMin|uMax|vMin|vMax}
geometry.volume
File Functions
fileExists fileSearch
Asset and Image Functions
assetInfo assetsSortRatio assetsSortSize imageInfo
imagesSortRatio
Occlusion Functions
inside overlaps touches
Miscellaneous Functions
convert getGeoCoord print Simple Types Operations
Other Keywords
attr const import style
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 listCount listFirst
listIndex listItem listLast listRandom
listRange listRemove listRemoveAll listRetainAll
listSize listTerminate
File, Asset and Image Utility Functions
assetApproxRatio assetApproxSize assetBestRatio assetBestSize
assetFitSize fileBasename fileDirectory fileExtension
fileName fileRandom imageApproxRatio imageBestRatio
Color Utility Functions
colorRamp
Miscellaneous Information
CGA Changelog Annotations Asset Search Builtin Assets
Texturing Euler Angles

3.1.1. alignScopeToAxes
Synopsis
alignScopeToAxes()
alignScopeToAxes(alignAxesSelector)
Parameters
alignAxesSelector (selstr)
{x | y | z} The world coordinate axis to align to
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).
Variants of the operation align only one axis:
x axis of the scope (the z axis is then projected to the world coordinates yz-plane).
y axis of the scope (the x axis is then projected to the world coordinates xz-plane).
z axis of the scope (the x axis is then projected to the world coordinates xy-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.
3.1.2. 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
Aligning to the lowest edge
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, any, world.lowest)

Applying alignScopeToGeometry() with the any and world.lowest
selectors 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).
3.1.3. 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.
3.1.4. cleanupGeometry operation
Synopsis
cleanupGeometry(componentSelector, tol)
Parameters
componentSelector (selstr)
What components to clean up:
vertices: merges vertices and removes colinear vertices.
edges: merges vertices and removes shared edges between coplanar faces.
faces: merges vertices and removes duplicate faces and degenerated faces with small
area.
all: cleans up all components.
tol (float)
Controls the rigorousness of the cleanup operation. Valid values are in the range [0, 1]. While 0 only
cleans up matching components (e.g. vertices with identical coordinates are merged or adjacent faces
with identical normals are combined), 1 is more aggressive: vertices up to a distance of 1m are merged,
and normals with intermediate angles up to 10 degrees are considered coplanar. For values in-between
0 and 1 linear interpolation is applied.
The cleanupGeometry operation cleans up the current shape's geometry. This allows for optimizing the
geometry for subsequent cga operations.
Related
convexify operation
innerRect operation
mirror operation
reduceGeometry operation
reverseNormals operation
setNormals operation
trim operation
Examples
Cleaning up a triangulated asset
Init-->
i("myHouse.dae")
The original asset (464 faces, 758 vertices).
Init-->
i("myHouse.dae")
cleanupGeometry(all, 0)
Mild cleanup removes most disturbing edges
(190 faces, 752 vertices).
Init-->
i("myHouse.dae")
cleanupGeometry(all, 0.1)
Increasing the tolerance gets rid of the remaining
nasty edges (146 faces, 616 vertices).
3.1.5. color operation
Synopsis
color(s)
color(r,g,b)
color(r,g,b,o)
Parameters
s (string)
Color to set, in the format "#rrggbb" or "#rrggbboo" (hex).
r,g,b (float,float,float)
Color to set in red, green, blue components (range is 0.0 to 1.0).
r,g,b,o (float,float,float,float)
Color to set in red, green, blue, opacity components (range is 0.0 to 1.0).
The color operation sets the color of the current shape's material.
Note: this command has the same effect as set(material.color.{r|g|b}, 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 : color(1, 0, 0) 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.
3.1.6. 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, object.side: 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,
world.side: 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 the section below for more details.
street.front, street.back, street.left, street.right, street.side: If the
streetWidth attribute is available on the initial shape, these selectors can be used to identify
street-facing components. See the section below for more details.
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!

Street Selectors
Components adjacent to a street can be selected with the street.front selector, rear components can be selected
with the street.back selector, and components in between front and back can be selected with the street.left
and street.right selectors. street.side combines left and right components.
The picture above shows some examples for the street.xxx selectors.
These selectors depend on the availability of the streetWidth attribute map; see Auto-generated street width
attributes. If the attribute is not available, component selection falls back to the object.xxx selectors.
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.
3.1.7. 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.
Related
cleanupGeometry operation
innerRect operation
mirror operation
trim 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:

3.1.8. deleteHoles operation
Synopsis
deleteHoles()
Parameters
The deleteteHoles operation deletes the holes in the faces of the current shape's geometry.
Related
geometry.nHoles function
3.1.9. envelope
Synopsis
envelope(direction, maxHeight, frontBaseHeight, frontAngle)
envelope(direction, maxHeight, frontBaseHeight, frontAngle, backBaseHeight, backAngle)
envelope(direction, maxHeight, frontBaseHeight, frontAngle, backBaseHeight, backAngle,
sideBaseHeight, sideAngle)
envelope(direction, maxHeight, frontBaseHeight, frontAngle, backBaseHeight, backAngle,
rightBaseHeight, rightAngle, leftBaseHeight, leftAngle)
Parameters
direction (selstring)
Direction along which the envelope is errected (normal | world.up).
maxHeight (float)
Maximum height of the envelope in meters. If this height is reached, the volume is cut and sealed
horizontally.
frontBaseHeight (float)
Base height of the front sides in meters.
frontAngle (float)
Slope angle of front sides in degrees.
backBaseHeight (float)
Base height of the back sides in meters.
backAngle (float)
Slope angle of back sides in degrees.
sideBaseHeight (float)
Base height of both the right and left sides in meters.
sideAngle (float)
Slope angle of both the right and left sides in degrees.
rightBaseHeight (float)
Base height of the right sides in meters.
rightAngle (float)
Slope angle of right sides in degrees.
leftBaseHeight (float)
Base height of the left sides in meters.
leftAngle (float)
Slope angle of left sides in degrees.
Creates a building envelope above each face of the current shape's geometry. Each edge of the face is
classified according to the street.front, street.back, street.right, street.left, street.side selectors.
Sides with the according baseHeights are then built perpendicular to the face. Finally, sloped planes are added at
the top of each side, with the according slope angle.
Evaluation of the street.xxx selectors is based on the streetWidth attribute, see Auto-generated street width
attributes. If the attribute is not available, component selection falls back to the object.xxx selectors.
Basic envelope() operation parameters. The baseHeight and angle parameters of the other sides are analogue.
Example of street.front, street.back, street.right, street.left, street.side selectors applied on a lot of a
block (with auto-generated streetWidth attributes).

Related
extrude operation
offset operation
roofGable operation
roofHip operation
roofPyramid operation
roofShed operation
taper operation
Examples
Street-facing Slope
Lot-->
setback(10) { street.front : color(0,1,0)
FrontYard |
remainder : Building }
Building-->
envelope(normal, 50, 15, 30)

The example code above creates a building envelope with a slope of 30 degrees facing the street-side. Eave
height is 15 meters. Before creating the envelope, a front yard of 10 meters is split from the lot using the setback
operation in conjunction with the street.front selector.
3.1.10. extrude
Synopsis
extrude(height)
extrude(axisWorld, height)
Parameters
height (float)
How many units to extrude.
axisWorld (selstring)
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
envelope operation
offset operation
roofGable operation
roofHip operation
roofShed operation
taper 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.
3.1.11. 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
geometry.isInstanced function
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.
3.1.12. 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.
3.1.13. 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
convexify operation
innerRect operation
mirrorScope operation
s operation
trim operation
3.1.14. 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
3.1.15. NIL operation
Synopsis
NIL
The NIL operation deletes the current shape from the shape tree. It can be used e.g. to create holes in split
operations or to terminate recursive rules.
Related
push/pop operations
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
3.1.16. normalizeUV operation
Synopsis
normalizeUV(uvSet, uvNormalizeMode, uvNormalizeType)
Parameters
uvSet
Number of texture coordinates set (integer number in [0,5]). The numbering corresponds to the texture
layers of the material attribute, see also Texturing: Essential Knowledge.
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
translateUV operation
setupProjection operation
texture operation
material.map attribute
3.1.17. 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.
3.1.18. 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
NIL 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.
3.1.19. 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.
3.1.20. projectUV operation
Synopsis
projectUV(uvSet)
Parameters
uvSet
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
normalizeUV operation
rotateUV operation
scaleUV operation
texture operation
scope attribute
Example
Please refer to the examples in the setupProjection reference.
3.1.22. 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.
3.1.23. reduceGeometry operation
Synopsis
reduceGeometry(tol)
Parameters
tol (float)
Controls the number of vertices which are going to be removed from the geometry. Valid values are in
the range [0,1]. For instance, a value of 0.2 will reduce the vertex count of the geometry by 20%.
The reduceGeometry operation simplifies the geometry by applying a series of edge collapses.
Related
convexify operation
innerRect operation
mirror operation
trim operation
Examples
Reducing a Terrain
The picture above shows a shaded terrain mesh. Left: the original (16384 vertices, 16129 faces). Right: after
reduceGeometry(0.8) (3276 vertices, 5066 faces).
Closeup of the terrain meshes from the prvious picture. Left original, right reduced.
3.1.24. 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 Python Manual.
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.
3.1.25. 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
convexify operation
innerRect operation
mirror operation
s operation
trim 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.
Left box: face with index=0 not inverted right box: face with index=0 inverted
Lot -->
extrude(world.y,1)
comp(f){side: Facade}
Facade -->
case comp.index == 0:
color("#ff0000")
# = red
t(0,0,0.1)
else:
color("#00ff00")
# = green
t(0,0,0.1)
Lot -->
extrude(world.y,1)
comp(f){side: Facade}
Facade -->
case comp.index == 0:
color("#ff0000")
# = red
t(0,0,0.1)
reverseNormals
else:
color("#00ff00")
# = 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.
3.1.26. 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
envelope operation
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
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.
3.1.27. 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.
Scope
the first face)
Related
envelope operation
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
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.
3.1.28. 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.
Scope
the first face)
Related
envelope operation
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.
3.1.29. 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.
Scope
the first face)
Related
envelope operation
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
There is exactly one side roof face per Top shape edge.
Edge index should not be a concave edge!
3.1.30. 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 relative to the world origin.
3.1.31. 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
3.1.32. rotateUV
Synopsis
rotateUV(uvSet, rotAngle)
Parameters
uvSet
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:
3.1.33. 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)

3.1.34. 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 only contains one vertex, you probably want ti insert a geometry using the
i() operation.
Examples
Point Distribution on a Surface
Init-->
scatter(surface, 100, uniform) { Leaf }
Leaf-->
i("builtin:cube")
s(0.2,0.3,0.1)
color("#ff0000")
Uniform point distribution on a surface.
Init-->
scatter(surface, 100, gaussian) { Leaf }
Leaf-->
i("builtin:cube")
s(0.2,0.3,0.1)
color("#ff0000")
Gaussian normal point distribution on a surface.
Init-->
scatter(surface, 100, gaussian, left, '0.1) { Leaf }
Leaf-->
i("builtin:cube")
s(0.2,0.3,0.1)
color("#ff0000")
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.
3.1.35. scaleUV operation
Synopsis
scaleUV(float uvSet, float uFactor, float vFactor)
Parameters
uvSet
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
3.1.36. set operation
Synopsis
set(attribute, bool value)
set(attribute, float value)
set(attribute, string 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. There are two kinds of shape
attributes: builtin attributes such as material.color or scope.tx and generic attributes, which are declared as rule
attributes (see Attributes).

Related
material attribute
pivot attribute
scope attribute
seedian attribute
trim attribute
Examples
Builtin Shape Attributes
Enable horizontal trim planes
set(trim.horizontal, true)
Set x-translation of scope to 0
set(scope.tx, 0)
Set the material color's red component to 0.5
set(material.color.r, 0.5)
Assign the built-in test texture to the colormap
channel
set(material.colormap, "builtin:uvtest.png")
Generic Shape Attributes
version "2011.1"
attr floorNumber = -1
const floorHeight = 4
Init-->
extrude(30)
comp(f) {side : Side }
Side-->
split(y) { ~floorHeight: Floor }*
Floor-->
set(floorNumber, split.index)
split(x) { ~1 : Wall | {~3 : Tile}* | ~1 : Wall }
Tile-->
split(x) { 0.5 : Wall | ~1 : MidTile | 0.5 : Wall}
MidTile-->
split(y) { 0.5 : Wall | ~1 : Window | 0.5 : Wall }
Window-->
case floorNumber % 3 == 0:
color(1.0, 0.0, 1.0)
X
else:
X
Store floor index in a generic attribute, floorHeight. The attribute is then
used to color the windows on every 3rd floor pinkinsh.
3.1.37. setback operation
Synopsis
setback(setbackDistance) { selector operator operations | selector operator operations ... }
setback(setbackDistance, uvSet) { selector operator operations | selector operator operations ... }
Parameters
setbackDistance (float)
The setback distance.
uvSet (float)
The uv set to use for uv-based selectors. Default is 0.
selector (keyword)
front, back, left, right, top, bottom, side: 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, object.side: 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,
world.side: The edges' outwards normals in the polygon plane are analyzed by classifying
their directions into the corresponding world coordinate system quadrants.
street.front, street.back, street.left, street.right: Edges adjacent to a street
can be selected with the street.front selector, rear edges can be selected with the
street.back selector, and edges in between front and back can be selected with the
street.left and street.right selectors. street.side combines left and right edges.
These selectors depend on the availability of the streetWidth attribute map; see Auto-
generated street width attributes. If the attribute is not available, component selection falls
back to the object.xxx selectors.
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.
uv.left, uv.right, uv.bottom, uv.top: Selects edges based on their uv-coordinates.
The outwards-pointing normal of each edge is analyzed to classify the edge with (left,
right) beeing the negative and positive u-axis and (bottom, top) being the negative and
positive v-axis.
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 Street Front
LotInner-->Lot
Lot-->
setback(5) { street.front : Garten | remainder : Building }

Garten --> color("#00ff00")
Building-->
offset(-3, inside)
extrude(world.y, rand(5, 15))
3.1.38. setNormals
Synopsis
setNormals(normalsMode)
Parameters
normalsMode (selstr)
hard: use the face normals.
soft: for each vertex, use the average of the adjacent face normals.
The setNormals() operation sets the normals of the current shapes' geometry to the desired mode.
Related
convexify operation
innerRect operation
mirror operation
trim operation
Examples
Shaded Sphere
Shaded sphere with hard normals. Shaded sphere with soft normals.
3.1.39. 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
3.1.40. setupProjection operation
Synopsis
setupProjection(uvSet, axesSelector, texWidth, texHeight)
setupProjection(uvSet, axesSelector, texWidth, texHeight, widthOffset, heightOffset)
setupProjection(uvSet, axesSelector, texWidth, texHeight, widthOffset, heightOffset, 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 parameter 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
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)
setupProjection(0, scope.xy, 1.5, 1, 1)
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.
3.1.41. 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, backWidth, leftWidth) { selector operator operations | selector
operator operations }
Parameters
frontWidth (float)
Depth of front wing.
leftWidth (float)
Width of left wing.
rightWidth (float)
Width of right wing.
backWidth (float)
Depth of rear wing.
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 myFrontDepth = 5
attr myLeftWidth = 11
LotInner -->
Lot

Lot -->
offset(-3, inside)
shapeL(myFrontDepth,myLeftWidth) { shape : Footprint | remainder: NIL }

Footprint -->
extrude(rand(10,20)) color(1,0,0)

U-Shapes
A block filled with U-shapes.
attr myRightWidth = 3
LotInner -->
Lot

Lot -->
offset(-3, inside)
shapeU(myFrontDepth,myRightWidth,myLeftWidth) { shape : Footprint | remainder: NIL }

Footprint -->
O-Shapes
A block filled with O-shapes.
attr myRightWidth = 3
attr myBackDepth = 2

LotInner -->
Lot

Lot -->
offset(-3, inside)
shapeO(myFrontDepth,myRightWidth,myBackDepth,myLeftWidth) { shape : Footprint | remainder: NIL }
Footprint -->
3.1.44. split operation
Synopsis
XYZ Split (Cartesian Space)
split(splitAxis) { size1 : operations1 | size2 : operations2 | ... | sizen-1 : operationsn-1 }
split(splitAxis) { size1 : operations1 | size2 : operations2 | ... | sizen-1 : operationsn-1 }*
split(splitAxis, adjustSelector) { size1 : operations1 | ... | sizen-1 : operationsn-1 }
split(splitAxis, adjustSelector) { size1 : operations1 | ... | sizen-1 : operationsn-1 }*
UV Split (Texture Space)
split(splitDirection, surfaceParameterization, uvSet) { size1 : operations1 | ... | sizen-1 :
operationsn-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 geometry'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)
Number of texture a set/layer (integer number in [0,5]). The numbering corresponds to the texture layers
of the material attribute.
See Texturing for information about the texture layer IDs.
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)
with the ~ prefix, the remaining spaces between the split parts with absolute dimensions are
automatically adapted. If multiple floating parts are defined within a split, the dimensions are
weighed proportionally.
operations
A sequence of shape operations to execute on the newly created shape.
*
Repeat switch: the repeat switch triggers the repetition of the defined split into the current shape's
scope, as many times as possible. The number of repetitions and floating dimensions are adapted to the
best solution (best number of repetitions and least stretching).
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-->
setupProjection(0, scope.xy, '1, '1)
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.
3.1.45. 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
3.1.46. 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
envelope operation
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.
3.1.47. 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. Supported image formats are listed in Texturing Essentials.
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)
3.1.48. tileUV operation
Synopsis
tileUV(uvSet, textureWidth, textureHeight)
Parameters
uvSet
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. 0 is allowed and means don't
touch this axis.
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. 0 is allowed and means
don't touch this axis.
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-->

The default texture coordinates.
Street-->
tileUV(0, 20, 10)

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.
3.1.49. 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

3.1.50. translateUV operation
Synopsis
translateUV(uvSet, uOffset, vOffset)
Parameters
uvSet
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
3.1.51. 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
Related
comp (component split) operation
convexify operation
i operation
innerRect operation
mirror operation
3.2.1. comp shape attribute
Synopsis
string comp.sel
float comp.index
float 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)
3.2.2. 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)
3.2.3. Material Shape Attributes
The material shape attributes control the shading, texturing and export of the shape's geometry. CityEngine
supports six texture channels with a fixed semantic.
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 rule which did the last modification.
string material.shader
The shader name used for export (currently supported by
RIB and MI).
float material.color.{r|g|b}
Diffuse color. Individual access to each color component.
Default is white. 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}
Ambient color. Individual access to each color component.
Default is black.
float material.specular.{r|g|b}
Specular color. Individual access to each color component.
Default is black.
float material.opacity
Opacity factor. 1 is fully opaque, 0 is fully transparent.
Default is 1.
float material.reflectivity
Reflectivity factor. 0 is no reflection, 1 is full reflection (of the
Reflection Map set in the Panorama Layer). Note that
reflection depends on the specular color: the default black
color means no reflection!
float material.shininess
Phong specular exponent in the range [0, 128].
float material.bumpValue
Controls the bump scaling factor (if material.bumpmap is
set).
string material.colormap
string material.bumpmap
string material.dirtmap
Texture file paths for the texture channels. More details.
string material.specularmap
string material.opacitymap
string material.normalmap
float material.{colormap|...|normalmap}.s{u|v}
Per-channel texture scaling factors.
float material.{colormap|...|normalmap}.t{u|v}
Per-channel texture translation factors.
float material.{colormap|...|normalmap}.rw
Per-channel texture rotation factors. The texture is rotated
around the w-axis (w is the cross product of u and v).
Rendering and Export
For rendering in the CityEngine preview and for exporting the generated models, the material attributes need to be
mapped to the respective format. The following table shows what format implements which feature.
Feature
CE Viewport
(OpenGL)
KML/DAE
read
OBJ
read
3DS
write
KML/DAE
write
FBX
write
MI
write
OBJ
write
RIB
write
VOB
write
ABC
write
FileGDB
write
name Y Y Y Y Y Y Y Y Y Y - (3) -
shader - - - - - - Y - Y - - -
color Y (2) Y (1) Y Y Y (1) Y Y Y Y Y - Y
ambient Y Y Y - Y Y Y Y Y - - -
specular Y Y Y Y Y Y Y Y Y Y - -
opacity Y Y Y Y Y Y Y Y Y Y - -
reflectivity Y Y Y Y Y Y Y Y Y Y - -
shininess Y Y Y Y Y Y Y Y Y Y - -
bumpValue Y Y Y - Y - Y Y Y Y - -
colormap Y (2) Y (1) Y Y Y (1) Y Y Y Y Y - Y
bumpmap Y Y Y - Y Y Y Y Y Y - -
dirtmap Y (2) Y - - Y Y Y - Y Y - -
specularmap Y Y Y Y Y Y Y Y Y Y - -
opacitymap Y Y Y Y Y Y Y Y Y Y - -
normalmap Y Y - - Y Y Y - Y - - -
UV offset Y Y - - Y Y Y - Y Y - -
UV scale Y Y Y - Y Y Y - Y Y - -
Edges Y - - - - - - - - - - Y
Vertices Y - - - - - - - - - - Y
Remarks:
(1) The official COLLADA standard does not support a diffuse solid color and a diffuse texture at the same time.
The FCollada extension used by CE does.
(2) In the CityEngine viewport, the colormap and dirtmap values are multiplied with the (diffuse) color.
(3) The Alembic (ABC) exporter currently only exports geometry, no material attributes.
Related
set operation
projectUV operation
print operation
Texturing: Essential Knowledge
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)
3.2.4. CGA Shape Reference
material.color shape attribute
Synopsis
float material.color.{r|g|b}
string material.color.rgb
The material.color shape attribute controls the diffuse color).
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.
3.2.5. CGA Shape Reference
material.map shape attribute
Synopsis
string material.colormap
string material.bumpmap
string material.dirtmap
string material.specularmap
string material.opacitymap
string material.normalmap
float material.{colormap|...|normalmap}.s{u|v}
float material.{colormap|...|normalmap}.t{u|v}
float material.{colormap|...|normalmap}.rw
The material shape attribute consists of 6 texture layers.
Each texture layer consists of the file name of the associated texture
(material.{colormap|...|normalmap}),
scaling factors in u and v directions (material.{colormap|...|normalmap}.s{u|v]}),
offsets in u and v directions (float material.{colormap|...|normalmap}.t{u|v})
and rotation around the w-axis (material.{colormap|...|normalmap}.rw).
All these attributes can be set and read.
Each texture layer has a corresponding uv-set (texture coordinates) in the shape's geometry. More information
can be found in Texturing: Essential Knowledge
The bump map is interpreted as luminance map (CCIR 601).
The normal map is interpreted as normals in tangent space encoded as rgb colors.
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
Texturing: Essential Knowledge
3.2.6. 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
3.2.7. scope shape attribute
Synopsis
float scope.t{x|y|z}
float scope.r{x|y|z}
float scope.s{x|y|z}
float scope.elevation
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. The
scope.elevation attribute contains the the elevation above sealevel in meters of the origin of the current shape's
scope. This is the same as the y-coordinate of the CityEngine coordinate system; note that this attribute can not be
set.
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)
3.2.8. 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
3.2.9. 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


3.2.10. 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

3.2.11. uid shape attribute
Synopsis
float uid
The uid is the unique ID for each shape in a model hierachy.This can be used in conjuntion with reporting to
connect a report to a certain shape.
Example
Printing each shape's uid
UIDTest-->
print("UIDTest shape: " + uid)
Leaf
Leaf

Leaf-->
print("Leaf shape: " + uid)
Result:
UIDTest shape: 1
Leaf shape: 2
Leaf shape: 3
3.3.1. 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
3.3.2. 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
3.3.3. 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
3.3.4. 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
3.3.5. 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
3.3.6. 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
3.3.7. 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
3.3.8. 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
3.3.9. 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
3.3.10. 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
3.3.11. 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

3.3.12. 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
3.3.13. 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
3.3.14. 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
3.3.15. rint function
Synopsis
float rint(float x)
Returns
The rounded integer value of x. If x is integral, x is returned.

These function rounds x to the nearest integer.
Related
abs function
ceil function
floor function
3.3.16. 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
3.3.17. 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
3.3.18. 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
3.3.19. 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
3.3.20. 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
3.3.21. 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

3.3.22. 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
3.3.23. sel
Synopsis
float sel(string selstring)
Returns
Selector with the value of inputstring.
This conversion function allows to cast the inputstring to a selector.
Examples
colchannel(index) = "material.color."+index

A -->
set(sel(colchannel("r")),0.5)
3.3.24. 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"
3.3.25. 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
3.3.26. find
Synopsis
float find(string inputString, string matchString, float n)
Returns
Index of nth occurrence of matchString in inputString or -1 if not found.
This function returns the index of the of the nth 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.
3.3.27. 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

3.3.28. 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 = ""
3.3.29. geometry.angle function
Synopsis
float geometry.angle(angleSelector)
Parameters
angleSelector
Selector for the angle calculation. Valid selectors are:
maxSlope
Calculates the maximum slope of the shape, relative to the xz-plane, in degrees.
azimuth
Calculates the azimuth of the direction of the current shape's maximum slope, in degrees.
zenith
Calculates the difference between 90 degrees (zenith) and the maximum slope.
Returns
Angle of the current shape's geometry, depending on the selector, in degrees.
Azimuth is the horizontal angle measured clockwise from the north, i.e. 90 degrees is east, 180 degrees is south
and 270 degrees is west. Azimuth is in the range [0, 360[.
The geometry.angle(zenith) function returns the same value as ( 90 - geometry.angle(maxSlope) )
Examples
Cone-->
comp(f) { all : color(geometry.angle(maxSlope) / 90, 0.0, 0.0) Shape. }
Cone-->
comp(f) { all : color(0.5, geometry.angle(azimuth) / 360, 0.5) Shape. }
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.front,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,
street.front, street.back, street.right, street.left, street.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.
geometry.du/dv functions
Synopsis
float geometry.du(float uvSet, surfaceParameterization)
float geometry.dv(float uvSet, surfaceParameterization)
Parameters
uvSet
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.isClosedSurface function
Synopsis
bool geometry.isClosedSurface()
Returns
true if the all of the geometry's edges belong to exactly 2 faces.
Related
geometry.isConcave function
geometry.isRectangular function
geometry.isPlanar function
Synopsis
bool geometry.isConcave()
Returns
true if the geometry contains at least one concave face, false otherwise.
Related
Synopsis
bool geometry.isInstanced()
Returns
True if the current shape's geometry is the instance of an asset, i.e. the geometry has not been altered since the i()
operation, false otherwise.
The geometry.isInstanced() function can be used to e.g. check if an inserted asset was trimmed.
Related
i() operation
geometry.isOriented function
Synopsis
bool geometry.isOriented(orientationSelector)
Parameters
orientationSelector
Selector for the faces to check for. Valid selectors are:
back, bottom, front, top, left, right, side,
object.front,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
street.front, street.back, street.right, street.left, street.side
Returns
True if at least one of the geometry's faces matches the orientationSelector, false otherwise.
The geometry.isOriented function can be used to determine a shape's orientation.
Related
comp() operation
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.nHoles()
Returns
The (integral) number of holes (i.e holes in 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.{uMin|uMax|vMin|vMax} functions
Synopsis
float geometry.uMin()
float geometry.uMax()
float geometry.vMin()
float geometry.vMax()
float geometry.uMin(float uvSet)
float geometry.uMax(float uvSet)
float geometry.vMin(float uvSet)
float geometry.vMax(float uvSet)
Parameters
uvSet
Returns
The minimal or maximal u or v value of the selected uvset (the versions without parameter use uvset 0).
geometry.volume function
Synopsis
float geometry.volume()
Returns
Volume of the current shape's geometry.
Related
geometry.area function
3.3.44. 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
3.3.45. 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
An alphabetically sorted string list with all files in the workspace matching the searchQuery. Each entry is terminated
with a ";" (semicolon).
The fileSearch function lists all files in the workspace and matches their absolute path with the searchQuery.
Search queries are relative to the current project (i.e. the project in which the current rule file resides) except if the
searchQuery is based on an absolute workspace path (i.e. starts with a slash ("/") or a wildcard (* or ?). Pseudocode
of the matching algorithm:
result = ""
for all open projects in workspace :
if project == current project:
result += all matching files in project, relative to assets folder
result += all matching files in project, relative to project folder
fi

result += all matching files in project, relative to workspace root
sort result
end

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 '$'. Always put the '$' as the FIRST character if your searchQuery is a regular
expression! Note that with regular expressions, the semantics of the wildcards "*" and "?" changes. "*" matches the
preceding element zero or more times, therefore use ".*" to emulate the "match anything" behaviour.
File Properties
Following file properties can be querried:
Name: Filename
Ext: File extension
Project: Project name
Path: Filepath
Examples
In the following examples, we use a basic workspace with two projects and a few files. The examples are in
rule.cga, i.e. MyProject is the current project.
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;
/OtherProject/assets/glass.png;"
Because the searchQuery starts with an asterisk, all projects are included in the search.
print(fileSearch("?.png"))
# result = ";"
There is no png file with a 1-character-name in the root directory or the asset directory of the current project.
print(fileSearch("*/?.png"))
# result = "/MyProject/assets/textures/1.png;/MyProject/assets/textures/2.png;
/MyProject/assets/textures/4.png;"
Because of the leading asterisk, all folders are searched for a png file with a 1-character-name.
print(fileSearch("textures/*"))
# result = "/MyProject/assets/textures/1.png;/MyProject/assets/textures/2.png;/MyProject/assets/textures/4.png;"
All files in the "textures" subfolder of the asset folder in the current project match.
Example 5: Regular Expression to select specific characters
print(fileSearch("$[12].png"))
# result = ";"
There is no png file with name "1" or "2" in the root directory or the asset directory of the current project.
Example 6: Regular Expression to select specific characters, part 2
print(fileSearch("$textures/[12].png"))
# result = "/MyProject/assets/textures/1.png;/MyProject/assets/textures/2.png;"
All png files with name "1" or "2" in the "textures" subfolder of the asset folder in the current project match.
Example 7: Regular Expression + Wildcard
print(fileSearch("$.*/[12].png"))
All png files with name "1" or "2" match. Note the period before the asterisk!
Example 8: Regular Expression to select a range of characters
print(fileSearch("$textures/[2-5].png"))
All png files with name "2", "3, "4" or "5" in the "textures" subfolder of the asset folder in the current project match.
Example 9: Regular Expression + OR
print(fileSearch("$textures/[12].png|.*.obj"))
# /MyProject/assets/textures/1.png;/MyProject/assets/textures/2.png;/MyProject/assets/tower.obj;/OtherProject/assets/brick.obj;
All png files with name "1" or "2" in the "textures" subfolder of the asset folder in the current project and all obj files
in the workspace match.
Example 10: File Properties
print(fileSearch("Name=1.png"))
# result = "/MyProject/assets/textures/1.png;"
Only one file matches the name excatly.
Example 11: File Properties, AND
print(fileSearch("Project=OtherProject Ext=obj"))
# result = "/OtherProject/assets/brick.obj;"
Using white space, two or more queries can be anded. Here the only file matching the project name and the file
extension is matched.
3.3.46. 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.
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
3.3.47. assetsSortRatio function
Synopsis
string assetsSortRatio(string fileList, axisSelectorRatio)
Parameters
fileList
String list with geometry files, separated 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
3.3.48. 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
3.3.49. 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)
3.3.50. imagesSortRatio function
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
3.3.51. 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).
3.3.54. 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), converted 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
getGeoCoord function
scope.elevation attribute
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:
3.3.55. getGeoCoord function
Synopsis
float getGeoCoord(geoCoordSelector)
Parameters
geoCoordSelector
(X | Y | lon | lat) Geo Coordinate selector. X and Y select the 2D coordinate of the current scene's
coordinate system (e.g. UTM easting and northing coordinates); note that this coordinates are always in
the scene coordinate system's units. lon and lat select spherical latitude/longitude coordinates.
Returns
The selected coordinate of the origin of the scope of the current shape.

The getGeoCoord function converts the current scope position to geographical 2D coordinates.
Related
convert function
3.3.56. print function
Synopsis
float print(float value)
bool print(bool value)
string print(string value)
Returns
value.

The print function prints the parameter value and als returns it. The purpose of this function is mainly for
debugging.
Related
print operation
3.4. 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)

3.5.1. 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 through the inspector or by a map. See also "Attributes"
Attributes can be annotated to control their presentation in the inspector. See "Annotations"
.
Example
Defining an attribute with attr
attr height = 250 // define an attribute "height"
Lot-->extrude(height) A.

3.5.2. 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.

3.5.3. import
Synopsis
import id : "file.cga"
import id( style-id_1, ... , style-id_n) : "file.cga"
import id : "file.cga" ( attribute_1, ... , attribute_n )
import id : "file.cga" ( attribute_1 = value, ... , attribute_n = value )
Rules, attributes and functions from an existing rule file can be imported by a rule file through "import". Importing
a rule file makes all rules, attributes and functions of the imported rule file available prefixed by "id". If the imported
rule file contains multiple styles, by default all styles are imported and visible in the style manager. In order to limit
the styles available in an importing rule file, the set of imported styles can be specified by enumerating the imported
styles in parenthesis after the import id as in the second form of the import statement with "style-id1, ..., style-id_n".
By default, attribute values from an importing rule file (e.g. "height" in "main.cga" below) are propagated to the
imported rule file (e.g. "height" in "structure.cga" takes its value from "height" in "main.cga" below). In order to
disable this default behavior (e.g. because an attribute in an imported rule file has the same name but a different
semantic and should therefore not be overwritten), the attributes in an imported rule file can be protected by
enumerating them after the rule file as in the third variant of the import statement ("attribute_1, ..., attribute_n").
Attributes can not only be protected but an importing rule file can additionally specify a new value for the attribute by
redefining an attribute with an expression as in the fourth form of the import statement ("attribute_1 = value, ... ,
attribute_n = value") where the right hand side expression is evaluated in the scope of the importing rule file.
Setting the attribute source of an imported attribute in the inspector to something else than "Rule-defined value" will
disable this behavior for that attribute completely and the value will be taken from the designated source instead.
Imports can be annotated to control their attribute presentation in the inspector. See "Annotations".
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
3.5.4. style
Synopsis
style style-id
style style-id extends base-style-id
A style is a set of rules and attributes. Every rule file implicitly has a default style called "Default". Thus every
rule and attribute written in a rule file automatically belongs to the default style. Through the "style" statement, a
new style can be defined. Every style which is not the default style has to be based on an existing style. In its
simplest form, the "style" statement creates a new style based on the "Default" style. If a style has to be defined
on a different style than the default style, the second form of the "style" statements allows to explicitly name a
base style by "base-style-id". Thus the first form is completely equivalent (or just a shorthand) for "style style-id
extends Default". Within a style, rules and attributes of the base style can be redefined as well as new rules and
attributes can be added. Together with the import statement styles give a new design dimension for organizing
your rule files.
Example
Defining Styles
# define "color" attribute (green)
attr color = "#00ff00"
# create a green cube
Shape-->color(color) i("builtin:cube")
#define a new style "Blue_Bunny"
style Blue_Bunny
# re-define "color" attribute (blue)
attr color = "#0000ff"
# creates a blue bunny
Shape-->color(color) i("bunny.obj")
#define a new style "Red_Bull"
style Red_Bull
# re-define "color" attribute (red)
attr color = "#ff0000"
# creates a red bull
Shape-->color(color) i("bull.obj")
3.5.5. 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
3.6.1. 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

3.6.2. 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
Note: Indices are 0 - based.
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

3.6.3. 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"
3.6.4. 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 = ""
3.6.5. 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"
3.6.6. 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
3.6.7. 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
(";"). Each item must be followed by a semicolon, also the last one! The data type is "string", thus it is not an array
as used in other scripting languages.
Related
listClean function
listCount function
listFirst function
listIndex function
listItem function
listLast function
listRandom function
listRange function
listRemove function
listRemoveAll function
listRetainAll function
listSize function
listTerminate function
Examples
example.1
listAdd("rule;your;","city")
# result = "rule;your;city;"
example.2
listAdd("rule;your;","city;")
3.6.8. listClean
Synopsis
stringList listClean(string stringList)
Returns
Returns cleaned stringList.
This function checks if the stringList has the correct ";" at the end. Additionally, empty items (';;') are
removed.
Related
listAdd function
listCount function
listFirst function
listIndex function
listItem function
listLast function
listRandom function
listRange function
listRemove function
listSize function
Examples
example.1
listClean(";;;;;my;city;rules;;your;;city;;")
# result = "my;city;rules;your;city;"
example.2
listClean(";;cityengine;;;rules")
# result = "cityengine;rules;"
3.6.9. 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
listCount function
listIndex function
listItem function
listLast function
listRandom function
listRange function
listRemove 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
3.6.10. 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. Optional: leading or
trailing * in item are used as wildcard.
Note.1: Indices are 0 - based.
Related
listAdd function
listClean function
listCount function
listFirst function
listItem function
listLast function
listRandom function
listRange function
listRemove function
listSize function
Examples
example.1
listIndex("rule;your;city;","city")
# result = 2
example.2
listIndex("rule;your;city;","*y")
# result = 2
example.3
listIndex("rule;your;city;","*y*")
# result = 1

3.6.11. 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
listCount function
listFirst function
listIndex function
listLast function
listRandom function
listRange function
listRemove 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"
3.6.12. listLast
Synopsis
string listLast(string stringList)
Returns
Returns last item in stringList.
This function returns the last item in the stringList.
(";"). The data type is "string", thus it is not any real type of array as used in other scripting languages.
Related
listAdd function
listClean function
listCount function
listFirst function
listIndex function
listItem function
listRandom function
listRange function
listRemove 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
3.6.13. 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
Note.2: Stringlists are a series of strings stored inside one string. The elements are separated by a semicolon
Related
listAdd function
listClean function
listCount function
listFirst function
listIndex function
listItem function
listLast function
listRange function
listRemove 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.

3.6.14. 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).
Note.2: Stringlists are a series of strings stored inside one string. The elements are separated by a semicolon
Related
listAdd function
listClean function
listCount function
listFirst function
listIndex function
listItem function
listLast function
listRandom function
listRemove 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"
3.6.15. 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
listCount function
listFirst function
listIndex function
listItem function
listLast function
listRandom function
listRange function
listRemove 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.
3.6.16. listTerminate
Synopsis
float listTerminate(string stringList)
Returns
string list with seperator ";" at the end. Use this to fix string lists with a missing semicolon at the end. If the strringList
is already terminated, nothing happens.
Related
listAdd function
listClean function
listCount function
listFirst function
listIndex function
listItem function
listLast function
listRandom function
listRange function
listRemove function
listSize function
3.6.17. 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))
3.6.18. 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:
..
3.6.19. 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"))
3.6.20. 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.

3.6.21. 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"
3.6.22. 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"
3.6.23. 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/"
3.6.24. 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"
3.6.25. 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"
3.6.26. 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
3.6.27. imageApproxRatio
Synopsis
string imageApproxRatio(string searchQuery, string axisSelector, float n)
Parameters
searchQuery
yz | zx | 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))
..
3.6.28. imageBestRatio
Synopsis
string imageBestRatio(string searchQuery, string axisSelector)
Parameters
searchQuery
yz | zx | 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)
3.6.29. colorRamp
Synopsis
string colorRamp(string gradient, float value)
Parameters
gradient
Selector for different color ramp presets. Supported values are:
"whiteToBlack","greenToRed","yellowToRed","redToBlue","orangeToBlue","brownToBlue","spectrum".
value
A value between 0 and 1.
Returns
Hex color value from a color ramp (selected with gradient) according to the given value. Means the value is
mapped on the color ramp and the corresponding color is returned.
Examples
Yellow to red color ramp
@Range(0,1)
attr colorValue = 1
@StartRule
Shape -->
color ( colorRamp("yellowToRed",colorValue))
To visualize datasets, 'normalize' the values to the [0-1] range with the function " x_norm = 1 / (max - min) * (x
- min) ".
Ramp example images based on a GIS dataset
yellow to red :
red to blue :
green to red :
white to black :
orange to blue :
brown to blue :
spectrum :
3.7.1. CGA Changelog
City
Engine
version (=
CGA
version)
Changes
2014.1
CGAC 1.3
new operations:
deleteHoles operation.
new functions:
geometry.nHoles function.
geometry.isClosedSurface function.
new CGA Utility Library functions:
new features:
alignScopeToGeometry, convexify, envelope, cleanupGeometry, innerRect, scatter,
setback, shape{L|U|O} and reduceGeometry operations and geometry.isClosedSurface,
geometry.area (with selector) functions: holes in polygons are now supported.
convexify, innerRect, offset, shape{L|U|O} operations: uv coordinates and vertex
normals are not deleted anymore but interpolated for new inner vertices.
convexify, innerRect, offset operations: result is not planarized anymore.
color, operation: support for setting opacity (alpha).
changes to existing features:
Changed the defaults for recursion detection:
Maximum derivation depth: from 99 to 1024.
Maximum derivation width: from 50000 to 100000.
Maximum function call depth: from 256 to 1024.
Optimized function memory overhead (i.e. more interleaved functions beyond the default
limit are possible now before crash - actual limit depends on platform & function).
Collada reader: added support for polygons with holes.
str function and print, report operations: made float-to-string conversion independent of
locale (some numbers might be formatted differently now).
Internal geometry cleanup: improved handling of illegal holes (overlapping holes, wrong
vertex order).
bugfixes:
extrude operation: fixed polygon with holes handling.
convexify operation: fixed face consistency if several edges have identical length.
envelope operation: fixed border cases which led to "open volumes".
alignScopeToGeometry operation: fixed points/edge shapes support: scope size was set to
1 rather than 0, pivot orientation was not set to vertex/edge normal, fixed a crash if illegal
edge index was used on edge geometry.
setback and shape{L|U|O} operations: fixed memory leak.
split operations: fixed hole handling (produced illegal holes in certain cases).
offset, roofGable, roofHip and roofShed operations: made polygons with holes handling
more stable for illegal holes (hangers).
assetInfo, assetsSortRatio and assetsSortSize functions: fixed behaviour for
unknown/unloadable assets.
material shape attribute: material.XXXmap returns "builtin:unknowntexture.png" if
texture not found.
Fixed (deprecated) noStreetSide comp split selector handling.
Fixed a bug regarding edge/point geometry normals (CityEngine rendering only).
Fixed a bug in handling edges in empty geometries.
i operation: fixed a race condition in handling unknown assets which led to a crash.
Fixed an internal illegal pointer access which led to a crash.
print, report, set operations: fixed nan handling (avoid checks) and removed excess
newline (bool).
str function: fixed inf/nan handling.
listRange function: fixed a bug reading (illegal) non-;-terminated string list handling.
improved internal rad-to-degree conversion precision.
AssetErrors: report warnings from geometry conversion of inserted assets.
Fixed a vertex merge issue in trim/split (identical vertices were not merged).
CGA compiler:
Fixed a bug in extends (attribute values were not always propagated).
Fixed bugs in import (wrong attributes copied, protecting selected attributes
did protect all attributes).
Fixed a bug which led to a compile error if a rule had the same name as a
CGA Utility Library function.
2014.0
CGAC 1.2
new features:
offset, roofGable, roofHip, roofShed operations: holes in polygons are now supported.
setback operation: new syntax for selecting uv sets and new uv-based selectors uv.left,
uv.right, uv.bottom, uv.top; uv coordinates and vertex normals are not deleted
anymore but interpolated for new inner vertices.
tileUV operation: using 0 for the textureWidth or the textureHeight parameter protects
that coordinate from beeing touched.
import: attr value propagation logic was simplified.
bugfixes:
import: resolving assets from cross-project imports failed in some cases (imports which
imported a cga file from the same directory). This was fixed in the cga compiler (CGAC),
so existing rpks should be updated.
assetApproxRatio, assetApproxSize, assetBestRatio, assetBestSize, assetFitSize,
fileRandom, imageApproxRatio, imageBestRatio functions: fixed a bug which led to wrong
asset lookups if imported from a different project.
geometry.angle function: fixed a bug which led to wrong results.
fileSearch operation:
hits in the current project were reported in relative path notation; this got
changed to absolute workspace paths again.
crash fixed if illegal regexps were used in attr initialization
spaces within qoutes were broken
initialShape attributes returned wrong values if used in const / attr functions.
comp operation: for polygons with holes, the border, insider selectors and the = operator
were buggy.
imageInfo function: does not crash anymore on empty filename.
imagesSortRatio function: does not crash anymore on empty fileList.
split operation: fixed a bug which led to deletion of the last leaf of a uv-split in some
cases.
inside function: fixed a bug which led to wrong results.
Fixed a bug connected to inter-model occlusion of vertically distant initial shapes: ignore
neighborhood distance on y-axis for finding potential occlusions.
2013.1
CGAC 1.1
changed fundamental behaviour:
attr/const functions evaluation order: In previous CGA versions, attr and const
functions were evaluated lazily, i.e. when they were used for the first time. Remember that
attr and const functions are evaluated only once. This approach gave rise to the non-
intuitive behaviour that changing the code of some rule potentially changed the value of an
attr. Keep in mind that some functions (and obviously shape attributes) depend on the
current shape's geometry, and some even change the state of the current shape (e.g.
rand). Therefore (non-)evaluation of a const function cold have an influence on rule
execution.
Starting with 2013.1, all attr/const functions are evaluated before the start rule is
applied, on the initial shape with a seedian derived from the initial shape's seedian. The
initial shape's random number generator state is not affected.
While the new approach makes CGA coding more "intuitive", it changes the behaviour
compared to older versions.
inf/nan checks: In previous CGA versions, a number of operation and function float
parameters were tested for not-a-number / infinity (nan/inf) values at runtime. In most
cases, such values were replaced with 0 and a warning was issued. In others, the
operation was aborted.
CGA 2013.1 introduces a unified inf/nan behaviour: checking of all float paramers of builtin
functionality can be set to either "ignore" (= don't check), "abort with error" or "replace with
zero" see Grammarcore Preferences). The default behaviour is "replace with zero", which
comes closest to the classic behaviour.
While CGA 2013.1 provides more debugging capabilities regarding inf/nan values, the
behaviour is different than in previous versions.
Intra-occlusion and reports, print output, CGA error reporting: During resolving inta-
occlusion-queries, some shapes and sub-shapetrees get deleted (and re-evaluated). The
reports issued by report operations by the rule of that shapes (and the output of print
operations and functions plus all CGA errors/warnings) are deleted along with those
shapes.
While the new behaviour makes more sense (each report/print-output/error has associated
a shape in the model hierarchy), it is different than in previous versions.
listCount function
listRemove function
new features:
envelope, operation: added direction parameter, allowing for world up-axis aligned
envelopes.
cleanupGeometry, comp, extrude, split operations and geometry.nFaces, geometry.area,
geometry.volume functions: holes in polygons are now supported. However, other
operations might drop holes (and issue a CGA warning).
report operation: available with all licenses.
reduceGeometry operation: new, more efficient implementation - resulting geometry might
differ to previous version.
fileExists function: now returns true fo all builtins.
material.color.rgb attribute: return a hex string (see color operation) rather than a
three-floats-in -[0,1]-string.
listClean utility function: empty entries are filtered now.
listIndex utility function: support for wildcards.
envelope operation: deprecated signatures without direction parameter.
bugfixes:
alignScopeToGeometry operation: more robust regarding bad geometry (fixes a crash) and
better face material support.
assetsSortRatio function: fixed axisSelectorRatio parameter (crashed if yz was used).
assetsSortSize function: fixed axisSelectorSize parameter (yz was ignored).
envelope operation:
fixed missing top faces if one some of the baseHeights were equal to
maxHeight.
support for non-planar polygons.
fixed several numerical issues (crashes, incorrect geometry).
i operation and initial shape handling: added zero-angle removal and better face material
support.
print function: a newline is added after each invocation (like in the print operation.
comp, envelope setback, geometry.area, and geometry.isOriented operations/functions:
street.xxx selectors: do not fallback to object.xxx selectors if streetWith sttribute is not
defined for index 0 but for other indics.
Vertex meger (export + internal to a number of operations): more robust regarding bad
geometry (fixes a crash).
Triangulator (export, rendering and internal to a number of operations): correctly handle
near-identical vertices (led to inconsistent geometry and crashes).
Fixed a number of compiler bugs related to import, most important a bug which prevented
setting of imported generic attributes.
2012.1 new operations:
envelope operation
new functions:
geometry.angle function
new attributes:
uid attribute
colorRamp function
new features:
comp, setback, geometry.area, and geometry.isOriented operations: added
street.front, street.back, street.left, street.right, street.side selectors;
these selectors will fallback to the according object.xxx selectors if no streetWidth
attribute is present.
setback, geometry.area, and geometry.isOriented operations: added world.side,
object.side selectors.
Edges and vertices resulting from comp(e) or comp(v) are now rendered in the viewport
(the size can be controlled in the Grammarcore Preferences); only some formats support
exporting edges/vertices, see Rendering and Export feature table.
report operation: only available with advanced license.
reverseNormals operation: support for vertex normals.
setback, shapeL, shapeU, shapeO operations: New implementation.
scatter operation: No geometry is inserted anymore (a builtin:cube used to be inserted),
but the vertices are visible in the 3D Viewport.
comp, setback, geometry.area, and geometry.isOriented operations: streedSide,
noStreetSide selectors deprecated.
Asset Search: added the current project to the search path if rule file is in the Utility
Library.
bugfixes:
comp operation: using the combine (=) operator in conjunction with edges and vertices (e|v)
led to undefined behaviour. fixed.
geometry.isOriented operation: world.x selectors were inverted. fixed.
i (trimming) and split operations: fixed some bugs which led to inconsistent geometry
and increased performance for large geometries. This also speeds up export if vertex
merger is on.
alignScopeToAxes operation: works now also if the current shapes' geometry is empty
(e.g. after a scatter or comp(e|v) operation), and multi-mesh geometries do not loose
materials anymore.
2011.1 new functions:
getGeoCoord function
geometry.isOriented function
geometry.{uMin|uMax|vMin|vMax} functions
print functions
new attributes:
material.reflectivity, material.opacity, material.opacitymap,
material.opacitymap.{su|sv|tu|tv|rw} material.normalmap, material.normalmap.
{su|sv|tu|tv|rw} attributes
new features:
Added support for generic shape attributes: each shape can have its own copy of an
attribute, and the value is passed on to the successors. Values can be set with the set
operation.
Added support for styles: Rules and attributes can be bundled and named to form a style.
All styles derive from the default style. This is somewhat similar to inheritance in OOP.
On import of a rule file, attributes can now be protected and styles can be chosen.
color operation: added an overload which takes a float tripple.
geometry.area function: added object.front, streetSide and noStreedSide selectors.
case blocks can now be used between push [ and pop ] operations, i.e. a new scope can
be conditional.
CGA executen trace for debugging, see Grammarcore Preferences.
alignScopeToAxes operation: added x and z selectors.
material attributes:
if the shape material attribute is not modified: return attribute from first
geometry asset mesh material (i.e. always return the current value; on older
versions, always the shape material value was returned)
removed material.ambient.a attribute
deprecated material.color.a (replaced by material.opacity) and
material.map{3,4,5} (replaced by material.specularmap,
material.opacitymap, material.normalmap) attributes
changed material.bump to material.bumpValue
fundamental changes to transparency handling: the alpha channel of
material.colormap is always ignored now; alpha-maps must be set using the
material.opacitymap texture layer; similarly, material.opacity must be used
instead of material.color.a; rendering: CityEngine's GL preview now drops
fragments with alpha < 0.1, that used to be 0.3. note: all materials with opacity
are rendered after all other materials.
textures can be disabled by setting the filename to the empty string (i.e.
texture("") or set(material.opacitymap, "")); in previous versions, this
led to usage of "builtin:unknowntexture.png"; the default materials's
textures are set to the empty string instead of "not available".
If a texture can not be found, the texture name is always set to
"builtin:unknowntexture.png". This is also the case for misspelled
"builtin:XXX" textures (which were set to "builtin:default" in previous
versions).
"builtin:cube" now has texture coordinates for uv-set 0 (colormap) only (was 3: uv-sets
0, 1, 2 in previous versions).
For rendering and export, undefined uv-sets default to set 0 now (if 0 is defined), i.e. if e.g.
material.opacitymap is set to a valid texture, but uv-set 3 is undefined, the coordinates
form uv-set 0 are re-used. This was only the case for specular map before. See also
Texturing: Essential Knowledge.
fileSearch function (and all related functions in the Utility Library) got reworked:
search logic is more strict now (if searchQuery is not an absolute workspace
path, match relative to assets and root folders of current project (in old
versions, it was tried to match all folders and subfolders)
better performance
Geometry asset readers: extended consistency checks to handle polygons with collapsed
edges and dropped checking for non-planar faces.
Removed "drop shapes fully trimmed away" optimization in createShape operation: in
older versions, new shapes were not created if they would be completly behind an enabled
trimplane.
bugfixes:
scatter operation: gaussian distribution: fixed wrong mean calculation for right / bottom
cases; led to endless loops in certain cases.
vertex merger now respects topology (i.e. export with vertex merging option and all cga-
operations are o-shape safe).
The setback, shapeL, shapeU and shapeO operations received a facelift, fixing many
issues. Notably shapeO is much more stable now.
Fixed a fatal recursion-not-detected error in user-defined functions with arguments.
uv split operation:
fixed crash on geometries w/o uvsets.
fixed a precision bug.
innerRect operation: fixed shape placement if scope contains rotation.
Self-intersecting polygons are handled properly now (scatter, uv split operations and
rendering).
roofHip operation: fixed a crash in a specific situation (with overhang, on colinear
vertices).
fixed comp.sel (only contained last word, e.g "front" instead of "object.front").
fixed a bug in convexify: check resulting polys for zero area, remove degenerate ones -
led to crashes in follow-op operations in some cases.
rotate operation: fixed a bug in scope case (was rotated around pivot, not scope).
convert function: fixed a bug in convert((x|y|z), scope, pivot, orient, x, y, z)
(was size-sensitive).
material-per-face assets: improved support, material now survives deletion of zero-area
faces.
split / trim fix: cut-exactly-throug-edges situations with >1 points (o-shapes etc.).
fixed a bug in intra-occlusion geometry caching (led to wrong results).
Collada reader:
lines and points are ignored now (they were treaten as polygons in older
versions)
meshes consisting of textured and non-textured polygons are handled better
now (non-textured polygons receive (0,0) uvs on all vertices).
Image reader handles 16bit grayscale textures properly now.
faster and more stable geometry.area.
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.
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.
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, roofPyramidoperations 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, faceIndex) 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 imported 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)
-
3.7.2. Annotations
Synopsis
@StartRule
@Hidden
@Hidden(attr_1,...,attr_n)
@Group("level_1-group", ..., "level_n-group")
@Range(min, max)
@Range(value1, value2, value3, ...)
@Range(item_1 = value, ..., item_n = value)
@Color
@File
@File("ext_1", ..., "ext_n")
@Directory
@Location(x,y)
@Order(order)
@Description("description")
@Handle("handle_params")
Annotations are used to add additional information to a rule or an attribute. Annotations are optional and do not
affect the semantics of a rule and thus have no influence on the model generation. Annotations are mostly used to
give additional hints for user interface elements such as the Inspector on how to present attributes or rules.
@StartRule: Mark a rule as a start rule for the start rule chooser
@Hidden: Mark an attribute or rule as hidden (it will not appear in the inspector or start rule chooser)
@Hidden can also be used to hide a set of attributes (as in its second form with a list of attribute names)
before an import statement. Without explicitly naming the attributes, @Hidden before an important
statement will hide all imported attributes in the inspector.
@Group("level_1-group", ..., "level_n-group"): Set the group of the following attributes (the
inspector will group attributes accordingly). The current group is maintained accross imports. To leave
the current group, use @Group.
@Range(min, max): Set the numeric range of an attribute to min, max (inclusvie)
@Range(value1, value2, value3, ...): Set the range to specific values. Values can be numeric or
string.
@Range(item_1 = value, ..., item_n = value): Set the range of an attribute to the given
enumeration. Value can be numeric or string.
@Color: Mark an attribute as a color attribute which will present a color picker in the inspector.
@File: Mark an attribute as a file name. The inspector will present a file chooser.
@File("ext_1", ... , "ext_n"): Mark an attribute as a file name. The inspector will present a file
chooser for the given file extensions ("ext_1", ... , "ext_n")
@Directory: Mark an attribute as a directory name. The inspector will present a directory chooser.
@Location(x, y): Sets the 2D location of an attribute or rule for the visual CGA editor.
@Order(order): Sets the sort order for an attribute in the inspector. Where order is a numeric value.
@Description("description"): Adds a description to an attribute or rule which will be displayed as
tooltip in the inspector or as description in the start rule chooser or style manager.
@Handle("handle_params"): Adds an interactive handle to an attribute. The details of handle_params
are described elsewhere.
Example
Adding annotations
@StartRule
Start-->NIL
@Hidden
attr hide_me = 0
@Hidden
import hide_all_attrs: "imported.cga"
@Hidden(some_attr, another_attr)
import hide_some_attrs: "imported.cga"
@Group("First", "Second")
attr grouped = 0
@Range(5, 50)
attr height = 20
@Range(Low=0, Mid=1, High=2)
attr lod = 0
@Range(Red="#ff0000", Green="#00ff00", Blue="#0000ff")
attr color = "#000000"
@Color
attr userColor = "#000000"
@File
attr asset = "myfile.obj"
@File("tif", "tiff")
attr texture = "tex0.tiff"
@Directory
attr assets = "/assets/lod" + lod
@Location(0, 0)
Init-->NIL
@Order(1)
attr i_m_1st = 0
@Order(2)
attr i_m_2nd = 0
@Order(3)
attr i_m_3rd = 0
@Description("The building width")
attr width = 40
@Handle("shape=Solid align=right" )

Annotated attributes displayed in the Inspector.
3.7.3. 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 the root of the project where the rule file resides.
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 an example of an expanded folder structure
And below is are some excerpts from the corresponding rule file. First, some file paths are set up in the attr section;
these attributes are then used 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)
...
3.7.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 the first texture layer
(COLORMAP).
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")
3.7.5. Texturing: Essential Knowledge
This section explains concepts fundamental to a successful texturing experience.
Correspondence of uv-sets to texture layers
There is a 1:1 correspondence between uv-sets (texture coordinates sets) and texture layers (maps):
uv-set Texture Layer
0 colormap
1 bumpmap
2 dirtmap
3 specularmap
4 opacitymap
5 normalmap
For more details about the texture layers see Material Shape Attributes. and material.map: Texture Layers.
Defaults if no uv-set present
For rendering and export, each defined texture layer needs to be matched with a uv-set. If a texture layer has a
texture assigned, but the corresponding uv-set is not defined, the texture coordinates from uv-set 0 are used. If uv-
set 0 is undefined, the texture layer is ignored.
Supported Image Formats
Extension Description
bmp Microsoft's classic bitmap format.
dds Microsoft's DirectDraw Surface format.
gif The legendary Graphics Interchange Format.
jpg / jpeg JPEG compressed images.
png The popular Portable Network Graphics format.
psp / jsl Corel's Paint Shop Pro format.
sgi An homage to the Silicon Graphics workstations RIP.
tga Truevision Inc.'s TGA (or TARGA) format.
tif / tiff The flexible Tagged Image File Format.
Related
material shape attributes
material.map texture layers
deleteUV operation
projectUV operation
rotateUV operation
scaleUV operation
texture operation
4. Python Scripting
The Python Scripting Interface greatly enhances the possibilities of the CityEngine. Many tasks can be
automatized using specific Python commands.
1. Python Scripting Interface
1. Parameters and Attributes
2. Settings classes
3. Script-based Export
4. Special scripts
2. Commands by Category
3. Command Reference
4. Notes and Changelog

The availability of Python scripting depends on your CityEngine license. Not all CityEngine versions provide
the scripting environment.
4.1. Python Scripting Interface Usage
How to use the Python Console and the Editor inside 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.
See Commands by Category or Command Reference for a list of available CityEngine methods.
Command completion (Ctrl-Space) in the Python Console

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
Choose the scripts folder of a CityEngine project as Source Folder, set a Name for the module and choose one of
the templates.
New modules created via this dialog contain the following lines.
'''
Created on May 19, 2011
@author: andi
'''
from scripting import *
# get a CityEngine instance
ce = CE()
A header
an import statement that imports the CityEngine specific scripting module
from this module, the main instance ce is created, which allows to calling all CityEngine Python
commands
Running a script
To execute a script in the Editor, select PythonRun Script in the menu or press F9 . (Focus needs to be on a
Python script in the editor area to enable the Python menu).
Cancel all running Python scripts by choosing Cancel from the main toolbar (or by pressing esc ). As in the
console, you can use Ctrl-Space to show the command completion.
Below you see the default parts of the 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, 2011
@author: andi
'''
# get a CityEngine instance
ce = CE()
def export(objects):
dir = ce.toFSPath("models/")
name = "pythonTriggeredExport"
settings = OBJExportModelSettings()
settings.setBaseName(name)
settings.setOutputPath(dir)
ce.export(objects, settings)

if __name__ == '__main__':
export(ce.selection())
pass

Importing modules
Just like in regular Python, additional modules can be imported.
>>> import random
>>> random.randint(0,100)
69
To load your custom scripts, make sure to add the script directory to the Python system path, before importing your
module.
>>> import sys
>>> sys.path.append($PATH_TO_YOUR_SCRIPTS_DIRECTORY)
>>> import $YOUR_MODULE
Importing a custom Python module
Scripts shortcut menu
To quickly start a Python script it can be placed in the scripts menu ScriptsAdd scripts...
See also
Commands by Category
Command Reference

4.1.1. Parameters and Attributes
Details on the Python scripting API regarding parameters and attributes.
Parameter types for different objects
To get or set parameters a special prefix is required, starting with /ce/, followed by the type and the parameter
name:
Block Parameter on blocks /ce/block/PARAMETER, e.g. /ce/block/lotAreaMin
Street Parameters on graph segments /ce/street/PARAMETER, e.g. /ce/street/streetWidth
Intersection
Parameters
on graph nodes /ce/crossing/PARAMETER, e.g. /ce/street/minArcRadius
Rule Parameters
on shapes with rulefile
assigned
/ce/rule/PARAMETER, rule parameters defined as attrs in
the rule file
Available parameters for block, street and intersection are a fixed set (as shown in the inspector), whereas rule
parameters are an open list, defined by the attributes defined in the rule file.
Setting a user parameter
Assuming a block is selected

>>> block = ce.getObjectsFrom(ce.selection)[0]
>>> ce.setAttribute(block,"/ce/block/shapeCreation", False)
>>> ce.setAttributeSource(block,"/ce/block/shapeCreation", "USER")
The internal user attribute /ce/block/shapeCreation is set to false on the selected block. By setting the source of this
parameter to USER, the user attribute is now active for this parameter.
This changes the shapeCreation parameter on the selected block from True to False, (Disables the creation of lot
shapes on the block).
Using an object attribute as source for a parameter
Assuming a block is selected

>>> ce.setAttribute(block,"lotAreaMax", 3000)
adding a new object attribute to the selected block.
>>> ce.setAttributeSource(block,"/ce/block/lotAreaMax", "OBJECT")
Setting the source of the parameter lotAreaMax to OBJECT. This connects the existing object attribute with
matching name to the parameter. The parameter lotAreaMax now uses the value from the object attribute.
Listing attributes
Attributes of objects can be queried with ce.getAttribute, ce.getAttributeList() and
ce.getAttributeSource()
>>> ce.getAttributeList(block)
['/ce/block/seed', '/ce/block/shapeCreation', 'lotAreaMax']
Listing /ce/block/seed (user attribute), /ce/block/shapeCreation (user attribute), lotAreaMax (object attribute)
The list of internal attributes depends on the type of object queried, as well as previous user interaction on the
object.
>>> ce.getAttribute(block,"lotAreaMax")
3000.0
The value of the object attribute lotAreaMax
>>> ce.getAttributeSource(block,"/ce/block/lotAreaMax")
OBJECT
The source of the parameter /ce/block/lotAreaMax

>>> ce.getAttribute(block,"/ce/block/shapeCreation")
0
The value of the user attribute /ce/block/shapeCreation
>>> ce.getAttributeSource(block,"/ce/block/shapeCreation")
USER
The source of the parameter /ce/block/shapeCreation
4.1.2. Settings Classes
How to import and export data using setting classes.
Import and export calls are configured using special settings classes, which define the type of importer or exporter to
be used, as well as its settings. Available settings classes are listed on page Commands by Category (Operations,
Import, Export).
Import
In this example we want to import the shapefile testset_streets.shp, containing cartesian coordinates and not
needing projection on import.

importSettings = OBJImportSettings()
a new instance of the OBJ import settings class is created, containing the default settings.

importSettings.setImportAsStaticModel(False)
Setting a property of the import settings class.

print importSettings.getOffset()
[0.0, 0.0, 0.0]
Just to make sure what the set defaults are, a property of the import settings class is printed.

objfile = ce.toFSPath("assets/sphere.obj")
ce.importFile(objfile, importSettings)
setting file to import, and triggering the import with the prepared settings..

ce.importFile(objfile, importSettings, True)
setting the interactive param to True will show the import dialog and wait for user input to continue. This can be
helpful to check that import settings are set as expected.
The obj import dialog displayed with interactive enabled
Export
In this example we want to export a selection of models as obj files, with file granularity set to one file per shape.

exportSettings = OBJExportModelSettings()
a new instance of the settings class for obj model export is created, containing the default settings.

exportSettings.setBaseName("testExport")
exportSettings.setOutputPath(ce.toFSPath("models/"))
exportSettings.setFileGranularity(OBJExportModelSettings.START_SHAPE)
We set specific properties of the settings class, such as name, path and the file granularity
String parameters for functions can either be set by using the predefined string constants of a class
exportSettings.setGranularityFile(OBJExportModelSettings.START_SHAPE
or by setting the string directly
exportSettings.setGranularityFile("START_SHAPE")

ce.export(ce.selection(), exportSettings)
Starting the actual export on selected objects, using the prepared settings class.

ce.export(ce.selection(), exportSettings, True)
setting the interactive param to True will show the import dialog and wait for user input to continue. This can be
helpful to check that export settings are set as expected.
The obj model export dialog displayed with interactive enabled
Cleanup Graph Operation

cleanupSettings = CleanupGraphSettings()
a new instance of the settings class for cleanup operation is created, containing the default settings.

cleanupSettings.setIntersectSegments(False)
cleanupSettings.setMergeNodes(False)
cleanupSettings.setSnapNodesToSegments(False)
cleanupSettings.setResolveConflictShapes(True)
We set specific properties of the settings class: All cleanup options except conflict resolution are disabled

ce.cleanupGraph(ce.selection(), cleanupSettings)
Starting the cleanup operation on selected objects, using the prepared settings class.
See also
Command Reference

4.1.3. Script-based Export
Another powerful feature of the scripting interface is the Script Based Export. Arbitrary python commands can
be executed during model generation via callback methods.
Script-based export template
Create a new python export script from template File New ... Python Python Module
Choose Module: Export (Reporting) as template
Creating a new Python module from the export template
Export callback functions
When a new module is created from the export template, the following callback methods are present:
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.

Such a script can be used for
the Script based Export (Python)
This "exporter" generates the models and executes the attached python script in parallel. No geometry
files are created.
Any geometry exporter
The models are generated and exported as usual, the attached python script is executed in parallel.
OBJ export dialog with script set in Misc options
Example : Processing CGA report data
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.
The code below gives an example of how report data can be accessed and written to a file.
'''
Created on Nov 6, 2013
@author: andi
'''
# Get a CityEngine instance
ce = CE()
REPORT = ""
def initExport(exportContextOID):
global REPORT
REPORT = "Name,#Floors,totalFloorArea,averageFloorArea\n"
def finishModel(exportContextOID, shapeOID, modelOID):
shape = Shape(shapeOID)
model = Model(modelOID)
global REPORT
i = 0
totalArea = 0.0
reports = model.getReports()
if 'area' in reports.keys():
for area in reports['floorArea']:
totalArea +=area
i+=1
REPORT += "%s,%d,%f,%f\n" % (ce.getName(shape), i, area, area/i)
else :
REPORT += "%s,%d,%f,%f\n" % (model, 0, 0, 0)
def finishExport(exportContextOID):
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:
Name #Floors totalFloorArea avgFloorArea
LotSouth_35 5 357.3825 71.47651
LotSouth_37 4 335.8072 83.95179
LotSouth_38 3 379.4594 126.4865
... ... ... ...

Specific methods in callback functions
These Python methods only work in callback functions
method description
model.getReports() returns dict of CGA report() data
model.getOffsets() returns tuple of local/global export offsets

Checking Module Name
To prevent code outside the callback methods from being executed when the exporter calls the script, the module
attribute __name__ can be used to distinguish the caller.
if __name__ == '__main__':
#only do stuff is script is started directly
This allows to have a script that can both be used for normal Python exection as well as for script-based export, e.g.

def finishModel(exportContextOID, shapeOID, modelOID):
# export callback code
if __name__ == '__main__':
exportSettings = OBJExportModelSettings()
exportSettings.setMiscOptionsScript("/general/scripts/scriptbasedexport.py")
ce.export(ce.selection(), exportSettings)
In the example above the main clause will not be executed when the script is called by the script-based exporter
Module names in different contexts
Resulting module name __name__ in different contexts:
Context Module Name
context is being run by itself __main__
context is started from exporter __export__
context is started on startup procedure __startup__

See also
Command Reference

4.1.4. Special scripts
startup.py
If the file startup.py exists in the current CityEngine workspace, it will be imported as a module to the CityEngine
scripting module. The startup module is executed automatically during CityEngine startup, when a new Python
console is opened and when a script is run from the Python editor. Typical use cases for the startup script include
adding your scripting directory to the system path, or loading your custom modules to the scripting environment.
Make sure startup.py is well formed and does not contain errors. An incorrect startup.py can prevent the main
scripting module from being parsed, and can prevent correct execution of the scripting interface.
scripting.py
If the file scripting.py exists in the current CityEngine workspace root, tts content will be appended to the end of the
main CityEngine scripting module. scripting.py code executed automatically during CityEngine startup, when a new
Python console is opened and when a script is run from the Python editor. CityEngine needs to be restarted in order
to load changes in the file scripting.py.
Make sure scripting.py is well formed and does not contain errors. An incorrect scripting.py can prevent the
main scripting module from being parsed, and can prevent correct execution of the scripting interface.
See also
Command Reference
Scene Objects
CE.getObjectsFrom
CE.addGraphLayer
CE.addShapeLayer
CE.copy
CE.createShape
CE.delete
CE.findByOID
CE.getSceneCoordSystem
CE.getName
CE.getPosition
CE.getShapeFromModel
CE.getOID
CE.getVertices
CE.mergeLayers
CE.move
CE.rotate
CE.scale
CE.selection
CE.setCurveSmooth
CE.setCurveStraight
CE.setCurveHandle
CE.setName
CE.setPosition
CE.setSceneCoordSystem
CE.setSelection
CE.setVertices
Model.getOffsets
Model.getReports
Attributes
CE.addAttributeLayer
CE.deleteAttribute
CE.getAttribute
CE.getAttributeLayerExtents
CE.getAttributeList
CE.getAttributeSource
CE.getLayer
CE.getLayerAttributes
CE.getRuleFile
CE.getSeed
CE.getStartRule
CE.sampleBooleanLayerAttribute
CE.sampleFloatLayerAttribute
CE.sampleStringLayerAttribute
CE.setAttribute
CE.setAttributeLayerExtents
CE.setAttributeSource
CE.setLayerAttributes
CE.setRuleFile
CE.setSeed
CE.setStartRule
Shape Operations
CE.alignShapes
AlignShapesSettings
CE.cleanupShapes
CleanupShapesSettings
CE.convertModelsToShapes
CE.convertToStaticShapes
CE.generateModels
CE.reverseNormals
CE.subdivideShapes
SubdivideShapesSettings
CE.textureShapeTool
TexturingSettings
Graph/Street Operations
CE.alignGraph
AlignGraphSettings
CE.analyzeGraph
AnalyzeGraphSettings
CE.cleanupGraph
CleanupGraphSettings
CE.ComputeFirstStreetEdges
CE.createGraphSegments
ce.curveAutoSmooth
CurveAutoSmoothSettings
CE.generateBridges
GenerateBridgeSettings
CE.fitStreetWidths
FitStreetWidthSettings
CE.growStreets
GrowStreetsSettings
CE.resetShapeAttributes
CE.selectContinuousGraphObjects
SimplifyGraphSettings
CE.simplifyGraph
Terrain Operations
CE.alignTerrain
AlignTerrainSettings
CE.export
ImageExportTerrainSettings
CE.resetTerrain
ResetTerrainSettings
GUI
CE.get3DViews
CE.inspect
CE.openView
CE.refreshWorkspace
CE.waitForUIIdle
Filter
CE.isBlock
CE.isEnvironmentLayer
CE.isFile
CE.isFolder
CE.isGraphLayer

4.2. Python Scripting Commands by Category
@noUIupdate
View3D.addBookmark
View3D.frame
View3D.getBookmarks
View3D.getCameraAngleOfView
View3D.getCameraPerspective
View3D.getCameraPoI
View3D.getCameraPosition
View3D.getCameraRotation
View3D.restoreBookmark
View3D.setCameraAngleOfView
View3D.setCameraPerspective
View3D.setCameraPosition
View3D.setCameraRotation
View3D.setPoIDistance
View3D.snapshot
CE.isGraphNode
CE.isGraphSegment
CE.isInspector
CE.isLayer
CE.isModel
CE.isMapLayer
CE.isShape
CE.isShapeLayer
CE.isViewport
CE.scene
CE.withName
Import
CE.importFile
CEJImportSettings
DAEImportSettings
DXFImportSettings
FGDBImportSettings
KMLImportSettings
OBJImportSettings
OSMImportSettings
SHPImportSettings
Export
CE.export
CEWebSceneExportModelSettings
DAEExportModelSettings
DXFExportGraphSettings
DXFExportShapeSettings
FBXExportModelSettings
FGDBExportGraphSettings
FGDBExportModelSettings
OBJExportModelSettings
OBJExportShapeSettings
ScriptExportModelSettings
RIBExportModelSettings
SHPExportGraphSettings
VOBExportModelSettings
System
CE.getVersion
CE.getVersionBuild
CE.getVersionMajor
CE.getVersionMinor
CE.getVersionString
File
CE.closeFile
CE.newFile
CE.openFile
CE.saveFile
CE.toFSPath
CE.getRuleFileInfo
CE.upload
PortalUploadSettings
CE.exportRPK
RPKExportSettings
4.3. Python Scripting Command Reference

Package Contents

AlignGraphSettings
AlignShapesSettings
AlignStaticModelsSettings
AlignTerrainSettings
AnalyzeGraphSettings
CE
CEJImportSettings
CEWebSceneExportModelSettings
CleanupGraphSettings
CleanupShapesSettings
CurveAutoSmoothSettings
DAEExportModelSettings
DAEImportSettings
DXFExportGraphSettings
DXFExportShapeSettings
DXFImportSettings
FBXExportModelSettings
FGDBExportGraphSettings
FGDBExportModelSettings
FGDBImportSettings
FitStreetWidthSettings
GenerateBridgeSettings
GrowStreetsSettings
KMLExportModelSettings
KMLImportSettings
KMZImportSettings
Model
OBJExportModelSettings
OBJImportSettings
OSMImportSettings
PortalUploadSettings
RIBExportModelSettings
RPKExportSettings
ResetTerrainSettings
SHPExportGraphSettings
SHPExportShapeSettings
SHPImportSettings
ScriptExportModelSettings
SubdivideShapesSettings
TexturingSettings
VOBExportModelSettings
View3D
@noUIupdate
Status Commands
Status Commands
new findByOID
new copy
new mergeLayers
new addBookmark, restoreBookmark, getBookmarks
new exportRPK and settings class RPKExportSettings
new upload and settings class PortalUploadSettings
new Street/Graph operations
analyzeGraph and settings class AnalyzeGraphSettings
cleanupGraph and settings class CleanupGraphSettings
computeFirstStreetEdges
fitStreetWidths and settings class FitStreetWidthSettings
generateBridges and settings class GenerateBridgeSettings
setCurveHandle
simplifyGraph and settings class SimplifyGraphSettings
selectContinuousGraphObjects
new Shape operations
cleanupShapes and settings class CleanupShapeSettings
reverseNormals
textureShapeTool and settings class TexturingSettings
resetShapeAttributes
new Terrain operations
resetTerrain and settings class ResetTerrainSettings
alignTerrain and settings class AlignTerrainSettings
changed changed field names and values in settings classes of all model exporters
changed WebGLExportModelSettings renamed to CEWebSceneExportModelSettings
changed replaced connectivity methods (such as getNodesFromGraph) by extending getObjectsFrom.
changed replaced getUUID by getOID
removed MI Exporter
removed 3DS Exporter
2012
Status Commands
new setFirstEdge
new setStreetEdges
new separateFaces
new setCameraPoI
new combineShapes
new get/setExportedContent in CEWebSceneExportModelSettings
new get/setReportMode in DAEExportModelSettings and KMLExportModelSettings
new get/setFacesWithHoles, get/setTriangulatedMeshes in FGDBExportModelSettings
new/changed get/setStreetWidthSettings* in GrowStreetSettings
changed New argument in addAttributeLayer to add georeferenced textures.
changed *StreetWidth* changed to *StreetLanes* in AnalyzeGraphSetings
2013
Status Commands
new get/set for precision details in CEWebSceneExportModelSettings
changed get/setAddModelReports renamed to get/setEmitReports in FGDBExportModelSettings
changed set/getExportContent renamed to set/getExportGeometry in all export settings classes. Enums for
setExportGeometry renamed as well.
2014
4.4. Python Scripting Notes and Changelog
CityEngine Scripting Interface
The CityEngine scripting interface is based on Jython, a Java implementation of Python. Current version is 2.5.3.
CityEngine comes with the special Jython module scripting containing CityEngine specific commands (see list of
classes)
Jython supports almost all modules of the standard Python library. In addition, Jython can include arbitrary Java
classes to extend its functionality. Please see the Jython website for more details.
Changelog
2014.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
Status Commands
changed CleanupGraphSettings
fixed getVertices, getPosition on dynamic shapes
2010.1
Status Commands
new ExportTerrainSettings for all model export formats
new VOBExportModelSettings
new @noUIupdate
changed getObjectsFrom moved to class CE
2010.2
Status Commands
new getCameraPosition, getCameraRotation, getCameraPoI
new convertToStaticShapes
new setCurveStraight, setCurveSmooth, curveAutoSmooth + settings
new isStaticModel, isStaticModelLayer filters
new createStaticModel, addStaticModelLayer
new alignStaticModels + settings
new setSceneCoordSystem
new importAsStaticModel option for OBJ and DAE import settings
new FGDBImportSettings class
changed Syntax changes in settings classes (commands now in better readable CamelCase)
2010.3
Status Commands
update updated to Jython 2.5.2
new getLayer
2011
update updated to Jython 2.5.3
new convertModelsToShapes
new FGDBExportModelSettings
new FGDBExportGraphSettings
new WebGLExportModelSettings
new getSceneCoordSystem
new terrain export settings in all model export classes (e.g.
OBJExportModelSettings.setGeneralTerrainLayers)
removed all terrain export format settings classes(e.g. OBJExportTerrainSettings)
removed OBJExportShapeSettings (use model export with shape settings instead)
2011 SR1

CityEngine Help

Загружено:

Сведения о документе

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

CityEngine Help

Загружено:

Авторское право:

Доступные форматы

10/16/2014 CityEngine Help

Вам также может понравиться