Cesium Metadata: Unity vs Godot

#5 · open · 4 comments

GeorgeS2019

| **Godot Feature** | **Description** | |------------------|-----------------| | **TileMetadata** (`.cpp/.h`) | Godot’s approach to tile metadata—Unity uses more granular feature ID/property classes. |

Comments

GeorgeS2019

### 🧩 Unity’s Granular Feature Metadata System Unity breaks down metadata into **specialized, reusable components**, each handling a specific aspect of feature metadata: | Unity Class/File | Purpose | |------------------|---------| | `CesiumFeatureIdAttributeImpl.*` | Handles feature ID attributes embedded in vertex data. | | `CesiumFeatureIdTextureImpl.*` | Manages feature IDs stored in textures. | | `CesiumPropertyTablePropertyImpl.*` | Represents individual properties in a property table. | | `CesiumMetadataImpl.*` | Coordinates access to metadata across tiles. | | `CesiumMetadataValueImpl.*` | Optimizes value access and type conversion. | | `CesiumFeaturesMetadataUtility.*` | Provides utility functions for metadata parsing and conversion. | This modularity allows Unity to: - Support multiple feature ID sources (attributes, textures, implicit IDs). - Handle per-feature properties with type safety and performance optimizations. - Extend or override behavior for specific metadata types. --- ### 🧱 Godot’s TileMetadata: Simpler, Unified Godot’s `TileMetadata.cpp/h` acts as a **single container** for all metadata associated with a tile. It’s simpler and easier to manage but lacks the fine-grained separation seen in Unity. - Likely stores all feature IDs and properties in one structure. - Easier to integrate into Godot’s node system. - Less flexible for advanced metadata workflows (e.g., styling by feature ID, dynamic property access). --- ### 🧠 Summary Unity’s system is **more granular and extensible**, ideal for complex metadata-driven rendering or interaction. Godot’s approach is **simpler and more monolithic**, which works well for basic use cases but may require refactoring for advanced features.

GeorgeS2019

