How to use the CLI

Getting started

Running the script with the help option diplays CLI commands and options:

xplan-tools --help

The help option can also be called for commands and sub-commands:

xplan-tools convert --help

Conversion between different encodings

XPlanung data can be converted between different encodings using the convert command, e.g. from GML to JSON-FG

xplan-tools convert input.gml output.json

The encoding is derived from the file path or DB connection string (URI format). To convert, for instance, a GML file to a GeoPackage, we run

xplan-tools convert input.gml gpkg:///output.gpkg

XTrasse data can be converted between different encodings using the convert command, together with the option --xtrasse:

xplan-tools convert input.gml output.json --xtrasse

If no output is provided, the data is written to stdout in the internal encoding.

Utilizing style rules

XPlanung presentational objects can be augmented with style properties (stylesheetId, schriftinhalt) via the convert command with the option --add-style-properties:

xplan-tools convert input.gml output.gml --add-style-properties

If the option --ppo-to-pto is added, XP_PPO are converted to XP_PTO objects in order to populate schriftinhalt.

The underlying rules can e.g. be exported like this:

xplan-tools serialize-style styles.yaml --format yaml

Version migration

Migrating from Xplanung version 5.x to 6.0 is done with the CLI command

xplan-tools convert xplan5x.gml --to-version 6.0

for a .gml data file xplan5x.gml.

INSPIRE transformation

Using the CLI tool to convert XPlanung data from version 6.0 to INSPIRE PLU 4.0 is straightforward. Given a dataset xplan60.gml we run

xplan-tools convert xplan60.gml --to-version plu

Chaining version migration and INSPIRE transformation

Applying the transformation to INSPIRE PLU 4.0 from XPlanung data version 5.* is done with same command as before. Given a dataset xplan5x.gml we run

xplan-tools convert xplan5x.gml --to-version plu

Initializing a database

An XPlanung database with GeoPackage backend can be initialized like this:

xplan-tools manage-db create-schema gpkg:///example.gpkg

libpq env vars are supported for Postgres connections. Assuming all required parameters (PGHOST etc.) are provided this way, an empty connection string can be used:

xplan-tools manage-db create-schema postgresql://

Use custom schema in postgres database

By default, the necessary tables in the database are created in the public namespace. For postgres, custom schemas are supported, via:

xplan-tools manage-db create-schema postgresql://postgres:postgres@localhost:5432/postgres --schema my_schema

In the above example, it is assumed that the database user executing this command has sufficient privileges on the target schema (e.g., USAGE, CREATE, INSERT, DELETE, UPDATE) and that their search_path includes the specified schema. This is required for correct table creation and data manipulation.

Container image usage

Input data should be mounted in the /data directory in the container, e.g.

docker run \
-v input/dir:/data \
registry.opencode.de/xleitstelle/xplanung/xplan-tools:latest \
convert test.gml inspire.gml --to-version=plu

The output file will then be available in the mounted directory.