PyPRT Examples

PyPRT provides a Python binding for the CityEngine Procedural RunTime (PRT). This enables the execution of CityEngine CGA rules within Python. PyPRT allows to easily and efficiently generate 3D geometries, process them as Python data structures and export them to multiple 3D file formats.

This repo contains examples of PyPRT usage. You can find installation instructions and the source code in the main PyPRT repository.

Table of Contents

• Requirements
• Running the Examples
• Available Examples
• Provided Rule Packages
• Licensing Information

More Documentation

• Built-In PRT Encoders and Options
• Authoring of Rule Packages in CityEngine
• CityEngine SDK (PRT) C++ API Reference

Requirements

• Windows 10/11 64bit or Linux 64bit (RHEL 8/9 and compatible distributions)
• Python 3.8 64bit or later. Please note, we currently provide PyPRT builds for Python 3.8, 3.9, 3.10 and 3.11. For other Python versions, please build PyPRT yourself.
• Required Python packages: see envs directory

Running the examples

PyPRT can be installed with pip install pyprt or conda install -c esri pyprt. To run the examples a few more packages are required, so please read on! :-)

Using virtualenv and pip

1. Open a shell and change to the root of this example repository.
2. First time setup:
   1. Create a virtualenv: python3.8 -m venv .venv (replace python3.8 with path to desired Python version if necessary)
   2. Update to latest pip:
      • Linux: .venv/bin/python -m pip install --upgrade pip
      • Windows: .venv\Scripts\python -m pip install --upgrade pip
   3. Update to latest wheel:
   • Linux: .venv/bin/python -m pip install --upgrade wheel
   • Windows: .venv\Scripts\python -m pip install --upgrade wheel
   1. Install required packages for the example - this will fetch PyPRT from PyPI and all packages necessary to run the examples (replace py38 with the used Python version):
      • Linux: .venv/bin/python -m pip install -r envs/linux/requirements-py38.txt
      • Windows: .venv\Scripts\python -m pip install -r envs\windows\requirements-py38.txt
3. Activate the environment:
   • Linux: source .venv/bin/activate
   • Windows: .venv\Scripts\activate.bat
4. Now run the examples, e.g. python ex1_python_encoder.py
5. For the examples based on Jupyter Notebooks, first start jupyter with jupyter notebook and then open the desired example notebook in the opened browser window.

Alternative: using Anaconda

1. Open the Anaconda prompt and change to the directory where you checked out this repository.
2. Ensure you have a working Anaconda Python 64bit installation, e.g. for Python 3.8.
3. Run conda env create --prefix env --file envs/environment-py38.yml to install PyPRT and all dependencies for the examples (replace py38 with the used Python version).
   • In case conda env create takes very long or runs into errors, try to remove arcgis from environment-pyXX.yml and manually call conda install --prefix env -c esri arcgis.
4. Activate the Anaconda environment: conda activate ./env
5. Now run e.g. python ex1_python_encoder.py to execute the corresponding Python script. For the examples based on Jupyter Notebooks, first run jupyter notebook and open the desired example notebook in the opening browser page.

In case of issues with Jupyter Notebook

• If the map widgets in e.g. example 8 do not show up, try to manually enable the corresponding notebook extensions:
  • jupyter nbextension enable --py --sys-prefix widgetsnbextension
  • jupyter nbextension enable --py --sys-prefix arcgis
• If the notebook examples do not open correctly in a Conda environment, try to run conda update --all before running jupyter notebook. This will make sure the packages are up-to-date.

Available Examples

#	Features	Notes
1	This example shows the use of the Python encoder and the encoder options for generating (or not) geometries and CGA reports.
2	This example demonstrates the use of an OBJ file as initial shape.
3	In this example, the generated models are exported as OBJ files using the PRT OBJ exporter.
4	This example shows the two ways of calling the generate_model function in case of multiple successive geometry generations.
5	This example demonstrates how PyPRT can be used to collect a dataset stored as pandas dataframe, using the PyEncoder options.
6	In this examples, VisPy is used as a mesh visualization tool taking PyPRT generated model (vertices and faces) as input.
7	This example is about optimizing the attributes of a building generated on a parcel considering the green area of the building. SciPy is used as the optimization library.	PyVista is used as a visualization tool in this example.
8	This example demonstrates how PyPRT can be used with the ArcGIS API for Python in order to collect data from ArcGIS Online, generate 3D content and publish the content back to ArcGIS Online.	Please note that in order to publish and visualize the generated models, the user needs an ArcGIS Developer account. Also, the published item needs to be manually deleted from the ArcGIS Online account before the example script can be run again (we do not want to delete things from your account).
9	In this example, PyPRT is used as a 3D geometry converter. Using PyPRT, the ArcGIS JavaScript API and the ArcGIS API for Python, you can visualize your 3D model on a map in the Web.	Please note that in order to publish and visualize the generated models, the user needs an ArcGIS Online account. To try the example, run python ex9_model_vis_web.py --username=my_AGO_username in your Python environment.
10	This example demonstrates how an existing Scene Layer can be updated without having to touch any related Web Scenes. We use PyPRT to create a Scene Layer with a 3d visualization of the Swiss population density. We then recreate the Scene Layer with different visualization properties and show how the Web Scene updates automatically.	You might want to use the keyring package to store your credentials for arcgis.com. The example script will automatically pick them up. To store the credentials execute the following once in a terminal: $ python >>> import keyring >>> keyring.set_password("arcgis.com", "your_user", "your_password")

Provided Rule Packages

Rule Package	Shape Attributes	Attributes Default Values	Brief Description
candler.rpk	BuildingHeight Mode FloorHeight GroundfloorHeight TileWidth CorniceOverhang WindowHeight FrontWindowWidth RearWindowWidth SillSize CornerWallWidth WallTexture ColorizeWall	62.0 "Visualization" 3.5 4.3 3.55 1.2 2.05 2.15 1.2 0.26 1.0 "facade/walls/bricks.jpg" "#FCEFE2"	Allows generating a "candler" building model, which is textured, detailed and realistic.
envelope2002.rpk	Density_bonus_height shape_of_building lot_coverage_parameter height_first_tier first_setback_size height_second_tier second_setback_size ground_floors_use main_building_use create_green_spaces report_but_not_display_green etc...	60.0 1.0 60.0 12.2 3.0 40.0 3.0 "commercial" "residential" false false etc...	Allows generating a realistic and detailed building.
extrusion_rule.rpk	minBuildingHeight maxBuildingHeight buildingColor OBJECTID text	10.0 30.0 "#FF00FF" 0.0 "salut"	Performs a simple extrusion of the initial shape with a height equals to a random number between the min and maxBuildingHeight.
noRule.rpk			Performs the identity operation.
translateModel.rpk	vec_x vec_y vec_z	0.0 0.0 0.0	Allows translating the initial shape in x, y and z directions.

Licensing Information

PyPRT is free for personal, educational, and non-commercial use. Commercial use requires at least one commercial license of the latest CityEngine version installed in the organization. Redistribution or web service offerings are not allowed unless expressly permitted.

PyPRT is under the same license as the included CityEngine SDK. An exception is the PyPRT source code (without CityEngine SDK, binaries, or object code), which is licensed under the Apache License, Version 2.0 (the “License”); you may not use this work except in compliance with the License. You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0.

All content in the "Examples" directory/section is licensed under the APACHE 2.0 license as well.

For questions or enquiries, please contact the Esri CityEngine team (cityengine-info@esri.com).

Back to top

Go to source code