Convert formats with the CityParquet CLI

Convert CityJSON, CityJSONSeq, and CityGML into CityParquet packages and export them again from the command line.

The cityparquet command-line tool converts local city-model files into CityParquet packages and exports them again. This walkthrough uses a Delft CityJSONSeq file and shows the equivalent commands for CityJSON, CityGML and FlatCityBuf. For SQL-based conversion, use the DuckDB format-conversion tutorial.

Install the CLI

The CLI is published on crates.io as cityparquet-cli. With Rust and Cargo installed:

cargo install cityparquet-cli --locked
cityparquet --help

Cargo installs the cityparquet executable in its bin directory, normally ~/.cargo/bin; ensure that directory is on your PATH.

Without Rust, download a prebuilt binary from the repository’s releases instead. Each release of the crates attaches one archive per platform, cityparquet-vX.Y.Z-<target>: .tar.gz for Linux (x86_64 and aarch64-unknown-linux-gnu) and macOS (aarch64 and x86_64-apple-darwin), .zip for Windows (x86_64-pc-windows-msvc). Unpack it and put cityparquet on your PATH.

Convert CityJSONSeq to CityParquet

Download the Delft example into a working directory:

mkdir -p conversion-example
cd conversion-example
curl -fL https://cityjson.open3d.city/cityjsonseq/delft.city.jsonl \
  -o delft.city.jsonl

Convert it into a package:

cityparquet convert delft.city.jsonl --output delft_package

The package holds what the source carries and nothing more, which keeps it comparable with its source later. --lod0 would additionally synthesise an LoD0 footprint for every object that has no LoD0 geometry of its own.

The output is a directory containing one Parquet object table per CityGML module and a metadata.json file. Delft’s buildings and building parts go into building.parquet. Material, texture, and implicit-geometry sidecars are written when the source contains those data. See the package layout.

Use a new output directory for another conversion. To replace an existing package deliberately, add --overwrite.

Convert CityJSON, CityGML or FlatCityBuf

The same command accepts a CityJSON document, a CityGML 2.0 or 3.0 file, or a FlatCityBuf file. Replace these example input names with your own local files:

cityparquet convert model.city.json --output cityjson_package
cityparquet convert model.gml --output citygml_package
cityparquet convert model.fcb --output flatcitybuf_package

If a source lacks a coordinate reference system, supply its known EPSG code with --crs, for example --crs EPSG:7415 for the Dutch reference system. This declares the source CRS; it does not reproject coordinates or override a CRS already declared by the source.

Several input files can be merged into one package:

cityparquet convert tile_a.city.jsonl tile_b.city.jsonl --output combined_package

Export to CityJSONSeq or CityJSON

Pass the package directory and an output filename. The suffix selects the format:

cityparquet export delft_package delft_export.city.jsonl
cityparquet export delft_package delft_export.city.json

.city.jsonl produces CityJSONSeq; .city.json produces a single CityJSON document. Review the export report for any dropped instances or appearance references before treating the conversion as lossless.

Export to CityGML

A .gml suffix selects the CityGML writer. It writes CityGML 2.0 unless --citygml-version 3.0 asks for 3.0:

cityparquet export delft_package delft_export.gml
cityparquet export delft_package delft_export_3.gml --citygml-version 3.0

Every city object is written, with its geometry, semantic surfaces, attributes, appearance and ADE content, in the order the version’s schema requires. What the target version cannot hold is left out, and the export prints one warning: CityGML: line per kind with its count: a class the version lacks (a BuildingStorey in 2.0), or a LoD 4 geometry in 3.0 whose object already has geometry at LoD 3. Check those warnings for your model: no warning means the CityGML writer left nothing out. The report line’s last two numbers count what the export itself dropped, as for CityJSON.

Check the CityJSONSeq round trip

Compare the exported CityJSONSeq with the downloaded source:

cityparquet compare delft.city.jsonl delft_export.city.jsonl

equal (excluded: 21)

The comparator checks semantic equality rather than identical file bytes. It prints equal and exits with code 0 when the models match; the count in brackets is how many things it set aside rather than compared, such as the geographicalExtent it derives from the bounding box. Differences produce exit code 2 and a report. The comparator reads CityGML too, but a CityGML export does not compare equal to its CityJSON source: CityGML has no LoD 1.2 or 2.2, and the writer stores boolean attributes as text, so compare delft.city.jsonl delft_export.gml reports those differences and exits with code 2.

You now have a CityParquet package for analysis and exported files for exchange. Continue with Getting started to query a package, or inspect cityparquet convert --help and cityparquet export --help for command options.