Annotations

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.

Syntax

Annotations
@Angle
Adds a ° (degree) unit in Inspector and an unrestricted [0,360] range by default with slider. Use @Range to specify a different range.
Example: 
@Angle
attr angle = 180
@Color
Mark an attribute as a color attribute which will present a color picker in the inspector.
Example: 
@Color
attr userColor = "#000000"
@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. Use \n for linebreaks.
Example: 
@Description("The building width")
attr width = 40
@Directory
Mark an attribute as a directory name. The inspector will present a directory chooser.
Example: 
@Directory
attr assets = "/assets/lod" + lod
@DisplayName("name")
Adds a descriptive name to an attribute which will be displayed in the inspector instead of the attribute name.
Example: 
@DisplayName("Building height")
attr height = 20
@Distance
Adds a meter or foot unit (depending on the Coordinate System used by the scene) in Inspector.
Example: 
@Distance
attr distance = 1852
@Enum(value_1, value_2, ..., restricted=true)
Sets an enumeration with specific values. Values can be float or string. Parameter restricted is optional (default is true). If true no other values can be entered in the inspector or set by a handle.
Examples:
@Enum("low", "mid", "high")
attr lod = "low"

@Enum(10, 20, 30, restricted = false)
attr height = 20
If the @Enum annotation is applied to an array attribute, the enumeration is defined for the elements of the array.
Example:
@Enum("Residential", "Commercial")
attr floorUsage = ["Residential"]
@Enum(valuesAttr=name, restricted=true)
Sets an enumeration with specific values. The values are dynamically set by an attribute with name valuesAttr (of type float, float[], string or string[]). Parameter restricted is optional (default is true). If true no other values can be entered in the inspector or set by a handle.
Examples: 
@Enum(valuesAttr = lods)
attr lod = lods[0]
@Hidden
attr lods = ["low", "mid", "high"]

@Enum(valuesAttr = heights, restricted = false)
attr height = heights[1]
@Hidden
attr heights = [10, 20, 30]
If the @Enum annotation is applied to an array attribute, the enumeration is defined for the elements of the array.
Example:
@Enum(valuesAttr = usage)
attr floorUsage = [usage[0]]
@Hidden
attr usage = ["Residential", "Commercial"]
@File
Mark an attribute as a file name. The inspector will present a file chooser.
Example: 
@File
attr asset = "myfile.obj"
@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").
Example: 
@File("tif", "tiff")
attr texture = "tex0.tiff"
@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.
Example: 
@Group("First", "Second", "Third")
attr grouped = 0
@Group("level_1-group",..., "level_n-group", order)
Set the group and the sort order for groups/subgroups in the inspector (similar to @Order for attributes). Where order is a numeric value.
Example: 
@Group("First", "Second", "Third",1)
attr grouped = 0
@Handle(handle_params)
Adds an interactive handle to the following attribute.
Example: 
@Handle(shape=Solid, align=right)
attr dimension = 40
@Hidden
Mark an attribute or rule as hidden. Hidden attributes won't appear in CityEngine's inspector, but they will still be connected to matching object attributes automatically. Hidden rules won't appear in the start rule chooser. @Hidden before an import statement will hide all imported attributes in the inspector. All attributes imported in the hidden import will also be hidden.
Examples: 
@Hidden
attr hide_me = 0

@Hidden
import hide_me: "rule.cga"
@Hidden(attribute_1, ... , attribute_n)
@Hidden can also be used to hide a set of imported attributes before an import statement.
Example: 
@Hidden(attribute_1, attribute_2)
import rule: "rule.cga"
@In{Mesh|Polygon|Line|Point|PointCloud}
These annotations can be used to communicate the expected geometry type of the start shape. While these annotations currently have no effect in CityEngine, ArcPro expects each start rule (see above) to be annotated with the expected input type (as of ArcPro 2.4, only @InMesh, @InPolygon, @InLine and @InPoint are supported). If there is none, it defaults to @InPolygon. So if you export a rpk to be used with different geometry types in ArcPro, make sure you add one of these annotations.
@MaterialFile
Mark an attribute as a material file name. The inspector will present a specific material file chooser.
Example: 
@MaterialFile
attr mat = "myMaterial.cgamat"
@Order(order)
Sets the sort order for an attribute in the Inspector, where order is a numeric value.
Example: 
@Order(1)
attr i_m_1st = 0
@Order(2)
attr i_m_2nd = 0
@Order(13)
attr i_m_3rd = 0
@Out(granularity=separatedShapes|combinedShape)
This annotation can be used to communicate the suggested granularity of the output geometry. The default is combinedShape. While this annotation currently has no effect in CityEngine, it is essential to trigger leaf shape generation in ArcPro. Add it to the start rule in that case.
@Percent
Adds a % unit in Inspector and an unrestricted [0,1] range that displays as [0,100]. Use @Range to specify a different range. In the CGA File, the value has to be initialized to the real value (e.g. 0.1 for 10%). The Inspector will display the value in percent (e.g. 10%). The user has to enter the value in percent in the inspector.
Example: 
@Percent
attr inflation = 0.012
@Range(min=value, max=value, stepsize=0, restricted=true)
Sets the numeric range of an attribute by parameters min and max (inclusive). Parameter stepsize is optional (default is 0). If set to >0, possible values are set in respective steps starting from the minimum value. Sliders in the Inspector respect the step size. Parameter restricted is optional (default is true). If set to true, any numerical input value is set to the nearest possible value in the Inspector.
Examples: 
@Range(min=5, max=50)
attr height = 20

@Range(min=0, max=45, stepsize=15, restricted=false)
attr angle = 30
If the @Range annotation is applied to an array attribute, the range is defined for the elements of the array.
Example:
@Range(min=2.5, max=7)
attr floorHeights = [4, 5.5, 5.5]
@StartRule
Mark a rule as a start rule for the start rule chooser.
Example: 
@StartRule
Start-->NIL

Copyright ©2008-2024 Esri R&D Center Zurich. All rights reserved.