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
• @Color
• @Description("description")
• @Directory
• @DisplayName("name")
• @Distance
• @Enum(value_1, value_2, ..., restricted=true)
• @Enum(valuesAttr=name, restricted=true)
• @File
• @File("ext_1", ..., "ext_n")
• @Group("level_1-group", ..., "level_n-group")
• @Group("level_1-group", ..., "level_n-group", order)
• @Handle(handle params)
• @Hidden
• @Hidden(attribute_1, ... , attribute_n)
• @InLine
• @InMesh
• @InPoint
• @InPointCloud
• @InPolygon
• @MaterialFile
• @Order(order)
• @Out(granularity=separatedShapes|combinedShape)
• @Percent
• @Range(min=value_1, max=value_2, stepsize=0, restricted=true)
• @StartRule

Examples

@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 tool tip in the inspector or as description in the start rule chooser or style manager. Use \n for line breaks. 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. Example: @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. Examples: @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 across 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 the 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{Line|Mesh|Point|PointCloud|Polygon} These annotations can be used to communicate the expected geometry type of the start shape. While these annotations currently have no effect in CityEngine, ArcGIS Pro expects each start rule (see above) to be annotated with the expected input type (as of ArcGIS Pro 2.4, only @InPolygon, @InMesh, @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 ArcGIS Pro, 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(3) 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 ArcGIS Pro. 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_1, max=value_2, 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