Tutorial Notes – 06: Basic Shape Grammar

Buildings generated from the tutorial’s four CGA scripts (click to enlarge)



ESRI says the Tutorial 6 scripts contain “all the steps needed to create a basic building”.  Oh, I’ll vouch for that. You should understand what each of these functions do and how they can be grouped to get the results you want.

My strategy with this tutorial: Whenever I learn a new programming language, CGA in this case, I often spend time just looking at code until it becomes familiar. Maybe that’s a holdover from my days as a music major.  Like a piece of sheet music, I should be able to “sight read” any script and articulate, step by step, what’s going on.  This tutorial talks you through the scripts in just the same way, and there is plenty learn.

Rather than reproduce a talk-through, I will instead list and describe all of the Shape Operations, Utility Functions, Built-In Functions and other programming features that appear in the Tutorial 6 scripts. Descriptions are based on ESRI documentation. Some of these are covered in posts in the CGA Code Lessons category; run a search using this term.


  • builtin: – Calls assets and textures which are built-in to CityEngine and are always available.
  • case/else – The CGA equivalent of an if/elseif/else statement, used to generate different successors for different conditions of rule parameters or shape attributes.
  • color – Sets the color of the current shape’s material.
  • comp(f) – Component Split for the shape’s faces (f), a shape operation that puts each defined component into a new shape
  • extrude( ) – A shape operation that extrudes the shape along the designated axis. Think of how they make spaghetti.
  • fileRandom( ) – A utility function that returns a random file from a list specified in a searchQuery.
  • i( ) – Insert, a shape operation that 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 so its bounding box coincides with the scope.
  • NIL – Just what it says. Assign this Shape Operation to segments in Split operations to create holes.  It can also be used to terminate recursive rules.
  • primitiveCube( ) – A Shape Operation that inserts a cube shape of a specified size into the scope of the current shape.
  • projectUV( ) – As x, y, z are coordinates in three-dimension space, u, v are coordinates on a two-dimensional plane. Think of a slide projector. You are going to project a texture onto a surface with the x,y coordinates lining up with the u,v coordinates as defined in setupProjection, below.
  • rand( ) – A built-in function that returns a random value between designated minimum and maximum values.
  • s( ) – As in Scope, a shape operation that sets the size vector scope.s.
    A scope is an invisible box that surrounds each shape and defines its maximum dimensions.
  • set( ) – A shape operation that sets a value to a shape attribute of the current shape.
  • setupProjection( ) – A shape operation that defines a coordinate system (u,v) for textures applied to surfaces. Used with projectUV above.
  • split(x) and split(y) – A shape operation that splits a shape along the designated axis, x, y or z.
  • t( ) – A shape operation that translates (moves) a shape/scope by the vector along it’s x-, y- and/or z- axes
  • texture( ) – a shape operation that names the texture file to use on a shape, as in the illustration below.

Items from the Tutorial 6 asset library include roof and window textures, sash windows and shop windows (click to enlarge)



Leave a Reply

Your email address will not be published. Required fields are marked *