vtkGLTFDocumentLoader.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
// SPDX-License-Identifier: BSD-3-Clause

#ifndef vtkGLTFDocumentLoader_h
#define vtkGLTFDocumentLoader_h

#include "GLTFSampler.h"         // For "Sampler"
#include "vtkIOGeometryModule.h" // For export macro
#include "vtkObject.h"
#include "vtkResourceStream.h" // For "vtkResourceStream"
#include "vtkSmartPointer.h"   // For "vtkSmartPointer"
#include "vtkURILoader.h"      // For "vtkURILoader"

#include <map>    // For std::map
#include <memory> // For std::shared_ptr
#include <set>    // For std::set
#include <string> // For std::string
#include <vector> // For std::vector

VTK_ABI_NAMESPACE_BEGIN
class vtkCellArray;
class vtkDataArray;
class vtkFloatArray;
class vtkImageData;
class vtkMatrix4x4;
class vtkPoints;
class vtkPolyData;
class vtkUnsignedShortArray;

class VTKIOGEOMETRY_EXPORT vtkGLTFDocumentLoader : public vtkObject
{
public:
  static vtkGLTFDocumentLoader* New();
  vtkTypeMacro(vtkGLTFDocumentLoader, vtkObject);
  void PrintSelf(ostream& os, vtkIndent indent) override;

  enum class Target : unsigned short
  {
    ARRAY_BUFFER = 34962,
    ELEMENT_ARRAY_BUFFER = 34963
  };

  enum class AccessorType : unsigned char
  {
    SCALAR,
    VEC2,
    VEC3,
    VEC4,
    MAT2,
    MAT3,
    MAT4,
    INVALID
  };

  enum class ComponentType : unsigned short
  {
    BYTE = 5120,
    UNSIGNED_BYTE = 5121,
    SHORT = 5122,
    UNSIGNED_SHORT = 5123,
    UNSIGNED_INT = 5125,
    FLOAT = 5126
  };

  /* The following structs help deserialize a glTF document, representing each object. As such,
   * their members mostly match with the specification. Default values and boundaries are set
   * according to the specification.
   * Most of these structs contain a name property, which is optional, and, while being loaded, is
   * not currently exploited by the loader.
   * They are mostly root-level properties, and once created, are stored into vectors in the Model
   * structure.
   */

  struct BufferView
  {
    int Buffer;
    int ByteOffset;
    int ByteLength;
    int ByteStride;
    int Target;
    std::string Name;
  };

  struct Accessor
  {
    struct Sparse
    {
      int Count;
      int IndicesBufferView;
      int IndicesByteOffset;
      ComponentType IndicesComponentType;
      int ValuesBufferView;
      int ValuesByteOffset;
    };
    int BufferView;
    int ByteOffset;
    ComponentType ComponentTypeValue;
    bool Normalized;
    int Count;
    unsigned int NumberOfComponents;
    AccessorType Type;
    std::vector<double> Max;
    std::vector<double> Min;
    bool IsSparse;
    Sparse SparseObject;
    std::string Name;
  };

  struct MorphTarget
  {
    // accessor indices from the .gltf file, the map's keys correspond to attribute names
    std::map<std::string, int> AttributeIndices;
    // attribute values
    std::map<std::string, vtkSmartPointer<vtkFloatArray>> AttributeValues;
  };

  struct Primitive
  {
    // accessor indices from the .glTF file, the map's keys correspond to attribute names
    std::map<std::string, int> AttributeIndices;
    int IndicesId;
    vtkSmartPointer<vtkCellArray> Indices;

    // attribute values from buffer data
    std::map<std::string, vtkSmartPointer<vtkDataArray>> AttributeValues;

    vtkSmartPointer<vtkPolyData> Geometry;

    std::vector<MorphTarget> Targets;

    int Material;
    int Mode;
    int CellSize; // 1, 2 or 3, depending on draw mode

    // Primitive-specific extension metadata
    struct Extensions
    {
      // KHR_draco_mesh_compression extension
      // Only metadata are read (decoding and modifying the internal model is not done yet)
      struct KHRDracoMeshCompression
      {
        int BufferView = -1;
        std::map<std::string, int> AttributeIndices;
      };
      Primitive::Extensions::KHRDracoMeshCompression KHRDracoMetaData;
    };
    Primitive::Extensions ExtensionMetaData;
  };

  struct Node
  {
    std::vector<int> Children;
    int Camera;
    int Mesh;
    int Skin;

