Merge pull request #10479 from CesiumGS/model-experimental-articulations

Add support for `AGI_articulations` to `ModelExperimental`

Author: ptrgags

CHANGES.md

@@ -15,6 +15,7 @@
 - Added `modelUpAxis` and `modelForwardAxis` constructor options to `Cesium3DTileset` [#10439](https://github.com/CesiumGS/cesium/pull/10439)
 - Added `heightReference` to `ModelExperimental`. [#10448](https://github.com/CesiumGS/cesium/pull/10448)
 - Added `silhouetteSize` and `silhouetteColor` to `ModelExperimental`. [#10457](https://github.com/CesiumGS/cesium/pull/10457)
+- Added support for `AGI_articulations` to `ModelExperimental`. [#10479](https://github.com/CesiumGS/cesium/pull/10479)
 
 ##### Fixes :wrench:
 

Source/Core/ArticulationStageType.js

@@ -0,0 +1,23 @@
+/**
+ * An enum describing the type of motion that is defined by an articulation stage
+ * in the AGI_articulations extension.
+ *
+ * @alias {ArticulationStageType}
+ * @enum {String}
+ *
+ * @private
+ */
+const ArticulationStageType = {
+  XTRANSLATE: "xTranslate",
+  YTRANSLATE: "yTranslate",
+  ZTRANSLATE: "zTranslate",
+  XROTATE: "xRotate",
+  YROTATE: "yRotate",
+  ZROTATE: "zRotate",
+  XSCALE: "xScale",
+  YSCALE: "yScale",
+  ZSCALE: "zScale",
+  UNIFORMSCALE: "uniformScale",
+};
+
+export default Object.freeze(ArticulationStageType);

Source/Scene/GltfLoader.js

@@ -1,27 +1,28 @@
 import arrayFill from "../Core/arrayFill.js";
+import ArticulationStageType from "../Core/ArticulationStageType.js";
+import AttributeType from "./AttributeType.js";
+import Axis from "./Axis.js";
 import Cartesian3 from "../Core/Cartesian3.js";
 import Cartesian4 from "../Core/Cartesian4.js";
 import Check from "../Core/Check.js";
 import ComponentDatatype from "../Core/ComponentDatatype.js";
 import Credit from "../Core/Credit.js";
 import defaultValue from "../Core/defaultValue.js";
 import defined from "../Core/defined.js";
-import InterpolationType from "../Core/InterpolationType.js";
 import FeatureDetection from "../Core/FeatureDetection.js";
-import Matrix4 from "../Core/Matrix4.js";
-import Quaternion from "../Core/Quaternion.js";
-import Sampler from "../Renderer/Sampler.js";
 import getAccessorByteStride from "./GltfPipeline/getAccessorByteStride.js";
 import getComponentReader from "./GltfPipeline/getComponentReader.js";
-import numberOfComponentsForType from "./GltfPipeline/numberOfComponentsForType.js";
-import AttributeType from "./AttributeType.js";
-import Axis from "./Axis.js";
-import GltfStructuralMetadataLoader from "./GltfStructuralMetadataLoader.js";
 import GltfLoaderUtil from "./GltfLoaderUtil.js";
+import GltfStructuralMetadataLoader from "./GltfStructuralMetadataLoader.js";
 import InstanceAttributeSemantic from "./InstanceAttributeSemantic.js";
+import InterpolationType from "../Core/InterpolationType.js";
+import Matrix4 from "../Core/Matrix4.js";
 import ModelComponents from "./ModelComponents.js";
+import numberOfComponentsForType from "./GltfPipeline/numberOfComponentsForType.js";
+import Quaternion from "../Core/Quaternion.js";
 import ResourceCache from "./ResourceCache.js";
 import ResourceLoader from "./ResourceLoader.js";
+import Sampler from "../Renderer/Sampler.js";
 import SupportedImageFormats from "./SupportedImageFormats.js";
 import VertexAttributeSemantic from "./VertexAttributeSemantic.js";
 
@@ -40,6 +41,8 @@ const AnimationSampler = ModelComponents.AnimationSampler;
 const AnimationTarget = ModelComponents.AnimationTarget;
 const AnimationChannel = ModelComponents.AnimationChannel;
 const Animation = ModelComponents.Animation;
+const ArticulationStage = ModelComponents.ArticulationStage;
+const Articulation = ModelComponents.Articulation;
 const Asset = ModelComponents.Asset;
 const Scene = ModelComponents.Scene;
 const Components = ModelComponents.Components;
@@ -1570,11 +1573,16 @@ function loadNode(loader, gltf, gltfNode, supportedImageFormats, frameState) {
     defaultValue.EMPTY_OBJECT
   );
   const instancingExtension = nodeExtensions.EXT_mesh_gpu_instancing;
+  const articulationsExtension = nodeExtensions.AGI_articulations;
 
   if (defined(instancingExtension)) {
     node.instances = loadInstances(loader, gltf, nodeExtensions, frameState);
   }
 
+  if (defined(articulationsExtension)) {
+    node.articulationName = articulationsExtension.articulationName;
+  }
+
   const meshId = gltfNode.mesh;
   if (defined(meshId)) {
     const mesh = gltf.meshes[meshId];
@@ -1813,6 +1821,61 @@ function loadAnimations(loader, gltf, nodes) {
   return animations;
 }
 
+function loadArticulationStage(gltfStage) {
+  const stage = new ArticulationStage();
+  stage.name = gltfStage.name;
+
+  const type = gltfStage.type.toUpperCase();
+  stage.type = ArticulationStageType[type];
+
+  stage.minimumValue = gltfStage.minimumValue;
+  stage.maximumValue = gltfStage.maximumValue;
+  stage.initialValue = gltfStage.initialValue;
+
+  return stage;
+}
+
+function loadArticulation(gltfArticulation) {
+  const articulation = new Articulation();
+  articulation.name = gltfArticulation.name;
+
+  const gltfStages = gltfArticulation.stages;
+  const gltfStagesLength = gltfStages.length;
+
+  const stages = new Array(gltfStagesLength);
+  for (let i = 0; i < gltfStagesLength; i++) {
+    const stage = loadArticulationStage(gltfStages[i]);
+    stages[i] = stage;
+  }
+
+  articulation.stages = stages;
+
+  return articulation;
+}
+
+function loadArticulations(gltf) {
+  const extensions = defaultValue(gltf.extensions, defaultValue.EMPTY_OBJECT);
+  const articulationsExtension = extensions.AGI_articulations;
+
+  if (!defined(articulationsExtension)) {
+    return [];
+  }
+
+  const gltfArticulations = articulationsExtension.articulations;
+  if (!defined(gltfArticulations)) {
+    return [];
+  }
+
+  const gltfArticulationsLength = gltfArticulations.length;
+  const articulations = new Array(gltfArticulationsLength);
+  for (let i = 0; i < gltfArticulationsLength; i++) {
+    const articulation = loadArticulation(gltfArticulations[i]);
+    articulations[i] = articulation;
+  }
+
+  return articulations;
+}
+
 function getSceneNodeIds(gltf) {
   let nodesIds;
   if (defined(gltf.scenes) && defined(gltf.scene)) {
@@ -1864,6 +1927,7 @@ function parse(
   const nodes = loadNodes(loader, gltf, supportedImageFormats, frameState);
   const skins = loadSkins(loader, gltf, nodes);
   const animations = loadAnimations(loader, gltf, nodes);
+  const articulations = loadArticulations(gltf);
   const scene = loadScene(gltf, nodes);
 
   const components = new Components();
@@ -1881,6 +1945,7 @@ function parse(
   components.nodes = nodes;
   components.skins = skins;
   components.animations = animations;
+  components.articulations = articulations;
   components.upAxis = loader._upAxis;
   components.forwardAxis = loader._forwardAxis;
 

Source/Scene/ModelComponents.js

@@ -794,6 +794,15 @@ function Node() {
    * @private
    */
   this.morphWeights = [];
+
+  /**
+   * The name of the articulation affecting this node, as defined by the
+   * AGI_articulations extension.
+   *
+   * @type {String}
+   * @private
+   */
+  this.articulationName = undefined;
 }
 
 /**
@@ -951,6 +960,84 @@ function Animation() {
   this.channels = [];
 }
 
+/**
+ * An articulation stage belonging to an articulation from the
+ * AGI_articulations extension.
+ *
+ * @alias {ModelComponents.ArticulationStage}
+ * @constructor
+ *
+ * @private
+ */
+function ArticulationStage() {
+  /**
+   * The name of the articulation stage.
+   *
+   * @type {String}
+   * @private
+   */
+  this.name = undefined;
+
+  /**
+   * The type of the articulation stage, defined by the type of motion it modifies.
+   *
+   * @type {ArticulationStageType}
+   * @private
+   */
+  this.type = undefined;
+
+  /**
+   * The minimum value for the range of motion of this articulation stage.
+   *
+   * @type {Number}
+   * @private
+   */
+  this.minimumValue = undefined;
+
+  /**
+   * The maximum value for the range of motion of this articulation stage.
+   *
+   * @type {Number}
+   * @private
+   */
+  this.maximumValue = undefined;
+
+  /**
+   * The initial value for this articulation stage.
+   *
+   * @type {Number}
+   * @private
+   */
+  this.initialValue = undefined;
+}
+
+/**
+ * An articulation for the model, as defined by the AGI_articulations extension.
+ *
+ * @alias {ModelComponents.Articulation}
+ * @constructor
+ *
+ * @private
+ */
+function Articulation() {
+  /**
+   * The name of the articulation.
+   *
+   * @type {String}
+   * @private
+   */
+  this.name = undefined;
+
+  /**
+   * The stages belonging to this articulation. The stages are applied to
+   * the model in order of appearance.
+   *
+   * @type {ModelComponents.ArticulationStage[]}
+   * @private
+   */
+  this.stages = [];
+}
+
 /**
  * The asset of the model.
  *
@@ -1015,6 +1102,13 @@ function Components() {
    */
   this.animations = [];
 
+  /**
+   * All articulations in the model as defined by the AGI_articulations extension.
+   *
+   * @type {ModelComponents.Articulation[]}
+   */
+  this.articulations = [];
+
   /**
    * Structural metadata containing the schema, property tables, property
    * textures and property mappings
@@ -1360,6 +1454,8 @@ ModelComponents.AnimationSampler = AnimationSampler;
 ModelComponents.AnimationTarget = AnimationTarget;
 ModelComponents.AnimationChannel = AnimationChannel;
 ModelComponents.Animation = Animation;
+ModelComponents.ArticulationStage = ArticulationStage;
+ModelComponents.Articulation = Articulation;
 ModelComponents.Asset = Asset;
 ModelComponents.Components = Components;
 ModelComponents.TextureReader = TextureReader;

Source/Scene/ModelExperimental/ModelExperimental.js

@@ -1294,6 +1294,57 @@ Object.defineProperties(ModelExperimental.prototype, {
   },
 });
 
+/**
+ * Sets the current value of an articulation stage.  After setting one or
+ * multiple stage values, call ModelExperimental.applyArticulations() to
+ * cause the node matrices to be recalculated.
+ *
+ * @param {String} articulationStageKey The name of the articulation, a space, and the name of the stage.
+ * @param {Number} value The numeric value of this stage of the articulation.
+ *
+ * @exception {DeveloperError} The model is not loaded. Use ModelExperimental.readyPromise or wait for ModelExperimental.ready to be true.
+ *
+ * @see ModelExperimental#applyArticulations
+ *
+ * @example
+ * // Sets the value of the stage named "MoveX" belonging to the articulation named "SampleArticulation"
+ * model.setArticulationStage("SampleArticulation MoveX", 50.0);
+ */
+ModelExperimental.prototype.setArticulationStage = function (
+  articulationStageKey,
+  value
+) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.number("value", value);
+  if (!this._ready) {
+    throw new DeveloperError(
+      "The model is not loaded. Use ModelExperimental.readyPromise or wait for ModelExperimental.ready to be true."
+    );
+  }
+  //>>includeEnd('debug');
+
+  this._sceneGraph.setArticulationStage(articulationStageKey, value);
+};
+
+/**
+ * Applies any modified articulation stages to the matrix of each node that
+ * participates in any articulation. Note that this will overwrite any node
+ * transformations on participating nodes.
+ *
+ * @exception {DeveloperError} The model is not loaded. Use ModelExperimental.readyPromise or wait for ModelExperimental.ready to be true.
+ */
+ModelExperimental.prototype.applyArticulations = function () {
+  //>>includeStart('debug', pragmas.debug);
+  if (!this._ready) {
+    throw new DeveloperError(
+      "The model is not loaded. Use ModelExperimental.readyPromise or wait for ModelExperimental.ready to be true."
+    );
+  }
+  //>>includeEnd('debug');
+
+  this._sceneGraph.applyArticulations();
+};
+
 /**
  * Resets the draw commands for this model.
  *