Features From CityEngine Rules (3D Analyst)

Available with 3D Analyst license.

Summary

Generates 3D geometries from existing 2D and 3D input features using rules authored in ArcGIS CityEngine.

Usage

• Input features can be points, polygons, or multipatches. @StartRule in the CityEngine rule package file (.rpk) should specify the input feature type that is expected: @InPoint annotation for points, @InPolygon for polygons, or @InMesh for multipatch features. If @StartRule is not annotated with one of these, the feature type will be assumed to be polygon. An error will be raised if an unexpected geometry type is input.

• Input features can be procedurally symbolized feature layers. CityEngine rules typically define a number of properties (called attrs in CityEngine) that control how the output 3D models are generated from input shapes. For example, a rule that generates a building shell might have an attr of type double for BuildingHeight and an attr of type integer for FloorCount. If the input feature class has an attribute field with the same name and data type as a CityEngine rule property, values from that attribute field are automatically used to generate the output models. This automatic matching of CityEngine rule properties to attribute fields is called default field mapping.

  If the input feature layer is symbolized with single symbol symbology whose symbol contains one procedural symbol layer that references the same rule package as the input rule package, the tool will apply the overrides configured in the procedural symbol layer when creating the output. In this way the procedural symbol layer can be used to configure custom field mapping where the mapped field names do not exactly match the rule package attribute names, or to override a rule package attribute using a single custom value. See attribute-driven symbology for more information.

• The Rule Package parameter value is a CityEngine .rpk file. It is a compressed file containing a compiled CityEngine rule and associated assets used by that rule. The Export Leaf Shapes parameter is only available if the input rule package states that it supports this operation by containing the following CGA annotation: @StartRule @Out (granularity=separatedShapes).

• When leaf shapes are generated using the Export Leaf Shapes parameter, a standard set of feature classes are created in the same location as the primary output multipatch feature class and have the naming conventions as follows: <outputFC_Points>, <outputFC_MPoints>, and <outputFC_Lines>. All output feature classes contain an OriginalOID attribute field that references the ObjectID of the input feature from which the output was generated. The OriginalOID field can be used to join the output feature class to the input feature class. If reports are generated using the Include Reports parameter, the output feature class will also get an attribute for each report.

• An OriginalOID field is added to the output feature classes to contain the ObjectID of the input feature from which each output feature has been generated. If the input feature class already has a field named OriginalOID, the new field name is appended numerically, for example, OriginalOID2.

• Detailed errors or warnings raised during conversion are written to either a log file named ArcGISProLog<process ID and GUID>.xml (when the tool is run interactively in ArcGIS AllSource and diagnostic logging is enabled) or pythonLog<process ID and GUID>.xml (when the tool is run using a stand-alone Python script and if the diagnostic logging is enabled) in which <process ID and GUID> is a process ID and a new GUID that is appended to the name of the log file with each run of the tool, for example, ArcGISProLog-12300~1A9C1C2A-A2CB-41AF-BEB9-1F8CDC4F6D29.xml or pythonLog-2160~807AFBC8-CA35-4370-9F90-4EDB2F9238AE.xml. This file is located in <Install drive>:\Users\<user name>\Documents\ArcGIS\Diagnostics.

Parameters

Dialog

