FlatCityBuf CLI

A command-line interface for converting between CityJSON and FlatCityBuf (FCB) formats, with support for spatial and attribute indexing.

Installation

Option 1: Install from crates.io (Recommended)

cargo install fcb_cli --locked

This installs the fcb binary to your Cargo bin directory (usually ~/.cargo/bin/).

Option 2: Build from Source

# Clone the repository
git clone https://github.com/cityjson/flatcitybuf.git
cd flatcitybuf/src/rust

# Build in release mode
cargo build --release -p fcb_cli

Option 3: Run with Cargo (Development)

cd flatcitybuf/src/rust
cargo run -p fcb_cli -- <command> [args]

# Example: convert CityJSONSeq to FCB
cargo run -p fcb_cli -- ser -i input.city.jsonl -o output.fcb

Usage

fcb <COMMAND> [OPTIONS]

Commands

ser - Serialize CityJSON to FCB

Convert CityJSON files to FlatCityBuf format with optional indexing.

fcb ser -i INPUT -o OUTPUT [OPTIONS]

Options:

• -i, --input INPUT... - Input file(s) or glob patterns (supports multiple files, use '-' for stdin)
• -o, --output OUTPUT - Output file (use '-' for stdout)
• -a, --attr-index ATTRIBUTES - Comma-separated list of attributes to create index for
• -A, --index-all-attributes - Index all attributes found in the dataset
• -s, --spatial-index - Enable spatial indexing (default: true)
• --attr-branching-factor FACTOR - Branching factor for attribute index (default: 256)
• -b, --bbox BBOX - Bounding box filter in format "minx,miny,maxx,maxy"
• -g, --ge - Automatically calculate and set geospatial extent in header (default: true)

Examples:

# basic conversion from CityJSONSeq
fcb ser -i input.city.jsonl -o output.fcb

# convert CityJSON file (standard .json format)
fcb ser -i city.city.json -o output.fcb

# multiple input files
fcb ser -i file1.city.jsonl file2.city.jsonl -o merged.fcb

# glob patterns to process all matching files
fcb ser -i 'data/*.city.jsonl' -o output.fcb
fcb ser -i 'cities/**/*.city.json' -o all_cities.fcb

# with attribute indexing
fcb ser -i delft.city.jsonl -o delft_attr.fcb \
  --attr-index identificatie,tijdstipregistratie,b3_is_glas_dak,b3_h_dak_50p \
  --attr-branching-factor 256

# index all attributes
fcb ser -i data.city.jsonl -o data.fcb --index-all-attributes

# with bounding box filter
fcb ser -i large_dataset.city.jsonl -o filtered.fcb \
  --bbox "4.35,52.0,4.4,52.1"

# from stdin to stdout
cat input.city.jsonl | fcb ser -i - -o - > output.fcb

deser - Deserialize FCB to CityJSON

Convert FlatCityBuf files back to CityJSON format.

fcb deser -i INPUT -o OUTPUT

Options:

• -i, --input INPUT - Input FCB file (use '-' for stdin)
• -o, --output OUTPUT - Output file (use '-' for stdout)

Examples:

# basic conversion
fcb deser -i input.fcb -o output.city.jsonl

# from stdin to stdout
cat input.fcb | fcb deser -i - -o - > output.city.jsonl

info - Show FCB file information

Display metadata and statistics about an FCB file.

fcb info -i INPUT

Example:

fcb info -i delft.fcb

Output includes:

• File size in MB
• FCB version
• Feature count
• Bounding box coordinates
• Indexed attributes
• Title (if present)
• Geographical extent

cbor - Convert CityJSON to CBOR

Convert CityJSON to Concise Binary Object Representation format.

fcb cbor -i INPUT -o OUTPUT

bson - Convert CityJSON to BSON

Convert CityJSON to Binary JSON format.

fcb bson -i INPUT -o OUTPUT

Format Support

Input Formats

• CityJSON (.city.json) - Standard CityJSON files
• CityJSON Text Sequences (.city.jsonl) - Line-delimited CityJSON features
• FCB (.fcb) - FlatCityBuf binary format

Multi-file Support: The ser command accepts multiple input files and glob patterns. When merging files with different coordinate transforms, vertices are automatically aligned to the first file's transform.

Output Formats

• FCB (.fcb) - FlatCityBuf binary format with optional indexing
• CityJSON Text Sequences (.city.jsonl) - Line-delimited CityJSON features
• CBOR - Concise Binary Object Representation
• BSON - Binary JSON

Examples Workflow

# 1. convert cityjson to fcb with attribute indexing
fcb ser -i dataset.city.jsonl -o dataset.fcb \
  --attr-index "building_type,height,year_built" \
  --attr-branching-factor 256

# 2. check file information
fcb info -i dataset.fcb

# 3. convert back to cityjson
fcb deser -i dataset.fcb -o output.city.jsonl

# 4. filter by bounding box and index all attributes
fcb ser -i large_city.city.jsonl -o filtered_city.fcb \
  --bbox "4.35,52.0,4.4,52.1" \
  --index-all-attributes

Error Handling

The CLI provides detailed error messages for common issues:

• Invalid file formats
• Missing input files
• Malformed bounding box coordinates
• Memory limitations for large datasets

License

MIT License - see LICENSE file for details.

Related

• FlatCityBuf Core Library
• FlatCityBuf WASM
• CityJSON Specification