Setup and Usage¶

For using the City2TABULA tool, you have two main options: the recommended Docker-based setup for ease of use and consistency, or a manual installation for advanced users who prefer direct control over the environment for development purposes.

Docker Setup (recommended)¶

Prerequisites (Docker)¶

Requirement	Version	Notes	Download Link
Docker	20.10+		docker.com
Docker Compose	2.0+		docs.docker.com

Step 1. Download release¶

Download the latest release from GitHub. Unzip the downloaded file and navigate to the project directory:

cd city2tabula-<version>

Step 2. Download data¶

Place your 3D city data file (.gml or .json) under data/ directory before starting the containers:

data/
├── lod2/<country>/*(.gml | .json)
└── lod3/<country>/*(.gml | .json)

Example

For example, if you have a LoD2 CityGML file for Germany, you would place it in data/lod2/germany/ directory. If you have a corresponding LoD3 file, it would go in data/lod3/germany/. The directory structure should look like this:

data/
├── lod2/
│   └── germany/
│       └── germany_lod2.gml
└── lod3/
    └── germany/
        └── germany_lod3.gml

Tip

you can create subdirectories within the country directory if you have files for multiple cities or regions, e.g., data/lod2/germany/berlin/ and data/lod2/germany/munich/. Just ensure that the files are organized under the correct LoD and country directories for the tool to process them correctly.

You can download from sources listed in Data section

Step 3. Create Docker Container¶

This will build the Docker images, start the containers, and run the interactive setup script to configure environment variables and database connection settings. Follow the prompts to complete the setup.

Choose and run the appropriate command for your operating system:

# Linux/macOS
make setup

# Windows (Command Prompt)
setup.bat setup

# Windows (PowerShell)
./setup.ps1 setup

Step 4. Create database¶

After the setup is complete, you can create the database with:

# Linux/macOS
make create-db

# Windows (Command Prompt)
setup.bat create-db

# Windows (PowerShell)
./setup.ps1 create-db

Note

If you have already created the database, you will need to change the database name or reset the existing database before running the above command again. To change the database name update environment configuration in docker.env file. To reset the database, use the following command:

# Linux/macOS
make configure

# Windows (Command Prompt)
setup.bat configure

# Windows (PowerShell)
./setup.ps1 configure

To reset the database, use:

# Linux/macOS
make reset-db

# Windows (Command Prompt)
setup.bat reset-db

# Windows (PowerShell)
./setup.ps1 reset-db

Step 5. Run feature extraction¶

Final step is to run the feature extraction process, which will execute the full City2TABULA pipeline and generate the output data in the database. Use the following command:

# Linux/macOS
make extract-features

# Windows (Command Prompt)
setup.bat extract-features

# Windows (PowerShell)
./setup.ps1 extract-features

Development Setup¶

Only for Unix-based systems (Linux/macOS)

This setup is mainly intended for Linux development environments. If you’re on Windows, Docker is strongly recommended. Local installation on Windows might require additional configuration (e.g., WSL2, manual Java setup) and is not covered in this guide.

Prerequisites (dev)¶

Requirement	Version	Notes	Download Link
Go	1.21+	required for City2TABULA	golang.org
PostgreSQL	17+	required for City2TABULA & CityDB Tool	postgresql.org
PostGIS	3.5+	required for working with spatial data	postgis.net
Java	17+	required for CityDB Tool	oracle.com
Git	2.25+	required for City2TABULA	git-scm.com
CityDB Importer/Exporter	v1.1.0	Unzip and place the `citydb-tool` directory at your preferred location.	github.com

Step 1. Clone the repository¶

git clone https://github.com/thd-spatial-ai/city2tabula.git
cd city2tabula

Step 2. Install PostgreSQL, PostGIS and the CityDB tool¶

Install the versions listed in the prerequisites table above. Unzip the CityDB Importer/Exporter release and note the path to the extracted citydb-tool-<version> directory — you'll need it in Step 4.

Step 3. Build the binary¶

go build -o city2tabula ./cmd

Step 4. Configure environment variables¶

cp .env.example .env

Edit .env and set at minimum:

COUNTRY              # e.g. germany — must match one of the supported TABULA/EPISCOPE countries
DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_NAME  # your local PostgreSQL instance
CITYDB_SRID / CITYDB_SRS_NAME  # matching your COUNTRY, see the reference list in .env.example
CITYDB_TOOL_PATH     # path to the citydb-tool directory from Step 2

Step 5. Add your data¶

Place your 3D city data file(s) under data/, following the same layout as the Docker setup:

data/
├── lod2/<country>/*(.gml | .json)
└── lod3/<country>/*(.gml | .json)

Step 6. Create the database and run the pipeline¶

./city2tabula -create-db          # creates CityDB + City2TABULA schemas and imports your data
./city2tabula -extract-features   # runs the feature extraction pipeline

Use ./city2tabula -help to see all available flags (e.g. -reset-db, -link-pylovo).