GPM 1.2 support

[javagl]

Summary

The document "The Generic Point-cloud Model (GPM): Implementation and Exploitation, Version 1.2, 2024-02-29" from the National Geospatial-Intelligence Agency (NGA) is published at https://nsgreg.nga.mil/csmwg.jsp .

And I'll now try to summarize a 264 page document in one paragraph 😎 :

The "GPM" is the "Generic Point-cloud Model", and describes methods for modeling error propagation (or "uncertainty") within point clouds that have been acquired e.g. with LIDAR scanners, for the use in a geospatial context. In GPM Version 1.2, these concepts have been generalized to be applicable to meshes. The idea is to store error metadata inside a glTF, using a glTF extension. The main elements of the data can very roughly be summarized to be "anchor points", which are a sort of reference points with a known location and known error/uncertainty, and "per-point errors" (PPE), which, in the case of mesh data, are stored in a texture. The anchor points are stored at the top-level of the glTF. The per-point error textures are associated with mesh primitives, similar to Property Textures in EXT_structural_metadata.

Description

The current (DRAFT) state of this PR:

• There are classes that reflect the structure of the GPM data more or less direcly.
  • These are currently located in a Source/Scene/Model/Extensions/Gpm subfolder.
  • They mimic the structures of the JSON schema that defines the extension, with minor adjustments for the CesiumJS API (e.g. using a Cartesian3 instead of a number[3] array for some position and such). We can argue about the 1:1 mapping of the JSON schema structures. The result may be "inconvenient" in some way. But trying to find a good "convenience layer" requires a deep understanding of the goals and usage patterns.
  • Related: We can talk about the naming. There's a class like Spdcf. It could be called StrictlyPositiveDefiniteCorrelationFunction. If someone thinks that it should be renamed: Please suggest sensible names for its properties A and T here as well...
• These classes are filled with life during loading, starting from the GltfLoader
  • There are two new loaders, GltfGpmLoader and GltfMeshPrimitiveGpmLoader, that are hooked into the GltfLoader
  • The GltfGpmLoader loads the top-level GPM information, and offers it as the classes described above
  • The GltfMeshPrimitiveGpmLoader loads the GPM information for each mesh primitive. This involves loading the PPE (per-point error) textures. Right now, this data is translated into instances for "structural metadata", like EXT_structural_metdata, but there are many details to be sorted out here...

Some high-level considerations:

The extension is probably not something that could be considered as "the most widely used core functionality of CesiumJS". And I think that it could make sense to have an infrastructure (or at least some ideas) about how to handle ~"highly use-case specific (vendor) glTF extensions" in general. This could go as far as establishing some "plugin-concept" that allows plugging in loaders for specific extensions into the GltfLoader, and transporting the parsed and loaded data back to the client.

Right now, for the GPM data, this is done ... very pragmatically. The Model/Extensions/Gpm subdirectory already suggests that there might be other directories in Model/Extensions/... that contain the respective extension classes. The loaders are currently hard-wired into the GltfLoader, but it might be relatively easy to find some sort of abstraction there. The question about how to transport the extension information to the client is still open.
The apprach here right now is:

• There is a new ModelComponents.extensions dictionary that can store "anything"
• The GltfGpmLoader loads the GPM JSON, translates it into an object, and this is eventually just stored as
  loader._components.extensions["NGA_gpm_local"] = gpmLoader._gltfGpmLocal;
• There is a function Model3DTileContent.getExtension that just forwards to Model.getExtension, and allows clients to obtain that parsed data like
  const extensionObject = modelContent.getExtension("NGA_gpm_local")
  (the point is: There should probably not be some Model.getNgaGpmLocal function in the Model class...)

Details about the point that the 'mesh primitive GPM data' is currently translated into something that resembles EXT_structural_metadata will be added here soon. But there are too many details to be sorted out (and that are likely to change) to explain that right now.

Testing plan

TBD

Author checklist

• I have submitted a Contributor License Agreement
• I have added my name to CONTRIBUTORS.md
• I have updated CHANGES.md with a short summary of my change
• I have added or updated unit tests to ensure consistent code coverage
• I have updated the inline documentation, and included code examples where relevant
• I have performed a self-review of my code

[github-actions]

Thank you for the pull request, @javagl!

✅ We can confirm we have a CLA on file for you.