CesiumFeaturesMetadataDescription.h

Go to the documentation of this file.

// Copyright 2020-2026 CesiumGS, Inc. and Contributors
 
#pragma once
 
#include "CesiumFeatureIdSet.h"
#include "CesiumMetadataEncodingDetails.h"
#include "CesiumMetadataPropertyDetails.h"
#include "CesiumMetadataValue.h"
#include "Containers/Array.h"
#include "Containers/UnrealString.h"
#include "Misc/Guid.h"
 
#include "CesiumFeaturesMetadataDescription.generated.h"
 
#pragma region Features descriptions
 
/**
 * @brief Determines how features in a Cesium3DTileset will be visually styled.
 */
UENUM()
enum class ECesiumFeatureStylingMode : uint8 {
  /**
   * Metadata values are passed through textures to the generated material. This
   * enables numeric properties to be used with typical material logic.
   *
   * Due to limitations with Unreal materials, properties that contain strings,
   * matrices, and arrays may not be able to be properly encoded.
   */
  Material,
  /**
   * Visual styles for each feature are evaluated in Blueprints before being
   * passed to the generated material. This enables flexible interaction with
   * metadata properties that are not supported in materials, such as strings
   * and big integers. However, this can impact performance since Blueprints are
   * executed on the main thread.
   *
   * The class assigned to BlueprintStyleClass on the component must implement
   * the ICesium3DTilesStylingProvider interface.
   */
  Blueprint
};
 
/**
 * @brief Description of a feature ID set from either EXT_mesh_features or
 * EXT_instance_features.
 */
USTRUCT()
struct CESIUMRUNTIME_API FCesiumFeatureIdSetDescription {
  GENERATED_USTRUCT_BODY()
 
  /**
   * The display name of the feature ID set. If the feature ID set already has a
   * label, this will use the label. Otherwise, if the feature ID set is
   * unlabeled, a name will be generated like so:
   *
   * - If the feature ID set is an attribute, this will appear as
   * "_FEATURE_ID_<index>", where <index> is the set index specified in
   * the attribute.
   * - If the feature ID set is a texture, this will appear as
   * "_FEATURE_ID_TEXTURE_<index>", where <index> increments with the number
   * of feature ID textures seen in an individual primitive.
   * - If the feature ID set is an implicit set, this will appear as
   * "_IMPLICIT_FEATURE_ID". Implicit feature ID sets don't vary in definition,
   * so any additional implicit feature ID sets across the primitives are
   * counted by this one.
   *
   * This name will also be used to represent the feature ID set in the
   * generated material.
   */
  UPROPERTY(EditAnywhere, Category = "Cesium|Features")
  FString Name;
 
  /**
   * The type of the feature ID set.
   */
  UPROPERTY(EditAnywhere, Category = "Cesium|Features")
  ECesiumFeatureIdSetType Type = ECesiumFeatureIdSetType::None;
 
  /**
   * The name of the property table that this feature ID set corresponds to.
   */
  UPROPERTY(EditAnywhere, Category = "Cesium|Features")
  FString PropertyTableName;
 
  /**
   * The method used to apply styling to individual features.
   *
   * By default, metadata properties are encoded to textures and passed the
   * generated material, allowing use with material logic. However, they can
   * also be styled in a prepass using Blueprints.
   */
  UPROPERTY(EditAnywhere, Category = "Cesium|Features")
  ECesiumFeatureStylingMode StylingMode = ECesiumFeatureStylingMode::Material;
};
 
/**
 * @brief Description of the feature ID sets available from the
 * EXT_mesh_features and EXT_instance_features extensions in a glTF.
 *
 * This aggregates the feature ID sets of all visible glTF primitives in the
 * model. This describes the feature IDs that can be made accessible
 * to Unreal Engine materials.
 */
USTRUCT()
struct CESIUMRUNTIME_API FCesiumPrimitiveFeaturesDescription {
  GENERATED_USTRUCT_BODY()
 
