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
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.
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.
fcb_demo.mp4
- 3DBAG all (70GB): serialised whole 3DBAG dataset with spatial and attribute indexing
- 3DBAG small (3.4GB)
- Delft (6MB)
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
| 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 |
FlatCityBuf delivers 10-20× faster data retrieval compared to CityJSONTextSequence formats:
| 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
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
- 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
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)
- Rust toolchain (1.83.0 or later)
- Node.js ≥ 22.12 (for the TypeScript reader in
src/ts)
Rust CLI: Install from crates.io
cargo install fcb_cli --lockedThis installs the fcb binary to your Cargo bin directory (usually ~/.cargo/bin/).
Python: Install from PyPI
pip install flatcitybufFor more details, see PyPI documentation
JavaScript/TypeScript: Install from npm
npm install @cityjson/flatcitybufFor more details, see npm documentation
# 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 --releaseThe 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.
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# Core reading benchmarks
cargo bench -p fcb_core --bench read -- --release- 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!
We welcome contributions from the community! Please see our Contributing Guidelines for details on:
- 🐛 Reporting bugs
- 💡 Requesting features
- 🔧 Submitting pull requests
- 📝 Improving documentation
This project builds upon the excellent work of the geospatial and 3D GIS community:
-
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).
- CityJSON - For the semantic foundation of 3D city models
- FlatBuffers - Google's cross-platform serialization library
- OGC CityGML - International standard for 3D city models
This project is licensed under the MIT License - see the LICENSE file for details.
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}
}