Label	Explanation	Data Type
Input Features	The input point, polygon, or multipatch features. Input features can be procedurally symbolized feature layers. Field mapping (attribute-driven symbol properties) will be honored.	Feature Layer
Rule Package	The CityEngine rule package file (*.rpk) containing CGA rule information and assets. The rule annotated with @StartRule in the .rpk file should be annotated @InPoint for a rule package intended for point features, @InPolygon for a rule package intended for polygon features, or @InMesh for a rule package intended for multipatch features. If @StartRule is not annotated with @InPoint, @InPolygon, or @InMesh, the feature type will be assumed to be polygon.	File
Output Features	The output feature class containing multipatch features with CGA rules applied. An OriginalOID field is added to the output feature classes to contain the ObjectID of the input feature from which each output feature has been generated.	Feature Class
Include Existing Fields (Optional)	Specifies whether the output feature class will include the attribute fields of the input feature class. Checked—The attribute fields of the input feature class will be included in the output feature class. This is the default. Unchecked—The attribute fields of the input feature class will not be included in the output feature class. This option will be used automatically if the Export Leaf Shapes parameter is checked.	Boolean
Include Reports (Optional)	Specifies whether the output will include additional reporting fields as specified by the procedural rule package. Depending on how the rule package has been authored, it may contain logic that generates one or more reports as the models are created. These reports can contain a variety of information about the features. An example is a rule package that reports the number of windows generated for each building model. Checked—The output feature class will include new attribute fields to hold reported values for each feature as defined by the rule package report generation logic. A unique attribute is created for each reported value. Unchecked—Reports generated in the rule package will be ignored, and no new attributes relating to the reports will be generated. This is the default. This parameter is ignored if the rule package does not contain logic to generate reports.	Boolean
Export Leaf Shapes (Optional)	Specifies whether each input feature will be convert to a single, merged multipatch feature or become a set of many features that can be points, lines, or multipatches. CityEngine rule packages construct content by generating component pieces and merging them into a single 3D object. However, these components, or leaf shapes, can also be stored as separate features. This option can be especially important when running analytical operations using subelements of a 3D object, such as the windows of a building. For example, a rule may generate seamless building models from input polygon footprints, or alternatively, it may create separate features for each apartment face, including an outward-facing panel, a representative center point, and lines showing the borders. In this example, the apartment panels, center points, and outlines are all considered leaf shapes. Checked—Additional output feature classes will be generated. The attribute fields from the input feature class will not be included in the output feature class. The output feature class will contain a field named OriginalOID that references the ObjectID of the input feature from which the output was generated. Unchecked—Additional output feature classes will not be generated, even if additional leaf shapes are defined in the logic of the rule. All of the geometry will be contained within the output multipatch features. This is the default.	Boolean

Derived Output

Label	Explanation	Data Type
Output Point Features	When leaf shapes are generated, an output point feature class is created in the same location as the primary output multipatch feature class.	Feature Class
Output Line Features	When leaf shapes are generated, an output polyline feature class is created in the same location as the primary output multipatch feature class.	Feature Class
Output Multipoint Features	When leaf shapes are generated, an output polygon feature class is created in the same location as the primary output multipatch feature class.	Feature Class

Python

arcpy.ddd.FeaturesFromCityEngineRules(in_features, in_rule_package, out_feature_class, {in_existing_fields}, {in_include_reports}, {in_leaf_shapes})

