cuulee / py3dtilers

Tilers accepting various input formats (OBJ, 3dCity databases, GeoJson) and producing 3dTiles tilesets.

Python 3DTiles Tilers

p3dtilers is a Python tool and library allowing to build 3D Tiles tilesets out of various geometrical formats e.g. OBJ, GeoJSON, IFC or CityGML through 3dCityDB databases.

p3dtilers uses py3dtiles python library (forked from Oslandia's py3dtiles) for its in memory representation of tilesets.

py3dtilers can only produce Batched 3D Models (B3DM). If you want to produce Point Clouds (PNTS), see Oslandia's py3dtiles CLI.

CLI Features

• ObjTiler: converts OBJ files to a 3D Tiles tileset
• GeojsonTiler: converts GeoJson files to a 3D Tiles tileset
• IfcTiler: converts IFC files to a 3D Tiles tileset
• CityTiler: converts CityGML features (e.g buildings, water bodies, terrain...) extracted from a 3dCityDB database to a 3D Tiles tileset
• TilesetReader: read, merge or transform 3DTiles tilesets

Installation from sources

For Unix

Install binary sub-dependencies with your platform package installer e.g. for Ubuntu use

apt-get install -y libpq-dev       # required usage of psycopg2 within py3dtilers
apt install python3 python3-pip    # Python3 version must be <=3.9

First create a safe python virtual environment (not mandatory yet quite recommended)

apt install virtualenv
virtualenv -p python3 venv
. venv/bin/activate
(venv)$

Then, depending on your use case, proceed with the installation of py3dtilers per se

• py3dtilers usage use case:
  Point pip directly to github (sources) repository with

  (venv)$ pip install git+https://github.com/VCityTeam/py3dtilers.git

• py3dtilers developers use case:
  Download py3dtilers sources on your host and install them with pip:

  apt install git
  git clone https://github.com/VCityTeam/py3dtilers
  cd py3dtilers
  (venv)$ pip install -e .

For Windows

Install python3 (<= 3.9).

In order to install py3dtilers from sources use:

git clone https://github.com/VCityTeam/py3dtilers
cd py3dtilers
python3 -m venv venv
. venv/Scripts/activate
(venv)$ pip install -e .

About IfcOpenShell dependency

Caveat emptor: make sure, that the IfcOpenShell dependency was properly installed with help of the python -c 'import ifcopenshell' command. In case of failure of the importation try re-installing but this time with the verbose flag, that is try

(venv)$ pip install -e . -v

and look for the lines concerning IfcOpenShell.

Usage

In order to access to the different flavors of tilers, refer to the corresponding readmes to discover their respective usage and features:

• CityTiler readme
• GeojsonTiler readme
• ObjTiler readme
• IfcTiler readme
• TilesetReader readme

Useful tutorials:

• CityTiler usage example
• GeojsonTiler usage example
• Visualize 3DTiles in Cesium, iTowns or UD-Viz
• Create 3DTiles from OpenStreetMap data
• Host CityGML data in 3DCityDB

Develop with py3dtilers

Running the tests (optional)

After the installation, if you additionally wish to run unit tests, use

(venv)$ pip install -e .[dev,prod]
(venv)$ pytest

To run CityTiler's tests, you need to install PostgreSQL and Postgis.

To setup PostgreSQL with Postgis on Windows, follow the first step (1. Download PostgreSQL/PostGIS) of 3DCityDB tutorial.
For Ubuntu, follow this tutorial.

Coding style

First, install the additional dev requirements

(venv)$ pip install -e .[dev]

To check if the code follows the coding style, run flake8

(venv)$ flake8 .

You can fix most of the coding style errors with autopep8

(venv)$ autopep8 --in-place --recursive py3dtilers/

If you want to apply autopep8 from root directory, exclude the venv directory

(venv)$ autopep8 --in-place --exclude='venv*' --recursive .

Developing py3dtilers together with py3dtiles

By default, the py3dtilers' setup.py build stage uses github's version of py3dtiles (as opposed to using Oslandia's version on Pypi. When developing one might need/wish to use a local version of py3dtiles (located on host in another directory e.g. by cloning the original repository) it is possible

1. to first install py3dtiles by following the installation notes
2. then within the py3dtilers (cloned) directory, comment out (or delete) the line reference to py3dtiles.

This boils down to :

$ git clone https://github.com/VCityTeam/py3dtiles
$ cd py3dtiles
$ ...
$ source venv/bin/activate
(venv)$ cd ..
(venv)$ git clone https://github.com/VCityTeam/py3dtilers
(venv)$ cd py3dtilers
(venv)$ # Edit setup.py and comment out py3dtiles reference
(venv)$ pip install -e .
(venv)$ pytest

Concerning CityTiler

• For developers, some design notes
• Credentials: CityTiler original code is due to Jeremy Gaillard (when working at LIRIS, University of Lyon, France)

Configuring your IDE

When configuring your IDE to run a specific tiler, you must indicate the module you want to run (e.g. py3dtilers.CityTiler.CityTiler) and not the path to the file (i.e. not ${workspace_root}/py3dtilers/CityTiler/CityTiler.py), otherwise python will not be able to resolve the relative import of the Tilers to the Common package of py3dtilers. An example of launch configuration in VSCode:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "<launch_config_name>", // e.g. "CityTiler" or "bozo"
            "type": "python",
            "request": "launch",
            "module": "<tiler_module>", // e.g. py3dtilers.CityTiler.CityTiler
            "args": ["--db_config_path", "${workspaceRoot}/py3dtilers/CityTiler/<my_config_file.yml>"],
            "console": "integratedTerminal"
        }
    ]
}

Profiling

Python standard module cProfile allows to profile Python code.

In code

Import modules:

import cProfile
import pstats

Profile the code between enable() and disable():

cp = cProfile.Profile()
cp.enable()  # Start profiling
   
# code here

cp.disable()  # Stop profiling
p = pstats.Stats(cp)
p.sort_stats('tottime').print_stats()  # Sort stats by time and print them

In command line

cProfile can be run in the shell with:

python -m cProfile script.py