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. The @StartRule in the CityEngine rule package (.rpk) file should specify the input feature type it is expecting: @InPoint annotation for points, @InPolygon for polygons, or @InMesh for multipatch features. If the @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 usually 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 procedurally symbolized, the custom field mappings and symbol properties defined in the procedural symbol layer are honored. You can use custom field mapping to override the default field mapping behavior defined by the rule package.

  • The input Rule Package is a CityEngine rule package (.rpk). 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 declares that it supports this operation by containing the following CGA annotation: @StartRule @Out (granularity=separatedShapes).

  • When leaf shapes are generated with 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 attribute field named OriginalOID 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 with the Include Reports parameter, the output feature class will also get an attribute for each report.

  • A field named OriginalOID is added to the output feature class(es) 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 a log file named PRT#.txt (where # is a numeral that increases incrementally with each run of the tool). This file is located in <Install drive>:\Users\<user name>\AppData\Local\ESRI\GeoProcessing.

Syntax

arcpy.3d.FeaturesFromCityEngineRules(in_features, in_rule_package, out_feature_class, {in_existing_fields}, {in_include_reports}, {in_leaf_shapes})
ParameterExplanationData Type
in_features

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 (*.rpk) file containing CGA rule information and assets. The rule annotated with @StartRule in the CityEngine rule package (.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 the @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. A field named OriginalOID is added to the output feature class(es) to contain the ObjectID of the input feature from which each output feature has been generated.

Feature Class
in_existing_fields
(Optional)

Controls whether the output feature class inherits the attribute fields of the input feature class. This parameter is not considered when the in_leaf_shapes parameter is used.

  • INCLUDE_EXISTING_FIELDSThe attribute fields of the input feature class will be included in the output feature class. This is the default.
  • DROP_EXISTING_FIELDSNo attribute fields originating from the input feature class will be added to 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 hold a wide variety of information about the features. An example is a rule package that reports the number of windows generated for each building model. This parameter is ignored if the rule package does not contain logic to generate reports.

  • INCLUDE_REPORTSNew attribute fields are created on the output feature class to hold reported value for each feature as defined by the rule package report generation logic. A unique attribute is created for each reported value.
  • EXCLUDE_REPORTSReports generated within the rule package are ignored, and no new attributes relating to these reports are generated. This is the default.
Boolean
in_leaf_shapes
(Optional)

CityEngine rule packages construct content by generating component pieces and merging them together into a single 3D object. However, it is also possible to store these components, or leaf shapes, as separate features. This option can be especially important for running analytical operations against subelements of a 3D object, such as the windows of a building.

This parameter determines whether each input feature is one of the following:

  • Converted into a single, merged, multipatch feature
  • Becomes a set of many features that can be points, lines, or multipatches

For example, a rule may generate seamless building models from input polygon footprints, or alternatively, it could 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_SHAPEAdditional output feature classes are generated. This is the default. The attribute fields from the input feature class are not included in the output feature class. The output feature class contains a field named OriginalOID that references the ObjectID of the input feature from which the output was generated.
  • FEATURE_PER_SHAPEAdditional output feature classes are not generated, even if additional leaf shapes are defined in the logic of the rule. All of the geometry is contained within the output multipatch features.
Boolean

Derived Output

NameExplanationData 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 (Python window)

The following Python window script demonstrates how to use the FeaturesFromCityEngineRules tool in immediate mode:

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

Environments

This tool does not use any geoprocessing environments.

Licensing information

  • Basic: Requires 3D Analyst
  • Standard: Requires 3D Analyst
  • Advanced: Requires 3D Analyst

Related topics