Update changelog and upgrade guide

CHANGES.md

@@ -1,11 +1,36 @@
 # Change Log
 
+### v2.0.0 - ?
+
+##### Breaking Changes :mega:
+
+- Removed `FCesiumIntegerColor`, `FCesiumFloatColor`, `UCesiumFeatureTexturePropertyBlueprintLibrary::GetIntegerColorFromTextureCoordinates` and `UCesiumFeatureTexturePropertyBlueprintLibrary::GetFloatColorFromTextureCoordinates`. Check out the [upgrade guide](Documentation/upgrade-to-2.0-guide.md) for how retrieve metadata from property textures with the new API.
+- Renamed `GetTextureCoordinateIndex` to `GetUnrealUVChannel` in both `UCesiumFeatureIdTextureBlueprintLibrary` and `UCesiumPropertyTexturePropertyBlueprintLibrary`. Contrary to what the documentation claimed, this function retrieved the index of the texture coordinate set in the *Unreal static mesh*, which is not necessarily equal to the texture coordinate set index in the *glTF primitive*. For the latter value, use `GetGltfTextureCoordinateSetIndex` instead.
+
+##### Additions :tada:
+
+- Added new functions to `UCesiumPropertyTexturePropertyBlueprintLibrary` to retrieve detailed property information and get the values of the property as a certain type. Check out the [upgrade guide](Documentation/upgrade-to-2.0-guide.md) for how retrieve metadata from property textures with the new API.
+- Added `UCesiumMetadataPickingBlueprintLibrary::FindUVFromHit`, which computes the UV coordinates from a line trace hit without requiring "Support UV Hit Info" to be enabled. This can used to retrieve more accurate feature IDs or metadata values by sampling more accurately from a point on the face.
+- Added `GetPropertyTableValuesFromHit` and `GetPropertyTextureValuesFromHit` to `UCesiumMetadataPickingBlueprintLibrary` to retrieve the respective metadata from a line trace hit. For both functions, the target to sample is specified by index.
+- Added `UCesiumFeatureIdSetBlueprintLibrary::GetFeatureIDFromHit` to retrieve the feature ID from a line trace hit on a primitive containing the feature ID set. This returns more accurate values for feature ID textures than `GetFeatureIDForVertex`.
+- Added `UCesiumPrimitiveFeaturesBlueprintLibrary::GetFeatureIDFromHit` to retrieve the feature ID from a line trace hit on a primitive, where the desired feature ID set is specified by index. For feature ID textures, this returns more accurate values than `GetFeatureIDFromFace`. 
+- Added `UCesiumFeatureIdTextureBlueprintLibrary::GetFeatureIDForUV`, which samples a feature ID texture with `FVector2D` UV coordinates.
+- Added `GetGltfTextureCoordinateSetIndex` to `UCesiumFeatureIdTextureBlueprintLibrary` and `UCesiumPropertyTexturePropertyBlueprintLibrary` to avoid ambiguity with `GetUnrealUVChannel`.
+- Added `UCesiumMetadataValueBlueprintLibrary::GetValuesAsStrings` to convert a map of `FCesiumMetadataValues` to their string representations.
+
+##### Deprecated :hourglass:
+
+- `UCesiumFeatureIdTextureBlueprintLibrary::GetFeatureIDForTextureCoordinates` has been deprecated. Use `UCesiumFeatureIdTextureBlueprintLibrary::GetFeatureIDForUV` instead.
+- `UCesiumPropertyTexturePropertyBlueprintLibrary::GetSwizzle` and `UCesiumPropertyTexturePropertyBlueprintLibrary::GetComponentCount` have been deprecated, since they are no longer necessary to handle property texture property values in the plugin. Use `UCesiumPropertyTexturePropertyBlueprintLibrary::GetChannels` instead.
+- `UCesiumMetadataPickingBlueprintLibrary::GetMetadataValuesForFace` has been deprecated. Use `UCesiumMetadataPickingBlueprintLibrary::GetPropertyTableValuesForHit` instead.
+- `UCesiumMetadataPickingBlueprintLibrary::GetMetadataValuesForFaceAsStrings` has been deprecated. Use `UCesiumMetadataValueBlueprintLibrary::GetValuesAsStrings` to convert the output of `UCesiumMetadataPickingBlueprintLibrary::GetPropertyTableValuesForHit` instead.
+- `UCesiumPropertyTableBlueprintLibrary::GetMetadataValuesForFeatureAsStrings` has been deprecated. Use `UCesiumMetadataValueBlueprintLibrary::GetValuesAsStrings` to convert the output of `UCesiumPropertyTableBlueprintLibrary::GetMetadataValuesForFeature` instead.
+
 ### v2.0.0 Preview 1 - 2023-10-02
 
 ##### Breaking Changes :mega:
 
 - Feature IDs and metadata are now parsed through the `EXT_mesh_features` and `EXT_structural_metadata` extensions respectively. Models with `EXT_feature_metadata` will still be parsed, but their metadata will no longer be accessible. See the [upgrade guide](Documentation/upgrade-to-2.0-guide.md) for the full changelog and for tips on upgrading to the new API.