  /**
   * @brief The feature ID sets to make accessible to the material. Note that
   * the order of feature ID sets in this array does not necessarily
   * correspond to the order of these feature ID sets in a glTF
   * primitive.
   */
  UPROPERTY(
      EditAnywhere,
      Category = "Cesium|Features",
      Meta = (TitleProperty = "Name"))
  TArray<FCesiumFeatureIdSetDescription> FeatureIdSets;
};
#pragma endregion
 
#pragma region Metadata descriptions
 
// These don't exhaustively cover the possibilities of glTF metadata
// classes, they only cover the subset that can be encoded into textures. The
// following types are excluded:
// - enums
// - strings that cannot be parsed as numbers or colors
// - matrices
// - variable length arrays
// - arrays of non-scalar, non-boolean elements
//
// Additionally, if a property contains fixed-length arrays, only the first four
// elements can be encoded.
 
/**
 * @brief Description of a property table property that should be encoded for
 * access on the GPU.
 */
USTRUCT()
struct CESIUMRUNTIME_API FCesiumPropertyTablePropertyDescription {
  GENERATED_USTRUCT_BODY()
 
  /**
   * The name of this property. This will be how it is referenced in the
   * material.
   */
  UPROPERTY(EditAnywhere, Category = "Cesium|Metadata")
  FString Name;
 
  /**
   * Describes the underlying type of this property and other relevant
   * information from its EXT_structural_metadata definition. Not all types of
   * properties can be encoded to the GPU, or coerced to GPU-compatible types.
   */
  UPROPERTY(EditAnywhere, Category = "Cesium|Metadata")
  FCesiumMetadataPropertyDetails PropertyDetails;
 
  /**
   * Describes how the property will be encoded as data on the GPU, if possible.
   */
  UPROPERTY(EditAnywhere, Category = "Cesium|Metadata")
  FCesiumMetadataEncodingDetails EncodingDetails;
};
 
/**
 * @brief Description of a property table containing properties to be encoded
 * for access in Unreal materials.
 */
USTRUCT()
struct CESIUMRUNTIME_API FCesiumPropertyTableDescription {
  GENERATED_USTRUCT_BODY()
 
  /**
   * @brief The name of this property table. If this property table has no name
   * in the EXT_structural_metadata extension, then its class name is used
   * instead.
   */
  UPROPERTY(EditAnywhere, Category = "Cesium|Metadata")
  FString Name;
 
  /**
   * @brief Descriptions of the properties to upload to the GPU.
   */
  UPROPERTY(
      EditAnywhere,
      Category = "Cesium|Metadata",
      Meta = (TitleProperty = "Name"))
  TArray<FCesiumPropertyTablePropertyDescription> Properties;
};
 
/**
 * @brief Description of a property texture property that should be made
 * accessible to Unreal materials. A property texture property's data is
 * already available through a texture, so no additional encoding details need
 * to be specified.
 */
USTRUCT()
struct CESIUMRUNTIME_API FCesiumPropertyTexturePropertyDescription {
  GENERATED_USTRUCT_BODY()
 
  /**
   * The name of this property. This will be how it is referenced in the
   * material.
   */
  UPROPERTY(EditAnywhere, Category = "Cesium|Metadata")
  FString Name;
 
  /**
   * Describes the underlying type of this property and other relevant
   * information from its EXT_structural_metadata definition.
   */
  UPROPERTY(EditAnywhere, Category = "Cesium|Metadata")
  FCesiumMetadataPropertyDetails PropertyDetails;
};
 
/**
 * @brief Description of a property texture with properties that should be
 * made accessible to Unreal materials.
 */
USTRUCT()
struct CESIUMRUNTIME_API FCesiumPropertyTextureDescription {
  GENERATED_USTRUCT_BODY()
 
  /**
   * @brief The name of this property texture.
   */
  UPROPERTY(EditAnywhere, Category = "Cesium|Metadata")
  FString Name;
 
  /**
   * @brief Descriptions of the properties to upload to the GPU.
   */
  UPROPERTY(
      EditAnywhere,
      Category = "Cesium|Metadata",
      Meta = (TitleProperty = "Name"))
  TArray<FCesiumPropertyTexturePropertyDescription> Properties;
};
 
