FlatCityBuf 🏙️

✨ 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!

https://github.com/user-attachments/assets/ab49f026-1907-4a25-a5fb-8bc69e9a102b

🎯 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

bash pip install flatcitybuf

JavaScript/TypeScript: Install from npm

bash npm install @cityjson/flatcitybuf

Build from Source

```bash

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.

```bash

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 fcbcli ser -i data.city.jsonl -o data.fcb --attr-index attributename,attribute_name2 --attr-branching-factor 256

Show information about the file

cargo run -p fcb_cli info -i data.fcb ```

🧪 Run Benchmarks

```bash

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

If you use FlatCityBuf in your research, please cite:

bibtex @article{flatcitybuf, title={FlatCityBuf: a new cloud-optimised CityJSON format}, author={[Hidemichi Baba, Hugo Ledoux, Ravi Peters]}, year={2025}, url={https://repository.tudelft.nl/record/uuid:6727c979-5e46-4fe0-9349-a7803e825d02} }