-- Removed `FCesiumIntegerColor`, `FCesiumFloatColor`, `UCesiumPropertyTextureProperty::GetIntegerColorFromTextureCoordinates` and `UCesiumPropertyTextureProperty::GetFloatColorFromTextureCoordinates`. Check out the [upgrade guide](Documentation/upgrade-to-2.0-guide.md) for how retrieve metadata from property textures with the new API.
 - Removed `CesiumMetadataFeatureTable`, `UCesiumMetadataFeatureTableBlueprintLibrary`, `UCesiumMetadataPrimitiveBlueprintLibrary::GetFeatureTables`, and `UCesiumMetadataUtilityBlueprintLibrary::GetFeatureIDForFace`. These have been deprecated since Unreal Engine 4.26.
 - The old sub-level system, based on Unreal's old (and now deprecated) World Composition system, has been removed. Instead, create Level Instance Actors and attach the "Cesium Sub Level Component" to them to achieve similar functionality. Old levels will automatically be converted to the new system when they are loaded in the Editor.
 - `CesiumSunSky` now uses a default `TransmittanceMinLightElevationAngle` value on its `SkyAtmosphere` component of 90.0 degrees instead of -90.0 degrees. This will generally improve lighting when far from the CesiumGeoreference origin, but it is a breaking change because it may change the lighting conditions in existing levels, particularly at sunrise and sunset.

Documentation/upgrade-to-2.0-guide.md

@@ -190,10 +190,11 @@ Additionally, `UCesiumFeatureTableBlueprintLibrary` has been renamed to `UCesium
 
 - Renamed `GetNumberOfFeatures` to `GetPropertyTableSize`.
 - Renamed `GetMetadataValuesForFeatureID` to `GetMetadataValuesForFeature`. Only values from valid properties are retrieved.
-- Renamed `GetMetadataValuesAsStringForFeatureID` to `GetMetadataValuesForFeatureAsStrings`. Only strings from valid properties are retrieved.
 - Added the `GetPropertyNames` function to retrieve the names of all properties, including invalid ones.
 - Added the `FindProperty` function to retrieve a property of a specific name from the property table. Returns an invalid instance if no property in the property table has that name.
 
+Note that `GetMetadataValuesForFeatureAsStrings`, which was previously renamed from `GetMetadataValuesAsStringForFeatureID` in the v2.0 preview release, has been deprecated. Instead, use `UCesiumMetadataValueBlueprintLibrary::GetValuesAsStrings` to convert the output of `GetMetadataValuesForFeature`.
+
 Finally, `UCesiumMetadataPropertyBlueprintLibrary` has been renamed to `UCesiumPropertyTablePropertyBlueprintLibrary` with the following changes:
 
 - Deprecated `GetTrueType` and `GetTrueComponentType`. Use `GetValueType` to get the type information as a `FCesiumMetadataValueType` instead.
@@ -209,7 +210,46 @@ Finally, `UCesiumMetadataPropertyBlueprintLibrary` has been renamed to `UCesiumP
   - `GetVector4`
   - `GetMatrix`
 
