feat: support CityJSON's extension (#20)

* manage test data with git

* added test data

* define extension schema

* fix fb schema

* impl encoding of extension

* decode

* add e2e for extension

* style: format code with Rustfmt

This commit fixes the style issues introduced in 805d9c8 according to the output
from Rustfmt.

Details: #20

* docs: document about extension

* Update src/rust/fcb_core/src/writer/serializer.rs

Co-authored-by: Copilot <[email protected]>

---------

Co-authored-by: deepsource-autofix[bot] <62050782+deepsource-autofix[bot]@users.noreply.github.com>
Co-authored-by: Copilot <[email protected]>

Author: 3 people

.cursor/rules/memory/progress.md

@@ -9,21 +9,25 @@ While optimized data formats such as PMTiles, FlatBuffers, Mapbox Vector Tiles,
 ## Problems to be Solved
 
 ### Lack of Efficient 3D City Model Data Formats
+
 - Existing formats like CityJSON and CityJSONSeq are not optimized for large-scale cloud processing.
 - Limited support for spatial indexing and efficient querying.
 - Inefficiencies in downloading and processing large 3D city model datasets.
 
 ### Scalability Issues in Cloud-Native Environments
+
 - High storage and processing costs for unoptimized 3D city models.
 - Challenges in handling arbitrary extents of urban data dynamically.
 - Lack of standardized methods for fetching, sorting, and filtering large-scale 3D datasets.
 
 ### Limited Adoption of Optimized Binary Formats
+
 - Current 3D data formats do not leverage modern binary serialization techniques.
 - Need for improved compression, indexing, and partial fetching for cloud and web applications.
 - Performance limitations in current file formats for visualization and analysis.
 
 ### Research Gaps
+
 - Lack of specialized approaches for cloud-native processing of 3D city models.
 - Existing research has focused on text-based formats rather than optimized binary encoding.
 - Limited studies evaluating real-world performance benefits of FlatBuffers in geospatial applications.
@@ -32,11 +36,13 @@ While optimized data formats such as PMTiles, FlatBuffers, Mapbox Vector Tiles,
 ## How It Should Work
 
 ### Implementation of FlatBuffers for CityJSON
+
 - Integrate FlatBuffers as an optimized binary format for CityJSON.
 - Support for spatial indexing to enhance data retrieval performance.
 - Implement spatial sorting and partial fetching via HTTP Range requests.
 
 ### Optimization Methodology
+
 1. **Comprehensive Review**: Evaluate existing optimized formats (e.g., PMTiles, Cloud Optimized GeoTIFF).
 2. **Format Adaptation**: Modify CityJSON to incorporate efficient binary storage and indexing.
 3. **Benchmarking**: Compare performance with traditional CityJSON and assess scalability in cloud environments.
@@ -45,6 +51,7 @@ While optimized data formats such as PMTiles, FlatBuffers, Mapbox Vector Tiles,
 6. **Web-Based Query Optimization**: Enhance interactive applications through HTTP Range requests and on-the-fly decoding.
 
 ### Cloud-Native Processing Enhancements
+
 - Enable single-file containment of entire urban areas.
 - Reduce cloud storage and computation costs through efficient serialization.
 - Improve web-based access and real-time querying capabilities.
@@ -90,7 +97,6 @@ While optimized data formats such as PMTiles, FlatBuffers, Mapbox Vector Tiles,
    - Implement intelligent batching of nearby features based on spatial proximity.
    - Add client-side caching to avoid redundant requests for previously fetched data.
 
-
 3. **Performance Benchmarking for Large Datasets**
    - Evaluate large-scale data retrieval and identify performance bottlenecks.
    - Develop standardized benchmark suite for comparing with other formats.
@@ -174,37 +180,74 @@ While optimized data formats such as PMTiles, FlatBuffers, Mapbox Vector Tiles,
 ## Next Milestones
 
 ### Milestone 1: Core Optimization
+
 - Optimize Attribute Index for streaming with progressive loading.
 - Implement intelligent batching for HTTP Range Requests.
 - Complete comprehensive benchmarking suite for large datasets.
 - Address critical performance bottlenecks identified in profiling.
 - Enhance documentation with performance optimization guidelines.
 
 ### Milestone 2: Format Extensions
