Annotations #1: @Group, @Order, @Range, @Color, @Hidden

See CityEngine online documentation for the full list of Annotations

*   *   *   *   *

One defining feature of CityEngine is that we can dynamically parameterize design elements.  Put another way, we can adjust the full variety of a shape’s features in a scene using drop-down menus, sliders and form fields in the Shape Inspector panel.

Setting up these dynamic variables is done using Annotations. Create a .cga file and copy the following code into it, then save it as annotations.cga. Create a shape and assign the rule to it. The product is seen in the illustration at the top of the page.

 * File: annotations.cga
 * Created: 12 Feb 2018 09:10:23 GMT
 * Author: Jeff Herzer

version "2017.1"

// Tier 1
@Group("Dimensions", 1)

attr dimX = 1
attr dimY = 1
attr dimZ = 1.6
attr red = "#ff0000"

const green = "#00ff00"

// Tier 2
@Group("Faces", "Colors", 2)

// Tier 2a

@Color @Order(1)
attr colorFront = "#ff0000"

@Color @Order(2)
attr colorBack = "#00ff00"

@Color @Order(3)
attr colorLeft = "#0000ff"

@Color @Order(4)
attr colorRight = "#ffff00"

@Group("Faces", "CMYK", 3)
@Color @Order(4)
 attr colorC = "#00ffff"
@Color @Order(2)
 attr colorM = "#ff00ff" 
@Color @Order(3)
 attr colorY = "#ffff00" 
@Color @Order(1)
 attr colorK = "#000000" 

CubeFaces -->
 front: CubeFront |
 back : CubeBack |
 left : CubeLeft |
 right : CubeRight

CubeFront -->
CubeBack -->
CubeLeft -->
CubeRight -->

The code produces a cube with default x,y,z dimensions of 1, 1, and 1.6.  Using the @Group annotation, we have produced a group of controls under the name Dimensions, and two groups of controls (Colors and CMYK)  under the name Faces and subname Colors.

Note that dimY and dimZ variables have been given a range of 1 to 5 with a default value of 1. The dimY variable has a default value but no range is assigned. When we declare a range, the control in the Shape Inspector is given an adjustable slider below the parameter. The slider will move you between the minimum and maximum values. With no range declared, the dimX control has no slider.

You can change numeric parameters by simply entering them.  For controls with ranges, you can add numbers outside the range. As seen in the illustration below, numbers will change to bold face once a figure has been altered from its default.


@Hidden - This annotation will keep an attribute from appearing on the Inspector.  You can also do this by declaring a constant (const) rather than an attribute (attr).  Remember that attributes can be changed externally while constants cannot.

@Group(name, subname, #) - Declare groups by name followed by as many subnames are needed. In the Faces group, the two subgroups are created using the code @Group("Faces", "Colors", 2) and @Group("Faces", "CMYK", 3).  The numbers at the end allow us to list these groups in the order we wish; without the numbers, they would display alphabetically.

@Order(#) - For arranging subgroups in the desired order. Note that we have arranged the CMYK controls non-alphabetically.

@Color - This annotation marks an attribute as being a color value and causes a color chip to appear for the value selected. When the color chip is clicked, you can pick new color from the pop-up Color panel that pops up; or you can simply enter a hexidecimal color value in the form and <enter> to change it.


Do some experiments by adding new categories, subcategories and sub-subcategories.

Leave a Reply

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