-### Metadata Picking
+In the `EXT_structural_metadata` specification, properties may contain *transformations* that affect the interpretation of their values in some way. These include `offset`, `scale`, `noData`, and `defaultValue`. A `min` and `max` value may also be specified if the property is a numeric type. To retrieve these values in Unreal Engine, use the `GetOffset`, `GetScale`, `GetNoDataValue`, `GetDefaultValue`,  `GetMinimumValue`, and `GetMaximumValue` functions respectively. These return the value as a `FCesiumMetadataValue`, which can later be converted to the appropriate type. 
+
+### Property Textures
+
+Property textures in `EXT_structural_metadata` are derived from the feature textures in `EXT_feature_metadata`. As such, `FCesiumFeatureTexture` has been renamed to `FCesiumPropertyTexture`, and `UCesiumFeatureTextureBlueprintLibrary` to `UCesiumPropertyTextureBlueprintLibrary`. Additionally, `UCesiumFeatureTextureBlueprintLibrary::GetPropertyKeys` is now `UCesiumPropertyTextureBlueprintLibrary::GetPropertyNames`.
+
+In previous versions of Cesium for Unreal, `FCesiumFeatureTextureProperty` did not preserve the type information of the properties. Instead, it used specialized structs – `FCesiumIntegerColor` and `FCesiumFloatColor` – to hold the channel values of a pixel in the texture. These structs required the user to determine the property's type and manually construct the correct metadata value from the pixel. To remove this extra work on the user, the newly-renamed `FCesiumPropertyTextureProperty` now interprets the texture channels on the user's behalf and returns the values as the property's specified type.
+
+The `ECesiumPropertyTextureStatus` has been added to indicate whether a property texture is valid. Invalid property textures will not have any metadata properties. Additionally, a `FCesiumPropertyTextureProperty` can now report its `ECesiumPropertyTexturePropertyStatus`, indicating when it has experienced an error. 
+
+Finally, `UCesiumFeatureTexturePropertyBlueprintLibrary` has been renamed to `UCesiumPropertyTexturePropertyBlueprintLibrary`, and its functionality now mirrors that of `UCesiumPropertyTablePropertyBlueprintLibrary` with the following changes:
+
+- Added `GetValueType`, `GetBlueprintType`, `GetArrayElementBlueprintType`, and `GetArraySize` to retrieve accurate type information from a property texture property.
+- Added `GetOffset`, `GetScale`, `GetMinimumValue`, `GetMaximumValue`, `GetNoDataValue`, and `GetDefaultValue` to retrieve the property's more granular details.
+- Added `GetChannels` to retrieve the texture channel information of a property texture property. This contains the indices of the channels that are used to construct the property's value from the texture.
+- Added `Get` functions to `UCesiumPropertyTexturePropertyBlueprintLibrary` to retrieve values of the property as a certain type from the given UV coordinates. This is a subset of the functions available on `UCesiumPropertyTablePropertyBlueprintLibrary`, since property texture properties are more limited in type. This includes:
+  - `GetByte`
+  - `GetInteger`
+  - `GetFloat`
+  - `GetFloat64`
+  - `GetIntPoint`
+  - `GetVector2D`
+  - `GetIntVector`
+  - `GetVector`
+  - `GetVector4`
+  - `GetArray`
+  - `GetValue`
+  - `GetRawValue`
+
+Unfortunately, there is no easy way to implement backwards compatibility for the older API, so `FCesiumIntegerColor` and `FCesiumFloatColor` have been **removed** without replacement. Consequently, the `GetIntegerColorFromTextureCoordinates` and `GetFloatColorFromTextureCoordinates` that were previously in `UCesiumFeatureTexturePropertyBlueprintLibrary` are also removed.
+
+TODO picking functions here
+
+### Metadata Access
+
+For both `EXT_feature_metadata` and `EXT_structural_metadata`, the extensions use different specifications based on which glTF component it is extending. They could extend the individual glTF primitives as well the glTF model itself. Previously, the `FCesiumMetadataModel` and `FCesiumMetadataPrimitive` structs were used to differentiate between the placements of the `EXT_feature_metadata` extension. In Cesium for Unreal v2.0, the `FCesiumModelMetadata` and `FCesiumPrimitiveMetadata` struts are used for `EXT_structural_metadata`.
+
+`FCesiumMetadataModel` has simply been renamed to `FCesiumModelMetadata`, representing the metadata specified by the `EXT_structural_metadata` extension on the root glTF model. However, `FCesiumMetadataPrimitive` was not so simple to rename. In `EXT_feature_metadata`, the primitive extension stored both metadata *and* feature IDs, whereas the `EXT_structural_metadata` primitive extension only indicated metadata. To handle this distinction, the `FCesiumMetadataPrimitive` is treated as separate from the newer `FCesiumPrimitiveMetadata` struct. `FCesiumMetadataPrimitive` is still deprecated, so instead use `FCesiumPrimitiveFeatures` to access the feature IDs of a primitive and `FCesiumPrimitiveMetadata` to access its metadata.
+
+### TODO: Metadata Picking
 
 *Picking* refers to the act of selecting a feature (e.g., selecting by mouse click) and querying it for information. Typically, picking is used to access the metadata of a particular feature.
 