/**
 * @brief Description of a property attribute property that should be encoded
 * for access on the GPU.
 *
 * This is similar to FCesiumPropertyTablePropertyDescription, but is limited to
 * the types that are supported for property attribute properties.
 */
USTRUCT()
struct CESIUMRUNTIME_API FCesiumPropertyAttributePropertyDescription {
  GENERATED_USTRUCT_BODY()
 
  /**
   * The name of this property. This will be how it is referenced in the
   * material.
   */
  UPROPERTY(EditAnywhere, Category = "Cesium")
  FString Name;
 
  /**
   * Describes the underlying type of this property and other relevant
   * information from its EXT_structural_metadata definition. Not all types of
   * properties can be encoded to the GPU, or coerced to GPU-compatible types.
   */
  UPROPERTY(EditAnywhere, Category = "Cesium")
  FCesiumMetadataPropertyDetails PropertyDetails;
 
  /**
   * Describes how the property will be encoded as data on the GPU, if possible.
   */
  UPROPERTY(EditAnywhere, Category = "Cesium")
  FCesiumMetadataEncodingDetails EncodingDetails;
};
 
/**
 * @brief Description of a property attribute with properties that should be
 * made accessible to Unreal materials.
 */
USTRUCT()
struct CESIUMRUNTIME_API FCesiumPropertyAttributeDescription {
  GENERATED_USTRUCT_BODY()
 
  /**
   * @brief The name of this property attribute.
   */
  UPROPERTY(EditAnywhere, Category = "Cesium")
  FString Name;
 
  /**
   * @brief Descriptions of the properties to upload to the GPU.
   */
  UPROPERTY(EditAnywhere, Category = "Cesium", Meta = (TitleProperty = "Name"))
  TArray<FCesiumPropertyAttributePropertyDescription> Properties;
};
 
/**
 * @brief Names of the metadata entities referenced by the
 * EXT_structural_metadata on a glTF's primitives.
 *
 * This aggregates the metadata of all visible glTF primitives in the model.
 * This lists the names of the property textures actually used by the glTF
 * primitive, indicating it can be sampled with the primitive's texture
 * coordinates in the Unreal material.
 */
USTRUCT()
struct CESIUMRUNTIME_API FCesiumPrimitiveMetadataDescription {
  GENERATED_USTRUCT_BODY()
 
  /**
   * @brief The names of the property textures used by the glTF primitives
   * across the tileset.
   *
   * This should be a subset of the property textures listed in the model
   * metadata. Property textures can be passed to the material even if they are
   * not explicitly used by a glTF primitive, but the primitive may lack the
   * corresponding sets of texture coordinates intended to sample them.
   */
  UPROPERTY(
      EditAnywhere,
      Category = "Cesium|Metadata",
      Meta = (TitleProperty = "Name"))
  TSet<FString> PropertyTextureNames;
};
 
/**
 * @brief Description of metadata from a glTF's EXT_structural_metadata
 * extension that should be uploaded to the GPU for access in Unreal materials.
 */
USTRUCT()
struct CESIUMRUNTIME_API FCesiumModelMetadataDescription {
  GENERATED_USTRUCT_BODY()
 
  /**
   * @brief Descriptions of property tables to encode for access in Unreal
   * materials.
   */
  UPROPERTY(
      EditAnywhere,
      Category = "Cesium|Metadata",
      Meta = (TitleProperty = "Name"))
  TArray<FCesiumPropertyTableDescription> PropertyTables;
 
  /**
   * @brief Descriptions of property textures to make accessible to Unreal
   * materials.
   */
  UPROPERTY(
      EditAnywhere,
      Category = "Cesium|Metadata",
      Meta = (TitleProperty = "Name"))
  TArray<FCesiumPropertyTextureDescription> PropertyTextures;
};
 
#pragma endregion
 
#pragma region Tileset Statistics
 
/**
 * @brief Supported statistic semantics from the 3D Tiles specification.
 */
