PyPRT - Python Bindings for CityEngine SDK

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.

Table of Contents

• Installation
• Minimal Example
• Documentation
• Development
• Licensing Information

Installation

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.

Minimal Example

# 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()

Documentation

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

Development

Project Overview

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.

Requirements

• C++ Compiler (C++ 17)
  • Windows: MSVC 14.37 (Visual Studio 2022) or later
  • Linux: GCC 11.2 or later (we build and test on RHEL8 and compatible)
• Python (version >=3.8, <=3.11)
  • Packages: wheel, arcgis, twine, sphinx, pkginfo, xmlrunner
• Optional: Conda (e.g. miniconda3)
• CMake (version >= 3.19)
• Ninja

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:

• On Windows, use the shortcuts provided by Visual Studio or run vcvarsall.bat of the desired MSVC toolchain.
• On RHEL-based Linux, run e.g. source /opt/rh/gcc-toolset-11/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

Build Python Wheel

1. Open a shell in the PyPRT git root.
2. First time only: set up a virtual Python environment with build dependencies for PyPRT. Adapt python3.8 and the envs file to your desired OS/Python combination.
   1. Create the virtual environment: python3.8 -m venv .venv
   2. Get latest pip: .venv/bin/python -m pip install --upgrade pip
   3. Get latest wheel: .venv/bin/python -m pip install --upgrade wheel
   4. Install build dependencies for PyPRT: .venv/bin/python -m pip install -r envs/linux/wheel/requirements-py3.8.txt
3. Run .venv/bin/python -m build --wheel. This will build the CMake project and Python package. See below for native debug mode.
4. The resulting wheel is written to the temporary 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.

Build Conda Package

1. Install Miniconda or Anaconda.
2. Open a shell in the PyPRT git root and activate Miniconda (or Anaconda).
3. First time only: run 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).
4. First time only: run conda install -n pyprt -c esri arcgis (this is a workaround to reduce conda env resolving time in the step above)
5. Activate the new conda env: conda activate pyprt
6. Run conda build ./conda-recipe. This will build the CMake project and Python packages. See below for native debug mode.
7. The resulting package is written to the <miniconda home>/envs/pyprt/conda-bld/{platform} directory.

Iterative Python Development

1. Open a shell in the PyPRT git root.
2. First time only: setup a virtual Python environment with build dependencies for PyPRT, see "Build Python Wheel" above.
3. Run source .venv/bin/activate (on Windows, run .venv\Scripts\activate.bat) to activate the required Python packages.
4. Install PyPRT in current pip environment in dev mode by running 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.
5. Now you can iterate on the Python part of PyPRT...
6. To leave development mode, run pip uninstall pyprt
7. Run deactivate to leave the venv shell.

Iterative C++ Development

The src/cpp directory contains a standard CMake project with the PyPRT native extension module.

1. Follow the steps as in the section "iterative Python development" above.
2. We need to tell CMake to install the native extension module into the "live" editable PyPRT package: 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
3. Optional: To debug the native extension module, switch CMake to RelWithDebInfo mode: -DCMAKE_BUILD_TYPE=RelWithDebInfo. This will disable optimization (-O0) to provide correct per-line debugging.
4. Build with cmake --build build/cpp-release-build --target install

Running Unit Tests

Quick way to build and run all tests in a separate virtual environment:

1. Open a shell in the PyPRT git root.
2. Run helper script: python build_and_run_tests.py

Detailed steps to run tests for development (basically what the build_and_run_tests.py script does):

1. Open a shell in the PyPRT git root.
2. First time only: setup a virtual Python environment with build dependencies for PyPRT, see "Build Python Wheel" above.
3. Build and install PyPRT into local env: .venv/bin/python setup.py install
4. Run the tests: .venv/bin/python tests/run_tests.py
5. Uninstall PyPRT from local env: .venv/bin/python -m pip uninstall pyprt
6. Cleanup intermediate build files: .venv/bin/python setup.py clean --all

Build the API documentation

1. Install PyPRT in development mode as described above.
2. Run .venv/bin/sphinx-build docs build/sphinx, this will output the html files into the build/sphinx directory.
3. Leave development mode also as described above.

Build with Docker

Note: On Windows, Docker needs to be switched to "Windows Containers".

Build Wheels

1. Open a shell in the PyPRT git root
2. Create the base image for the desired build toolchain (adapt to your desired Python version):
   • Linux: docker build --rm -f envs/linux/base/Dockerfile -t pyprt-base:linux .
   • Windows: docker build --rm -f envs\windows\base\Dockerfile -t pyprt-base:windows-py3.8 --build-arg BASE_IMAGE=python:3.8-windowsservercore-1809 .
3. Create the desired image for the build toolchain (adapt to your desired Python version):
   • Linux: docker build --rm -f envs/linux/wheel/Dockerfile -t pyprt:linux-py3.8 --build-arg PY_VER=3.8 .
   • Windows: docker build --rm -f envs\windows\wheel\Dockerfile -t pyprt:windows-py3.8 --build-arg PY_VER=3.8 .
4. Run the build
   • Linux: 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'
   • Windows: docker run --rm -v %cd%:C:\temp\pyprt\root -w C:\temp\pyprt\root pyprt:windows-py3.8 cmd /c "python -m build --wheel"
5. The resulting wheel should appear in the dist directory.

Build Conda Packages

1. Open a shell in the PyPRT git root
2. Create the base image for the desired build toolchain:
   • Linux: docker build --rm -f envs/linux/base/Dockerfile -t pyprt-base:linux .
   • Windows: docker build --rm -f envs\windows\base\Dockerfile -t pyprt-base:windows .
3. Create the desired image for the build toolchain (adapt py3.8 to your desired Python version):
   • Linux: docker build --rm -f envs/linux/conda/Dockerfile -t pyprt:linux-py3.8-conda --build-arg PY_VER=3.8 .
   • Windows: docker build --rm -f envs\windows\conda\Dockerfile -t pyprt:windows-py3.8-conda --build-arg PY_VER=3.8 .
4. Run the build
   • Linux: 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'
   • Windows: 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"
5. The resulting conda package will be located in the current directly (PyPRT git repo root).

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 ([email protected]).

Back to top