@@ -225,16 +265,6 @@ To retrieve the values as strings, use **"Get Metadata Values For Face As String
 
 ![Get Metadata Values For Face](Images/getMetadataValuesForFaceAsStrings.jpeg)
 
-### TODO: Feature Textures -> Property Textures
-
-- Renamed `FCesiumFeatureTexture` to `FCesiumPropertyTexture`.
-- Renamed `FCesiumFeatureTextureProperty` to `FCesiumPropertyTextureProperty`.
-- Renamed `UCesiumFeatureTexturePropertyBlueprintLibrary` to `UCesiumPropertyTexturePropertyBlueprintLibrary`. `GetPropertyKeys` is now `GetPropertyNames`.
-- Added `FCesiumPropertyArray`, which represents an array retrieved from the `EXT_structural_metadata` extension.
-- Renamed `FCesiumMetadataModel` to `FCesiumModelMetadata`, which represents the metadata specified by the `EXT_structural_metadata` extension on the root glTF model.
-- Added `FCesiumPrimitiveMetadata`, which represents the metadata specified by the `EXT_structural_metadata` extension on a glTF mesh primitive.
-- `FCesiumMetadataPrimitive` has been deprecated. Instead, use `FCesiumPrimitiveFeatures` to access the feature IDs of a primitive and `FCesiumPrimitiveMetadata` to access its metadata.
-
 <h2 id="styling">Styling with EXT_mesh_features and EXT_structural_metadata</h2>
 
 *Styling* refers to the visual modification of data based on some information – usually metadata – and rules built around it by the developer. Previous versions of Cesium for Unreal allowed styling with the `UCesiumEncodedMetadataComponent`, which made `EXT_feature_metadata` accessible in Unreal materials. In this way, Unreal's material editor and rendering systems could be leveraged to visually alter tilesets based on their metadata.
@@ -243,6 +273,9 @@ In Cesium for Unreal v2.0, `UCesiumEncodedMetadataComponent` has been deprecated
 
 ![CesiumFeaturesMetadataComponent](Images/cesiumFeaturesMetadataComponent.jpeg)
 
+- Added `UCesiumPrimitiveFeaturesBlueprintLibrary::GetFeatureIDFromHit` to retrieve the feature ID from a line trace hit on a primitive, where the desired feature ID set is specified by index. For feature ID textures, this returns more accurate values than `GetFeatureIDFromFace`.
+- Added `UCesiumPropertyTextureBlueprintLibrary::GetMetadataValuesFromHit` to retrieve the property texture property values from a line trace hit on the primitive. Each property may specify a different texture coordinate set, so this function accounts for each property's specified set.
+
 ### Auto Fill 
 
 Like its predecessor, the `UCesiumFeaturesMetadataComponent` contains descriptions of the feature ID sets and metadata properties in the tileset. These descriptions indicate which feature ID sets or metadata should be made available for styling in Unreal materials. The contents can be manually specified by a developer or automatically generated using the **Auto Fill** button. 

Source/CesiumRuntime/Private/CesiumFeatureIdSet.cpp

@@ -155,19 +155,10 @@ int64 UCesiumFeatureIdSetBlueprintLibrary::GetFeatureIDFromHit(
     return false;
   }
 
