Setup and Usage¶

There are two ways to run City2TABULA: the Docker setup, which is the recommended one, and a manual installation for development work that needs direct control over the environment.

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 the 3D city data under data/ before starting the containers, one folder per source dataset:

data/
├── lod2/<country>/<dataset>/
│   ├── attribution.json
│   ├── gml/        # CityGML files
│   └── cityjson/   # CityJSON files
└── lod3/<country>/<dataset>/
    ├── attribution.json
    ├── gml/
    └── cityjson/

Example

A Bavarian LoD2 dataset goes in its own folder under data/lod2/germany/, with its CityGML files in gml/:

data/
└── lod2/
    └── germany/
        └── bavaria/
            ├── attribution.json
            └── gml/
                └── 786_5416.gml

Every dataset folder needs an attribution file

attribution.json credits the dataset's provider and is required: a missing or invalid file stops the import with an error naming the folder. Its format is described in Dataset attribution file.

Only gml/ (imported as CityGML) and cityjson/ (imported as CityJSON) are read; a dataset folder needs at least one of them. Anything else in a dataset folder, such as downloaded archives, scripts or licence documents, is ignored. A model file directly in a country folder is an error.

The Data page lists sources to download from.

Step 3. Create Docker Container¶

This builds the Docker images, starts the containers, and runs the interactive setup script for the environment variables and database connection settings. The script prompts for each value.

Run the command for the operating system in use:

# Linux/macOS
make setup

# Windows (Command Prompt)
setup.bat setup

# Windows (PowerShell)
./setup.ps1 setup

Step 4. Create database¶

After setup completes, create the database:

# Linux/macOS
make create-db

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

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

Note

Running this against an existing database requires either a different database name or a reset first. The database name is set in docker.env. To change it:

# 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¶

The final step runs the extraction pipeline and writes the output data to the database:

# 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 targets Linux development environments. On Windows, use the Docker setup: a local installation there needs additional configuration (WSL2, a manual Java setup) that this guide does not cover.

Prerequisites (dev)¶

Requirement	Version	Notes	Download Link
Go	1.25+	Builds City2TABULA	golang.org
PostgreSQL	15 to 18	Used by City2TABULA and citydb-tool	postgresql.org
PostGIS	3.4+	Spatial types and functions	postgis.net
Java	17+	Required by citydb-tool	oracle.com
Git	2.25+	Clones the repository	git-scm.com
citydb-tool	v1.3.2	Unzip and place the `citydb-tool` directory anywhere; its path goes in `.env`	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. Unzip the citydb-tool release and note the path to the extracted citydb-tool-<version> directory, which Step 4 needs.

Step 3. Build the binary¶

go build -o c2t ./cmd/c2t

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  # the local PostgreSQL instance
CITYDB_TOOL_PATH     # path to the citydb-tool directory from Step 2 (not needed in Docker, where it is in the image)

Every key is described in Configuration. CITYDB_SRID and CITYDB_SRS_NAME are derived from COUNTRY. Set them only for a country missing from that lookup table (internal/config/srid.go).

DB_NAME is a base name. The tool appends the country's ISO 3166-1 alpha-2 code (DB_NAME=city2tabula with COUNTRY=netherlands gives city2tabula_nl) and creates the database if it is absent. To use an existing database, give that database the suffixed name.

Step 5. Add the data¶

Place the 3D city data under data/ in the same layout as the Docker setup: one folder per source dataset holding an attribution.json, a gml/ folder for CityGML and a cityjson/ folder for CityJSON.

data/
├── lod2/<country>/<dataset>/{attribution.json, gml/, cityjson/}
└── lod3/<country>/<dataset>/{attribution.json, gml/, cityjson/}

Step 6. Create the database and run the pipeline¶

./c2t -create-db          # creates CityDB and City2TABULA schemas, then imports the data
./c2t -extract-features   # runs the feature extraction pipeline

./c2t -help lists every flag, including -reset-db and -link-pylovo.