VTK  9.5.20250802
vtkGLTFDocumentLoader.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
2// SPDX-License-Identifier: BSD-3-Clause
3
28#ifndef vtkGLTFDocumentLoader_h
29#define vtkGLTFDocumentLoader_h
30
31#include "GLTFSampler.h" // For "Sampler"
32#include "vtkIOGeometryModule.h" // For export macro
33#include "vtkObject.h"
34#include "vtkResourceStream.h" // For "vtkResourceStream"
35#include "vtkSmartPointer.h" // For "vtkSmartPointer"
36#include "vtkURILoader.h" // For "vtkURILoader"
37
38#include <map> // For std::map
39#include <memory> // For std::shared_ptr
40#include <string> // For std::string
41#include <vector> // For std::vector
42
43VTK_ABI_NAMESPACE_BEGIN
44class vtkCellArray;
45class vtkDataArray;
46class vtkFloatArray;
47class vtkImageData;
48class vtkMatrix4x4;
49class vtkPoints;
50class vtkPolyData;
52
53class VTKIOGEOMETRY_EXPORT vtkGLTFDocumentLoader : public vtkObject
54{
55public:
58 void PrintSelf(ostream& os, vtkIndent indent) override;
59
63 enum class Target : unsigned short
64 {
65 ARRAY_BUFFER = 34962,
67 };
68
73 enum class AccessorType : unsigned char
74 {
75 SCALAR,
76 VEC2,
77 VEC3,
78 VEC4,
79 MAT2,
80 MAT3,
81 MAT4,
82 INVALID
83 };
84
89 enum class ComponentType : unsigned short
90 {
91 BYTE = 5120,
92 UNSIGNED_BYTE = 5121,
93 SHORT = 5122,
94 UNSIGNED_SHORT = 5123,
95 UNSIGNED_INT = 5125,
96 FLOAT = 5126
97 };
98
99 /* The following structs help deserialize a glTF document, representing each object. As such,
100 * their members mostly match with the specification. Default values and boundaries are set
101 * according to the specification.
102 * Most of these structs contain a name property, which is optional, and, while being loaded, is
103 * not currently exploited by the loader.
104 * They are mostly root-level properties, and once created, are stored into vectors in the Model
105 * structure.
106 */
107
113 {
119 std::string Name;
120 };
121
128 struct Accessor
129 {
134 struct Sparse
135 {
136 int Count;
142 };
147 int Count;
148 unsigned int NumberOfComponents;
150 std::vector<double> Max;
151 std::vector<double> Min;
154 std::string Name;
155 };
156
164 {
165 // accessor indices from the .gltf file, the map's keys correspond to attribute names
166 std::map<std::string, int> AttributeIndices;
167 // attribute values
168 std::map<std::string, vtkSmartPointer<vtkFloatArray>> AttributeValues;
169 };
170
179 {
180 // accessor indices from the .glTF file, the map's keys correspond to attribute names
181 std::map<std::string, int> AttributeIndices;
184
185 // attribute values from buffer data
186 std::map<std::string, vtkSmartPointer<vtkDataArray>> AttributeValues;
187
189
190 std::vector<MorphTarget> Targets;
191
193 int Mode;
194 int CellSize; // 1, 2 or 3, depending on draw mode
195
196 // Primitive-specific extension metadata
198 {
199 // KHR_draco_mesh_compression extension
200 // Only metadata are read (decoding and modifying the internal model is not done yet)
202 {
203 int BufferView = -1;
204 std::map<std::string, int> AttributeIndices;
205 };
207 };
209 };
210
217 struct Node
218 {
219 std::vector<int> Children;
221 int Mesh;
222 int Skin;
223
226
228
230
231 std::vector<float> InitialRotation;
232 std::vector<float> InitialTranslation;
233 std::vector<float> InitialScale;
234 std::vector<float> InitialWeights;
235 std::vector<float> Rotation;
236 std::vector<float> Translation;
237 std::vector<float> Scale;
238 std::vector<float> Weights;
239
240 // Object-specific extension metadata
242 {
243 // KHR_lights_punctual extension
245 {
246 int Light = -1;
247 };
249 };
251
252 std::string Name;
253
255 };
256
261 struct Mesh
262 {
263 std::vector<struct Primitive> Primitives;
264 std::vector<float> Weights;
265 std::string Name;
266 };
267
274 {
275 int Index = -1;
276 int TexCoord = -1;
277 std::vector<double> Offset;
278 std::vector<double> Scale;
279 double Rotation = 0.0;
280 };
281
286 struct Image
287 {
289 std::string MimeType;
290 std::string Uri;
291
293
294 std::string Name;
295 };
296
303 struct Material
304 {
305 enum class AlphaModeType : unsigned char
306 {
307 OPAQUE,
308 MASK,
309 BLEND
310 };
311
313 {
315 std::vector<double> BaseColorFactor;
316
320 };
321
323
329 std::vector<double> EmissiveFactor;
330
333
335
336 std::string Name;
337
338 // extension KHR_materials_unlit
339 bool Unlit;
340 };
341
346 struct Texture
347 {
350 std::string Name;
351 };
352
357 struct Sampler : public GLTFSampler
358 {
359 std::string Name;
360 };
361
367 struct Scene
368 {
369 std::vector<unsigned int> Nodes;
370 std::string Name;
371 };
372
378 struct Skin
379 {
380 std::vector<vtkSmartPointer<vtkMatrix4x4>> InverseBindMatrices;
381 std::vector<int> Joints;
384 std::string Name;
386 };
387
395 {
396 struct Sampler
397 {
398 enum class InterpolationMode : unsigned char
399 {
400 LINEAR,
401 STEP,
402 CUBICSPLINE
403 };
405 unsigned int Input;
406 unsigned int Output;
408
411
415 void GetInterpolatedData(float t, size_t numberOfComponents, std::vector<float>* output,
416 bool forceStep = false, bool isRotation = false) const;
417 };
418
419 struct Channel
420 {
421 enum class PathType : unsigned char
422 {
423 ROTATION,
424 TRANSLATION,
425 SCALE,
426 WEIGHTS
427 };
431 };
432
433 float Duration; // In seconds
434 std::vector<Animation::Channel> Channels;
435 std::vector<Animation::Sampler> Samplers;
436 std::string Name;
437 };
438
444 struct Camera
445 {
446 // common properties
447 double Znear;
448 double Zfar;
449 bool IsPerspective; // if not, camera mode is orthographic
450 // perspective
451 double Xmag;
452 double Ymag;
453 // orthographic
454 double Yfov;
456 std::string Name;
457 };
458
466 {
467 // KHR_lights_punctual extension
469 {
470 struct Light
471 {
472 enum class LightType : unsigned char
473 {
474 DIRECTIONAL,
475 POINT,
476 SPOT
477 };
479
480 std::vector<double> Color;
481 double Intensity;
482 double Range;
483
484 // Type-specific parameters
487
488 std::string Name;
489 };
490 std::vector<Light> Lights;
491 };
493 };
494
498 struct Model
499 {
500 std::vector<Accessor> Accessors;
501 std::vector<Animation> Animations;
502 std::vector<std::vector<char>> Buffers;
503 std::vector<BufferView> BufferViews;
504 std::vector<Camera> Cameras;
505 std::vector<Image> Images;
506 std::vector<Material> Materials;
507 std::vector<Mesh> Meshes;
508 std::vector<Node> Nodes;
509 std::vector<Sampler> Samplers;
510 std::vector<Scene> Scenes;
511 std::vector<Skin> Skins;
512 std::vector<Texture> Textures;
513
515
516 std::string BufferMetaData;
518 std::string FileName;
521 };
522
527 bool ApplyAnimation(float t, int animationId, bool forceStep = false);
528
532 void ResetAnimation(int animationId);
533
535
540 bool LoadFileBuffer(VTK_FILEPATH const std::string& fileName, std::vector<char>& glbBuffer);
541 bool LoadStreamBuffer(vtkResourceStream* stream, std::vector<char>& glbBuffer);
543
545
553 bool LoadModelMetaDataFromFile(VTK_FILEPATH const std::string& FileName);
556
560 bool LoadModelData(const std::vector<char>& glbBuffer);
561
566
570 std::shared_ptr<Model> GetInternalModel();
571
576
580 virtual std::vector<std::string> GetSupportedExtensions();
581
585 const std::vector<std::string>& GetUsedExtensions();
586
593 void BuildGlobalTransforms(unsigned int nodeIndex, vtkSmartPointer<vtkMatrix4x4> parentTransform);
594
599
603 static void ComputeJointMatrices(const Model& model, const Skin& skin, Node& node,
604 std::vector<vtkSmartPointer<vtkMatrix4x4>>& jointMats);
605
612 virtual void PrepareData() {}
613
615
620 vtkSetMacro(GLBStart, vtkTypeInt64);
621 vtkGetMacro(GLBStart, vtkTypeInt64);
623
625
630 vtkSetMacro(LoadAnimation, bool);
631 vtkGetMacro(LoadAnimation, bool);
632 vtkBooleanMacro(LoadAnimation, bool);
634
636
641 vtkSetMacro(LoadImages, bool);
642 vtkGetMacro(LoadImages, bool);
643 vtkBooleanMacro(LoadImages, bool);
645
647
652 vtkSetMacro(LoadSkinMatrix, bool);
653 vtkGetMacro(LoadSkinMatrix, bool);
654 vtkBooleanMacro(LoadSkinMatrix, bool);
656
657protected:
659 ~vtkGLTFDocumentLoader() override = default;
660
661private:
662 struct AccessorLoadingWorker;
663
664 struct SparseAccessorLoadingWorker;
665
666 template <typename Type>
667 struct BufferDataExtractionWorker;
668
670 void operator=(const vtkGLTFDocumentLoader&) = delete;
671
675 bool LoadSkinMatrixData();
676
681 bool ExtractPrimitiveAttributes(Primitive& primitive);
682
689 bool ExtractPrimitiveAccessorData(Primitive& primitive);
690
695 bool BuildPolyDataFromPrimitive(Primitive& primitive);
696
700 bool BuildPolyDataFromSkin(Skin& skin);
701
705 bool LoadAnimationData();
706
710 bool LoadImageData();
711
712 std::shared_ptr<Model> InternalModel;
713
714 static const std::vector<std::string> SupportedExtensions;
715 std::vector<std::string> UsedExtensions;
716 vtkTypeInt64 GLBStart = 0;
717
721 bool LoadAnimation = true;
722 bool LoadImages = true;
723 bool LoadSkinMatrix = true;
724};
725
726VTK_ABI_NAMESPACE_END
727#endif
object to represent cell connectivity
abstract superclass for arrays of numeric data
dynamic, self-adjusting array of float
Deserialize a GLTF model file.
AccessorType
Defines an accessor's type.
bool LoadModelMetaDataFromFile(const std::string &FileName)
Reset internal Model struct, and serialize glTF metadata (all json information) into it.
void ResetAnimation(int animationId)
Restore the transforms that were modified by an animation to their initial state.
bool LoadModelMetaDataFromStream(vtkResourceStream *stream, vtkURILoader *loader=nullptr)
Reset internal Model struct, and serialize glTF metadata (all json information) into it.
virtual std::vector< std::string > GetSupportedExtensions()
Get the list of extensions that are supported by this loader.
bool LoadModelData(const std::vector< char > &glbBuffer)
Load buffer data into the internal Model.
void BuildGlobalTransforms(unsigned int nodeIndex, vtkSmartPointer< vtkMatrix4x4 > parentTransform)
Concatenate the current node's local transform to its parent's global transform, storing the resultin...
static unsigned int GetNumberOfComponentsForType(vtkGLTFDocumentLoader::AccessorType type)
Returns the number of components for a given accessor type.
static void ComputeJointMatrices(const Model &model, const Skin &skin, Node &node, std::vector< vtkSmartPointer< vtkMatrix4x4 > > &jointMats)
Compute all joint matrices of the skin of a specific node.
virtual void PrepareData()
Some extensions require a preparation on the model before building VTK objects.
void PrintSelf(ostream &os, vtkIndent indent) override
Methods invoked by print to print information about the object including superclasses.
Target
Define an openGL draw target.
static vtkGLTFDocumentLoader * New()
bool ApplyAnimation(float t, int animationId, bool forceStep=false)
Apply the specified animation, at the specified time value t, to the internal Model.
const std::vector< std::string > & GetUsedExtensions()
Get the list of extensions that are used by the current model.
~vtkGLTFDocumentLoader() override=default
vtkGLTFDocumentLoader()=default
bool LoadStreamBuffer(vtkResourceStream *stream, std::vector< char > &glbBuffer)
Load the binary part of a binary glTF (.glb) file.
ComponentType
Define a type for different data components.
bool LoadFileBuffer(const std::string &fileName, std::vector< char > &glbBuffer)
Load the binary part of a binary glTF (.glb) file.
std::shared_ptr< Model > GetInternalModel()
Get the internal Model.
bool BuildModelVTKGeometry()
Converts the internal Model's loaded data into more convenient vtk objects.
void BuildGlobalTransforms()
Build all global transforms.
topologically and geometrically regular array of data
a simple class to control print indentation
Definition vtkIndent.h:108
represent and manipulate 4x4 transformation matrices
abstract base class for most VTK objects
Definition vtkObject.h:162
represent and manipulate 3D points
Definition vtkPoints.h:139
concrete dataset represents vertices, lines, polygons, and triangle strips
Abstract class used for custom streams.
Hold a reference to a vtkObjectBase instance.
Helper class for readers and importer that need to load more than one resource.
dynamic, self-adjusting array of unsigned short
This struct describes a glTF sampler object.
Definition GLTFSampler.h:16
This struct describes an accessor.sparse glTF object.
This struct describes an accessor glTF object.
vtkSmartPointer< vtkFloatArray > OutputData
vtkSmartPointer< vtkFloatArray > InputData
void GetInterpolatedData(float t, size_t numberOfComponents, std::vector< float > *output, bool forceStep=false, bool isRotation=false) const
Get the interpolated animation output at time t.
This struct describes a glTF animation object.
std::vector< Animation::Channel > Channels
std::vector< Animation::Sampler > Samplers
This struct describes a glTF bufferView object.
This struct describes a glTF camera object.
This struct contains extension metadata.
This struct describes a glTF image object.
vtkSmartPointer< vtkImageData > ImageData
This struct describes a glTF material object.
This struct describes a glTF mesh object.
std::vector< struct Primitive > Primitives
This struct contains all data from a gltf asset.
std::vector< std::vector< char > > Buffers
std::vector< BufferView > BufferViews
vtkSmartPointer< vtkResourceStream > Stream
std::vector< Animation > Animations
std::vector< Material > Materials
std::vector< Accessor > Accessors
vtkSmartPointer< vtkURILoader > URILoader
This struct describes a glTF Morph Target object.
std::map< std::string, vtkSmartPointer< vtkFloatArray > > AttributeValues
std::map< std::string, int > AttributeIndices
Node::Extensions::KHRLightsPunctual KHRLightsPunctualMetaData
This struct describes a glTF node object.
vtkSmartPointer< vtkMatrix4x4 > GlobalTransform
vtkSmartPointer< vtkMatrix4x4 > Matrix
vtkSmartPointer< vtkMatrix4x4 > Transform
std::vector< float > InitialTranslation
Primitive::Extensions::KHRDracoMeshCompression KHRDracoMetaData
This struct describes a glTF primitive object.
vtkSmartPointer< vtkCellArray > Indices
std::map< std::string, int > AttributeIndices
vtkSmartPointer< vtkPolyData > Geometry
std::map< std::string, vtkSmartPointer< vtkDataArray > > AttributeValues
This struct describes a glTF sampler object.
This struct describes a glTF scene object.
std::vector< unsigned int > Nodes
This struct describes a glTF asset.
std::vector< vtkSmartPointer< vtkMatrix4x4 > > InverseBindMatrices
vtkSmartPointer< vtkPolyData > Armature
This struct describes a glTF textureInfo object, mostly used in material descriptions They contain tw...
This struct describes a glTF texture object.
#define ARRAY_BUFFER
#define ELEMENT_ARRAY_BUFFER
#define VTK_FILEPATH