-  if (!pGltfComponent->GetStaticMesh() ||
-      !pGltfComponent->GetStaticMesh()->GetRenderData()) {
-    return false;
-  }
-
-  auto& LODResources =
-      pGltfComponent->GetStaticMesh()->GetRenderData()->LODResources[0];
-  auto PositionBuffer = LODResources.VertexBuffers.PositionVertexBuffer;
-
   auto faceIndices = std::visit(
       CesiumFaceVertexIndicesFromAccessor{
           Hit.FaceIndex,
-          static_cast<int64_t>(PositionBuffer.GetNumVertices())},
+          pGltfComponent->PositionAccessor.size()},
       pGltfComponent->IndexAccessor);
 
   int64 VertexIndex = faceIndices[0];

Source/CesiumRuntime/Private/CesiumGltfComponent.cpp

@@ -546,7 +546,7 @@ static void createTexCoordAccessorsForFeaturesMetadata(
   for (const FCesiumPropertyTexture& propertyTexture : propertyTextures) {
     auto properties =
         UCesiumPropertyTextureBlueprintLibrary::GetProperties(propertyTexture);
-    for (const auto propertyIt : properties) {
+    for (const auto& propertyIt : properties) {
       int64 gltfTexCoordSetIndex =
           UCesiumPropertyTexturePropertyBlueprintLibrary::
               GetGltfTextureCoordinateSetIndex(propertyIt.Value);

Source/CesiumRuntime/Private/CesiumMetadataPickingBlueprintLibrary.cpp

@@ -120,6 +120,7 @@ bool UCesiumMetadataPickingBlueprintLibrary::FindUVFromHit(
   std::array<FVector, 3> Positions;
   for (size_t i = 0; i < Positions.size(); i++) {
     auto Position = pGltfComponent->PositionAccessor[VertexIndices[i]];
+    // The Y-component of glTF positions must be inverted
     Positions[i] = FVector(Position[0], -Position[1], Position[2]);
   }
 

Source/CesiumRuntime/Public/CesiumFeatureIdTexture.h

@@ -199,9 +199,9 @@ class CESIUMRUNTIME_API UCesiumFeatureIdTextureBlueprintLibrary
    * per-vertex metadata.
    *
    * This works if the vertex contains texture coordinates for the relevant
-   * texture coordinate set as indicated by GetUnrealUVChannel. If the vertex
-   * has no such coordinates, or if the feature ID texture itself is invalid,
-   * this returns -1.
+   * texture coordinate set as indicated by GetGltfTextureCoordinateSetIndex. If
+   * the vertex has no such coordinates, or if the feature ID texture itself is
+   * invalid, this returns -1.
    */
   UFUNCTION(
       BlueprintCallable,
@@ -212,9 +212,9 @@ class CESIUMRUNTIME_API UCesiumFeatureIdTextureBlueprintLibrary
       int64 VertexIndex);
 
   /**
-   * Gets the feature ID corresponding to the pixel specified by the UV texture
-   * coordinates. The feature ID can be used with a FCesiumPropertyTable to
-   * retrieve the per-pixel metadata.
+   * Gets the feature ID from a given line trace hit on the primitive containing
+   * this feature ID texture. The feature ID can be used with a
+   * FCesiumPropertyTable to retrieve the corresponding metadata.
    *
    * If the feature ID texture is invalid, this returns -1.
    */

Source/CesiumRuntime/Public/CesiumPropertyTable.h

@@ -161,6 +161,7 @@ class CESIUMRUNTIME_API UCesiumPropertyTableBlueprintLibrary
       UPARAM(ref) const FCesiumPropertyTable& PropertyTable,
       int64 FeatureID);
 
+  PRAGMA_DISABLE_DEPRECATION_WARNINGS
   /**
    * Gets all of the property values for a given feature as strings, mapped by
    * property name. This will only include values from valid property table
@@ -177,8 +178,13 @@ class CESIUMRUNTIME_API UCesiumPropertyTableBlueprintLibrary
   UFUNCTION(
       BlueprintCallable,
       BlueprintPure,
-      Category = "Cesium|Metadata|PropertyTable")
+      Category = "Cesium|Metadata|PropertyTable",
+      Meta =
+          (DeprecatedFunction,
+           DeprecationMessage =
+               "Use GetValuesAsStrings to convert the output of GetMetadataValuesForFeature instead."))
   static TMap<FString, FString> GetMetadataValuesForFeatureAsStrings(
       UPARAM(ref) const FCesiumPropertyTable& PropertyTable,
       int64 FeatureID);
+  PRAGMA_ENABLE_DEPRECATION_WARNINGS
 };