+
 - Evaluate and implement support for Arrow and Parquet encoding.
 - Develop compression strategies for geometry and attribute data.
 - Create adapters for seamless format conversion.
 - Implement advanced spatial indexing techniques.
 - Enhance CI/CD pipeline with automated performance testing.
 
 ### Milestone 3: Language Support
+
 - Release Python implementation.
 - Develop C++ implementation.
 - Create JavaScript/TypeScript SDK for browser environments.
 - Ensure cross-language test compatibility.
 - Publish packages to language-specific repositories.
 
 ### Milestone 4: Visualization & Integration
+
 - Implement Three.js-based Web Viewer with LOD support.
 - Develop browser-based conversion tools for common 3D formats.
 - Create plugins for QGIS, ArcGIS, and other GIS software.
 - Implement texture and material rendering in web environments.
 - Release comprehensive integration examples for third-party tools.
 
-
 ## Recent Updates
+
 - Integrated spatial indexing and binary search tree.
 - Added WebAssembly support for FlatCityBuf.
 - Improved texture handling in CityJSON encoding.
 - Completed initial benchmarking against CityJSON and CityJSONSeq.
-- Created preliminary documentation for the file format specification.
+- Created preliminary documentation for the file format specification.
+
+## progress status
+
+- [x] basic flatbuffers schema for cityjson - completed
+- [x] spatial indexing implementation (hilbert r-tree) - completed
+- [x] encoding of geoms with shared vertices - completed
+- [x] encoding of materials - completed
+- [x] encoding of textures - completed
+- [x] encoding of appearance - completed
+- [x] encoding of semantics - completed
+- [x] encoding of attributes - completed
+- [x] extension support - completed
+- [ ] js/wasm query engine - in progress
+- [ ] python wrapper - in progress
+- [ ] web-based query optimizer - in progress
+- [ ] partial geom retrieval - planned
+- [ ] versioning support - planned
+
+## what's next
+
+- **query engine refinement:** optimize the query engine for more complex spatial and attribute queries
+- **python wrapper:** complete the python interface for broader ecosystem integration
+- **web-based query optimizer:** finish the visualization tool for query plan optimization
+- **partial geometry retrieval:** implement efficient retrieval of partial geometries for large objects
+- **extension documentation:** create more comprehensive documentation and examples for utilizing extensions
+- **benchmarking extensions:** measure performance impact of different extension usage patterns
+
+## known issues
+
+- performance bottlenecks in attribute indexing with large datasets
+- memory usage spikes during encoding of complex geometries
+- limitations in the current implementation of lod switching
+- extension attributes may impact query performance for complex filter operations

.cursor/rules/memory/specification.md