![Image](https://github.com/user-attachments/assets/214dc520-eea1-41b2-a422-b272e50f01e0)

GeorgeS2019

<html> <body> <html><head></head><body>To bring Godot’s Cesium TileMetadata.h closer to the granular, modular system Unity uses, you’d want to break out responsibilities into specialized classes rather than funneling everything through <code>TileMetadata</code> + <code>CesiumPropertyInfo</code>. Here’s a structured list of changes and additions: <hr> <h2>🔑 Proposed Class Additions for Granularity</h2> <h3>1. Feature ID Sources</h3> <ul> <li><code>FeatureIdAttributeSource</code> <ul> <li>Handles feature IDs embedded in vertex attributes.</li> <li>Provides GPU‑friendly pathways for instancing/selection.</li> </ul></li> <li><code>FeatureIdTextureSource</code> <ul> <li>Manages feature IDs stored in textures.</li> <li>Supports caching and late binding for texture‑based IDs.</li> </ul></li> <li><code>FeatureIdImplicitSource</code> <ul> <li>Provides implicit ID generation when no explicit source exists.</li> <li>Useful for fallback or procedural tiles.</li> </ul></li> </ul> <hr> <h3>2. Property Wrappers</h3> <ul> <li><code>PropertyTableProperty</code> <ul> <li>Represents a single property with type‑safe getters.</li> <li>Lazy conversion (only convert when accessed).</li> <li>Mirrors Unity’s <code>CesiumPropertyTablePropertyImpl</code>.</li> </ul></li> </ul> <hr> <h3>3. Value Layer</h3> <ul> <li><code>MetadataValue</code> <ul> <li>Encapsulates typed accessors (<code>as_float64()</code>, <code>as_vec3f()</code>, <code>try_get_enum()</code>).</li> <li>Small‑object optimization to reduce Variant churn.</li> <li>Dedicated conversion layer separate from template helpers.</li> </ul></li> </ul> <hr> <h3>4. Metadata Coordination</h3> <ul> <li><code>MetadataCoordinator</code> <ul> <li>Centralized manager for multiple property tables.</li> <li>Provides unified API for querying properties across tables.</li> <li>Similar to Unity’s <code>CesiumMetadataImpl</code>.</li> </ul></li> </ul> <hr> <h3>5. Utility Functions</h3> <ul> <li><code>MetadataUtility</code> <ul> <li>Static helpers for parsing, validation, and conversion.</li> <li>Enum range validation, matrix mapping, color type handling.</li> <li>Equivalent to Unity’s <code>CesiumFeaturesMetadataUtility</code>.</li> </ul></li> </ul> <hr> <h3>6. Matrix & Enum Support</h3> <ul> <li><code>MatrixPropertyHandler</code> <ul> <li>Implements conversion paths for Mat2/Mat3/Mat4.</li> <li>Maps glm matrices to Godot Matrix types.</li> </ul></li> <li><code>EnumPropertyHandler</code> <ul> <li>Stores enum tables and validates ranges.</li> <li>Prevents silent coercion into scalars/booleans.</li> </ul></li> </ul> <hr> <h2>🛠 Structural Changes to TileMetadata.h</h2> <ul> <li>Refactor <code>TileMetadata</code> into a facade: <ul> <li>Delegates to specialized classes (<code>FeatureIdSource</code>, <code>PropertyTableProperty</code>, <code>MetadataValue</code>).</li> <li>Keeps <code>Dictionary/Variant</code> outputs for GDScript ergonomics.</li> </ul></li> <li>Introduce caching layer: <ul> <li>Preconvert common types (e.g., Float64→Float32 vec arrays).</li> <li>Avoid repeated coercions in hot loops.</li> </ul></li> <li>Add accessor API: <ul> <li><code>get_property(name)</code> → returns <code>PropertyTableProperty</code>.</li> <li><code>get_feature_id(source, index)</code> → dispatches to correct <code>FeatureIdSource</code>.</li> </ul></li> </ul> <hr> <h2>📊 Comparison Snapshot</h2> Unity Granular System | Godot Current | Proposed Godot Additions -- | -- | -- CesiumFeatureIdAttributeImpl | None | FeatureIdAttributeSource CesiumFeatureIdTextureImpl | None | FeatureIdTextureSource CesiumPropertyTablePropertyImpl | CesiumPropertyInfo | PropertyTableProperty CesiumMetadataImpl | TileMetadata | MetadataCoordinator CesiumMetadataValueImpl | Template helpers | MetadataValue CesiumFeaturesMetadataUtility | Inline templates | MetadataUtility <hr> <h2>🎯 Outcome</h2> By modularizing into these classes: <ul> <li>Granularity: Each metadata source/type is handled independently.</li> <li>Performance: Typed accessors and caching reduce Variant overhead.</li> <li>Extensibility: New metadata forms (colors, packed bitfields, GPU pathways) can be added without touching core.</li> <li>Developer ergonomics: Typed wrappers for C++ performance, Dictionary/Variant for GDScript prototyping.</li> </ul> <hr> </body></html> </body> </html>

GeorgeS2019

<html> <body> <html><head></head><body><h1>Comparison of Unity granular feature metadata system and Godot Cesium metadata API</h1> <hr> <h2>High-level differences</h2> Aspect | Unity granular system (Cesium for Unity) | Godot Cesium API (code provided) -- | -- | -- Feature ID sources | Separate implementations for vertex attributes, textures, and implicit IDs via CesiumFeatureIdAttributeImpl, CesiumFeatureIdTextureImpl | No explicit feature ID source abstraction; focuses on property table parsing via CesiumGltf::PropertyTableView Property access model | Strongly typed property wrappers (CesiumPropertyTablePropertyImpl) with centralized coordination (CesiumMetadataImpl) | Properties normalized into Godot Dictionary and Variant via CesiumPropertyInfo and EPropertyType/EComponentType Value typing and conversion | Dedicated value layer (CesiumMetadataValueImpl) optimizing type coercion and performance | Template-based mapping to Variant, with enums for type/component and warnings for narrowing conversions Extensibility | Modular implementations per metadata source; behavior can be extended or overridden per type/source | Centralized conversion path; extensibility requires altering template helpers or adding new EPropertyType/EComponentType cases Performance strategy | Source-specific optimizations; avoids unnecessary allocations; type-safe access paths | Conversion to Variant and Dictionary for engine interoperability; potential overhead and narrowing during float64→float32 Developer ergonomics | Strong separation of concerns, clear source-specific APIs, C#-friendly | Single entry point (TileMetadata) yielding engine-native structures (Dictionary/Variant), GDScript-friendly <blockquote> Summary: Unity emphasizes modular, source-specific metadata handling with strong typing and performance specialization, while the Godot code prioritizes a unified, engine-native representation via Dictionary/Variant for broad usability. </blockquote> <hr> <h2>What the Godot Cesium API exposes</h2> <ul> <li>Entry point: <ul> <li>TileMetadata aggregates property tables with <code>init</code>, <code>add_table(const CesiumGltf::PropertyTableView&)</code>, and exposes them via <code>get_table(index)</code> returning a Godot <code>Dictionary</code>.</li> </ul></li> <li>Type system: <ul> <li>EPropertyType covers scalar, vectors, matrices, string, boolean, enum.</li> <li>EComponentType describes underlying numeric types (Int/Uint 8–64, Float32/64).</li> </ul></li> <li>Value container: <ul> <li>CesiumPropertyInfo holds propertyType, componentType, isArray, and a Variant <code>data</code>.</li> </ul></li> <li>Conversion helpers: <ul> <li>get_component_type<T> infers numeric component types using CesiumGltf traits and C++ type traits.</li> <li>make_vector_type<T> maps glm vectors to Godot Vector2/Vector3/Vector4 or integer vector variants, with error/warning handling for invalid types and narrowing.</li> <li>make_array_type<T> converts metadata arrays to Godot Array of Variants, preserving element type info in the parent.</li> <li>make_metadata_value<T> is the central dispatcher, distinguishing arrays, VecN, strings, booleans/scalars via CesiumGltf trait checks, then returning a Ref to CesiumPropertyInfo.</li> </ul></li> <li>Runtime representation: <ul> <li>Property tables are stored in <code>std::vector<Dictionary></code> (<code>m_tables</code>) and an overall <code>Dictionary</code> cache (<code>m_accesibleRepresentation</code>), aligning with Godot’s scripting ergonomics.</li> </ul></li> </ul> <hr> <h2>Where Unity provides more granularity</h2> <ul> <li>Feature ID sources: <ul> <li>Unity: Different classes for attributes vs textures vs implicit IDs allow tailored parsing, caching, and late binding per source.</li> <li>Godot (code shown): No separate abstraction for feature ID sources; all metadata arrives via PropertyTableView and is normalized into Variants.</li> </ul></li> <li>Property table access and typing: <ul> <li>Unity: Per-property wrappers with type safety and fast paths, avoiding per-access boxing/unboxing.</li> <li>Godot: Unified Variant-based container simplifies usage, but introduces runtime type checks and potential conversions.</li> </ul></li> <li>Value conversion layer: <ul> <li>Unity: A dedicated value layer abstracts type coercion, minimizing allocations and branch cost across hot paths.</li> <li>Godot: Conversion is embedded in templates; warnings are emitted on narrowing (e.g., Float64→Float32), but there’s no separate optimization layer.</li> </ul></li> <li>Extensibility surface: <ul> <li>Unity: Drop-in extensions for new metadata forms (e.g., new texture encodings) without touching core property accessors.</li> <li>Godot: To introduce new types (e.g., color types, packed bitfields), you extend EPropertyType/EComponentType and the conversion helpers.</li> </ul></li> </ul> <hr> <h2>Strengths of the Godot approach</h2> <ul> <li>Engine-native ergonomics: <ul> <li>Dictionary/Variant outputs integrate seamlessly with GDScript and Godot’s editor tooling, speeding prototyping and scripting.</li> </ul></li> <li>Clear vector and array handling: <ul> <li>Explicit mapping to Vector2/Vector3/Vector4 and Array makes common GIS/3D use cases straightforward.</li> </ul></li> <li>Safety cues during conversion: <ul> <li>ERR_PRINT/WARN_PRINT provide immediate feedback on invalid component mixes and narrowing conversions, aiding debugging.</li> </ul></li> </ul> <hr> <h2>Gaps relative to Unity and practical enhancements</h2> <ul> <li>Missing feature ID source abstraction: <ul> <li>Add interfaces like IFeatureIdSource with concrete implementations for vertex attributes, textures, and implicit IDs.</li> <li>Benefit: Enables targeted caching, GPU-friendly pathways, and selective refresh.</li> </ul></li> <li>Dedicated value layer for performance: <ul> <li>Introduce a MetadataValue class encapsulating typed accessors (e.g., as_float64(), as_vec3f(), try_get_enum()) with small-object optimization.</li> <li>Benefit: Reduces Variant churn and branchy template paths in hot loops.</li> </ul></li> <li>Per-property wrappers: <ul> <li>Create PropertyTableProperty objects exposing type-safe getters and lazy conversion, keyed by property name.</li> <li>Benefit: Mirrors Unity’s property-centric ergonomics and aids static analysis.</li> </ul></li> <li>Matrix support parity: <ul> <li>The enum lists Mat2/Mat3/Mat4, but conversion paths for matrices are not implemented.</li> <li>Implement glm→Godot matrix mapping or a custom Matrix type for consistent handling.</li> </ul></li> <li>Enum typing and validation: <ul> <li>Add enum value tables and range validation to avoid silently treating enums as booleans/scalars in mixed cases.</li> </ul></li> <li>Batch access and caching: <ul> <li>Cache common conversions (e.g., Float64→Float32 vec arrays) per table to avoid repeated per-feature coercions.</li> </ul></li> </ul> <hr> <h2>Example usage patterns and recommended wrappers</h2> <ul> <li>Godot scripting-friendly accessor layer: <ul> <li>Goal: Keep Dictionary/Variant for GDScript while offering typed C++ access for performance-critical paths.</li> <li>Design: <ul> <li>TileMetadataView: exposes <code>get_table_names()</code>, <code>get_property(name)</code>, <code>get_feature_id(source, index)</code> with typed returns.</li> <li>MetadataCache: memoizes conversions and provides bulk readers (e.g., <code>read_vec3_array(property)</code>).</li> </ul></li> </ul></li> <li>Feature ID integration path: <ul> <li>Add: <code>FeatureIdAttributeSource</code>, <code>FeatureIdTextureSource</code>, <code>FeatureIdImplicitSource</code> classes.</li> <li>Expose: Unified API <code>get_feature_id(Index3D position)</code> that dispatches to the configured source.</li> </ul></li> <li>Type-safe property API: <ul> <li>Add: <code>Property<T></code> wrapper with explicit specializations for scalar, vector, matrix, boolean, string, enum.</li> <li>Provide: <code>try_get<T>(name)</code> returning std::optional<T> to avoid Variant ambiguity.</li> </ul></li> </ul> <hr> <h2>Personalized guidance for your workflow</h2> <ul> <li>For visualization pipelines and large tilesets: <ul> <li>Use typed caches for vec arrays and avoid per-frame Variant parsing; preconvert Float64 data to Float32 if your renderer is single precision.</li> </ul></li> <li>For GPU interop experiments: <ul> <li>Feature IDs via attributes are the most direct path to GPU instancing or selection buffers; add an attribute-source class before texture-based IDs.</li> </ul></li> <li>For editor tooling: <ul> <li>Keep the Dictionary/Variant output for GDScript tools, but back it with typed C++ views to preserve both agility and performance.</li> </ul></li> </ul> </body></html> </body> </html>