CGA attributes

Attributes are a set of global variables defined in the rule file with the following properties:

  • They are global relative to the scope of the rule file.
  • Each attribute is initialized to a specific value in the rule file.
  • The attribute values can be changed individually on a per shape basis.

You can do this in the Rules pane in the Inspector window.

Note:

In contrast to functions, attributes are evaluated only once at the beginning of the generation process.

Example

attr height = 150
attr landuse = "residential"

Lot --> extrude(height) Envelope(landuse)

In this example, 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"

In this example, there is a 50 percent chance that landuse evaluates to "residential" and a 50 percent chance that it evaluates to "industrial". For each shape, the conditional or stochastic attributes are evaluated once and stay constant during the generation process.

Similarly, you can use the rand() function:

attr height = rand(30,50)

Lot --> extrude(height) Envelope

Envelope --> 
    case height < 40 : SmallBuilding
    else: LargeBuilding

For each shape that has the Lot start rule, height evaluates to a value between 30 and 50 units. This height is constant and can be used everywhere in the rule file.

Note:
  • You can click and edit the value or use the slider to modify the value. See Map attributes with the Connection Editor for more information about using different sources to control input of rule attributes.
  • The display of attributes in the Inspector window can be controlled by CGA annotations.
  • You can use interactive handles to edit attributes in the 3D view.

Change attributes in the Inspector window

You can set the values of functions marked with attr individually for each initial shape in the Inspector window. For instance, the definition below yields an entry in the Rule Parameters section.

@Range(min=10, max=40)
attr height = 20

Working with material attributes

As CGA materials consist of several attributes, you can manage CGA materials by using .cgamat files. These files are typically created with the CGA Material Encoder that is accessible using the model exporters.

version "2024.0"

@MaterialFile
attr myMaterial = "/ESRI.lib/assets/Materials/Architectural/Walls/Brick/Brick_StretcherBond_10x10_Black.cgamat"

Init -->
	primitiveCube()
	setMaterial(readMaterial(myMaterial))

A typical workflow for assigning materials to CGA models involves exposing string attributes that represent paths to .cgamat files. For example, the above rule assigns the path of one of the materials from ESRI.lib to the myMaterial attribute. The material file is read by the readMaterial function which turns it into an array of key and value pairs that can be passed to the setMaterial operation.

A string attribute can be annotated with the @MaterialFile annotation that enables the Material Browser window for the attribute. To access the Material Browser window, click the Material button Material browser or click Browser from the drop-down menu in the Inspector window.

Note:
The material browser is populated with all materials from ESRI.lib.

Also, to preview a .cgamat file in the Navigator window, right-click the file and select File Preview.

The Material Browser window provides a grid-like gallery with previews of all .cgamat material files within ESRI.lib.

Material browser

The Material Browser window displays the name of the active attribute in the title bar. Each time you select a material, it is applied to the selected models in the CityEngine scene.

Note:
The Material Browser window is non-blocking which means you can modify the camera and inspect the current selected material on the models in the Viewport window.

Click Apply to apply the material, or click Cancel to exit the Material Browser window without applying.

Also, changing the scene selection closes the Material Browser window without applying the material, similar to the Cancel button.

Assign values to multiple shapes

You can manually assign a value to multiple initial shapes quickly. Complete the following steps to assign attributes to multiple shapes:

  1. Select two initial shapes that have a rule file assigned with the height, roofColor, and roofType attributes.

    Selected shapes assigned with rule that has height, roofColor, and roofType attributes

  2. Change the height value to 40.

    The height values of both selected shapes are changed.

    Selected shapes with height values changed

  3. Select only one shape (or model), and change the height value back to the rule default of 20.
  4. Select both models.

    The height value is displayed as a question mark (?), indicating that the two selected models do not share the same value for this attribute.