@@ -510,3 +510,115 @@ graph TD
 ```
 
 this structure allows for efficient querying and retrieval of city objects based on both spatial and attribute criteria.
+
+## extension support
+
+flatcitybuf implements full support for the cityjson extension mechanism, allowing customization of the data model while maintaining compatibility with standard tools.
+
+### extension mechanism background
+
+cityjson extensions enable users to:
+
+1. **add new attributes** to existing cityobjects
+2. **create new cityobject types** beyond the standard types
+3. **add new properties** at the root level of a cityjson file
+4. **define new semantic surface types**
+
+extensions are identified using a "+" prefix (e.g., "+noise") and are defined in json schema files hosted at urls referenced in the cityjson file.
+
+### extension schema implementation
+
+flatcitybuf supports extensions through specialized schema components in three main areas:
+
+#### 1. extension definition in `extension.fbs`
+
+```flatbuffers
+table Extension {
+  name: string;                    // Extension name (e.g., "+Noise")
+  description: string;             // Description of the extension
+  url: string;                     // URL to the extension schema
+  version: string;                 // Extension version
+  version_cityjson: string;        // Compatible CityJSON version
+  extra_attributes: string;        // Stringified JSON schema for attributes
+  extra_city_objects: string;      // Stringified JSON schema for city objects
+  extra_root_properties: string;   // Stringified JSON schema for root properties
+  extra_semantic_surfaces: string; // Stringified JSON schema for semantic surfaces
+}
+```
+
+#### 2. extended cityobjects in `feature.fbs`
+
+```flatbuffers
+enum CityObjectType:ubyte {
+  // ... standard types ...
+  ExtensionObject
+}
+
+table CityObject {
+  type: CityObjectType;
+  extension_type: string; // e.g. "+NoiseCityFurnitureSegment"
+  // ... other fields ...
+}
+```
+
+#### 3. extended semantic surfaces in `geometry.fbs`
+
+```flatbuffers
+enum SemanticSurfaceType:ubyte {
+  // ... standard types ...
+  ExtraSemanticSurface
+}
+
+table SemanticObject {
+  type: SemanticSurfaceType;
+  extension_type: string; // e.g. "+ThermalSurface"
+  // ... other fields ...
+}
+```
+
+#### 4. extension references in header
+
+extensions are referenced in the header, allowing applications to understand which extensions are used in the file:
+
+```flatbuffers
+table Header {
+  // ... other fields ...
+  extensions: [Extension];  // List of extensions used
+  // ... other fields ...
+}
+```
+
+### encoding and decoding strategy
+
+the encoding and decoding of extensions follows these principles:
+
+1. **self-contained extensions**: extension schemas are embedded directly in the file as stringified json, making the file self-contained and usable without external references.
+
+2. **enum with extension marker**: special enum values (`extensionobject`, `extrasemanticssurface`) combined with a string field (`extension_type`) handle extended types. this approach maintains enum efficiency while supporting unlimited extension types.
+
+3. **unified attribute storage**: extension attributes are treated the same as core attributes, both encoded in the attributes byte array. this simplifies implementation and maintains query performance.
+
+4. **root properties**: extension properties at the root level are stored in the header's attributes field.
+
+when encoding:
+
+- if a cityobject type starts with "+", it's encoded as `extensionobject` with the full type name stored in the `extension_type` field
+- if a semantic surface type starts with "+", it's encoded as `extrasemanticssurface` with the full type name stored in the `extension_type` field
+- extension-specific attributes are encoded as regular attributes in the binary attribute array
+
+when decoding:
+
+- if a cityobject has type `extensionobject` and a non-null `extension_type`, the extension type name is used
+- if a semantic surface has type `extrasemanticssurface` and a non-null `extension_type`, the extension type name is used
+- all attributes are decoded, regardless of whether they belong to the core schema or extensions
+
+### benefits of this approach
+
+this implementation balances several key factors:
+
+- **performance**: maintains fast access to core data structures
+- **flexibility**: supports any cityjson extension
+- **self-containment**: makes files usable without external references
+- **simplicity**: uses consistent patterns for extension handling
+
+the schema is agnostic about the validity of extension data, focusing instead on accurately representing the structure of extended cityjson files in an efficient binary format.

.cursor/rules/rust.mdc

@@ -1,6 +1,7 @@
 ---
 description: Coding rules for Rust implementation in FlatCityBuf
 globs: src/rust/**
+alwaysApply: false
 ---
 # Rust Coding Guidelines for Library Development
 
@@ -73,7 +74,7 @@ flatcitybuf/
 ---
 
 ## Error Handling
-- Use `anyhow` for application code and `thiserror` for package-level errors.
+- Use `thiserror` for package-level errors.
 - Avoid panics in library code; return errors instead.
 - Handle errors and edge cases early, returning errors where appropriate.
 

.gitignore

@@ -59,8 +59,8 @@ __pycache__/
 temp/
 
 benchmark_data/
-src/rust/fcb_core/tests/data/
-!src/rust/fcb_core/tests/data/.gitkeep
+src/rust/fcb_core/tests/data/*.fcb
+src/rust/fcb_core/tests/data/*.json
 .cursorrules
 
 *.fcb

src/fbs/extension.fbs

@@ -0,0 +1,17 @@
+
+
+// Extension is a struct that contains schema of the extension.
+// To simplify FlatBuffers schema, we just store stringified JSON schema.
+// This Extension can be derived from ExtensionMeta's url.
+table Extension {
+  // "type": "CityJSONExtension" isn't written in the file as it's obvious
+  name: string; // name of the extension. It's the same as ExtensionMeta's name.
+  description: string; // description of the extension. It's the same as ExtensionMeta's description.
+  url: string; // url of the extension. It's the same as ExtensionMeta's url.
+  version: string; // version of the extension. It's the same as ExtensionMeta's version.
+  version_cityjson: string; // version of the extension in CityJSON format.
+  extra_attributes: string; // extra attributes of the extension. stringified JSON object.
+  extra_city_objects: string; // extra city objects of the extension. stringified JSON object.
+  extra_root_properties: string; // extra root properties of the extension. stringified JSON object.
+  extra_semantic_surfaces: string; // extra semantic surfaces of the extension. stringified JSON object.
+}

src/fbs/feature.fbs

@@ -46,7 +46,10 @@ enum CityObjectType:ubyte {
   TunnelHollowSpace,
   TunnelFurniture,
 
-  WaterBody
+  WaterBody,
+
+  // Extension objects. Since we can't expect the extended city object type, just mark it as "ExtensionObject".
+  ExtensionObject
 }
 
 struct Vertex {
@@ -64,6 +67,7 @@ table CityFeature {
 
 table CityObject {
   type:CityObjectType;
+  extension_type: string; // extension type of the city object. e.g. +NoiseCityFurnitureSegment
   id:string (key, required);
   geographical_extent:GeographicalExtent;
   geometry:[Geometry];

src/fbs/geometry.fbs

@@ -21,7 +21,10 @@ enum SemanticSurfaceType:ubyte {
   TrafficArea,
   AuxiliaryTrafficArea,
   TransportationMarking,
-  TransportationHole
+  TransportationHole,
+
+  // Extension objects. In the JSON data, it's written like "+ThermalSurface". However as we can't expect the extended semantic surface type, just mark it as "ExtraSemanticSurface".
+  ExtraSemanticSurface
 }
 
 enum GeometryType:ubyte {
@@ -85,6 +88,7 @@ table SemanticObject {
   attributes:[ubyte];
   children:[uint];
   parent:uint = null;       // default is null, important to be able to check if this field is set
+  extension_type: string; // extension type of the semantic object. e.g. "+ThermalSurface"
 }
 
 struct TransformationMatrix {

src/fbs/header.fbs

@@ -4,6 +4,7 @@
 // Reference: https://github.com/flatgeobuf/flatgeobuf/blob/master/src/fbs/header.fbs
 
 include "geometry.fbs";
+include "extension.fbs";
 
 enum ColumnType: ubyte {
   Byte,                         // Signed 8-bit integer
@@ -138,8 +139,11 @@ table Header {
   identifier: string;                       // Dataset identifier
   reference_date: string;                   // Reference date
   title: string;                            // Dataset title
+  // geometry templates
   templates: [Geometry];
   templates_vertices: [DoubleVertex];
+  // extensions
+  extensions: [Extension];
   // Point of contact
   poc_contact_name: string;                 // Point of contact name
   poc_contact_type: string;                 // Point of contact type

src/rust/fcb_core/Cargo.toml

@@ -15,12 +15,13 @@ wasm = [
   "js-sys",
   "getrandom",
 ]
+extension = ["cjseq/extension"]
 
 [dependencies]
 bytes = { workspace = true, optional = true }
 flatbuffers = { workspace = true }
 byteorder = { workspace = true }
-cjseq = { workspace = true }
+cjseq = { workspace = true, features = [] }
 tempfile = { workspace = true }
 serde_json = { workspace = true }
 anyhow = { workspace = true }

src/rust/fcb_core/src/error.rs

@@ -1,3 +1,4 @@
+use cjseq::error::CjseqError;
 use flatbuffers::InvalidFlatbuffer;
 use serde_json;
 use thiserror::Error;
@@ -70,6 +71,12 @@ pub enum Error {
         #[from]
         source: crate::cjerror::CjError,
     },
+
+    #[error("Cjseq error: {source}")]
+    CjseqError {
+        #[from]
+        source: CjseqError,
+    },
 }
 
 impl Error {
@@ -102,3 +109,5 @@ impl Error {
         )
     }
 }
+
+pub type Result<T> = std::result::Result<T, Error>;