FlatCityBuf 🏙️

A cloud-optimized binary format for storing and retrieving 3D city models

Bringing the semantic richness of CityJSON with the performance of FlatBuffers

🚀 Getting Started • 📊 Benchmarks • 📖 Documentation • 🤝 Contributing

---

✨ Overview

FlatCityBuf revolutionizes 3D city model storage and retrieval by combining the semantic richness of CityJSON with the performance benefits of FlatBuffers binary serialization and advanced spatial indexing techniques.

Demo

Web prototype can be available from here!

fcb_demo.mov

Example FlatCityBuf File

• 3DBAG all (70GB): serialised whole 3DBAG dataset with spatial and attribute indexing
• 3DBAG small (3.4GB)
• Delft (6MB)

🎯 Why FlatCityBuf?

Traditional CityJSON formats face significant challenges in large-scale urban applications:

• Slow parsing: Entire files must be loaded and parsed
• Memory intensive: High memory consumption for large datasets
• No spatial queries: Lack of efficient spatial indexing
• Limited cloud support: Poor performance with remote data access

🚀 Key Features

Feature	Benefit
⚡ Zero-copy Access	Access specific city objects without parsing entire files
☁️ Cloud Optimized	HTTP range requests for partial data retrieval
🗺️ Spatial Indexing	Packed R-tree for lightning-fast spatial queries
🔍 Attribute Indexing	Static B+Tree for instant attribute-based filtering
🌐 Multi-platform	Rust core with WASM bindings for web applications

---

🚄 Performance & Benchmarks

FlatCityBuf delivers 10-20× faster data retrieval compared to CityJSONTextSequence formats:

Speed Comparison Results

Dataset	CityJSON	FlatCityBuf	Speed Improvement	Memory Reduction
3DBAG	56 ms	6 ms	8.6×	4.7× less memory
3DBV	3.8 s	122ms	32.6×	4.5× less memory
Helsinki	4.0 s	132ms	30.6×	2.9× less memory
NYC	887 ms	43 ms	20.7×	4.1× less memory

📈 Performance: 8.6-256× faster queries with 2.1-6.4× less memory usage

---

🏗️ Project Structure

flatcitybuf/
├── 📦 fcb_core/          # Core library for reading/writing FlatCityBuf
├── 🛠️ fcb_cli/           # Command-line interface and tools
├── 🌐 fcb_wasm/         # WebAssembly bindings for browsers
├── 📚 docs/             # Documentation and examples
└── 🧪 examples/         # Usage examples and tutorials

Technology Stack

• Core: Rust with zero-copy deserialization
• Serialization: FlatBuffers schema with custom optimizations
• Spatial Index: Packed R-tree for efficient range queries
• Attribute Index: Static B+Tree for attribute indexing
• Web Support: WebAssembly bindings via wasm-pack
• CLI: Comprehensive command-line tools

---

🚀 Getting Started

Prerequisites

• Rust toolchain (1.83.0 or later)
• wasm-pack (for WebAssembly builds)

📦 Installation

Package Manager Installation

Python: Install from PyPI

pip install flatcitybuf

For more details, see PyPI documentation

JavaScript/TypeScript: Install from npm

npm install @cityjson/flatcitybuf

For more details, see npm documentation

Build from Source

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

# Build the core library and CLI
cargo build --workspace --all-features --exclude fcb_wasm --release

# Build WebAssembly module (optional)
cd wasm && wasm-pack build --target web --release --out-dir ../../ts

🛠️ CLI Usage

Convert CityJSONSeq to FlatCityBuf

replace cargo run -p fcb_cli with fcb in the following commands if you want to use the binary directly.

# Basic conversion
cargo run -p fcb_cli ser -i input.city.jsonl -o output.fcb

# With compression and indexing options
cargo run -p fcb_cli ser -i data.city.jsonl -o data.fcb

# With spatial index and attribute index
cargo run -p fcb_cli ser -i data.city.jsonl -o data.fcb --attr-index attribute_name,attribute_name2 --attr-branching-factor 256

# Show information about the file
cargo run -p fcb_cli info -i data.fcb

🧪 Run Benchmarks

# Core reading benchmarks
cargo bench -p fcb_core --bench read -- --release

---

📚 Documentation

• API Documentation - Comprehensive API reference
• MSc thesis at TU Delft - FlatCityBuf was developed by @hideba for his MSc thesis in Geomatics, read all the details!

---

🤝 Contributing

We welcome contributions from the community! Please see our Contributing Guidelines for details on:

• 🐛 Reporting bugs
• 💡 Requesting features
• 🔧 Submitting pull requests
• 📝 Improving documentation

---

🙏 Acknowledgements & Special Thanks

Core Contributors

This project builds upon the excellent work of the geospatial and 3D GIS community:

Technical Foundations

• FlatGeobuf - FlatGeobuf team Licensed under BSD 2-Clause License. Provided the foundational spatial indexing algorithms and FlatBuffers integration patterns.

• CityBuf - 3DBAG organisation Original FlatBuffers schema for CityJSON features, authored by Ravi Peters (3DGI) and Balázs Dukai (3DGI).

Standards & Specifications

• CityJSON - For the semantic foundation of 3D city models
• FlatBuffers - Google's cross-platform serialization library
• OGC CityGML - International standard for 3D city models

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📖 Citation

The reserach paper has been published on 20th 3D GeoInfo conference in 2025. The paper is publicly availabe on ISPRS achives and its DOI is 10.5194/isprs-archives-XLVIII-4-W15-2025-17-2025

If you use FlatCityBuf in your research, please cite:

@inproceedings{25_3dgeoinfo_fcb,
 author = {Baba, Hidemichi and Ledoux, Hugo and Peters, Ravi},
 title = {{FlatCityBuf}: {A} new cloud-optimised {CityJSON} format},
 booktitle = {Proceedings 20th 3D GeoInfo Conference},
 year = {2025},
 volume = {XLVIII-4/W15-2025},
 pages = {17--24},
 address = {Tokyo, Japan},
 publisher = {ISPRS},
 doi = {10.5194/isprs-archives-XLVIII-4-W15-2025-17-2025}
}

---

⭐ Star us on GitHub • 🐛 Report Issues • 💬 Discussions