UENUM()
enum class ECesiumMetadataStatisticSemantic : uint8 {
  None = 0 UMETA(Hidden),
  /**
   * The minimum property value occurring in the tileset.
   */
  Min,
  /**
   * The maximum property value occurring in the tileset.
   */
  Max,
  /**
   * The arithmetic mean of property values occurring in the tileset.
   */
  Mean,
  /**
   * The median of property values occurring in the tileset.
   */
  Median,
  /**
   * The standard deviation of property values occurring in the tileset.
   */
  StandardDeviation,
  /**
   * The variance of property values occurring in the tileset.
   */
  Variance,
  /**
   * The sum of property values occurring in the tileset.
   */
  Sum
};
 
/**
 * @brief A statistic for a metadata property's values.
 */
USTRUCT()
struct FCesiumMetadataPropertyStatisticValue {
  GENERATED_USTRUCT_BODY()
  /**
   * @brief The semantic of this statistic.
   */
  UPROPERTY(EditAnywhere, Category = "Cesium|Metadata|Statistics")
  ECesiumMetadataStatisticSemantic Semantic;
 
  /**
   * @brief The value of this statistic. This reflects the value on the tileset
   * it is attached to and should not be edited by users.
   */
  UPROPERTY(Transient, VisibleAnywhere, Category = "Cesium|Metadata|Statistics")
  FCesiumMetadataValue Value;
};
 
/**
 * @brief The statistics for a given metadata property.
 */
USTRUCT()
struct FCesiumMetadataPropertyStatisticsDescription {
  GENERATED_USTRUCT_BODY()
  /**
   * @brief The identifier of this property.
   */
  UPROPERTY(EditAnywhere, Category = "Cesium|Metadata|Statistics")
  FString Id;
 
  /**
   * @brief The available statistics for this property.
   */
  UPROPERTY(
      EditAnywhere,
      Category = "Cesium|Metadata|Statistics",
      Meta = (TitleProperty = "Semantic"))
  TArray<FCesiumMetadataPropertyStatisticValue> Values;
};
 
/**
 * @brief The statistics for a given metadata class.
 */
USTRUCT()
struct FCesiumMetadataClassStatisticsDescription {
  GENERATED_USTRUCT_BODY()
  /**
   * @brief The identifier of this class.
   */
  UPROPERTY(EditAnywhere, Category = "Cesium|Metadata|Statistics")
  FString Id;
 
  /**
   * @brief The statistics of properties belonging to this class.
   */
  UPROPERTY(
      EditAnywhere,
      Category = "Cesium|Metadata|Statistics",
      Meta = (TitleProperty = "Id"))
  TArray<FCesiumMetadataPropertyStatisticsDescription> Properties;
};
 
#pragma endregion
 
/**
 * @brief Description of both feature IDs and metadata from a glTF via the
 * EXT_mesh_features and EXT_structural_metadata extensions. Indicates what
 * parts of the extension should be uploaded to the GPU for access in Unreal
 * materials.
 */
USTRUCT()
struct CESIUMRUNTIME_API FCesiumFeaturesMetadataDescription {
  GENERATED_USTRUCT_BODY()
 
public:
  /**
   * @brief Description of the statistics reported by the tileset. Each entry
   * represents a class and its cumulative statistics.
   */
  UPROPERTY(EditAnywhere, Category = "Cesium", Meta = (TitleProperty = "Id"))
  TArray<FCesiumMetadataClassStatisticsDescription> Statistics;
 
  /**
   * @brief Description of the feature ID sets available from the
   * EXT_mesh_features or EXT_instance_features extensions in a glTF.
   */
  UPROPERTY(EditAnywhere, Category = "Cesium", Meta = (TitleProperty = "Name"))
  FCesiumPrimitiveFeaturesDescription PrimitiveFeatures;
 
  /**
   * @brief Description of the metadata used by the EXT_structural_metadata on a
   * glTF's primitives.
   */
  UPROPERTY(EditAnywhere, Category = "Cesium", Meta = (TitleProperty = "Name"))
  FCesiumPrimitiveMetadataDescription PrimitiveMetadata;
 
  /**
   * @brief Description of metadata from a glTF's EXT_structural_metadata
   * extension.
   */
  UPROPERTY(EditAnywhere, Category = "Cesium", Meta = (TitleProperty = "Name"))
  FCesiumModelMetadataDescription ModelMetadata;
};