FlatCityBuf 🏙️
July 27, 2026 · View on GitHub
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
Try the browser viewer live at
flatcitybuf-prototype.hideba.me —
open a .fcb over HTTP range requests (the full 3DBAG dataset by default) or a
local file, run spatial and attribute queries, and render the result with
deck.gl. No server component; reading is pure TypeScript, with export to
CityJSON/OBJ using a lazy-loaded WASM helper. Source in
examples/web. Supersedes the earlier WASM-based prototype.
https://github.com/user-attachments/assets/3ae6a0f8-7e31-42da-8f59-0396f037c716
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 plus a pure TypeScript reader for the browser and Node.js |
🚄 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
├── 🌐 src/ts/ # Pure TypeScript reader (browser + Node.js)
├── 📚 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: Pure TypeScript reader (
@cityjson/flatcitybuf), no WebAssembly - CLI: Comprehensive command-line tools
Language Bindings
FlatCityBuf provides bindings for multiple languages:
- Python – Pure-Python reader, no compiled dependency (
pip install flatcitybuf) - C++ – Native C++ bindings via CXX bridge
- TypeScript – Pure TypeScript reader for the browser or Node.js (
@cityjson/flatcitybuf)
🚀 Getting Started
Prerequisites
- Rust toolchain (1.83.0 or later)
- Node.js ≥ 22.12 (for the TypeScript reader in
src/ts)
📦 Installation
Package Manager Installation (Recommended)
Rust CLI: Install from crates.io
cargo install fcb_cli --locked
This installs the fcb binary to your Cargo bin directory (usually ~/.cargo/bin/).
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_py --release
The browser/Node.js reader is a separate pure TypeScript package in src/ts
(published as @cityjson/flatcitybuf); build it with npm ci && npm run build
from src/ts. See src/ts/README.md.
🛠️ CLI Usage
Convert CityJSON/CityJSONSeq to FlatCityBuf
Replace cargo run -p fcb_cli -- with fcb in the following commands if you want to use the installed binary directly.
Input and output are positional: the input comes first, the output second.
# Basic conversion from CityJSONSeq
fcb ser input.city.jsonl output.fcb
# Convert standard CityJSON file
fcb ser city.city.json output.fcb
# Multiple input files -- the last positional is the output
fcb ser file1.city.jsonl file2.city.jsonl merged.fcb
# Glob patterns to process all matching files
fcb ser 'data/*.city.jsonl' output.fcb
fcb ser 'cities/**/*.city.json' all_cities.fcb
# With spatial index and attribute index
fcb ser data.city.jsonl data.fcb --attr-index attribute_name,attribute_name2 --attr-branching-factor 256
# Back to CityJSONSeq
fcb deser data.fcb output.city.jsonl
# Show information about the file
fcb info data.fcb
🧪 Run Benchmarks
# Core reading benchmarks
cargo bench -p fcb_core --bench read -- --release
📚 Documentation
- API Documentation - Comprehensive API reference
- API reference, all languages - Rust, C++, Python and TypeScript docs, rebuilt on every push to
main - 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}
}