Name	Explanation	Data Type
in_features	The input point, polygon, or multipatch features. Input features can be procedurally symbolized feature layers. Field mapping (attribute-driven symbol properties) will be honored.	Feature Layer
in_rule_package	The CityEngine rule package file (*.rpk) containing CGA rule information and assets. The rule annotated with @StartRule in the .rpk file should be annotated @InPoint for a rule package intended for point features, @InPolygon for a rule package intended for polygon features, or @InMesh for a rule package intended for multipatch features. If @StartRule is not annotated with @InPoint, @InPolygon, or @InMesh, the feature type will be assumed to be polygon.	File
out_feature_class	The output feature class containing multipatch features with CGA rules applied. An OriginalOID field is added to the output feature classes to contain the ObjectID of the input feature from which each output feature has been generated.	Feature Class
in_existing_fields (Optional)	Specifies whether the output feature class will include the attribute fields of the input feature class. This parameter is not considered when the in_leaf_shapes parameter is used. INCLUDE_EXISTING_FIELDS—The attribute fields of the input feature class will be included in the output feature class. This is the default. DROP_EXISTING_FIELDS—The attribute fields of the input feature class will not be included in the output feature class. This option will be used automatically if the in_leaf_shapes parameter is set to FEATURE_PER_LEAF_SHAPE.	Boolean
in_include_reports (Optional)	Depending on how the rule package has been authored, it may contain logic that generates one or more reports as the models are created. These reports can contain a variety of information about the features. An example is a rule package that reports the number of windows generated for each building model. INCLUDE_REPORTS—The output feature class will include new attribute fields to hold reported values for each feature as defined by the rule package report generation logic. A unique attribute is created for each reported value. EXCLUDE_REPORTS—Reports generated in the rule package will be ignored, and no new attributes relating to the reports will be generated. This is the default. This parameter is ignored if the rule package does not contain logic to generate reports.	Boolean
in_leaf_shapes (Optional)	Specifies whether each input feature will be convert to a single, merged multipatch feature or become a set of many features that can be points, line, or multipatches. CityEngine rule packages construct content by generating component pieces and merging them into a single 3D object. However, these components, or leaf shapes, can also be stored as separate features. This option can be especially important when running analytical operations using subelements of a 3D object, such as the windows of a building. For example, a rule may generate seamless building models from input polygon footprints, or alternatively, it may create separate features for each apartment face, including an outward-facing panel, a representative center point, and lines showing the borders. In this example, the apartment panels, center points, and outlines are all considered leaf shapes. FEATURE_PER_LEAF_SHAPE—Additional output feature classes will be generated. The attribute fields from the input feature class will not be included in the output feature class. The output feature class will contain a field named OriginalOID that references the ObjectID of the input feature from which the output was generated. FEATURE_PER_SHAPE—Additional output feature classes will not be generated, even if additional leaf shapes are defined in the logic of the rule. All of the geometry will be contained within the output multipatch features. This is the default.	Boolean

Derived Output

Name	Explanation	Data Type
out_points	When leaf shapes are generated, an output point feature class is created in the same location as the primary output multipatch feature class.	Feature Class
out_lines	When leaf shapes are generated, an output polyline feature class is created in the same location as the primary output multipatch feature class.	Feature Class
out_multipoints	When leaf shapes are generated, an output polygon feature class is created in the same location as the primary output multipatch feature class.	Feature Class

Code sample

FeaturesFromCityEngineRules example 1 (Python window)

The following Python window script demonstrates how to use the FeaturesFromCityEngineRules function in immediate mode.

import arcpy

arcpy.CheckOutExtension("3D")
arcpy.env.workspace = "C:/data"
arcpy.ddd.FeaturesFromCityEngineRules("in_polygons", 
                                      "rules.rpk", 
                                      "out_multipatches")

FeaturesFromCityEngineRules example 2 (stand-alone script)

The following Python window script demonstrates how to enable diagnostic logging when using the FeaturesFromCityEngineRules function in a stand-alone Python script.

import arcpy
import ctypes
from arcpy import env

def enableDiagnostics(enable: bool = True):
  pro = arcpy.GetInstallInfo()['InstallDir']
  dll = ctypes.CDLL(f'{pro}/bin/DADFLib.dll')
  if enable:
    dll.EventLogEnable()
  else:
    dll.EventLogDisable()

def setLogLevel(level: int = 2):
  pro = arcpy.GetInstallInfo()['InstallDir']
  dll = ctypes.CDLL(f'{pro}/bin/DADFLib.dll')
  dll.EventLogSetLogLevel(level)

enableDiagnostics(True) #enable diagnostic logging
# Setting a log level (0 == error, 1 == warning, 2 == information, 3 == debug)
# will get that level and everything below it. 0 is only errors, 1 is warnings and errors etc.
setLogLevel(3) # Max diagnostic log level 

arcpy.CheckOutExtension("3D")
env.workspace = r"C:\data"
arcpy.ddd.FeaturesFromCityEngineRules(r"geometry.gdb\in_polygons", 
                                      "rules.rpk", 
                                      r"geometry.gdb\out_multipatches")

Environments

This tool does not use any geoprocessing environments.