    vtkSmartPointer<vtkMatrix4x4> Transform;
    vtkSmartPointer<vtkMatrix4x4> GlobalTransform;

    bool TRSLoaded;

    vtkSmartPointer<vtkMatrix4x4> Matrix;

    std::vector<float> InitialRotation;
    std::vector<float> InitialTranslation;
    std::vector<float> InitialScale;
    std::vector<float> InitialWeights;
    std::vector<float> Rotation;
    std::vector<float> Translation;
    std::vector<float> Scale;
    std::vector<float> Weights;

    // Object-specific extension metadata
    struct Extensions
    {
      // KHR_lights_punctual extension
      struct KHRLightsPunctual
      {
        int Light = -1;
      };
      Node::Extensions::KHRLightsPunctual KHRLightsPunctualMetaData;
    };
    Node::Extensions ExtensionMetaData;

    std::string Name;

    void UpdateTransform();
  };

  struct Mesh
  {
    std::vector<struct Primitive> Primitives;
    std::vector<float> Weights;
    std::string Name;
  };

  struct TextureInfo
  {
    int Index = -1;
    int TexCoord = -1;
    std::vector<double> Offset;
    std::vector<double> Scale;
    double Rotation = 0.0;
  };

  struct Image
  {
    int BufferView;
    std::string MimeType;
    std::string Uri;

    vtkSmartPointer<vtkImageData> ImageData;

    std::string Name;
  };

  struct Material
  {
    enum class AlphaModeType : unsigned char
    {
      OPAQUE,
      MASK,
      BLEND
    };

    struct PbrMetallicRoughness
    {
      TextureInfo BaseColorTexture;
      std::vector<double> BaseColorFactor;

      TextureInfo MetallicRoughnessTexture;
      float MetallicFactor;
      float RoughnessFactor;
    };

    PbrMetallicRoughness PbrMetallicRoughness;

    TextureInfo NormalTexture;
    double NormalTextureScale;
    TextureInfo OcclusionTexture;
    double OcclusionTextureStrength;
    TextureInfo EmissiveTexture;
    std::vector<double> EmissiveFactor;

    AlphaModeType AlphaMode;
    double AlphaCutoff;

    bool DoubleSided;

    std::string Name;

    // extension KHR_materials_unlit
    bool Unlit;

    // extension KHR_materials_ior
    double IOR;
  };

  struct Texture
  {
    int Sampler;
    int Source;
    std::string Name;
  };

  struct Sampler : public GLTFSampler
  {
    std::string Name;
  };

  struct Scene
  {
    std::vector<unsigned int> Nodes;
    std::string Name;
  };

  struct Skin
  {
    std::vector<vtkSmartPointer<vtkMatrix4x4>> InverseBindMatrices;
    std::vector<int> Joints;
    int InverseBindMatricesAccessorId;
    int Skeleton;
    std::string Name;
    vtkSmartPointer<vtkPolyData> Armature;
  };

  struct Animation
  {
    struct Sampler
    {
      enum class InterpolationMode : unsigned char
      {
        LINEAR,
        STEP,
        CUBICSPLINE
      };
      InterpolationMode Interpolation;
      unsigned int Input;
      unsigned int Output;
      int NumberOfComponents;

      vtkSmartPointer<vtkFloatArray> InputData;
      vtkSmartPointer<vtkFloatArray> OutputData;

      void GetInterpolatedData(float t, size_t numberOfComponents, std::vector<float>* output,
        bool forceStep = false, bool isRotation = false) const;
    };

    struct Channel
    {
      enum class PathType : unsigned char
      {
        ROTATION,
        TRANSLATION,
        SCALE,
        WEIGHTS
      };
      int Sampler;
      int TargetNode;
      PathType TargetPath;
    };

    float Duration;                // In seconds
    std::set<float> AllTimestamps; // In seconds
    std::vector<Animation::Channel> Channels;
    std::vector<Animation::Sampler> Samplers;
    std::string Name;
  };

  struct Camera
  {
    // common properties
    double Znear;
    double Zfar;
    bool IsPerspective; // if not, camera mode is orthographic
    // perspective
    double Xmag;
    double Ymag;
    // orthographic
    double Yfov;
    double AspectRatio;
    std::string Name;
  };

  struct Extensions
  {
    // KHR_lights_punctual extension
    struct KHRLightsPunctual
    {
      struct Light
      {
        enum class LightType : unsigned char
        {
          DIRECTIONAL,
          POINT,
          SPOT
        };
        LightType Type;

