Merge pull request #5584 from rahwang/entity-model-matrix

make entity model matrix computation public
CesiumGS · Jul 26, 2017 · 960418e · 960418e
2 parents bd22854 + 3097115
commit 960418e
Show file tree

Hide file tree

Showing 7 changed files with 37 additions and 20 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -19,6 +19,7 @@ Change Log
 * Fixed issue where composite 3D Tiles that contained instanced 3D Tiles with an external model reference would fail to download the model.
 * Added behavior to `Cesium3DTilesInspector` that selects the first tileset hovered over if no tilest is specified. [#5139](https://github.com/AnalyticalGraphicsInc/cesium/issues/5139)
 * Added ability to provide a `width` and `height` to `scene.pick`. [#5602](https://github.com/AnalyticalGraphicsInc/cesium/pull/5602)
+* Added `Entity.computeModelMatrix` which returns the model matrix representing the entity's transformation. [#5584](https://github.com/AnalyticalGraphicsInc/cesium/pull/5584)
 * Added ability to set a style's `color`, `show`, or `pointSize` with a string or object literal. `show` may also take a boolean and `pointSize` may take a number. [#5412](https://github.com/AnalyticalGraphicsInc/cesium/pull/5412)
 * Added setter for `KmlDataSource.name` to specify a name for the datasource [#5660](https://github.com/AnalyticalGraphicsInc/cesium/pull/5660).
 * Added setter for `GeoJsonDataSource.name` to specify a name for the datasource [#5653](https://github.com/AnalyticalGraphicsInc/cesium/issues/5653)

diff --git a/Source/DataSources/BoxGeometryUpdater.js b/Source/DataSources/BoxGeometryUpdater.js
@@ -362,7 +362,7 @@ define([
         return new GeometryInstance({
             id : entity,
             geometry : BoxGeometry.fromDimensions(this._options),
-            modelMatrix : entity._getModelMatrix(Iso8601.MINIMUM_VALUE),
+            modelMatrix : entity.computeModelMatrix(Iso8601.MINIMUM_VALUE),
             attributes : attributes
         });
     };
@@ -394,7 +394,7 @@ define([
         return new GeometryInstance({
             id : entity,
             geometry : BoxOutlineGeometry.fromDimensions(this._options),
-            modelMatrix : entity._getModelMatrix(Iso8601.MINIMUM_VALUE),
+            modelMatrix : entity.computeModelMatrix(Iso8601.MINIMUM_VALUE),
             attributes : {
                 show : new ShowGeometryInstanceAttribute(isAvailable && entity.isShowing && this._showProperty.getValue(time) && this._showOutlineProperty.getValue(time)),
                 color : ColorGeometryInstanceAttribute.fromColor(outlineColor),
@@ -555,7 +555,7 @@ define([
         }
 
         var options = this._options;
-        var modelMatrix = entity._getModelMatrix(time);
+        var modelMatrix = entity.computeModelMatrix(time);
         var dimensions = Property.getValueOrUndefined(box.dimensions, time, options.dimensions);
         if (!defined(modelMatrix) || !defined(dimensions)) {
             return;

diff --git a/Source/DataSources/CylinderGeometryUpdater.js b/Source/DataSources/CylinderGeometryUpdater.js
@@ -367,7 +367,7 @@ define([
         return new GeometryInstance({
             id : entity,
             geometry : new CylinderGeometry(this._options),
-            modelMatrix : entity._getModelMatrix(Iso8601.MINIMUM_VALUE),
+            modelMatrix : entity.computeModelMatrix(Iso8601.MINIMUM_VALUE),
             attributes : attributes
         });
     };
@@ -399,7 +399,7 @@ define([
         return new GeometryInstance({
             id : entity,
             geometry : new CylinderOutlineGeometry(this._options),
-            modelMatrix : entity._getModelMatrix(Iso8601.MINIMUM_VALUE),
+            modelMatrix : entity.computeModelMatrix(Iso8601.MINIMUM_VALUE),
             attributes : {
                 show : new ShowGeometryInstanceAttribute(isAvailable && entity.isShowing && this._showProperty.getValue(time) && this._showOutlineProperty.getValue(time)),
                 color : ColorGeometryInstanceAttribute.fromColor(outlineColor),
@@ -573,7 +573,7 @@ define([
         }
 
         var options = this._options;
-        var modelMatrix = entity._getModelMatrix(time);
+        var modelMatrix = entity.computeModelMatrix(time);
         var length = Property.getValueOrUndefined(cylinder.length, time);
         var topRadius = Property.getValueOrUndefined(cylinder.topRadius, time);
         var bottomRadius = Property.getValueOrUndefined(cylinder.bottomRadius, time);

diff --git a/Source/DataSources/EllipsoidGeometryUpdater.js b/Source/DataSources/EllipsoidGeometryUpdater.js
@@ -374,7 +374,7 @@ define([
         return new GeometryInstance({
             id : entity,
             geometry : new EllipsoidGeometry(this._options),
-            modelMatrix : entity._getModelMatrix(Iso8601.MINIMUM_VALUE),
+            modelMatrix : entity.computeModelMatrix(Iso8601.MINIMUM_VALUE),
             attributes : attributes
         });
     };
@@ -407,7 +407,7 @@ define([
         return new GeometryInstance({
             id : entity,
             geometry : new EllipsoidOutlineGeometry(this._options),
-            modelMatrix : entity._getModelMatrix(Iso8601.MINIMUM_VALUE),
+            modelMatrix : entity.computeModelMatrix(Iso8601.MINIMUM_VALUE),
             attributes : {
                 show : new ShowGeometryInstanceAttribute(isAvailable && entity.isShowing && this._showProperty.getValue(time) && this._showOutlineProperty.getValue(time)),
                 color : ColorGeometryInstanceAttribute.fromColor(outlineColor),
@@ -589,7 +589,7 @@ define([
         }
 
         var radii = Property.getValueOrUndefined(ellipsoid.radii, time, radiiScratch);
-        var modelMatrix = entity._getModelMatrix(time, this._modelMatrix);
+        var modelMatrix = entity.computeModelMatrix(time, this._modelMatrix);
         if (!defined(modelMatrix) || !defined(radii)) {
             if (defined(this._primitive)) {
                 this._primitive.show = false;

diff --git a/Source/DataSources/Entity.js b/Source/DataSources/Entity.js
@@ -1,5 +1,6 @@
 define([
         '../Core/Cartesian3',
+        '../Core/Check',
         '../Core/createGuid',
         '../Core/defaultValue',
         '../Core/defined',
@@ -32,6 +33,7 @@ define([
         './WallGraphics'
     ], function(
         Cartesian3,
+        Check,
         createGuid,
         defaultValue,
         defined,
@@ -581,9 +583,16 @@ define([
     var orientationScratch = new Quaternion();
 
     /**
-     * @private
+     * Computes the model matrix for the entity's transform at specified time. Returns undefined if orientation or position
+     * are undefined.
+     *
+     * @param {JulianDate} time The time to retrieve model matrix for.
+     * @param {Matrix4} [result] The object onto which to store the result.
+     *
+     * @returns {Matrix4} The modified result parameter or a new Matrix4 instance if one was not provided. Result is undefined if position or orientation are undefined.
      */
-    Entity.prototype._getModelMatrix = function(time, result) {
+    Entity.prototype.computeModelMatrix = function(time, result) {
+        Check.typeOf.object('time', time);
         var position = Property.getValueOrUndefined(this._position, time, positionScratch);
         if (!defined(position)) {
             return undefined;

diff --git a/Source/DataSources/ModelVisualizer.js b/Source/DataSources/ModelVisualizer.js
@@ -100,7 +100,7 @@ define([
 
             var modelMatrix;
             if (show) {
-                modelMatrix = entity._getModelMatrix(time, modelMatrixScratch);
+                modelMatrix = entity.computeModelMatrix(time, modelMatrixScratch);
                 uri = Property.getValueOrUndefined(modelGraphics._uri, time);
                 show = defined(modelMatrix) && defined(uri);
             }

diff --git a/Specs/DataSources/EntitySpec.js b/Specs/DataSources/EntitySpec.js
@@ -241,13 +241,20 @@ defineSuite([
         }).toThrowDeveloperError();
     });
 
-    it('_getModelMatrix returns undefined when position is undefined.', function() {
+    it('computeModelMatrix throws if no time specified.', function() {
+        var entity = new Entity();
+        expect(function() {
+            entity.computeModelMatrix();
+        }).toThrowDeveloperError();
+    });
+
+    it('computeModelMatrix returns undefined when position is undefined.', function() {
         var entity = new Entity();
         entity.orientation = new ConstantProperty(Quaternion.IDENTITY);
-        expect(entity._getModelMatrix(new JulianDate())).toBeUndefined();
+        expect(entity.computeModelMatrix(new JulianDate())).toBeUndefined();
     });
 
-    it('_getModelMatrix returns correct value.', function() {
+    it('computeModelMatrix returns correct value.', function() {
         var entity = new Entity();
 
         var position = new Cartesian3(123456, 654321, 123456);
@@ -257,28 +264,28 @@ defineSuite([
         entity.position = new ConstantProperty(position);
         entity.orientation = new ConstantProperty(orientation);
 
-        var modelMatrix = entity._getModelMatrix(new JulianDate());
+        var modelMatrix = entity.computeModelMatrix(new JulianDate());
         var expected = Matrix4.fromRotationTranslation(Matrix3.fromQuaternion(orientation), position);
         expect(modelMatrix).toEqual(expected);
     });
 
-    it('_getModelMatrix returns ENU when quaternion is undefined.', function() {
+    it('computeModelMatrix returns ENU when quaternion is undefined.', function() {
         var entity = new Entity();
         var position = new Cartesian3(123456, 654321, 123456);
         entity.position = new ConstantProperty(position);
 
-        var modelMatrix = entity._getModelMatrix(new JulianDate());
+        var modelMatrix = entity.computeModelMatrix(new JulianDate());
         var expected = Transforms.eastNorthUpToFixedFrame(position);
         expect(modelMatrix).toEqual(expected);
     });
 
-    it('_getModelMatrix works with result parameter.', function() {
+    it('computeModelMatrix works with result parameter.', function() {
         var entity = new Entity();
         var position = new Cartesian3(123456, 654321, 123456);
         entity.position = new ConstantProperty(position);
 
         var result = new Matrix4();
-        var modelMatrix = entity._getModelMatrix(new JulianDate(), result);
+        var modelMatrix = entity.computeModelMatrix(new JulianDate(), result);
         var expected = Transforms.eastNorthUpToFixedFrame(position);
         expect(modelMatrix).toBe(result);
         expect(modelMatrix).toEqual(expected);