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.

Database configuration via settings

Database behaviour is configured through settings, read from environment variables prefixed with XMAS_ or from a .env file in the working directory. For example, db_srid is set via XMAS_DB_SRID:

XMAS_DB_SRID=25833 xplan-tools manage-db create-schema postgresql://

The settings that affect schema creation are also exposed directly as options on create-schema, which take precedence when given:

Setting (`XMAS_…`)	`create-schema` option	Purpose
`XMAS_DB_SRID`	`--srid`	EPSG SRID of the geometry columns.
`XMAS_DB_SCHEMA`	`--schema`	PostgreSQL schema for the tables (see above); `public` if unset.
`XMAS_DB_VIEWS`	`--views`	Whether per-geometry-type views are created.

The remaining settings tune PostgreSQL data access rather than schema creation: XMAS_DB_INSERT_BATCH_SIZE (features per bulk-insert batch) and the connection-pool settings XMAS_DB_POOL_SIZE, XMAS_DB_POOL_MAX_OVERFLOW, XMAS_DB_POOL_TIMEOUT, XMAS_DB_POOL_RECYCLE and XMAS_DB_POOL_PRE_PING. See the settings reference for defaults and details.

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.