        std::vector<double> Color;
        double Intensity;
        double Range;

        // Type-specific parameters
        double SpotInnerConeAngle;
        double SpotOuterConeAngle;

        std::string Name;
      };
      std::vector<Light> Lights;
    };
    KHRLightsPunctual KHRLightsPunctualMetaData;
  };

  struct Model
  {
    std::vector<Accessor> Accessors;
    std::vector<Animation> Animations;
    std::vector<std::vector<char>> Buffers;
    std::vector<BufferView> BufferViews;
    std::vector<Camera> Cameras;
    std::vector<Image> Images;
    std::vector<Material> Materials;
    std::vector<Mesh> Meshes;
    std::vector<Node> Nodes;
    std::vector<Sampler> Samplers;
    std::vector<Scene> Scenes;
    std::vector<Skin> Skins;
    std::vector<Texture> Textures;

    Extensions ExtensionMetaData;

    std::string BufferMetaData;
    int DefaultScene;
    std::string FileName;
    vtkSmartPointer<vtkResourceStream> Stream;
    vtkSmartPointer<vtkURILoader> URILoader;
  };

  bool ApplyAnimation(float t, int animationId, bool forceStep = false);

  void ResetAnimation(int animationId);


  bool LoadFileBuffer(VTK_FILEPATH const std::string& fileName, std::vector<char>& glbBuffer);
  bool LoadStreamBuffer(vtkResourceStream* stream, std::vector<char>& glbBuffer);


  bool LoadModelMetaDataFromFile(VTK_FILEPATH const std::string& FileName);
  bool LoadModelMetaDataFromStream(
    vtkResourceStream* stream, vtkURILoader* loader = nullptr, bool quiet = false);

  bool LoadModelData(const std::vector<char>& glbBuffer);

  bool BuildModelVTKGeometry();

  std::shared_ptr<Model> GetInternalModel();

  static unsigned int GetNumberOfComponentsForType(vtkGLTFDocumentLoader::AccessorType type);

  virtual std::vector<std::string> GetSupportedExtensions();

  const std::vector<std::string>& GetUsedExtensions();

  bool GetIsBinary();

  void BuildGlobalTransforms(unsigned int nodeIndex, vtkSmartPointer<vtkMatrix4x4> parentTransform);

  void BuildGlobalTransforms();

  static void ComputeJointMatrices(const Model& model, const Skin& skin, Node& node,
    std::vector<vtkSmartPointer<vtkMatrix4x4>>& jointMats);

  virtual void PrepareData() {}


  vtkSetMacro(GLBStart, vtkTypeInt64);
  vtkGetMacro(GLBStart, vtkTypeInt64);


  vtkSetMacro(LoadAnimation, bool);
  vtkGetMacro(LoadAnimation, bool);
  vtkBooleanMacro(LoadAnimation, bool);


  vtkSetMacro(LoadImages, bool);
  vtkGetMacro(LoadImages, bool);
  vtkBooleanMacro(LoadImages, bool);


  vtkSetMacro(LoadSkinMatrix, bool);
  vtkGetMacro(LoadSkinMatrix, bool);
  vtkBooleanMacro(LoadSkinMatrix, bool);

protected:
  vtkGLTFDocumentLoader() = default;
  ~vtkGLTFDocumentLoader() override = default;

private:
  struct AccessorLoadingWorker;

  struct SparseAccessorLoadingWorker;

  template <typename Type>
  struct BufferDataExtractionWorker;

  vtkGLTFDocumentLoader(const vtkGLTFDocumentLoader&) = delete;
  void operator=(const vtkGLTFDocumentLoader&) = delete;

  bool LoadSkinMatrixData();

  bool ExtractPrimitiveAttributes(Primitive& primitive);

  bool ExtractPrimitiveAccessorData(Primitive& primitive);

  bool BuildPolyDataFromPrimitive(Primitive& primitive);

  bool BuildPolyDataFromSkin(Skin& skin);

  bool LoadAnimationData();

  bool LoadImageData();

  std::shared_ptr<Model> InternalModel;

  static const std::vector<std::string> SupportedExtensions;
  std::vector<std::string> UsedExtensions;
  bool IsBinary = false;
  vtkTypeInt64 GLBStart = 0;

  bool LoadAnimation = true;
  bool LoadImages = true;
  bool LoadSkinMatrix = true;
};

VTK_ABI_NAMESPACE_END
#endif