Python bindings for the "Procedural Runtime" (PRT) of CityEngine by Esri.
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 or export them to multiple 3D file formats.
Run pip install pyprt
in your (virtual) Python environment or conda install -c esri pyprt
in a Conda environment. Then use import pyprt
in your scripts.
We provide wheels and Conda packages for Python 3.8, 3.9, 3.10 and 3.11 on Linux and Windows. For other Python versions please build PyPRT yourself.
# see example.py in repository root
import os
import pyprt
pyprt.initialize_prt()
# Define the input geometry
shape_geometry = pyprt.InitialShape([0, 0, 0, 0, 0, 100, 100, 0, 100, 100, 0, 0])
# Setup ModelGenerator instance for input geometry
model_generator = pyprt.ModelGenerator([shape_geometry])
# Setup generation parameters
repo_path = os.path.dirname(os.path.realpath(__file__))
rpk = os.path.join(repo_path, 'tests/data/extrusion_rule.rpk')
shape_attributes = {'shapeName': 'myShape', 'seed': 555}
encoder = 'com.esri.pyprt.PyEncoder'
encoder_options = {'emitReport': True, 'emitGeometry': True}
# Generate the model
generated_models = model_generator.generate_model([shape_attributes], rpk, encoder, encoder_options)
# Access the result
for model in generated_models:
index = model.get_initial_shape_index()
cga_report = model.get_report()
vertices = model.get_vertices()
print(f"Model {index} has vertices: {vertices} and reports {cga_report}")
pyprt.shutdown_prt()
The project is composed of two parts: the C++ native directory (src
) and Python-only directory (pyprt
). The C++ part contains a standard CMake project with PyPRT native extension. The Python bindings are done using pybind11. The pyprt
directory contains Python helper functions.
A note regarding the meaning of "open a shell" in the following sections: this implies that the shell also needs to have the correct C++ compiler activated:
vcvarsall.bat
of the desired MSVC toolchain.source /opt/rh/devtoolset-9/enable
.Note: on Windows, replace bin
with Scripts
in the following commands. Some commands also differ in their file extension between Linux and Windows (.sh
vs .bat
and similar). Please refer to the venv
documentation for details: https://docs.python.org/3.8/library/venv.html
python3.8
and the envs
file to your desired OS/Python combination.
python3.8 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install --upgrade wheel
.venv/bin/python -m pip install -r envs/linux/wheel/requirements-py3.8.txt
.venv/bin/python -m build --wheel
. This will build the CMake project and Python package. See below for native debug mode.dist
folder.Note: To build a wheel with the native extension module in debug mode, edit the debug
argument to CMakeExtension
at the bottom of setup.py
. Also see "Iterative C++ Development" below.
conda env create -n pyprt --file envs/linux/conda/environment-py3.8.yml
to create a conda environment with all the required Python packages (adapt to your desired OS/Python combination).conda install -n pyprt -c esri arcgis
(this is a workaround to reduce conda env resolving time in the step above)conda activate pyprt
conda build ./conda-recipe
. This will build the CMake project and Python packages. See below for native debug mode.<miniconda home>/envs/pyprt/conda-bld/{platform}
directory.source .venv/bin/activate
(on Windows, run .venv\Scripts\activate.bat
) to activate the required Python packages.python -m pip install --force-reinstall -e .
(note the dot at the end). This will use CMake to build the native extension module and copy it into the python source directory.pip uninstall pyprt
deactivate
to leave the venv shell.The src/cpp
directory contains a standard CMake project with the PyPRT native extension module.
cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=./src/python/pyprt/pyprt -DPython_EXECUTABLE:FILEPATH=./.venv/bin/python -S src/cpp -B build/cpp-release-build
RelWithDebInfo
mode: -DCMAKE_BUILD_TYPE=RelWithDebInfo
. This will disable optimization (-O0
) to provide correct per-line debugging.cmake --build build/cpp-release-build --target install
Quick way to build and run all tests in a separate virtual environment:
python build_and_run_tests.py
Detailed steps to run tests for development (basically what the build_and_run_tests.py
script does):
.venv/bin/python setup.py install
.venv/bin/python tests/run_tests.py
.venv/bin/python -m pip uninstall pyprt
.venv/bin/python setup.py clean --all
.venv/bin/sphinx-build docs build/sphinx
, this will output the html files into the build/sphinx
directory.Note: On Windows, Docker needs to be switched to "Windows Containers".
docker build --rm -f envs/linux/base/Dockerfile -t pyprt-base:linux .
docker build --rm -f envs\windows\base\Dockerfile -t pyprt-base:windows-py3.8 --build-arg BASE_IMAGE=python:3.8-windowsservercore-1809 .
docker build --rm -f envs/linux/wheel/Dockerfile -t pyprt:linux-py3.8 --build-arg PY_VER=3.8 .
docker build --rm -f envs\windows\wheel\Dockerfile -t pyprt:windows-py3.8 --build-arg PY_VER=3.8 .
docker run --rm -e DEFAULT_UID=$(id -u) -e DEFAULT_GID=$(id -g) -v $(pwd):/tmp/pyprt/root -w /tmp/pyprt/root pyprt:linux-py3.8 bash -c 'python -m build --wheel'
docker run --rm -v %cd%:C:\temp\pyprt\root -w C:\temp\pyprt\root pyprt:windows-py3.8 cmd /c "python -m build --wheel"
dist
directory.docker build --rm -f envs/linux/base/Dockerfile -t pyprt-base:linux .
docker build --rm -f envs\windows\base\Dockerfile -t pyprt-base:windows .
py3.8
to your desired Python version):
docker build --rm -f envs/linux/conda/Dockerfile -t pyprt:linux-py3.8-conda --build-arg PY_VER=3.8 .
docker build --rm -f envs\windows\conda\Dockerfile -t pyprt:windows-py3.8-conda --build-arg PY_VER=3.8 .
docker run --rm -e DEFAULT_UID=$(id -u) -e DEFAULT_GID=$(id -g) -v $(pwd):/tmp/pyprt/root -w /tmp/pyprt/root pyprt:linux-py3.8-conda bash -c 'conda build ./conda-recipe && cp -r /tmp/pyprt/pyprt-conda-env/conda-bld/linux-64/pyprt*.tar.bz2 /tmp/pyprt/root'
docker run --rm -v %cd%:C:\temp\pyprt\root -w C:\temp\pyprt\root pyprt:windows-py3.8-conda cmd /c "conda build ./conda-recipe && copy C:\temp\conda\envs\pyprt\conda-bld\win-64\pyprt-*.tar.bz2 C:\temp\pyprt\root"
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 ([email protected]).