getting_started.md

Getting started

Introduction

In this document we run pg2b3dm on a sample dataset, a shapefile from Delaware containing building footprints with a height attribute. The generated 3D tiles are visualized in a MapBox viewer.

Prerequisites

Docker GDAL (ogr2ogr)

Download data

The dataset we will use is part of the US Building Footprints.

Download dataset:

Delaware - Dover (22,532 buildings available)

Unzip the file. It contains a 'bldg_footprints.shp' shapefile with building height column.

Setup PostGIS

1] Create Docker network

In this tutorial, we'll start 3 containers: one with PostGIS database, one with the tessellation tool and finally the tiling tool pg2b3dm. Because those containers need to communicate they must be in the same network. So we'll create a network first and add the 2 containers later.

If you have already installed a PostGIS server you can skip this step.

docker network create  mynetwork

2] Start PostGIS database

docker run -d --name some-postgis -e POSTGRES_PASSWORD=postgres -p 5432:5432 -it --network mynetwork mdillon/postgis

Import buildings to PostGIS

Import the buildings to database using ogr2ogr.

ogr2ogr -f "PostgreSQL" PG:"host=localhost user=postgres password=postgres dbname=postgres" bldg_footprints.shp -nlt POLYGON -nln delaware_buildings

In PostGIS, a spatial table 'delaware_buildings' is created.

PSQL into PostGIS

PSQL into PostGIS and do a count on the buildings:

psql -U postgres

postgres=# select count(*) from delaware_buildings;

Clean data

Maybe there are some invalid polygons, let's remove them first.

postgres=# DELETE from delaware_buildings where ST_IsValid(wkb_geometry)=false;

Add id field with text type

postgres=# ALTER TABLE delaware_buildings ADD COLUMN id varchar;
postgres=# UPDATE delaware_buildings SET id = ogc_fid::text;

Add column for output triangulated geometry

postgres=# ALTER TABLE delaware_buildings ADD COLUMN  geom_triangle geometry;

Colors and styling

Add two more columns to the delaware_buildings table:

postgres=# ALTER TABLE delaware_buildings ADD COLUMN style json;
postgres=# ALTER TABLE delaware_buildings ADD COLUMN shaders json;

Update the style column with a JSON file containing walls, roof, floor colors:

Colors used:

#008000: green (floor)

#FF0000: rood (rood)

#EEC900: wall (geel)

postgres=# UPDATE delaware_buildings SET style = ('{ "walls": "#EEC900", "roof":"#FF0000", "floor":"#008000"}');

The 'colors' column will be filled in next 'bertt/tesselate_building' step.

now exit psql:

postgres=# exit

Run bertt/tesselate_building

Run bertt/tesselate_building. It does the following:

• reads the footprint heights and geometries (from wkb_geometry);

• extrudes the buildings with height value;

• triangulate the building and gets the colors per triangle;

• writes geometries to column geom_triangle (as polyhedralsurface geometries);

• writes shaders info (color code per triangle) into shaders column;

docker run -it --name tessellation --network mynetwork bertt/tesselate_building -h some-postgis -U postgres -d postgres -f cesium -t delaware_buildings -i wkb_geometry -o geom_triangle --idcolumn ogc_fid --stylecolumn style --shaderscolumn shaders

Run pg2b3dm

Run pg2b3dm, the program will make a connection to the database and 1 tileset.json and 927 b3dm's will be created in the output directory.

docker run -v $(pwd)/output:/app/output -it --network mynetwork geodan/pg2b3dm -h some-postgis -U postgres -c geom_triangle -t delaware_buildings -d postgres -a id,height --shaderscolumn shaders

Visualize in Cesium

Copy the generated tiles to sample_data\delaware\cesium\ (overwrite the tileset.json and sample tiles in tiles directory there).

Put folder 'sample_data' on a webserver (for example $ python3 -m http.server) and navigate to /delaware/cesium/index.html

If all goes well in Delaware - Dover you can find some 3D Tiles buildings.

Sample live demo in Cesium: https://geodan.github.io/pg2b3dm/sample_data/delaware/cesium/