[058-059] Applying Colors and Shape Attributes in CityEngine CGA

Learn the color() and set() commands in Esri CityEngine to apply materials and control dynamic shape attributes programmatically.

This comprehensive CGA scripting tutorial covers the dual approaches to rendering materials in Esri CityEngine. You will learn how to apply simple colors using hexadecimal values and RGB arrays, modify shape properties dynamically with the set() command, and implement the @Hidden annotation to keep programmatically overridden attributes from causing interface conflicts in the Inspector UI.

So far, we have covered the most basic commands that define shape geometries: comp, split, extrude, and scope.

Applying Colors in CityEngine CGA

Starting today, we will look at commands for applying materials to shapes. First, we will examine the color command, which applies a simple color to a shape.

Below is the reference for the color command.

CityEngine CGA color reference
figure 1 : CGA color Command Reference (https://doc.arcgis.com/en/cityengine/latest/cga/cga-color.htm)

As commands go, it is on the relatively simple side.

All you need to decide when using color is whether to handle the color value as a hexadecimal or as an r, g, b array.

Using Hexadecimal and RGB Color Values

When handling it as a hexadecimal, you write the 0–255 values corresponding to r, g, b, and o converted into hex values after the '#' symbol.

Here, 'o' represents opacity, and you do not need to write it if the color is fully opaque.

Red is color("#FF0000"), green is color("#00FF00"), and blue is color("#0000FF").

When handling it as an array, instead of choosing values from 0 to 255, you write them using real numbers between 0 and 1.

Red is color(1,0,0), green is color(0,1,0), and blue is color(0,0,1).

You can use whichever of the two is more convenient for you.

Personally, I use hexadecimal when simply selecting and applying a color, and I use the array method when I need to calculate or dynamically modify colors through operations.

Shall we take a look at the code?

# Hexadecimal
@Color
attr color_hex = "#FF0000"

# RGB variables
attr color_r = 0
attr color_g = 1
attr color_b = 0

# Array
attr color_array = [0, 0, 1]

Lot -->
    color(color_hex) primitiveCone() A.
    
    t(30,0,0)
color(color_r, color_g, color_b) B.

    t(30,0,0) color(color_array[0], color_array[1], color_array[2]) C.

Cone A has hexadecimal applied; Cone B uses r, g, b as separate variables; and Cone C applies r, g, b as a mapped array.

CityEngine CGA color() demonstration

It makes sense right away, doesn't it?

You can use whichever method is more comfortable for you.

When using hexadecimal, make sure to add the @Color annotation. This allows you to use the system's built-in color picker interface.

As a helpful note,

Colors are inherited, so once assigned, they will persist as long as the rule sequence continues to propagate.

If you want to change the color, you simply re-declare it at the desired rule step.

Try modifying the code above slightly so you can control opacity as well.

Using set() to Modify Shape Attributes

There are two ways to apply a simple color material: using the color() command we learned earlier, and using the set(attribute, value) command.

Now, we will look at the second method, which involves modifying the attribute value of a Shape.

Changing Material Attributes with set()

Although it is used less frequently, the coding is highly intuitive, and it is essential to learn because you will encounter it when analyzing CGA files written by others at your learning stage.

First, let's explore which of the Shape attribute values corresponds to color.

Shape material attributes reference
figure 3 : Shape material color attributes (RGB vs Hex)

The top one specifies each color channel individually, while the bottom one accepts input as a hexadecimal code. We already touched upon this in our previous lesson.

These values belonging to shape attributes can be manipulated using the set() command.

So, let's examine set() as well.

CityEngine set command reference
figure 4 : CGA set() Command Reference (https://doc.arcgis.com/en/cityengine/latest/cga/cga-set.htm)

Using it is very straightforward.

Simply pass the attribute name and the value inside the parentheses, separated by a comma.

Now, let's verify how it is used in actual code.

Lot1 -->
    set(material.color.r, 1)
    set(material.color.g, 0)
    set(material.color.b, 0)

Lot2 -->
    extrude(10) set(material.color, "#00FF00")
    X.

Lot1 defines each RGB color component separately, whereas Lot2 utilizes a hex code representation.

CityEngine set color result
figure 6 : Visual result of Lot1 and Lot2 after set() execution

You can use whichever approach suits you best.

What is crucial here is understanding the set() command.

The set() command is not restricted only to Shape attributes; it can be applied to any declared CGA attribute.

Shall we inspect the following code?

attr r = 0

Lot -->
    extrude(10) set(r, 1) color(r, 0, 0)
    X.

After defining an attribute named r with an initial value, we modify it to 1 inside Lot and then apply it via color().

Custom attribute change visual result
figure 8 : Red color applied successfully as the attribute updates inside the rule

As expected, the color changes to red.

The syntax is fairly simple.

Understanding Attribute Overrides and Inspector Behavior

However, there is a crucial catch that you must be aware of.

Even though the r attribute was clearly changed from 0 to 1 inside the code execution, checking the Inspector panel reveals that the value of r remains at its initially declared value of 0.

This is because when attribute values are dynamically modified within the CGA code context, the changes are not reflected back onto the Inspector panel UI.

And this can lead to confusing scenarios, like the one below.

attr floors = 3
attr floor_height = 3

Lot -->
    set(floor_height, 2)
    extrude(floors * floor_height)
    X.

The code above extrudes a shape by the product of the number of floors and the floor height. However, the floor_height was overridden to 2 right before extrusion.

Extrude height inconsistency with Inspector
figure 10 : Inspector shows floor_height as 3, but extruded height is actually 6m (3 floors * 2m)

Since we changed floor_height to 2 before extruding, the building height evaluates to 6m.

Yet, the floor_height value in the Inspector panel still displays 3.

Now, try modifying floor_height inside the Inspector panel. The UI value will change, but the actual building height will remain completely unchanged.

This happens because every time that rule is executed, floor_height is forcibly hardcoded back to 2.

To prevent confusion, any attribute values that are modified internally within your code should ideally be hidden from the UI using the @Hidden annotation.

  This is especially important when creating reusable procedural assets for other users, since mismatched Inspector values can easily cause debugging confusion.

I added this tip because it's a very common pitfall that people run into when coding CGA rules.

Be sure to keep this in mind.

Specifically, modifying an attribute inside your code prevents those programmatic changes from reflecting in the Inspector UI, rendering UI-based overrides ineffective.

“Questions reveal not how little we know, but how deeply we understand. Meaningful questions begin with recognizing the limits of our knowledge.”
— Yoo Sun-Kyung, The Quality of Questions
Continue Learning
Explore complete tutorial collections for CityEngine and Global Mapper.

Comments

Popular posts from this blog

029] How to Split Polygon Areas with Intersecting Lines in Global Mapper

[008] How to Understand CGA Rule Structure in CityEngine (Beginner Guide)

046] How to Create Parallel Offset Lines in Global Mapper