You can export CityEngine scenes into a set of Universal Scene Description (USD) files with minimal loss of information, which makes it suitable as an interchange format for further processing of (potentially) large scenes in VFX pipelines. CityEngine layers, object boundaries, and asset instance information are preserved after export. Any PBR materials are exported to the USDPreviewSurface material, which guarantees correct shading in any compatible downstream application without additional material assignment work.
Use cases
The following are use cases for exporting USD data:
- Focus on compatibility with tools such as SideFX Houdini and its Solaris component, Foundry Katana, and corresponding USD-compatible renderers.
- Export large models with complex rules while retaining shape granularity (no merging of geometry). This allows edits (for example, move or scale) to individual objects (for example, buildings) in downstream tools without the exporting the whole scene again.
- Preserve instances—for example, inserted assets not involved in CGA operations are exported as separate nodes. This allows limited editing (translate or scale) of these assets in downstream tools.
- Support for PBR materials using the standard USDPreviewSurface material schema.
Export options
In addition to some of the general export options, the following options are available for USD export:
| Option | Description |
|---|---|
| Mesh Merging | Choose between creating one mesh per material per object, or one mesh per object with materials being mapped to polygon groups. |
| File Type | Choose between exporting a hierarchy of .usdc files and textures or a single .usdz package. |
Exported file layout
For each USD export session, a set of directories and files is created:
- <basename>.usdc is the root file with references to the CityEngine layers.
- The layers directory receives one .usd file per involved CityEngine layer. The layer files contain the scene objects (for example, building models), which reference the geometry assets.
- The assets directory receives one .usd file per asset as well as two special files:
- generated.usdc receives all geometry that is generated by CGA.
- materials.usdc receives all unique materials.
- The textures directory receives all texture files referenced by materials.usdc.
Scene layout
Any USD importer will compose the above USD layer files into the following composed USD stage (scene graph):
| Scene Hierarchy | USD Prim Type | USD Kind |
|---|---|---|
/<export base name> | Xform | Group |
/<CityEngine layer(s)> | Xform | Group |
/<CityEngine object(s)> | Xform | Assembly |
/<generated CGA leaf shape(s)> | Xform | Component |
/mesh | Mesh | |
/material | Material | |
/PBRShader | UsdPreviewSurface | |
/<texture(s)> | UsdUVTexture | |
/<uv0Reader> | UsdPrimvarReader_float2 |
Items not in angle brackets are named as indicated in the table, all other prims take the corresponding CityEngine scene, asset, or UV set names. As an example, here's the USD prim path to a PBRShader prim in an exported model from the "Philadelphia" example: /Philadelphia/Development___Complete_Block/Shape/shape/material/PBRShader.
Metadata export
The USD exporter always writes metadata (object attributes, the main CGA rule attributes, non-default CGA user attribute values, and CGA reports) to USD prims (= the USD scene graph nodes). Because of different granularity, not all metadata are written to the same USD prims. The resulting USD attribute names are prefixed with "CityEngine:", see below.
By referring to the scene layout above, the metadata are written as follows:
- "CityEngine:ID" is written to all "CityEngine object(s)" and contains the CityEngine object ID (OID), as visible in the Information section of the CityEngine Inspector.
- Object attributes are also exported to "CityEngine object(s)" prims. The names are prefixed with "CityEngine:Object:". For example, the CityEngine "streetWidth" object attribute is exported as "CityEngine:Object:streetWidth" with values of type double array.
- The main CGA rule attributes are also written to the "CityEngine object(s)" prims:
- "CityEngine:Rule:RuleFile" receives the absolute workspace path to the cgb file, for example /Example_Philadelphia__2022_1/bin/Generic Modern Buildings.cgb.
- "CityEngine:Rule:StartRule" receives the start rule name used to generate the model.
- "CityEngine:Rule:RandomSeed" receives the per-object random seed, as visible in the Information section of the CityEngine Inspector.
- Non-default CGA attributes are also written to "CityEngine object(s)" prims and prefixed with "CityEngine:Rule:User:".
- CGA report values are written on the level of "generated CGA leaf shape(s)" as array values in non-summarized form. For example, the report produced by the CGA statement report("Lot Area (m2)",Lot_Area) ends up on the leaf shape prim as "CityEngine:Reports:Footprint_Area_m2" (Parentheses are converted to underscore) with an array value of all emitted reports.